@sabaiway/agent-workflow-kit 3.14.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,104 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 4.0.0 — a review receipt must say HOW the code reached the reviewer (AD-078)
+
+**BREAKING, and it costs money to ignore — read the two callouts before upgrading.**
+
+An `agy` code review that never received your change set can no longer produce a receipt that says it
+did — and a read-only review finally has a subagent vehicle that cannot flood you with approval
+prompts.
+
+> **Breaking 1 — existing `agy` code receipts stop attesting.** The reader now requires an `agy` code
+> receipt to declare `delivery`. Receipts written by any earlier bridge lack the field, so
+> `review-state --check` turns RED on a tree that was green before. **Migration: re-run the review.**
+> Nothing else is needed and no receipt file needs editing. This is the same call as kit 2.0.0
+> ([[AD-057]]): the incompatibility is created by the kit READER, so the kit takes the MAJOR alone.
+>
+> **Breaking 2 — the bundled `agy` bridge (5.0.0) changes what an OVERSIZED review COSTS.** It used
+> to refuse and spend nothing. It now DELIVERS the change set as a chunked feed, which spends **N+1
+> subscription turns** instead of one. The count is printed on stderr before the first turn is spent,
+> and `AGY_REVIEW_MAX_TOTAL_BYTES` (default **240000**) refuses the whole run pre-spend when the feed
+> would be larger than that. `AGY_REVIEW_ALLOW_ADDDIR` is retired: still recognized so an existing
+> settings line never warns as unknown, but it arms nothing — clear it with
+> `bridge-settings --unset AGY_REVIEW_ALLOW_ADDDIR --apply`. The bundled `codex` bridge (3.2.0) bounds
+> its repo file map by the same shared helper; for any realistic repo its assembled payload is
+> byte-unchanged.
+
+**Why this exists.** An oversized `agy` review once returned two BLOCKING findings citing lines
+612–767 of a 322-line file, naming functions that exist nowhere in the repository. It arrived as an
+ordinary REWORK verdict with `file:line` citations — indistinguishable, to anyone trusting the
+receipt, from a real review. The old escape hatch pointed the model at a staging file and asked it to
+read it; on a headless host that read is auto-denied, so the lane could return a confident invention
+or an empty SHIP with **no way to tell which**.
+
+**What changed here.** The receipt classifier now requires an `agy` code receipt to declare `delivery`
+— how the change set reached the model. Any well-formed declaration is accepted (the bridge emits
+`inline` or `fed`); what is rejected is SILENCE, because the classifier deliberately ignores wrapper
+versions and an old receipt at an unchanged fingerprint would otherwise still read as attesting.
+**Existing agy code receipts therefore stop satisfying the review-state gate — re-run the review.**
+The check runs after the verdict and grounding arms, so every other receipt class is byte-identical
+to before and a later bad receipt still vetoes an earlier ship.
+
+**The settings surface learned the word "retired".** A manifest entry can now carry a stated
+`retired` reason (validated, never a bare flag): the key stays RECOGNIZED so an existing line never
+starts warning as unknown, the writer refuses a new `--set` while `--unset` still clears it, and the
+reader, `--json`, the status line and the init/upgrade survival check all render it as retired rather
+than current. `AGY_REVIEW_ALLOW_ADDDIR` is the first such key, and the advisor item that used to
+recommend arming it is gone — a checked deletion, since the coverage guard fails on an offer no
+capability claims.
+
+**A read-only review now has a vehicle.** `/agent-workflow-kit agents` places a fourth subagent,
+`review-lens`: an additional independent read-only opinion on code your configured backends have
+already seen. The point is what it lacks — **no `Bash`**. A read-only fan-out sent to a full-tool
+subagent shells out for facts it could have read, and every shelled command is an approval prompt you
+never needed to see; three such floods in one session traced to this one gap, because the cheap
+vehicles are scoped away from review and a review-capable vehicle was always full-tool. The no-shell
+property is now asserted across the whole vehicle set, not one member. The lens never replaces your
+configured review recipe, and it is advisory like every review.
+
+**A deny rung was built for the gate hook, and REMOVED before release — the removal is the result.**
+The hook has exactly one answer for an agent's reflexive `grep … 2>/dev/null`: ask you. So the
+maintainer pays an approval for a decoration, over and over. The fix looked clean: refuse only a
+seeded read-only command that PROVABLY discards its output, since the shell was throwing that output
+away and a refusal could not destroy anything anyone wanted. The argument holds. The byte-level PROOF
+of "this command discards" does not, and could not be made to here — three council rounds produced
+five shell constructs that defeated it: `1<&2` (an fd dup routes stdout back out of `/dev/null` AFTER
+the approved `>`), a quoted literal `>/dev/null ` sitting in an argument, leading-token-only segment
+matching (`… && npm test` runs real work behind the read), a bare `&` (backgrounds the read, runs the
+rest), and a `#` comment (bash never executes that redirect at all). Every one was a FALSE REFUSAL.
+
+The general lesson, now written into the hook's own header: **on an ASK rung an incomplete scan merely
+over-asks, which is safe; on a DENY rung the identical incompleteness refuses real work.** Deciding
+whether a `>` is an operator or text requires lexing the shell, which this dependency-free hook
+deliberately does not do — so a deny rung needs a justification that does not rest on parsing command
+bytes. The hook therefore still **never emits `deny`**, the five counterexamples are kept as the
+specification for whoever attempts it next, and the prompt this was meant to remove is still there.
+Stating that plainly is worth more than shipping a refusal we cannot certify.
+
+## 3.15.0 — a shipped opt-in now advertises itself (AD-076)
+
+`/agent-workflow-kit upgrade` and `recommendations` now offer the closing-block detector that 3.14.0
+shipped.
+
+They did not, and that was the whole defect. 3.14.0 added the detector with a mode doc, a catalog row
+and a README row — every surface an agent reads — and no advisor entry. So a user who installed the
+update and ran `upgrade` was told «nothing is broken — process is optimal» while the capability from
+that very version sat unwired and unmentioned. Both statements were true alone. Together they meant
+the only route to the new feature was reading this file or interrogating the agent.
+
+The new item fires when no `Stop` hook runs the detector's runtime, states what goes unseen without
+it, and carries a hand-apply pointer to the mode doc — there is still no writer for this hook, and the
+doc carries the exact block plus the three merge cases. It matches on the runtime FILE NAME rather
+than an exact command, because with no writer every user pastes their own path: an exact comparison
+would keep nagging someone who already wired it.
+
+The reason this was structurally invited is worth stating. Every other surface of a new mode is
+drift-guarded — omit the `SKILL.md` row, the catalog entry or the mode doc and a test fails. The
+advisor is the one surface with no such guard, and the only one a user receives without asking. The
+guard that would close it needs an accurate claim for all 28 modes, so it is the next slice's first
+item rather than a hurried addition here.
+
 ## 3.14.0 — the closing state block gets a checker (AD-075)
 
 A new opt-in `Stop` hook reads the turn's final assistant message and warns when the closing state

package/README.md

@@ -241,15 +241,15 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit core-evidence` | any time | **the ONE loop-evidence writer** (strip-the-kit) — every core evidence record lands in a single append-only JSONL store inside the git dir (never committable; versioned schema, latest-per-key supersession, byte-identical duplicates refused, malformed lines fail every reader closed). `red-proof "<file>#<pattern>"` declares an observed-red **BEFORE a bugfix** (N/N red runs + content custody + base + the pre-fix fingerprint; green/mixed/timeout are DISTINGUISHED refusals — nothing written); `degrade --backend --reason` is the ONLY escape for an unavailable review backend (per-tree, never all backends); `summary` renders the whole loop state statelessly (gate result · per-backend verdicts · red-proofs · degrades) — no ledger, no rounds, nothing remembered. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
 | `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — makes the commit capture the whole current working tree, so «verified» and «about to be committed» are the same bytes (the receipt itself has a stated residual — see the mode doc). FIRST it refuses an **INDEX that lags the verified working tree** (the gates and the fingerprint describe the WORKING tree while `git commit` takes the INDEX alone, and the fingerprint cannot tell them apart — so a lagging index used to ship a strict subset of what was verified): unstaged tracked paths or reviewable untracked-not-ignored paths, named up to a bounded cap with the remainder stated, a dirty tracked **submodule** named separately with its own recovery, and fail-closed on an undecidable probe. This deliberately blocks a partial commit. Then it binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
-| `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (the sandbox-lane live recipe, or the worktrees-dir hand-apply-first grant advice) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (the sandbox-lane live recipe, the worktrees-dir hand-apply-first grant advice, or the agents hidden-mode reconcile follow-up) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit worktrees` | any time | **parallel feature worktrees** — run several features in DIFFERENT agent sessions on one repo, zero interference on working-tree files (the ONE exception is the dependency cache, below): `provision <slug> --plan <file>` creates a sibling git worktree on branch `aw/<slug>` and populates it (registry-derived footprint copy-if-missing — a tracked file is never overwritten; EXACTLY ONE seeded feature plan; the `handoff-<slug>.md` record from minute zero; `node_modules` symlinked where the link stays ignored — a shared MUTABLE dependency cache: writes through it hit MAIN's node_modules; for isolation run the printed isolated-install command (`--install` only PRINTS it; on `--resume` run the printed unlink-first recovery first); absolute root-pinned gate commands rebased on untracked copies only, and only while their bytes equal the MAIN source or its rebased form — user-modified copies stay untouched); `list` is read-only (slug, branch, base, dirty, handoff); `land <slug> --prepare` locks the common git dir, fail-closes on divergence or incomplete satellite state, transfers the complete accepted satellite diff onto a CLEAN main, runs sync plus the declared gates, and reports HEAD/TRANSFER/PREPARED OIDs — the commit ALWAYS stays a dialogue ask; `cleanup <slug>` takes the same lock and removes a LANDED worktree only after live landed-verification against main HEAD, while `--abandon` is the ONE destructive arm (destroys unlanded work; **no preview step** on any writer). The parent dir is the `docs/ai/worktrees.json` `parentDir` setting (default: the repo's sibling parent); an unwritable parent degrades to printed maintainer-pasted commands, and the one-time host consent that makes it promptless surfaces via `recommendations`. Never commits, never pushes, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
-| `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
+| `/agent-workflow-kit agents` | Claude Code · opt-in | **read-only subagents** — places bundled subagent definitions into `.claude/agents/`. **No vehicle gets `Bash`**, and that is the load-bearing property: a read-only fan-out on a full-tool subagent shells out for facts it could have read, and every shelled command is an approval prompt you never needed to see. Three ride a **cheap model** (haiku, low effort) for mechanical work — extraction sweeps, changelog fact-skeletons, gate-failure triage; the fourth, **`review-lens`**, is an ADDITIONAL independent read-only review opinion on code your configured backends have already seen (never a replacement for your review recipe, advisory like every review). Writing code and running gates stay on your main lane, and every vehicle's output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
 | `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. An opt-in **read-lane** (`--read-lane` → `docs/ai/lanes.json`, a **separate** file from `gates.json`) additionally auto-approves *compounds* of seeded read-only commands carrying no shell metaprogramming; `--apply --read-lane` verifies the placed hook is current first (delete-to-reseed otherwise). Preview by default; never writes `settings.local.json`; never commits. |
 | `/agent-workflow-kit state-block-guard` | Claude Code · opt-in | **closing-block detector** — a `Stop` hook that reads the turn's final assistant message and warns when the closing state block is defective: the «what I need from you» slot answering *nothing* (a turn that ENDS always needs a resume, so the answer is false, not merely unhelpful), or a first-person promise of imminent work in a turn that is over. Judged on the slot's first clause, so a real ask followed by a clause break and "nothing else" passes, and a promise gated on something named passes; matching is word-bounded and Unicode-aware, quoted and fenced examples are stripped, and the last STARTED block decides — an incomplete tail counts as no block rather than falling back to an earlier one. A message carrying no block at all is silent unless you pass `--require-block` — this kit does not mandate the block, and a hook that runs every turn must not warn every turn. The judgement is lexical and the mode doc names every residual it leaves. **Detection, never prevention** — a `Stop` hook cannot un-send the message it judges; what it buys is that a silent recurrence becomes a visible one. Warns via `systemMessage` and **exits 0 on every path**: never `deny`, never blocks the stop, never re-enters the model. Reads nothing but the message, makes no network call, approves nothing. This mode is **read-only and has no writer** — it ships the self-contained hook and a paste-ready wiring block you merge into `.claude/settings.json` yourself. |
-| `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the review byte cap, the oversized-review add-dir toggle. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the codex review byte cap, and `AGY_REVIEW_MAX_TOTAL_BYTES` (the ceiling on what an oversized agy code review may feed before it refuses pre-spend). `AGY_REVIEW_ALLOW_ADDDIR` is a **retired** compatibility key: still recognized so an existing line never warns as unknown, but it arms nothing — the writer refuses to set it and `--unset` clears it. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit autonomy-doctor` | opt-in, any time | **guarded sandbox provisioner "doctor"** — can this machine run the Claude sandbox, and (only with your consent) fix it: macOS Seatbelt built-in / Linux+WSL2 needs `bwrap`+`socat` / native Windows → WSL2. Flagless = **FS-only preview** (the diagnosis, the exact absolute-path command it WOULD run, the exact `--apply <pm>:<pkgs>` consent tuple — runs nothing, never claims ready); `--verify` runs the unprivileged proof (a `bwrap` user-namespace smoke + `socat -V`) — the **only** source of a Linux "ready (verified)" claim; `--apply <pm>:<pkgs>` is the consent-gated privileged install (the tuple must equal the previewed plan; everything executed resolves to absolute paths inside `/usr/bin:/bin:/usr/sbin:/sbin`; the exact command is re-printed immediately before execution), then verifies. Honest loud degrades (unknown PM, untrusted location, nested-sandbox INDETERMINATE, root-unproven) and a stated restart step. Sits **outside every velocity auto-approve tier**; never auto-runs, never writes repo files, never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.14.0'
+  version: '4.0.0'
 ---
 
 # agent-workflow-kit

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '4.1.0'
+  version: '5.0.0'
 ---
 
 # antigravity-cli-bridge
@@ -86,7 +86,7 @@ agy-run @path/to/prompt.md                    # prompt from a file
 AGY_MODEL="Claude Opus 4.6 (Thinking)" agy-run "..."   # pick a model
 AGY_TIMEOUT=10m agy-run "..."                 # agy's soft --print-timeout
 AGY_HARD_TIMEOUT=8m agy-run "..."             # hard wall-clock cap via timeout(1)
-agy-run "..." -- --add-dir . --dangerously-skip-permissions   # passthrough agy flags
+agy-run "..." -- --add-dir .                  # passthrough agy flags (never a permission widener)
 ```
 
 `agy` is **headless-only** here (`-p`/`--print`) and there is **no JSON output mode** in v1.0.13 — you
@@ -101,9 +101,11 @@ after `--`. Full detail: [`references/models-and-flags.md`](references/models-an
 `${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` holds `KEY=VALUE` lines,
 **parsed, never sourced** — a file line can never execute code. Precedence: explicit env (even
 empty — `KEY=` disables a knob for one run) > file > built-in default. File-settable keys for this
-bridge: `AGY_HARD_TIMEOUT` (duration string, e.g. `5m`/`30m`) and `AGY_REVIEW_ALLOW_ADDDIR`
-(`0`/`1`; arming the oversized `--add-dir` escape re-enables the Issue-001 stall risk — the hard
-timeout bounds it) — exactly the manifest `settings` block (the single source; the wrapper
+bridge: `AGY_HARD_TIMEOUT` (duration string, e.g. `5m`/`30m`) and `AGY_REVIEW_MAX_TOTAL_BYTES`
+(integer bytes, default `240000` — the ceiling on the SUM of all outgoing prompt bytes an oversized
+`code` review may feed). `AGY_REVIEW_ALLOW_ADDDIR` is **RETIRED**: still recognized so an existing
+line never warns as unknown, but it arms nothing — the writer refuses a new `--set` and `--unset`
+clears it — exactly the manifest `settings` block (the single source; the wrapper
 constants and `--help` are drift-guarded against it). Model keys are **not** file-settable. The
 file lives **outside every kit-managed tree**, so a kit refresh/upgrade can never wipe it; edit it
 by hand or via `/agent-workflow-kit bridge-settings` (preview-first, consent-gated).
@@ -142,9 +144,11 @@ hands to `timeout(1)`, or `uncapped`) — informational, never a receipt field.
 banner verbatim** when labeling a dispatch.
 
 Frontier default `Gemini 3.1 Pro (High)`; **any** model is allowed (a sub-frontier one earns a
-silenceable `AGY_PROBE=1` advisory). An oversized `code` review trips the byte ceiling with trim/split
-guidance; `AGY_REVIEW_ALLOW_ADDDIR=1` offloads only the change set to a private `--add-dir` staging dir
-(grounding stays inline). The service can still **stall on large/substantive prompts** (Issue-001) — keep
+silenceable `AGY_PROBE=1` advisory). An oversized `code` review is **DELIVERED, not refused**: the
+change set is cut into under-cap parts, fed over continuation turns and reviewed in a final turn, and
+the answer must reproduce a line the wrapper picked from each part — a missing or wrong echo is a
+FAILED review (`exit 4`, no receipt). `plan`/`diff` still refuse over the cap (their artifact is a
+file the operator can split). The service can still **stall on large/substantive prompts** (Issue-001) — keep
 reviews **focused**; the inherited hard timeout is the guard. Full playbook:
 [`references/driving-agy.md`](references/driving-agy.md).