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

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

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [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 +426,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.0.0}/KNOWLEDGE.md

@@ -707,3 +707,45 @@ 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.
+
+---

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

@@ -152,3 +152,9 @@
 {"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"}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 0.54.2
+Version: 1.0.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. `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`, `review pr-comments`, 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,115 @@ 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`, `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. So when an accepted plan handoff runs inside a **sandboxed**
+Codex planner and the implementation profile resolves to **unrestricted**, WADE
+starts a fresh detached Codex context rather than reusing the planner process. If
+it cannot open that context, the handoff fails rather than reporting an
+implementation session ready — open a new host terminal and run the displayed
+`wade implement <issue> --no-sandbox` command. When both sessions resolve to the
+same profile there is no mismatch and the ordinary nested-launch guard applies.
+
+The comparison uses the profile the planner **actually launched under**, so a
+`wade plan --sandbox` / `--no-sandbox` override is honored here rather than
+losing out to `ai.plan.sandbox`.
+
+#### 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 +857,11 @@ 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.
+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.
 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

{wade_cli-0.54.2 → wade_cli-1.0.0}/README.md

@@ -240,7 +240,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. `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`, `review pr-comments`, 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
 
@@ -312,7 +312,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:
@@ -653,59 +653,115 @@ 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`, `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. So when an accepted plan handoff runs inside a **sandboxed**
+Codex planner and the implementation profile resolves to **unrestricted**, WADE
+starts a fresh detached Codex context rather than reusing the planner process. If
+it cannot open that context, the handoff fails rather than reporting an
+implementation session ready — open a new host terminal and run the displayed
+`wade implement <issue> --no-sandbox` command. When both sessions resolve to the
+same profile there is no mismatch and the ordinary nested-launch guard applies.
+
+The comparison uses the profile the planner **actually launched under**, so a
+`wade plan --sandbox` / `--no-sandbox` override is honored here rather than
+losing out to `ai.plan.sandbox`.
+
+#### 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
 
@@ -765,10 +821,11 @@ 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.
+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.
 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