wade-cli 1.2.2__tar.gz → 1.2.5__tar.gz

{wade_cli-1.2.2 → wade_cli-1.2.5}/.gitignore

@@ -44,8 +44,7 @@ PR-SUMMARY.md
 .DS_Store
 Thumbs.db
 
-# uv
-uv.lock
+# uv.lock is tracked for the published Crossby contract (#511).
 
 # Local archive (pre-reset export)
 archive/

{wade_cli-1.2.2 → wade_cli-1.2.5}/AGENTS.md

@@ -92,6 +92,16 @@ No circular dependencies. Models are pure data. Services orchestrate. **Never im
 
 AI tool adapters are not part of this repo — they live in the external [`crossby`](https://github.com/ivanviragine/crossby) package (`pyproject.toml`). See `docs/dev/architecture.md` for what moved there.
 
+Native planning prefers Crossby's ordinary interactive launch with native Plan
+mode and supported approval flags. For deferred startup (currently Codex), WADE
+handles Crossby's typed ready/submitted events and sends the task exactly once;
+Crossby owns `/plan` and terminal mechanics. The public collected-session API
+remains the fallback for adapters without terminal Plan support. WADE owns explicit file/stdin
+handoff, review receipts bound to current content and frozen skills, validation,
+knowledge handoff, and task persistence; native flags/protocols stay upstream.
+Update the tracked `uv.lock` and Crossby contract tripwire with dependency
+adoptions. Native plans are not transcripts; never scrape tool storage to find them.
+
 CLI modules are thin dispatch — they parse flags via Typer, then call service methods. Business logic lives in `services/`, not in `cli/`.
 
 > Full package structure, command dispatch, config system, and subsystem details: see `docs/dev/architecture.md`

{wade_cli-1.2.2 → wade_cli-1.2.5}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v1.2.5] — 2026-09-16
+
+### Bug Fixes
+
+- launch Codex native UI with deferred prompt delivery (#514) (8424a77)
+
+## [v1.2.4] — 2026-09-16
+
+### Bug Fixes
+
+- restore native interactive planning for CLI tools (#513) (51ec787)
+
+## [v1.2.3] — 2026-09-15
+
+### Bug Fixes
+
+- integrate Crossby native planning sessions (#512) (c58ea77)
+
 ## [v1.2.2] — 2026-09-09
 
 ### Bug Fixes

{wade_cli-1.2.2 → wade_cli-1.2.5}/CONTRIBUTING.md

@@ -17,6 +17,10 @@ cd wade
 uv pip install -e ".[dev]"
 ```
 
+`uv.lock` is tracked for reproducible dependency validation. When adopting a
+Crossby release, update the declaration, lockfile and contract tripwire together;
+use `uv sync --all-extras` to verify the installed release without a local override.
+
 ## Running Checks
 
 > Always use the scripts — never invoke `pytest`, `mypy`, or `ruff` directly.
@@ -28,7 +32,7 @@ uv pip install -e ".[dev]"
 | `./scripts/check.sh` | Lint + type-check |
 | `./scripts/check.sh --lint` | Lint only |
 | `./scripts/check.sh --types` | mypy strict only |
-| `./scripts/fmt.sh` | Auto-format in-place |
+| `./scripts/fmt.sh [paths...]` | Auto-format selected paths (default: `src/`) |
 | `./scripts/check-all.sh` | Full suite (tests + lint + types) |
 
 ## Architecture

{wade_cli-1.2.2 → wade_cli-1.2.5}/KNOWLEDGE.ratings.jsonl

@@ -178,3 +178,15 @@
 {"dir": "stale", "event_id": "5fd6f7c8f26544249827eacae223694a", "id": "4d5fa933ffe6", "ts": "2026-09-08T18:20:11.796646+00:00"}
 {"dir": "stale", "event_id": "e4417aa5f0064b3f9c7e47f3fdae4ffe", "id": "8a9bfc96", "ts": "2026-09-08T19:15:19.450727+00:00"}
 {"dir": "stale", "event_id": "647e662229b04eb19f5a337d2c0a1d27", "id": "4d419ec6629c", "ts": "2026-09-08T19:15:19.602521+00:00"}
+{"dir": "stale", "event_id": "d8b30c93957946b087bc118cf807859d", "id": "9f5e5e2c", "ts": "2026-09-15T12:40:24.351399+00:00"}
+{"dir": "stale", "event_id": "23483fb102fb45a2bf60fbcb862110bd", "id": "2112b028ab73", "ts": "2026-09-15T12:40:24.525550+00:00"}
+{"dir": "stale", "event_id": "857f1e42499144c5a2b7a7c44a277de9", "id": "c55057c13ebb", "ts": "2026-09-15T12:40:24.692975+00:00"}
+{"dir": "up", "event_id": "79659f3434bd4bc8bf0e1dae2deae918", "id": "cb42b47b0a78", "ts": "2026-09-15T12:40:24.859865+00:00"}
+{"dir": "up", "event_id": "d41302d8d7844cc1bf6008fb9e6b1b81", "id": "8ee8260b", "ts": "2026-09-15T12:40:25.034740+00:00"}
+{"dir": "up", "event_id": "56ccbf428f61455292ebe28e7f6a5884", "id": "d7e3010043a2", "ts": "2026-09-15T12:40:25.199085+00:00"}
+{"dir": "up", "event_id": "613813c3b5e24b75ab9b5296a35ada5f", "id": "9eacd93219c1", "ts": "2026-09-15T12:40:25.361743+00:00"}
+{"dir": "up", "event_id": "d0fbb52cfa63456d81d455a83b7d0288", "id": "9f5e5e2c", "ts": "2026-09-15T15:24:18.473921+00:00"}
+{"dir": "up", "event_id": "4cc96512911d4170b894daf7e3b8ffae", "id": "97d81e85", "ts": "2026-09-15T15:24:18.626569+00:00"}
+{"dir": "up", "event_id": "66056751a7824f6bb780f4974e2e2d7d", "id": "b08abb58", "ts": "2026-09-15T15:24:18.781881+00:00"}
+{"dir": "up", "event_id": "86b45a2f2bf74f0c8736e3ce9c7a7642", "id": "40a26d7cfd61", "ts": "2026-09-15T15:24:18.938217+00:00"}
+{"dir": "stale", "event_id": "86da7ec333234953869f880b857ce682", "id": "6cd9b543", "ts": "2026-09-15T15:24:19.088735+00:00"}

{wade_cli-1.2.2 → wade_cli-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 1.2.2
+Version: 1.2.5
 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.30.0,>=0.29.0
+Requires-Dist: crossby<0.34.0,>=0.33.0
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0
@@ -209,8 +209,8 @@ wade plan ─▶ tasks + draft PRs ─▶ wade <N> ─▶ AI implements in an is
   `wade review pr-comments <N>`, and `wade cd <N>`.
 - **The AI runs** the session commands that enforce the workflow and open/update
   the PR: `wade implementation-session {check,sync,done}`,
-  `wade review-pr-comments-session {check,sync,done,fetch,resolve}`, and
-  `wade plan-session done`.
+  `wade review-pr-comments-session {check,sync,done,fetch,resolve}`. Native
+  planning returns an artifact; the parent runs its review and validation gates.
 
 ## Commands
 
@@ -273,19 +273,76 @@ These are invoked by the AI during a session — you normally don't run them by
 | `wade review-pr-comments-session fetch <N>` | Fetch unresolved PR review comments as markdown |
 | `wade review-pr-comments-session resolve <thread>` | Mark a PR review thread as resolved on GitHub |
 | `wade plan-session check` | Verify detached planning capabilities before writing plan artefacts or knowledge votes |
-| `wade plan-session done <plan_dir>` | Finalize a planning session |
+| `wade plan-session done <plan_dir>` | Import an optional native plan (`--from-file` / `--from-stdin`), validate, and complete the reviewed handoff |
 | `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. `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
 
-`wade plan` runs an AI planning session and then, from the validated plan files
-it produces, creates a lightweight task plus a draft PR for each one (labeled by
-complexity). Plan files are **strictly validated** before they become tasks — a
-`PLAN*.md` missing a valid `## Complexity` or a conventional-commit title is
-dropped with a loud error rather than silently becoming a task with no complexity
-label.
+`wade plan` launches **Claude, Cursor, Copilot, OpenCode, Antigravity CLI, and Codex**
+in their own interactive terminal, with **native Plan mode active before the
+first task turn**. You keep the tool's UI, questions, and conversation. Crossby
+validates native support and translates approval flags. For Codex, Crossby
+submits `/plan` first and WADE sends the task on its ready event. Native questions
+and subsequent interaction stay in the tool.
+
+Use `--permission-mode` (or `--yolo`) for the native approval policy:
+
+| CLI | Supported modes while planning |
+|-----|--------------------------------|
+| Claude | `default`, `auto`, `yolo` |
+| Cursor | `default`, `auto`, `yolo` |
+| Copilot | `default`, `accept-edits`, `yolo` |
+| OpenCode | `default`, `yolo` |
+| Antigravity CLI | `default`, `yolo` |
+| Codex CLI | `default`, `accept-edits`, `auto`, `yolo` |
+
+Unsupported combinations fail before creating a planning worktree. These are
+native approval settings, not permission to implement the plan. The later
+implementation offer still requires an explicit decision.
+
+Where the tool supports a native output-directory setting (Claude), WADE uses
+`.wade/plans/native/`. Other tools can keep their native location. Before exit, the planning
+workflow submits it with `wade plan-session done .wade/plans --from-file <path>`;
+`--from-stdin` accepts explicit Markdown when no file is available. WADE writes
+its canonical copies. `wade review plan <file>` reviews those copies inside the
+session; prompt-mode review emits the frozen method and requires actual
+self-review followed by `--ack-self-review`. Run `done` again after review.
+Changed content requires a current review before completion. A missing-review
+error on the first import means the file was imported and awaits review.
+
+One task can be plain Markdown (`# feat: title`, `## Complexity`, tasks and
+acceptance criteria). Multiple tasks use the explicit versioned
+[plan bundle contract](templates/workflows/reference/plan-output-contract.md),
+with filenames and `depends_on` relationships; headings do not imply task
+boundaries. Knowledge-enabled sessions include `knowledge_votes` in that bundle,
+including an explicit empty list when appropriate. The parent revalidates the
+completed handoff after exit, then creates tasks and draft PRs. Failed or missing
+handoffs retain output and create no tasks.
+
+**Codex requires CLI 0.154.x and a POSIX terminal (macOS/Linux).** Crossby's
+current startup adapter waits for the rendered Plan indicator before WADE sends
+the initial task; unknown versions or an unrecognized startup screen fail
+without retrying the task. This temporary terminal adapter can be replaced by a
+native launch flag when Codex provides one. WADE requires the task-submitted
+event before collecting the explicit reviewed handoff. Codex can submit plan
+Markdown through `--from-stdin`; no native file destination is assumed.
+
+All native terminals now use the ordinary sandbox default (off), including Codex;
+use `--sandbox` or `ai.plan.sandbox: true` to retain confinement. The retained
+collector fallback has its own safe default (on). Explicit `--sandbox`, `--network-access` /
+`--no-network-access`, and `--trusted-dir` require support from the selected tool.
+No network flag adds no network grant and does not promise isolation.
+`--approval-policy on-request|untrusted|never` and `--timeout` are collector
+settings; interactive terminals use `--permission-mode` and have no time limit.
+Set `ai.plan.mode` to `interactive` or leave it unset for native terminals.
+GUI launchers remain unsupported for planning.
+
+Authentication, model availability, and successful handoff are runtime checks.
+Native terminal output is retained for recovery; usage is reported only when
+the adapter can extract it from that output. WADE's handoff ID is not a native
+CLI session ID.
 
 `wade plan --issue <N>` re-plans an existing task. If the session produces a
 single plan file, it's attached to `#N` and the task stays open. If the
@@ -296,8 +353,6 @@ per plan file, a comment and a `> **Superseded by ...**` banner are added to
 `--yolo`/non-interactive). If any plan file fails to become a task, `#N` is
 left open with a warning instead of superseding on a partial split.
 
-Antigravity CLI (`agy`) planning sessions launch in normal file-writing mode within a guarded git planning worktree rather than `agy`'s native `--mode plan` (which sandboxes writes to its own per-conversation artifact store outside the worktree). WADE's plan-artifact guard strictly confines writes to `.wade/plans/` and scratch paths, preserving planning safety while generating real plan files. Antigravity CLI planning therefore requires a guarded git planning worktree.
-
 ### Base branch
 
 By default WADE branches from and merges into the project's configured main branch (`project.main_branch` in `.wade.yml`, falling back to the repo's detected default). To target a different branch — e.g. `develop` or a `release/*` branch — declare it once, at planning time, in an optional `## Base Branch` section of the plan file:
@@ -497,16 +552,17 @@ enough to pick up improvements, with no re-init or migration.
 | Worktree containment | Writes that land outside your worktree |
 | Plan-artifact | During `wade plan`, writes to anything but plan artifacts |
 | Session completion | Finishing an implement/review session with unfinished work not yet run through `done` (nudges once) |
-| Plan completion | Finishing a `wade plan` session that produced no valid `PLAN*.md` yet (nudges once) |
+| Native plan completion (parent gate) | Creating tasks before authoritative import, review, and strict plan validation |
 
 The session-completion guard keys on the same fact `done` records — a sha-keyed
 `.wade/done@<HEAD>` marker written when `done`'s gates pass — so it nudges only
 when the branch has commits ahead of its base **and** `done` has not finalized
 the current commit. An early "stopping to ask a question" turn (no commits ahead)
-never triggers it. The plan-completion guard is the planning counterpart: it
-nudges once if a plan session is about to end with no valid plan file (a title
-with a conventional-commit prefix plus a `## Complexity`). Both fail **open** — a
-session is never trapped.
+never triggers it. This Stop nudge fails **open**. Native planning does not
+install the old file-based Stop nudge. Interactive sessions explicitly import,
+review, and complete their plans before exit; the parent revalidates them. Codex
+retains parent-side collection and review. Native transports may differ in hook
+support; completion does not depend on hooks firing.
 
 Independently of that nudge, `wade plan` now **strictly validates** plan files
 before creating tasks: a `PLAN*.md` missing a valid `## Complexity` or a
@@ -530,8 +586,8 @@ the label never fails task creation, and a body with no `## Complexity` section
 just skips it. An explicit `--label complexity:X` takes precedence over the body
 value, so the task never ends up with two conflicting complexity labels.
 
-If some files pass and others fail, an interactive run asks whether to continue
-with the valid ones; `--yolo` and non-interactive runs continue without asking.
+If some files pass and others fail, a human must explicitly accept a
+dependency-closed valid subset, even with `--yolo`. Noninteractive runs abort.
 If you decline, or if every plan file fails validation, no tasks are created —
 the generated `PLAN*.md` are preserved to a temp directory so you can fix the
 reported errors and re-run instead of regenerating from scratch.
@@ -652,6 +708,10 @@ Description body here. Sub-headings, code blocks, anything markdown.
 
 ### Permission modes
 
+These autonomy tiers apply to ordinary launches and supported native Plan
+terminals. Codex planning retains parent-only default/YOLO with a separate
+collector approval policy, as described above.
+
 `--permission-mode` sets how much autonomy the AI tool is granted — an axis
 independent of the delegation `--mode` (which controls *how* a tool is
 dispatched: prompt/interactive/headless). The tiers, most→least permissive, are
@@ -661,16 +721,17 @@ dispatched: prompt/interactive/headless). The tiers, most→least permissive, ar
 |------|----------|
 | `default` | Prompt for every action (no autonomy grant). |
 | `accept-edits` | Auto-apply file edits; still prompt for shell/commands. Claude and Antigravity CLI. |
-| `auto` | Classifier-mediated auto mode (a model reviews each non-read action). Claude only. |
+| `auto` | Classifier-mediated auto mode (a model reviews each non-read action). Claude and Cursor. |
 | `yolo` | Full autonomy — no prompts. |
 
 `--yolo` is a back-compat alias for `--permission-mode yolo`; an explicit
 `--permission-mode` wins when both are given. The same values are accepted in
 `.wade.yml` as `ai.permission_mode` (global) or `ai.<command>.permission_mode`
 (per-command), with `yolo: true` still honored as the alias. A tier a tool
-doesn't support is downgraded automatically (e.g. `auto` → `accept-edits` on
-non-Claude tools) with a warning — WADE forwards the requested tier and
-[`crossby`](https://github.com/ivanviragine/crossby) owns the downgrade ladder.
+doesn't support is downgraded automatically for ordinary launches (for example,
+`auto` → `accept-edits` when classifier auto is unavailable), with a warning — WADE forwards the requested tier and
+[`crossby`](https://github.com/ivanviragine/crossby) owns the downgrade ladder. Native Plan combinations are validated strictly and
+rejected if unsupported.
 **Headless launches are always read-only** — any of `deps` /
 `review_plan` / `review_implementation` / `review_batch` dispatched in headless
 delegation mode runs at `default` regardless of the configured tier, and no
@@ -713,6 +774,9 @@ failure feedback, and any truncation is labeled.
 
 ### AI runtime sandbox profile
 
+The defaults below apply to **non-plan launches**. Native planning uses the
+independent request policies described in [Planning & base branches](#planning--base-branches).
+
 `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).
@@ -722,9 +786,9 @@ runtime boundary only — it never relaxes WADE's own guards (see below).
 | `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
+Network access is **on in both non-plan profiles** and is not configurable for
+ordinary launches. Not every phase needs it (dependency analysis does not),
+but the phases that do — `git
 fetch`/`push`, `gh`, package installs — cannot work without it, and the profile
 is fixed at launch.
 

{wade_cli-1.2.2 → wade_cli-1.2.5}/README.md

@@ -173,8 +173,8 @@ wade plan ─▶ tasks + draft PRs ─▶ wade <N> ─▶ AI implements in an is
   `wade review pr-comments <N>`, and `wade cd <N>`.
 - **The AI runs** the session commands that enforce the workflow and open/update
   the PR: `wade implementation-session {check,sync,done}`,
-  `wade review-pr-comments-session {check,sync,done,fetch,resolve}`, and
-  `wade plan-session done`.
+  `wade review-pr-comments-session {check,sync,done,fetch,resolve}`. Native
+  planning returns an artifact; the parent runs its review and validation gates.
 
 ## Commands
 
@@ -237,19 +237,76 @@ These are invoked by the AI during a session — you normally don't run them by
 | `wade review-pr-comments-session fetch <N>` | Fetch unresolved PR review comments as markdown |
 | `wade review-pr-comments-session resolve <thread>` | Mark a PR review thread as resolved on GitHub |
 | `wade plan-session check` | Verify detached planning capabilities before writing plan artefacts or knowledge votes |
-| `wade plan-session done <plan_dir>` | Finalize a planning session |
+| `wade plan-session done <plan_dir>` | Import an optional native plan (`--from-file` / `--from-stdin`), validate, and complete the reviewed handoff |
 | `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. `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
 
-`wade plan` runs an AI planning session and then, from the validated plan files
-it produces, creates a lightweight task plus a draft PR for each one (labeled by
-complexity). Plan files are **strictly validated** before they become tasks — a
-`PLAN*.md` missing a valid `## Complexity` or a conventional-commit title is
-dropped with a loud error rather than silently becoming a task with no complexity
-label.
+`wade plan` launches **Claude, Cursor, Copilot, OpenCode, Antigravity CLI, and Codex**
+in their own interactive terminal, with **native Plan mode active before the
+first task turn**. You keep the tool's UI, questions, and conversation. Crossby
+validates native support and translates approval flags. For Codex, Crossby
+submits `/plan` first and WADE sends the task on its ready event. Native questions
+and subsequent interaction stay in the tool.
+
+Use `--permission-mode` (or `--yolo`) for the native approval policy:
+
+| CLI | Supported modes while planning |
+|-----|--------------------------------|
+| Claude | `default`, `auto`, `yolo` |
+| Cursor | `default`, `auto`, `yolo` |
+| Copilot | `default`, `accept-edits`, `yolo` |
+| OpenCode | `default`, `yolo` |
+| Antigravity CLI | `default`, `yolo` |
+| Codex CLI | `default`, `accept-edits`, `auto`, `yolo` |
+
+Unsupported combinations fail before creating a planning worktree. These are
+native approval settings, not permission to implement the plan. The later
+implementation offer still requires an explicit decision.
+
+Where the tool supports a native output-directory setting (Claude), WADE uses
+`.wade/plans/native/`. Other tools can keep their native location. Before exit, the planning
+workflow submits it with `wade plan-session done .wade/plans --from-file <path>`;
+`--from-stdin` accepts explicit Markdown when no file is available. WADE writes
+its canonical copies. `wade review plan <file>` reviews those copies inside the
+session; prompt-mode review emits the frozen method and requires actual
+self-review followed by `--ack-self-review`. Run `done` again after review.
+Changed content requires a current review before completion. A missing-review
+error on the first import means the file was imported and awaits review.
+
+One task can be plain Markdown (`# feat: title`, `## Complexity`, tasks and
+acceptance criteria). Multiple tasks use the explicit versioned
+[plan bundle contract](templates/workflows/reference/plan-output-contract.md),
+with filenames and `depends_on` relationships; headings do not imply task
+boundaries. Knowledge-enabled sessions include `knowledge_votes` in that bundle,
+including an explicit empty list when appropriate. The parent revalidates the
+completed handoff after exit, then creates tasks and draft PRs. Failed or missing
+handoffs retain output and create no tasks.
+
+**Codex requires CLI 0.154.x and a POSIX terminal (macOS/Linux).** Crossby's
+current startup adapter waits for the rendered Plan indicator before WADE sends
+the initial task; unknown versions or an unrecognized startup screen fail
+without retrying the task. This temporary terminal adapter can be replaced by a
+native launch flag when Codex provides one. WADE requires the task-submitted
+event before collecting the explicit reviewed handoff. Codex can submit plan
+Markdown through `--from-stdin`; no native file destination is assumed.
+
+All native terminals now use the ordinary sandbox default (off), including Codex;
+use `--sandbox` or `ai.plan.sandbox: true` to retain confinement. The retained
+collector fallback has its own safe default (on). Explicit `--sandbox`, `--network-access` /
+`--no-network-access`, and `--trusted-dir` require support from the selected tool.
+No network flag adds no network grant and does not promise isolation.
+`--approval-policy on-request|untrusted|never` and `--timeout` are collector
+settings; interactive terminals use `--permission-mode` and have no time limit.
+Set `ai.plan.mode` to `interactive` or leave it unset for native terminals.
+GUI launchers remain unsupported for planning.
+
+Authentication, model availability, and successful handoff are runtime checks.
+Native terminal output is retained for recovery; usage is reported only when
+the adapter can extract it from that output. WADE's handoff ID is not a native
+CLI session ID.
 
 `wade plan --issue <N>` re-plans an existing task. If the session produces a
 single plan file, it's attached to `#N` and the task stays open. If the
@@ -260,8 +317,6 @@ per plan file, a comment and a `> **Superseded by ...**` banner are added to
 `--yolo`/non-interactive). If any plan file fails to become a task, `#N` is
 left open with a warning instead of superseding on a partial split.
 
-Antigravity CLI (`agy`) planning sessions launch in normal file-writing mode within a guarded git planning worktree rather than `agy`'s native `--mode plan` (which sandboxes writes to its own per-conversation artifact store outside the worktree). WADE's plan-artifact guard strictly confines writes to `.wade/plans/` and scratch paths, preserving planning safety while generating real plan files. Antigravity CLI planning therefore requires a guarded git planning worktree.
-
 ### Base branch
 
 By default WADE branches from and merges into the project's configured main branch (`project.main_branch` in `.wade.yml`, falling back to the repo's detected default). To target a different branch — e.g. `develop` or a `release/*` branch — declare it once, at planning time, in an optional `## Base Branch` section of the plan file:
@@ -461,16 +516,17 @@ enough to pick up improvements, with no re-init or migration.
 | Worktree containment | Writes that land outside your worktree |
 | Plan-artifact | During `wade plan`, writes to anything but plan artifacts |
 | Session completion | Finishing an implement/review session with unfinished work not yet run through `done` (nudges once) |
-| Plan completion | Finishing a `wade plan` session that produced no valid `PLAN*.md` yet (nudges once) |
+| Native plan completion (parent gate) | Creating tasks before authoritative import, review, and strict plan validation |
 
 The session-completion guard keys on the same fact `done` records — a sha-keyed
 `.wade/done@<HEAD>` marker written when `done`'s gates pass — so it nudges only
 when the branch has commits ahead of its base **and** `done` has not finalized
 the current commit. An early "stopping to ask a question" turn (no commits ahead)
-never triggers it. The plan-completion guard is the planning counterpart: it
-nudges once if a plan session is about to end with no valid plan file (a title
-with a conventional-commit prefix plus a `## Complexity`). Both fail **open** — a
-session is never trapped.
+never triggers it. This Stop nudge fails **open**. Native planning does not
+install the old file-based Stop nudge. Interactive sessions explicitly import,
+review, and complete their plans before exit; the parent revalidates them. Codex
+retains parent-side collection and review. Native transports may differ in hook
+support; completion does not depend on hooks firing.
 
 Independently of that nudge, `wade plan` now **strictly validates** plan files
 before creating tasks: a `PLAN*.md` missing a valid `## Complexity` or a
@@ -494,8 +550,8 @@ the label never fails task creation, and a body with no `## Complexity` section
 just skips it. An explicit `--label complexity:X` takes precedence over the body
 value, so the task never ends up with two conflicting complexity labels.
 
-If some files pass and others fail, an interactive run asks whether to continue
-with the valid ones; `--yolo` and non-interactive runs continue without asking.
+If some files pass and others fail, a human must explicitly accept a
+dependency-closed valid subset, even with `--yolo`. Noninteractive runs abort.
 If you decline, or if every plan file fails validation, no tasks are created —
 the generated `PLAN*.md` are preserved to a temp directory so you can fix the
 reported errors and re-run instead of regenerating from scratch.
@@ -616,6 +672,10 @@ Description body here. Sub-headings, code blocks, anything markdown.
 
 ### Permission modes
 
+These autonomy tiers apply to ordinary launches and supported native Plan
+terminals. Codex planning retains parent-only default/YOLO with a separate
+collector approval policy, as described above.
+
 `--permission-mode` sets how much autonomy the AI tool is granted — an axis
 independent of the delegation `--mode` (which controls *how* a tool is
 dispatched: prompt/interactive/headless). The tiers, most→least permissive, are
@@ -625,16 +685,17 @@ dispatched: prompt/interactive/headless). The tiers, most→least permissive, ar
 |------|----------|
 | `default` | Prompt for every action (no autonomy grant). |
 | `accept-edits` | Auto-apply file edits; still prompt for shell/commands. Claude and Antigravity CLI. |
-| `auto` | Classifier-mediated auto mode (a model reviews each non-read action). Claude only. |
+| `auto` | Classifier-mediated auto mode (a model reviews each non-read action). Claude and Cursor. |
 | `yolo` | Full autonomy — no prompts. |
 
 `--yolo` is a back-compat alias for `--permission-mode yolo`; an explicit
 `--permission-mode` wins when both are given. The same values are accepted in
 `.wade.yml` as `ai.permission_mode` (global) or `ai.<command>.permission_mode`
 (per-command), with `yolo: true` still honored as the alias. A tier a tool
-doesn't support is downgraded automatically (e.g. `auto` → `accept-edits` on
-non-Claude tools) with a warning — WADE forwards the requested tier and
-[`crossby`](https://github.com/ivanviragine/crossby) owns the downgrade ladder.
+doesn't support is downgraded automatically for ordinary launches (for example,
+`auto` → `accept-edits` when classifier auto is unavailable), with a warning — WADE forwards the requested tier and
+[`crossby`](https://github.com/ivanviragine/crossby) owns the downgrade ladder. Native Plan combinations are validated strictly and
+rejected if unsupported.
 **Headless launches are always read-only** — any of `deps` /
 `review_plan` / `review_implementation` / `review_batch` dispatched in headless
 delegation mode runs at `default` regardless of the configured tier, and no
@@ -677,6 +738,9 @@ failure feedback, and any truncation is labeled.
 
 ### AI runtime sandbox profile
 
+The defaults below apply to **non-plan launches**. Native planning uses the
+independent request policies described in [Planning & base branches](#planning--base-branches).
+
 `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).
@@ -686,9 +750,9 @@ runtime boundary only — it never relaxes WADE's own guards (see below).
 | `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
+Network access is **on in both non-plan profiles** and is not configurable for
+ordinary launches. Not every phase needs it (dependency analysis does not),
+but the phases that do — `git
 fetch`/`push`, `gh`, package installs — cannot work without it, and the profile
 is fixed at launch.