SamPlvs · SamPlvs · May 29, 2026 · May 29, 2026
@@ -20,8 +20,9 @@ Launch an agent team to execute a plan. Parses the plan, shows a phase review, a
 
 ```
 zo build plans/project.md [--gate-mode supervised|auto|full-auto] [--no-tmux]
-                          [--low-token] [--lead-model opus|sonnet|haiku]
-                          [--max-iterations N] [--no-headlines]
+                          [--bypass-permissions] [--low-token]
+                          [--lead-model opus|sonnet|haiku] [--max-iterations N]
+                          [--no-headlines]
 ```
 
 **Cost-saving options:**
@@ -30,20 +31,24 @@ zo build plans/project.md [--gate-mode supervised|auto|full-auto] [--no-tmux]
 - `--max-iterations N`: hard cap on Phase-4 experiment iterations. Wins over plan and preset.
 - `--no-headlines`: skip the end-of-session Haiku bullet summary (~1 Haiku call per run).
 
+**Permission prompts:**
+- `--bypass-permissions`: auto-approve **every** Claude Code tool-call prompt (Bash, Edit, Write, Read, ...) for the run. Independent of `--gate-mode` (which gates ZO's phases, not individual tool calls); implied by `--gate-mode full-auto`. Off by default. Works in tmux (temporary `.claude/settings.local.json` overlay, auto-restored on exit) and headless (`--dangerously-skip-permissions`) modes. See `docs/cli/build.mdx`.
+
 ### zo continue
 
 Resume a paused project. Shorthand for `zo build` with an existing plan -- finds the plan by project name and picks up from the current phase.
 
 ```
 zo continue [project-name] [--repo PATH] [--gate-mode supervised|auto|full-auto]
-                           [--low-token] [--lead-model opus|sonnet|haiku]
-                           [--max-iterations N] [--no-headlines]
+                           [--bypass-permissions] [--low-token]
+                           [--lead-model opus|sonnet|haiku] [--max-iterations N]
+                           [--no-headlines]
 ```
 
 **Options:**
 - `project-name`: optional if cwd contains `.zo/config.yaml` (auto-detected)
 - `--repo PATH`: path to delivery repo (overrides target file lookup)
-- `--low-token`, `--lead-model`, `--max-iterations`, `--no-headlines`: same semantics as `zo build`
+- `--low-token`, `--lead-model`, `--max-iterations`, `--no-headlines`, `--bypass-permissions`: same semantics as `zo build`
 
 ### zo draft
 

@@ -1115,3 +1115,15 @@ The `--no-headlines` flag is preserved (not removed) for backwards compatibility
 **Outcome:** Single feature-removal commit on branch `claude/remove-haiku-ticker`, PR opened against `main`. After rebase onto main (which now includes PR #92), pytest 760 passed / 7 skipped on both Python 3.11 and 3.12. ruff `src/` clean. validate-docs clean. Full CI-equivalent matrix run locally per PR-039 protocol before push. **No new PRIOR added** — this is a clean feature-removal driven by user feedback, not a failure-trace self-evolution.
 
 **Cross-reference:** PR-039 (pre-push verification must mirror full CI matrix) — this PR's verification followed that protocol end-to-end. Related to session 024's `--low-token` design where `headlines_disabled` was first introduced as a cost-saving preset field; this PR extends that thinking to the unconditional case (everyone gets the cost saving, not just `--low-token` users).
+
+---
+
+## Decision: 2026-05-29T10:00:00Z
+**Type:** DOCUMENTATION
+**Title:** Document `--bypass-permissions` in docs/COMMANDS.md — completing the PR #92 doc cascade
+
+**Decision:** Added `--bypass-permissions` to `docs/COMMANDS.md` (the terminal-command reference) in four places: the `zo build` usage block, a new "Permission prompts:" subsection under `zo build`, the `zo continue` usage block, and the `zo continue` "same semantics as `zo build`" options bullet. The description matches the framing already shipped in `docs/cli/build.mdx`: `--bypass-permissions` auto-approves **every** Claude Code tool-call prompt (Bash/Edit/Write/Read/...) for the run, is independent of `--gate-mode` (which gates ZO's phases, not individual tool calls), is implied by `--gate-mode full-auto`, is off by default, and works in both tmux (temporary `.claude/settings.local.json` overlay, auto-restored on exit) and headless (`--dangerously-skip-permissions`) modes.
+
+**Rationale:** PR #92 (session 031) shipped `--bypass-permissions` and updated `docs/cli/build.mdx` (full "Permission prompts" section + 6-row truth table) and `docs/cli/overview.mdx` (shared options table), but missed `docs/COMMANDS.md` — the reference that already documents the sibling build/continue flags (`--no-tmux`, `--low-token`, `--gate-mode`, and `--no-headlines` from session 032). COMMANDS.md was therefore the one surface where the flag was undiscoverable. Surfaced when the user asked whether the docs covered bypass-permissions; a targeted audit found build.mdx/overview.mdx complete and COMMANDS.md stale. PR-003 cascade discipline: a command's flag set must be reflected in COMMANDS.md.
+
+**Outcome:** 4 edits to `docs/COMMANDS.md` (10 insertions, 5 deletions); no code or tests touched. validate-docs.sh 10 passed / 0 failed / 1 pre-existing warning (client-blocklist skip). Docs + memory only, so the ruff/pytest CI matrix is unaffected by construction (zero `.py` files in the diff). **No new PRIOR** — clean cascade completion, not a failure-driven evolution; the generalisable lesson (PR-003: command flag sets cascade to COMMANDS.md) already exists. **Minor pre-existing drift noted, left out of scope:** README test badge reads 743 vs STATE's 760 post-#92/#93 (validate-docs "within tolerance"). Ships in branch `claude/document-bypass-permissions-commands`.
@@ -8,7 +8,9 @@ status: complete
 
 ## Current Position
 
-**Session 032 hand-off — pick up here.** Periodic Haiku headline ticker removed from `_launch_and_monitor` in `src/zo/cli.py`. The ticker spawned `claude -p --model haiku` every 60s during a run to summarise recent agent events into a 1-line headline — ~60 subprocess launches/hour at ~$0.0001-$0.0003 each, totalling ~$0.06-$0.18 per overnight run. User confirmed nobody uses it. Removed the `_maybe_print_headline` function, the `_last_headline_time` and `_headline_interval` timer variables, and the `_maybe_print_headline()` call inside `_print_status`. Kept the `_headline_buffer` list (still consumed once at session end by `_generate_session_summary` for a 2-3 bullet Haiku wrap-up, ~1 call/run, ~$0.0002 — cheap and useful). Kept `_generate_session_summary` and the `--no-headlines` flag; the flag's meaning narrows to "skip the end-of-session bullet summary too" (it can no longer disable the ticker, because the ticker doesn't exist). Updated docstrings, `_LOW_TOKEN_PRESET` inline comment, the auxiliary-call comment near the end-of-session call. **Docs cascade:** `docs/cli/build.mdx` (Step 5 monitoring sentence rewritten, "Headlines" Live-monitoring Card removed, options table `--no-headlines` row + `--low-token` accordion text updated), `docs/cli/overview.mdx` shared options table, `docs/quickstart.mdx` "What you'll see" bullet list + `--low-token` Note, `docs/COMMANDS.md` `--low-token` + `--no-headlines` lines, `docs/concepts/low-token-mode.mdx` two tables + the Batch API forward-looking note, `docs/reference/low-token-preset.mdx` preset table + override flag entry. **Behaviour change:** anyone running `zo build` today sees a console headline every 60s; after this PR they don't. End-of-session summary unchanged. After rebase onto main (now includes PR #92's bypass-permissions feature + 17 new tests), pytest 760 passed / 7 skipped on both Python 3.11 and 3.12. ruff src/ clean. validate-docs clean. **Next action when picking up:** unchanged — monitor Discussions for early external-user signal on Tier 2 sequencing, then resume Tier 1 (caveman ablation → onboarding hardening).
+**Session 033 hand-off — pick up here.** Documentation-only cascade completing a gap from PR #92. `--bypass-permissions` (added to `zo build` / `zo continue` in PR #92, session 031) was documented in `docs/cli/build.mdx` (full "Permission prompts" section + truth table) and `docs/cli/overview.mdx` (shared options table) but NOT in `docs/COMMANDS.md`, the terminal-command reference that documents the sibling flags (`--no-tmux`, `--low-token`, `--gate-mode`, `--no-headlines`). Added `--bypass-permissions` in 4 places: `zo build` usage block, a new "Permission prompts:" subsection under build, `zo continue` usage block, and the continue "same semantics as `zo build`" bullet. Framing matches build.mdx — auto-approves every Claude Code tool-call prompt, independent of `--gate-mode` (which gates ZO phases, not individual tool calls), implied by `--gate-mode full-auto`, off by default, tmux settings-overlay vs headless `--dangerously-skip-permissions`. validate-docs 10 passed / 0 failed / 1 pre-existing warning (client-blocklist skip). No code/tests touched (docs + memory only), so the ruff/pytest CI matrix is unaffected. **Minor pre-existing drift noted, NOT fixed (out of scope):** README test badge reads 743 while STATE reports 760 post-#92/#93 (validate-docs "within tolerance", passes). **Next action when picking up:** unchanged from session 032 — monitor Discussions for early external-user signal on Tier 2 sequencing, then resume Tier 1 (caveman ablation → onboarding hardening).
+
+**Session 032 hand-off (prior).** Periodic Haiku headline ticker removed from `_launch_and_monitor` in `src/zo/cli.py`. The ticker spawned `claude -p --model haiku` every 60s during a run to summarise recent agent events into a 1-line headline — ~60 subprocess launches/hour at ~$0.0001-$0.0003 each, totalling ~$0.06-$0.18 per overnight run. User confirmed nobody uses it. Removed the `_maybe_print_headline` function, the `_last_headline_time` and `_headline_interval` timer variables, and the `_maybe_print_headline()` call inside `_print_status`. Kept the `_headline_buffer` list (still consumed once at session end by `_generate_session_summary` for a 2-3 bullet Haiku wrap-up, ~1 call/run, ~$0.0002 — cheap and useful). Kept `_generate_session_summary` and the `--no-headlines` flag; the flag's meaning narrows to "skip the end-of-session bullet summary too" (it can no longer disable the ticker, because the ticker doesn't exist). Updated docstrings, `_LOW_TOKEN_PRESET` inline comment, the auxiliary-call comment near the end-of-session call. **Docs cascade:** `docs/cli/build.mdx` (Step 5 monitoring sentence rewritten, "Headlines" Live-monitoring Card removed, options table `--no-headlines` row + `--low-token` accordion text updated), `docs/cli/overview.mdx` shared options table, `docs/quickstart.mdx` "What you'll see" bullet list + `--low-token` Note, `docs/COMMANDS.md` `--low-token` + `--no-headlines` lines, `docs/concepts/low-token-mode.mdx` two tables + the Batch API forward-looking note, `docs/reference/low-token-preset.mdx` preset table + override flag entry. **Behaviour change:** anyone running `zo build` today sees a console headline every 60s; after this PR they don't. End-of-session summary unchanged. After rebase onto main (now includes PR #92's bypass-permissions feature + 17 new tests), pytest 760 passed / 7 skipped on both Python 3.11 and 3.12. ruff src/ clean. validate-docs clean. **Next action when picking up:** unchanged — monitor Discussions for early external-user signal on Tier 2 sequencing, then resume Tier 1 (caveman ablation → onboarding hardening).
 
 **Session 031 hand-off (prior).** New CLI flag `--bypass-permissions` added to `zo build` / `zo continue` to give users an explicit opt-in for auto-approving Claude Code tool-call permission prompts. Design lesson captured in **PRIORS PR-038** (a CLI flag should map to one concern; coupling visibility-mode to safety-mode silently bypasses user expectations). Behavior change worth flagging: previously `--no-tmux` ALWAYS injected `--dangerously-skip-permissions` into the Claude CLI command (`src/zo/wrapper.py:376` unconditional); now it's conditional on the resolved bypass setting. Truth table (resolver: `_resolve_bypass_permissions` at `src/zo/cli.py:301`): `--gate-mode supervised|auto` → bypass off unless explicit flag; `--gate-mode full-auto` → bypass implicitly on (no-human-on-gates + must-click-every-tool was a contradiction). **Tmux mode now also supports bypass** via a new `src/zo/permissions_overlay.py` module: writes `permissions.defaultMode: "bypassPermissions"` into `<cwd>/.claude/settings.local.json` on launch, backs up the original to a sibling `.zo-backup` file, restores via `atexit` on exit; `cleanup_stale_overlay()` called at every `_launch_and_monitor` invocation handles crashed-mid-run recovery from a leftover backup. Settings.local.json was also added to `.gitignore` in PR #91 (already merged) so the per-user file doesn't accumulate transient secrets in tracked state. **Tests added: +17** (`tests/unit/test_permissions_overlay.py` 12 cases covering existing-settings / no-settings / malformed / stale-cleanup / non-dict-permissions; `tests/unit/test_wrapper.py` 3 new cases for headless conditional flag + tmux overlay apply/skip; `tests/unit/test_cli.py` 1 case for the resolver truth table). pytest 760 passed / 7 skipped (was 743 + 7). validate-docs 10/11 (1 pre-existing warning, 0 failures — the previously-flagged test-count warning resolved naturally as the suite grew above 743). Docs updated: `docs/cli/build.mdx` gains a "Permission prompts" section with the full truth table and the behavior-change note; `docs/cli/overview.mdx` adds the flag to the shared options table. Power-user UX note: for an unattended prod-001 overnight run, `zo continue --repo /path/to/prod-001 --gate-mode full-auto` now Just Works in tmux without any manual settings.local.json tinkering.