wade-cli 0.54.2__tar.gz → 1.1.0__tar.gz

{wade_cli-0.54.2 → wade_cli-1.1.0}/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v1.1.0] — 2026-09-04
+
+### Features
+
+- diagnose sandboxed parent runtimes and keep review gates closed (#481) (4440220)
+
+## [v1.0.0] — 2026-09-03
+
+### Breaking Changes
+
+- replace the Codex network pin with a cross-tool sandbox profile (#479) (7fa9561)
+  `ai.network_access` is retired and the AI runtime now launches **unsandboxed by default**. Set `ai.sandbox: true` to restore the previous confinement.
+
+### Features
+
+- replace the Codex network pin with a cross-tool sandbox profile (#479) (7fa9561)
+
 ## [v0.54.2] — 2026-09-02
 
 ### Chores
@@ -415,6 +432,11 @@ The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
 ## [v0.33.0] — 2026-07-23
 
+### Breaking Changes
+
+- replace Gemini CLI support with Antigravity CLI (bump crossby to 0.10.x) (#336) (c54af6d)
+  Gemini CLI is no longer a supported AI tool. Projects with ai.default_tool: gemini (or a per-command tool: gemini) must switch to antigravity-cli or another supported tool.
+
 ### Features
 
 - replace Gemini CLI support with Antigravity CLI (bump crossby to 0.10.x) (#336) (c54af6d)

{wade_cli-0.54.2 → wade_cli-1.1.0}/KNOWLEDGE.md

@@ -707,3 +707,87 @@ uv.lock is gitignored in this repo, so a crossby pin bump needs BOTH `uv lock` a
 docs/dev/architecture.md's .wade.yml example hardcodes crossby's claude complexity-tier model IDs, so every crossby pin bump silently makes it stale — wade init writes whatever crossby.config.defaults.get_defaults() returns, not those literals. Update that block on every pin bump; note the crossby version RANGE is deliberately not restated in that file (architecture.md line ~171) so only the tier values need touching. Blast radius on existing projects is narrow: wade update re-resolves defaults but calls _patch_config without force, backfilling only tiers a config left unset.
 
 ---
+
+## d7e3010043a2 | 2026-09-02 | implementation | tags: hooks, codex, gotcha, sandbox | Issue #478
+
+`sandboxes_writes` is a STATIC crossby capability but the write boundary became launch-dependent once `ai.sandbox` existed (#478): it describes what a tool can do, not what this launch will do. Any code branching on it — today only `_install_guard_hooks` in `implementation_service/bootstrap.py` — must also consult the resolved profile, or under `sandbox=False` (Codex `--sandbox danger-full-access`) the worktree-containment guard narrows to the shell token and tool-call writes outside the worktree are guarded by nothing. Extends a44493f7, which documents the narrow-don't-skip rule but predates a disableable sandbox.
+
+---
+
+## 1c79175312c9 | 2026-09-02 | implementation | tags: config, validation, gotcha | Issue #478
+
+check_service.py's AI-section key allowlists are derived reflectively from AICommandConfig/AIConfig.model_fields (#368), so DELETING a config field silently drops its key from the allowlist and the generic 'unsupported key' loop turns an un-migrated .wade.yml into a HARD ERROR — independent of any type validator, and in the opposite direction from the drift #368 fixed. Any key retirement needs an explicit tolerance entry (_DEPRECATED_AI_KEYS, added by #478) unioned into both allowlists for the transition release.
+
+---
+
+## 58e3be66cd66 | 2026-09-02 | implementation | tags: codex, yolo, sandbox | Issue #478
+
+Codex --sandbox danger-full-access is APPROVAL-NEUTRAL: it is a distinct flag from --dangerously-bypass-approvals-and-sandbox, so disabling the runtime sandbox does not imply yolo and leaves the autonomy argv byte-identical. Sandbox and permission_mode stay orthogonal axes — one moves the OS boundary, the other the approval tier. Consistent with 1c18f1d4's separation of headless autonomy from permissions.
+
+---
+
+## 9eacd93219c1 | 2026-09-02 | implementation | tags: crossby, codex, gotcha | Issue #478
+
+crossby's network_access parameter defaults to False and survived the #478 sandbox toggle, so wade must keep PASSING it (LAUNCH_NETWORK_ACCESS=True) rather than omitting it: a sandboxed launch that dropped the kwarg pins sandbox_workspace_write.network_access=false and silently takes the network away from the fetch/push/gh lifecycle that requires it. Under sandbox=False crossby short-circuits and ignores the value. This is why issue #478's 'no network_access kwarg reaches any adapter' criterion could not be met literally.
+
+---
+
+## ee8722fe7f27 | 2026-09-03 | implementation | tags: config, migration, gotcha | Issue #478
+
+Config migrations in src/wade/config/migrations.py must test key PRESENCE, never the popped value: YAML `key:` with no value parses to None, so the natural `pop(key, None) is not None` idiom drops the key in memory while reporting 'unchanged'. That boolean is the only thing driving run_all_migrations' write-back, so a false 'unchanged' leaves the retired key on disk and any deprecation warning keyed to it recurs on every run. Use the _pop_if_present helper (#479) for any future key retirement.
+
+---
+
+## 6eb12fb5eb3a | 2026-09-03 | implementation | tags: tooling, git, gotcha | Issue #478
+
+scripts/changelog.py's format_range is re-run by generate() for EVERY tag range in history, so anything per-commit inside it multiplies by the repo's whole commit count on each regeneration — the original per-commit `git log -1` body lookup would have meant thousands of subprocesses once footer-only breaking changes forced every body to be read. Pull extra commit fields from get_commits' single batched git log instead, with \x1f/\x1e field/record separators because bodies are multi-line free text that breaks any newline- or pipe-delimited format.
+
+---
+
+## ace2eb931e5e | 2026-09-03 | implementation | tags: release, ci, gotcha | Issue #478
+
+The release version bump is derived from the PR title ALONE — .github/workflows/auto-version.yml greps only github.event.pull_request.title, never commit history — and done.py's PR-title sync overwrites that title from the ISSUE title on every done. So a `feat!:` commit with a real BREAKING CHANGE footer still ships as a MINOR release unless issue #N's own title carries the `!`; retitle the issue (gh issue edit --title, since wade task update only edits the body), not just the PR, or done reverts it.
+
+---
+
+## 1f23c00660aa | 2026-09-04 | implementation | tags: delegation, architecture, sandbox | Issue #480
+
+`delegation_service.delegate()` is the single dispatcher for deps, standalone plan/code review, and batch review — `deps_service` and `review_delegation_service` call it directly and `batch_review_service` reaches it through the latter — so a cross-cutting launch concern belongs there ONCE, not per service. Centralising costs per-operation context, so remediation text must ride on `DelegationRequest` fields rather than being generated inside the dispatcher. `implementation_service/batch.py` is NOT a launch path: it builds ["wade", "implement", <id>] and spawns child `wade` processes that reach the `core.py` check themselves, so a check there is a dead no-op implying coverage it does not add.
+
+---
+
+## 280ed6e410b6 | 2026-09-04 | implementation | tags: delegation, sandbox, gotcha, error-handling | Issue #480
+
+`DelegationResult.never_launched` means no process ever started (absent/unknown tool, `supports_headless` rejection, `CommandError` spawn failure, `OSError` on exec) — a non-zero exit AND a real timeout must both keep it False, because "relaunch the outer session" is wrong advice for a reviewer that actually ran. `utils.process.run` maps only `FileNotFoundError` to `CommandError`, so a `PermissionError` on a binary that resolves on PATH but cannot be executed escapes `_delegate_headless` entirely unless caught explicitly — one of the exact shapes an inherited sandbox produces. The interactive path needs an explicit `launched` flag because `adapter.launch` and the post-session output-file read share one exception handler.
+
+---
+
+## 65ee7eb64d81 | 2026-09-04 | implementation | tags: testing, sandbox, gotcha | Issue #480
+
+`tests/conftest.py` carries an autouse fixture clearing `runtime_env.SANDBOX_SIGNAL_ENV_VARS`, because `utils/runtime_env.py` reads the REAL environment — without it a suite run from inside a sandboxed Codex session sees a genuine SANDBOXED verdict and takes relaunch/diagnosis branches no test asked for. It clears only the sandbox-signal vars, never the identity markers (`CODEX_CLI`, `CLAUDE_CODE`, …) that existing tests patch directly. Any test asserting on the parent-sandbox diagnosis must also clear competing identity markers, since the probe returns the FIRST one it recognises.
+
+---
+
+## 397994e37408 | 2026-09-04 | implementation | tags: delegation, error-handling, gotcha | Issue #480
+
+`DelegationResult.never_launched` means no process ever started, and an explicit `launched` flag set after `adapter.launch()` returns is NOT enough to decide it: `launch` blocks until the child exits for most runtimes, so an adapter that checks the exit status raises `CalledProcessError` from a session that ran and failed. Classify the interactive launch boundary by exception SHAPE — an `OSError` at the spawn started nothing, every `subprocess.SubprocessError` variant carries a child that was created — and keep the post-launch section in its own handler. `utils.process.run` maps only `FileNotFoundError` to `CommandError`, so a `PermissionError` on a binary that resolves on PATH but cannot be executed escapes `_delegate_headless` unless caught explicitly.
+
+---
+
+## 12dd26da8910 | 2026-09-04 | implementation | tags: testing, gotcha, e2e | Issue #480
+
+A non-executable file earlier on PATH does NOT make a later real binary unreachable: CPython builds an exec candidate from every PATH entry and keeps going past EACCES, so an E2E test that drops a chmod 644 stand-in into the mocked bin dir still runs the users real tool. To force a denial-shaped spawn failure, narrow PATH in the child env to the mocked bin plus only the dirs actually needed (`wade`, `git`, `/usr/bin`, `/bin`). `shutil.which` skips non-executables, so it is the right assertion that no real binary remains reachable.
+
+---
+
+## 4668ee29b835 | 2026-09-04 | implementation | tags: delegation, sandbox, batch | Issue #480
+
+For issue #480, delegation_service.delegate() remains the one dispatcher for deps and standalone/batch reviews, but implement-batch crosses a different terminal-broker boundary. Diagnose a known parent sandbox once in implementation_service.batch before broker shells can lose its markers; child implementation checks remain a backstop, not the sole diagnosis.
+
+---
+
+## 54236b4243bc | 2026-09-04 | implementation | tags: testing, sandbox, gotcha | Issue #480
+
+For issue #480 sandbox tests, the autouse conftest fixture clears both SANDBOX_SIGNAL_ENV_VARS and real Codex identity markers in CODEX_IDENTITY_ENV_VARS. Tests that need another enclosing runtime still set or clear competing identity markers deliberately; do not claim the fixture never clears identity markers.
+
+---

{wade_cli-0.54.2 → wade_cli-1.1.0}/KNOWLEDGE.ratings.jsonl

@@ -152,3 +152,21 @@
 {"dir": "up", "event_id": "0d0c898f52b54710a8d50b82cf78444a", "id": "a15045c3", "ts": "2026-09-02T15:22:03.529067+00:00"}
 {"dir": "up", "event_id": "417925753e00400a98e04c6a7d41ccc4", "id": "ae5df2be", "ts": "2026-09-02T15:39:33.320072+00:00"}
 {"dir": "up", "event_id": "a23ed60deb074def962f804a7ff9541a", "id": "fb2a067bb103", "ts": "2026-09-02T15:39:33.521027+00:00"}
+{"dir": "up", "event_id": "e816bf9eda9842ffac928af977bd6ea3", "id": "a44493f7", "ts": "2026-09-02T22:00:41.291342+00:00"}
+{"dir": "up", "event_id": "53071621625c4c40a2f7fded2f48467a", "id": "5b61c9c6", "ts": "2026-09-02T22:00:41.466441+00:00"}
+{"dir": "up", "event_id": "980a8493a8bd42829e2a3057fa681c6a", "id": "fde883286787", "ts": "2026-09-02T22:00:41.632699+00:00"}
+{"dir": "up", "event_id": "5cde95ece3844529a88448383c60e822", "id": "d7e3010043a2", "ts": "2026-09-03T02:07:17.166938+00:00"}
+{"dir": "up", "event_id": "18179aae748f444487502929584aa632", "id": "6eb12fb5eb3a", "ts": "2026-09-03T12:24:58.444706+00:00"}
+{"dir": "up", "event_id": "0c1be71273e34c50b609348a7c09622e", "id": "1c79175312c9", "ts": "2026-09-03T12:24:58.649116+00:00"}
+{"dir": "up", "event_id": "67eb4181748e4cd2974a60ed014efe12", "id": "851bb6ec", "ts": "2026-09-04T11:02:22.496706+00:00"}
+{"dir": "up", "event_id": "b15b9eba905749c78eded32f991397a1", "id": "d7e3010043a2", "ts": "2026-09-04T11:02:22.654506+00:00"}
+{"dir": "stale", "event_id": "69e1b360de924aa5b0a27874d8be935e", "id": "8a9bfc96", "ts": "2026-09-04T11:02:22.809044+00:00"}
+{"dir": "up", "event_id": "79dac0524f60401fb457dcb44c62ac5a", "id": "1f23c00660aa", "ts": "2026-09-04T14:17:48.792141+00:00"}
+{"dir": "up", "event_id": "962d19cb9fa3460eb7f351bbdf0abe76", "id": "65ee7eb64d81", "ts": "2026-09-04T14:17:48.947672+00:00"}
+{"id": "280ed6e410b6", "superseded_by": "397994e37408", "ts": "2026-09-04T14:18:00.060874+00:00"}
+{"dir": "up", "event_id": "5aaf8dca23da43409dae899f50e04111", "id": "1f23c00660aa", "ts": "2026-09-04T16:19:49.643133+00:00"}
+{"dir": "up", "event_id": "96bedf22dcd74c3cabdace8dd850f125", "id": "280ed6e410b6", "ts": "2026-09-04T16:19:49.795516+00:00"}
+{"dir": "stale", "event_id": "de4b4ee2ffa24276a4b35d93ccb16b11", "id": "1f23c00660aa", "ts": "2026-09-04T22:14:03.557181+00:00"}
+{"dir": "stale", "event_id": "71f6ebba04cc4c86bc4e2d02ed19ea9d", "id": "65ee7eb64d81", "ts": "2026-09-04T22:14:03.707575+00:00"}
+{"id": "1f23c00660aa", "superseded_by": "4668ee29b835", "ts": "2026-09-04T22:14:10.938819+00:00"}
+{"id": "65ee7eb64d81", "superseded_by": "54236b4243bc", "ts": "2026-09-04T22:14:17.907524+00:00"}

{wade_cli-0.54.2 → wade_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 0.54.2
+Version: 1.1.0
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.11
-Requires-Dist: crossby<0.29.0,>=0.28.0
+Requires-Dist: crossby<0.30.0,>=0.29.0
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0
@@ -276,7 +276,7 @@ These are invoked by the AI during a session — you normally don't run them by
 | `wade plan-session done <plan_dir>` | Finalize a planning session |
 | `wade deps-session check` | Verify the detached dependency-analysis runtime before writing output or staging a knowledge vote |
 
-Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `implement`, `implement-batch`, `review pr-comments`, and the `wade <N>` shorthand also accept `--network` / `--no-network` (see [Codex sandbox](#codex-sandbox--network-policy)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
+Most workflow commands accept `--ai <tool>`, `--model <model>`, `--effort <level>`, `--permission-mode <tier>`, and `--yolo` to override configured defaults. `review pr-comments` additionally accepts `--effort none` to pin the tool default instead of a configured effort across a later wait/relaunch. `plan`, `implement`, and `review pr-comments` accept repeatable `--skill` and `--review-skill` methodology bindings plus `--refresh-skills` for an existing frozen session; `implement-batch` forwards the same binding request to every child session. Standalone plan/code/batch review and `task deps` accept repeatable `--skill`. `plan`, `implement`, `implement-batch`, standalone reviews (`review plan`, `review implementation`, `review batch`), `review pr-comments`, `task deps`, and the `wade <N>` shorthand also accept `--sandbox` / `--no-sandbox` (see [AI runtime sandbox profile](#ai-runtime-sandbox-profile)); batch and shorthand forward an explicit flag to the child session they launch. `implement` additionally supports `--detach` (new terminal tab), `--cd` (print worktree path only), and `--base <branch>` (see [Planning & base branches](#planning--base-branches)).
 
 ## Planning & base branches
 
@@ -348,7 +348,7 @@ for reviews"** after `wade implementation-session done` and comments land —
 resolves its tool, model, effort, and autonomy tier from a dedicated
 `ai.review_pr_comments` section (the same keys every `ai.<command>` section
 accepts: `tool`, `model`, `effort`, `mode`, `permission_mode` / `yolo`,
-`network_access`, `enabled`, `timeout`):
+`sandbox`, `enabled`, `timeout`):
 
 ```yaml
 ai:
@@ -689,59 +689,185 @@ appends a clearly labeled stderr tail containing at most the final 20 non-empty
 lines and 4,000 characters; if stdout is empty, that diagnostic is shown as the
 failure feedback, and any truncation is labeled.
 
-### Codex sandbox & network policy
-
-When WADE launches [Codex](https://github.com/openai/codex) in a linked
-worktree, Codex runs under `--sandbox workspace-write`, which confines writes to
-the worktree tree. A worktree's git metadata, however, lives **outside** that
-tree (`<main>/.git/worktrees/<wt>` and `<main>/.git`), so without extra grants
-every git write — `git add`/commit, ref updates, stash, and `wade
-sync`/`done` — fails with `Unable to create …/index.lock` or `could not write
-index`. WADE fixes this automatically: it passes the worktree's absolute path to
-the launcher, which grants those out-of-root git-metadata dirs as sandbox
-writable roots (the OS sandbox otherwise stays fully enabled — this widens
-nothing else). This is transparent; no Codex config or manual approval is
-needed, and it only affects Codex (every other tool ignores it).
-
-**Filesystem writes and network access are independent.** The metadata grant
-above makes **local** git work (stage, commit, stash, ref updates, and the
-local legs of `sync`/`done`) succeed with **network off**. Only operations that
-reach the network — `git fetch` (hence `sync`) and `git push` (hence the network
-leg of `done`) — need network access. It is **enabled by default** for the
-interactive lifecycle commands `wade implement` (including its batch children)
-and `wade review pr-comments`, because their readiness, sync, and completion
-steps require GitHub. Choose offline operation explicitly with `--no-network`,
-or in `.wade.yml`:
+### AI runtime sandbox profile
+
+`ai.sandbox` is a single cross-tool boolean that decides whether WADE launches
+the **AI runtime** inside its own filesystem sandbox. It governs the external
+runtime boundary only — it never relaxes WADE's own guards (see below).
+
+| Setting | Meaning |
+|---------|---------|
+| `sandbox: false` (**default**) | Launch the runtime unrestricted. Codex gets `--sandbox danger-full-access`, Cursor `--sandbox disabled`. Repository commands and delegated child tools keep **normal host access and credentials**. |
+| `sandbox: true` | Launch the runtime confined. Codex gets `--sandbox workspace-write`, Cursor `--sandbox enabled`. |
+
+Network access is **on in both profiles** and is no longer configurable — it is
+enabled for every WADE launch. Not every phase needs it (planning and
+dependency analysis deliberately do not), but the phases that do — `git
+fetch`/`push`, `gh`, package installs — cannot work without it, and the profile
+is fixed at launch.
+
+Set it globally or per command, and override it on any launch command
+(`implement`, `implement-batch`, `plan`, `review pr-comments`, `task deps`, `smart-start`,
+and the `i`/`r`/`p` aliases) with `--sandbox` / `--no-sandbox`:
 
 ```yaml
 ai:
-  network_access: false         # offline opt-out for interactive session commands
+  sandbox: true                 # confine every session's runtime
   implement:
-    network_access: true        # per-command override wins
+    sandbox: false              # ...except implementation (per-command wins)
 ```
 
-The policy applies to the **interactive session commands** — `wade implement`
-and `wade review pr-comments` — which are the ones that run `sync`/`done` and so
-may need `fetch`/`push`. The headless/analytical paths (`plan`, `deps`,
-`review plan`/`implementation`/`batch`) are **always** network-off by design:
-they never fetch or push, so `ai.network_access` does not apply to them and no
-flag enables it there. Precedence for the commands that honor it is
-`--network`/`--no-network` > `ai.<command>.network_access` >
-`ai.network_access` > **on for `implement` and `review_pr_comments`, otherwise
-off**. WADE always passes an explicit pin, so an ambient
-`network_access = true` in your own Codex `config.toml` can never silently
-enable network for a WADE-managed sandbox. Enabling network permits outbound
-access for commands inside the Codex workspace-write sandbox; it does not
-disable filesystem sandboxing or change approval-policy semantics.
-
-An accepted single-issue plan handoff starts implementation from a planning
-session that is always network-off. When both the planning tool and resolved
-implementation tool are Codex and the implementation policy resolves to enabled,
-WADE starts a fresh detached Codex context with network explicitly enabled;
-reusing the planner process would retain its immutable network-off sandbox. If
-WADE cannot open that detached context, the handoff fails rather than reporting
-an implementation session ready. Open a new host terminal and run the displayed
-`wade implement <issue> --network` command to continue with the required policy.
+Precedence: `--sandbox`/`--no-sandbox` > `ai.<command>.sandbox` > `ai.sandbox` >
+**unrestricted**. WADE pins the resolved profile explicitly in *both* directions,
+so an ambient setting in your own Codex `config.toml` can never silently move the
+boundary of a WADE-managed session. The resolved profile is printed at launch
+next to the tool, model, effort, and permission mode, with its meaning spelled
+out — the security posture is never left implicit.
+
+> **Why unrestricted is the default.** WADE runs a deliberately multi-model
+> workflow: a session delegates to reviewers and dependency analysers that
+> authenticate separately. Every `wade` command is a child of the AI runtime, so
+> a sandboxed outer runtime hands its sandbox to every child — and a separately
+> authenticated reviewer such as Claude Code loses its normal host login. That is
+> what makes delegated multi-model sessions fail in practice (#478).
+
+**`unrestricted` is not "unattended".** The profile is orthogonal to
+`permission_mode`: it moves the OS boundary, not the approval tier. Codex's
+`--sandbox danger-full-access` is a distinct flag from
+`--dangerously-bypass-approvals-and-sandbox`, so disabling the sandbox never
+implies `yolo` and never changes the resolved autonomy tier. Treat it as an
+intentional project opt-in to host access, not as a synonym for skipping prompts.
+
+Only tools with a sandbox toggle (Codex, Cursor) act on the setting. The
+capability handling is deliberately **asymmetric**, because the default is
+`false`:
+
+- `sandbox: false` on a tool that never sandboxed anything (Claude, Copilot, …)
+  is a silent no-op — those runtimes are already unrestricted.
+- `sandbox: true` **explicitly requested** on a tool with no sandbox toggle is a
+  visible error naming the tool. WADE cannot impose a boundary the runtime does
+  not have, and will not pretend it did. No tool ever receives an invented flag.
+
+#### Worktree git metadata under `sandbox: true`
+
+A worktree's git metadata lives **outside** the worktree tree
+(`<main>/.git/worktrees/<wt>` and `<main>/.git`), so under `workspace-write`
+every git write — `git add`/commit, ref updates, stash, and `wade sync`/`done` —
+would fail with `Unable to create …/index.lock` or `could not write index`. WADE
+fixes this automatically: it passes the worktree's absolute path to the launcher,
+which grants those out-of-root git-metadata dirs as sandbox writable roots (the
+OS sandbox otherwise stays fully enabled — this widens nothing else). It is
+transparent, needs no Codex config or manual approval, and is inert under
+`sandbox: false`, where there is no boundary to widen.
+
+#### WADE's own guards are unaffected
+
+Disabling the runtime sandbox does not disable WADE's containment. The
+worktree-containment guard actually gets **wider**: under `sandbox: true` it is
+narrowed to the shell token (Codex's sandbox already covers tool-call writes, but
+permits `/tmp` and `$TMPDIR`, so a shell redirect can still escape), while under
+`sandbox: false` the **full** matcher is installed because nothing else covers
+tool-call writes outside the worktree. The plan-artifact guard, lifecycle hooks,
+the Stop hook, and the pre-push backstop are identical in both profiles.
+
+#### Plan → implement handoff
+
+The sandbox is a launch-time OS property: a process started confined cannot drop
+its sandbox later. An accepted plan handoff runs after the planner child exits,
+so WADE assesses the **actual parent runtime enclosing the handoff**, not the
+former planner's requested profile. When that runtime is detected as sandboxed
+and implementation resolves to **unrestricted**, WADE fails the handoff rather
+than claiming a terminal child escaped the parent boundary. It names the runtime
+it could not escape, and you open a new host terminal and run the displayed
+`wade implement <issue> --no-sandbox` command. Without a published sandbox
+signal, the ordinary nested-launch guard applies rather than guessing.
+
+#### An inner `wade` process cannot escape a parent sandbox
+
+Every `wade` command you run from inside an AI CLI session is a **child** of that
+session. If the session was launched under an OS sandbox, every descendant
+inherits the boundary — no profile WADE resolves, and no flag it passes to a
+delegated runtime, can widen it. WADE will never claim otherwise, and there is no
+setting that changes it. **The fix is always to relaunch the outer session with
+the profile you want**, from a host terminal.
+
+What WADE does instead is say so. When the resolved profile is unrestricted and
+the enclosing runtime is *known* to be sandboxed, it names that runtime when it
+can (or says **the enclosing AI runtime** when an identity marker is absent) and
+prints the exact command to re-run — on implementation, plan,
+PR-comment review, and every delegated operation (dependency analysis, plan/code
+review, batch review), plus batch implementation before it dispatches terminal
+brokers. That command preserves the resolved tool, model, effort,
+and permission mode; only the sandbox profile changes to `--no-sandbox`.
+Implementation and PR-comment retries reuse their frozen method bindings rather
+than repeating `--skill` / `--review-skill` flags, while fresh delegated
+operations carry their requested bindings. It warns and proceeds rather than
+blocking: a delegated tool whose credentials happen to be reachable from inside
+the sandbox may still
+succeed, so refusing to try would break sessions that work today.
+
+Detection is deliberately **best-effort and conservative**. WADE reads only
+sandbox signals a runtime actually publishes and never infers confinement from
+tool identity — a tool that *can* be sandboxed is not a tool that *is* sandboxed.
+Today Codex publishes `CODEX_SANDBOX` for macOS Seatbelt, but its Linux Landlock
+sandbox with network enabled publishes neither that marker nor a usable
+`CODEX_SANDBOX_NETWORK_DISABLED` marker. WADE must report that Linux environment
+as *unknown*, not unrestricted; if the distinction matters, relaunch from a host
+terminal rather than expecting a diagnostic. When there is no signal WADE stays
+silent rather than asserting a cause it cannot support. A confident wrong
+diagnosis is worse than the opaque error it would replace. Managed Codex sessions
+are still recognised when they expose session/thread markers instead of the
+legacy `CODEX_CLI` marker; their displayed identity remains **Codex CLI**.
+
+An explicit unrestricted signal (for example, Codex's
+`CODEX_SANDBOX=danger-full-access`) is different from an absent signal: WADE
+does **not** recommend relaunching the outer session for a permission- or
+network-shaped launch failure in that case. The parent has already confirmed it
+is unrestricted, so check executable permissions and network configuration
+instead.
+
+**Troubleshooting order** when a delegated tool fails to launch:
+
+1. **Read what WADE printed.** An explicit sandbox-policy denial plus a named
+   runtime and command means relaunch the outer session with that command. A
+   generic permission or network denial also needs local checks below.
+2. **Check whether the reviewer actually started.** A reviewer that ran and
+   exited non-zero is a different problem; "relaunch the outer session" is wrong
+   advice for it. WADE distinguishes the two. A generic launch denial can also
+   be bad executable permissions or network configuration; a refusal WADE made
+   itself (an unknown tool, a tool with no headless mode) never reached the
+   sandbox and gets generic remediation instead.
+3. **Check executable permissions, network, and the tool's own login/PATH** in the runtime where it must run
+   (`gh auth status`, the delegate's own auth command). A separately
+   authenticated delegate needs its *own* credentials, not WADE's.
+4. **Re-run the phase readiness check** (`wade implementation-session check`,
+   `wade review-pr-comments-session check`, …) for a narrow `reason=…` and its
+   least-privilege remediation.
+5. **Only then** widen the profile — and widen the *outer* session, not the
+   child.
+
+> **Narrow, optional exception: Codex project prefix rules.** Codex can be
+> configured to run specific command prefixes outside its sandbox, which elevates
+> a single command without relaunching the session. It is a Codex-side setting
+> WADE neither writes nor reads, it applies per command rather than to the
+> session, and it does not change anything above: the session is still sandboxed
+> and every other child still inherits that. Treat it as an escape hatch for one
+> stubborn command, **not** as WADE's path for running unrestricted — that path
+> is relaunching the outer session.
+
+#### Migrating from `ai.network_access`
+
+`ai.network_access` was a Codex-only network pin, enabled by default for
+`implement` and `review_pr_comments` and off everywhere else. It is **retired**.
+An existing `.wade.yml` that still carries it keeps loading and passes
+`wade check` with a **warning, not an error**; the key is ignored, and `wade
+update` strips it — that is the only command that runs the config migration
+pipeline. Replace it with `ai.sandbox` if you want the old confinement back:
+
+```yaml
+ai:
+  sandbox: true                 # restores the pre-#478 Codex behaviour
+```
 
 ### Session readiness and least-privilege remediation
 
@@ -801,10 +927,27 @@ credentials, PATH, or sandbox execution access, it does not consume a
 timeout still counts as a bounded review attempt, so the review/fix loop cannot
 run forever.
 
-For Codex, keep `--sandbox workspace-write`; WADE/crossby add only the linked
-worktree's private/common Git metadata directories. Implementation and PR-comment
-sessions have network access by default for their GitHub lifecycle; use
-`--no-network` or `ai.network_access: false` when an offline sandbox is required.
+A reviewer that **never started** — including a sandbox-capability refusal before
+the launch — is recorded as an *unattempted* review so the state is auditable,
+and that record is deliberately inert: it satisfies no review
+requirement, spends no review pass, cannot overwrite a real receipt already
+written for the same commit, and leaves `wade implementation-session done` and
+`wade review-pr-comments-session done` closed. An infrastructure failure must
+never be able to certify a commit. A reviewer that started and exited non-zero
+stays distinguishable from one that never ran, because the two need opposite
+remediation.
+
+For Codex, WADE launches unsandboxed by default so delegated tools keep their
+own host credentials; set `ai.sandbox: true` (or pass `--sandbox`) to keep
+`--sandbox workspace-write`, where WADE/crossby add only the linked worktree's
+private/common Git metadata directories. Every session has network access in
+both profiles for its GitHub lifecycle.
+Standalone `wade review plan`, `wade review implementation`, and `wade review
+batch` runs also accept `--sandbox` / `--no-sandbox`; an inherited-sandbox
+diagnosis gives the host-terminal relaunch command with `--no-sandbox` so it
+overrides an `ai.sandbox: true` configuration. The command also preserves the
+selected review mode, tool, model, effort, permission mode, staged scope, and
+review-skill overrides so the retry reviews the same operation.
 For Claude Code and Cursor, allowlist the worktree/Git metadata paths and only
 the GitHub domains needed by the session rather than choosing unrestricted shell
 access. Copilot and VS Code need network plus usable `gh` credentials in their