brainclaw 1.15.0 → 1.17.0

package/dist/facts.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.15.0",
-  "generated_at": "2026-07-15T15:24:46.074Z",
+  "version": "1.17.0",
+  "generated_at": "2026-07-19T20:01:41.172Z",
   "tools": {
     "count": 67,
-    "published_count": 66,
+    "published_count": 65,
     "names": [
       "bclaw_bootstrap",
       "bclaw_release_notes",
@@ -75,7 +75,7 @@
     ]
   },
   "entities": {
-    "count": 17,
+    "count": 18,
     "names": [
       "plan",
       "step",
@@ -93,6 +93,7 @@
       "assignment",
       "agent_run",
       "action",
+      "agent",
       "cross_project_link"
     ],
     "short_label_prefixes": {
@@ -112,6 +113,7 @@
       "assignment": "asgn",
       "agent_run": "run",
       "action": "act",
+      "agent": "agt",
       "cross_project_link": "xpl"
     }
   },
@@ -217,7 +219,7 @@
         "workflow_model": "task-based",
         "tier": "A",
         "has_mcp": true,
-        "has_hooks": false,
+        "has_hooks": true,
         "has_skills": true,
         "has_rules": true,
         "instruction_file": "AGENTS.md",
@@ -470,7 +472,7 @@
   },
   "bench": {
     "schema": "brainclaw.bench.v1",
-    "generated_at": "2026-07-15T15:24:43.956Z",
+    "generated_at": "2026-07-19T20:01:39.038Z",
     "node_version": "v24.18.0",
     "platform": "linux-x64",
     "repeats": 3,
@@ -480,14 +482,14 @@
         "volume": "empty",
         "description": "fresh machine → init → first useful context. Baseline for time-to-first-value.",
         "duration_ms_median": 76,
-        "payload_chars_median": 1650,
-        "payload_tokens_est_median": 413
+        "payload_chars_median": 1640,
+        "payload_tokens_est_median": 410
       },
       {
         "name": "warm_work",
         "volume": "medium",
         "description": "bclaw_work consult over a real-shaped store (~200 plans / 500 handoffs / 450 claims).",
-        "duration_ms_median": 126,
+        "duration_ms_median": 135,
         "payload_chars_median": 2626,
         "payload_tokens_est_median": 657
       },
@@ -495,7 +497,7 @@
         "name": "first_edit",
         "volume": "medium",
         "description": "code_find + code_brief on the fresh-agent path (missing index, first touch).",
-        "duration_ms_median": 8,
+        "duration_ms_median": 7,
         "payload_chars_median": 442,
         "payload_tokens_est_median": 111
       }

package/docs/PROTOCOL.md

@@ -131,9 +131,13 @@ offered → accepted → started → (progress)* → completed
 ```
 
 Each transition is emitted via `transition('assignment', id, <status>)`.
-A worker that cannot reach the protocol transport (sandboxed) MAY drop a
-`LANE-RESULT.json` file at the worktree root as the fallback signal — the
-coordinator harvests it.
+A worker MAY drop a `LANE-RESULT.json` file at the worktree root and let the
+coordinator harvest it instead of emitting transitions itself. This is the
+coordinator-owned contract for a sandboxed worker: its sandbox makes `.git`
+read-only (so it cannot `git commit`), and the file is the harvestable signal —
+NOT because MCP is unreachable (a sandboxed worker does reach the MCP server,
+which runs out-of-process; dec#133). A genuinely MCP-less agent uses the same
+file as its only channel.
 
 ### 5.3 Claim sentinels
 

package/docs/concepts/coordinator-runbook.md

@@ -41,6 +41,9 @@ worker presumed dead
 │
 ├─ 1. LANE-RESULT.json at the worktree root?
 │     yes → it FINISHED. `brainclaw harvest <asgn> [--integrate]`. Done.
+│     (review lane: a `review_verdict` in the file is mapped onto the review
+│      loop by harvest — a `verdict` artifact is recorded and the loop
+│      auto-closes on `approve`; no manual bclaw_loop drive needed.)
 │
 ├─ 2. git evidence (shared helper: commits_ahead + dirty_tracked,
 │     surfaced by dispatch-status / dispatch watch):

package/docs/concepts/dispatch-lifecycle.md

@@ -152,16 +152,16 @@ You called `bclaw_coordinate(intent="review", open_loop=true, …)` and got back
 
 ## Worktree-as-contract harvest
 
-Some dispatched workers cannot self-commit or call MCP. For example, a sandboxed Codex run may have `dispatchCanCommit=false` because its writable root is the linked worktree, while `.git` lives outside that root. In that case the worker contract is intentionally small:
+Some dispatched workers cannot self-commit. For example, a sandboxed Codex run has `dispatchCanCommit=false` because its writable root is the linked worktree, while `.git` lives outside that root — so it cannot `git commit`. (It *can* still call brainclaw MCP — dec#133 — but the file-based contract below is used regardless, so harvesting stays coordinator-owned and does not depend on the worker's MCP writes.) In that case the worker contract is intentionally small:
 
 1. Edit files inside the dispatched worktree.
-2. Write `LANE-RESULT.json` at the worktree root.
+2. Write `LANE-RESULT.json` at the worktree root — `{ assignment_id, status: completed|blocked|failed, summary, files_changed?, artifacts?, notes? }`. For a **review** lane, the worker also sets `review_verdict` (`approve` | `request_changes`) and `review_summary`; harvest maps those onto the review loop and auto-closes it on `approve` (pln#628 Focus 4B — see [loop-engine.md](./loop-engine.md#automation-extending-bclaw_coordinateintentreview)).
 
 The worker does not need to commit, call `bclaw_assignment_update`, or release the claim itself. The worktree is the contract.
 
 When the coordinator runs `brainclaw harvest <assignment_id> --integrate`, brainclaw reads the worker's `LANE-RESULT.json`, commits the linked worktree diff on the worker's behalf onto the lane branch, then completes the assignment and releases the claim, including the normal plan-status cascade.
 
-The on-behalf commit is guarded by the linked-worktree check (`isLinkedWorktree`): integration only targets the worktree associated with the assignment, never the main repository. This keeps sandboxed-worker harvesting from turning into an accidental main-repo commit path.
+The on-behalf commit is guarded by the linked-worktree check (`isLinkedWorktree`): integration only targets the worktree associated with the assignment, never the main repository. This keeps sandboxed-worker harvesting from turning into an accidental main-repo commit path. It also excludes brainclaw's own transient/provisioned files from the lane commit — `LANE-RESULT.json`, `.brainclaw/`, `.brainclaw-worktree.json`, heartbeat files, and the `node_modules` link(s) brainclaw provisions (top-level + monorepo `**/node_modules`). The `node_modules` exclusion is tracked-aware: a project that *vendors* (commits) `node_modules` keeps a worker's change to a tracked file — only the freshly-provisioned link/dir is dropped.
 
 Integration is strictly additive and opt-in. Plain `brainclaw harvest <assignment_id>` remains report-only; it reads and reports the lane result without committing or mutating assignment / claim state. The on-behalf commit and lifecycle completion happen only when the coordinator passes `--integrate`.
 
@@ -255,7 +255,7 @@ A dead dispatch needs four cleanup steps (no single facade does all of them toda
 
 Spawn behaviour varies by agent. The capability profile in `src/core/agent-capability.ts` describes each agent's prompt delivery, sandbox model, and MCP availability. Per-agent caveats:
 
-- [codex.md](../integrations/codex.md#caveats) — `--sandbox workspace-write` required; spawned codex may not have brainclaw MCP wired; stdin_pipe prompt delivery; brief-ack required for headless dispatch detection.
+- [codex.md](../integrations/codex.md#caveats) — `--sandbox workspace-write` required; sandboxed codex reaches MCP but cannot `git commit` (dec#133 — coordinator harvests the worktree diff); stdin_pipe prompt delivery; brief-ack required for headless dispatch detection.
 - [claude-code.md](../integrations/claude-code.md) — interactive vs `-p` headless modes; tools whitelist.
 - [copilot.md](../integrations/copilot.md), [windsurf.md](../integrations/windsurf.md), [cline.md](../integrations/cline.md), [opencode.md](../integrations/opencode.md), [roo.md](../integrations/roo.md), [kilocode.md](../integrations/kilocode.md), [continue.md](../integrations/continue.md) — per-agent specifics.
 - [mistral-vibe.md](../integrations/mistral-vibe.md) — EU/GDPR self-hosted option.

package/docs/concepts/loop-engine.md

@@ -330,7 +330,11 @@ When `bclaw_coordinate(intent='review', open_loop: true)` is called, it:
 3. Links the provided handoff/candidate to the loop as an artifact at `change_summary`.
 4. Advances to `findings` and calls `bclaw_loop(intent: 'turn')` to dispatch to the reviewer.
 5. On turn completion with a verdict artifact, auto-advances; `reviewer_green` stop closes.
-6. On non-green verdict with `iteration_count < max`, advances to `author_response`, dispatches to author.
+6. On a `request_changes` verdict, the fix cycle re-dispatches the reviewer into the same worktree until `approve` or the `max_iterations` cap.
+
+**How the verdict reaches the loop (shipped, pln#628 Focus 4B).** A dispatched reviewer worker does not call `bclaw_loop` itself — it writes its outcome to `LANE-RESULT.json` at the worktree root, including an optional `review_verdict` (`approve` | `request_changes`) and `review_summary`. When the coordinator runs `brainclaw harvest <assignment_id>` (report-only path and `--integrate`), a review lane carrying a `review_verdict` is mapped onto its loop: brainclaw records a `verdict` artifact on the reviewer slot (`approve` → an `accepted…` body) and calls `advance`, which **auto-closes the loop on `reviewer_green` for `approve`** — no human driving `complete_turn`/`advance`.
+
+**The autonomous fix cycle (PR2, `--integrate` only).** On `request_changes`, `harvest --integrate` bumps the loop's round counter, **keeps the claim + worktree alive**, and re-dispatches the same reviewer slot into that **same worktree** (symmetric mode) with a findings-aware brief: apply the requested changes in place, then re-review. Commits accumulate on one branch — no fresh worktree per turn, so the branch-per-scope / refuse-unharvested-commits invariants are never tripped. The cycle repeats until `approve` (→ `reviewer_green` close) or the `max_iterations` cap (n=3 → auto-close `blocked`, handed to a human). The report-only harvest path never cycles (it can neither re-dispatch nor retain the claim); it defers `request_changes` to `--integrate` and still closes on `approve`. The mapping is idempotent, resolves the reviewer slot strictly by `assignment_id` (so symmetric multi-reviewer loops target the right slot), and runs the `complete_turn`+`advance` pair under the loop lock so an interrupted pass resumes rather than stalls. Asymmetric (author ≠ reviewer) cross-agent worktree sharing is a planned follow-up.
 
 ### Symmetric review-AND-fix mode
 
@@ -514,7 +518,7 @@ Status after Codex schema review (cnd#574 / `dec_be66ccbf`, verdict `needs_revis
 
 The loop surface exposed over MCP is intentionally narrow:
 
-- **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. Drive subsequent turns with `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")`.
+- **Review loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="asymmetric"|"symmetric", targetAgents=[…])` opens the loop and dispatches the first turn. The reviewer's verdict is then harvested from `LANE-RESULT.json` (`review_verdict`) and **auto-advances/closes the loop on approve** — no manual driving needed for the approve path (pln#628 Focus 4B). `bclaw_loop(intent="turn"|"complete_turn"|"advance"|"close")` remains available to drive turns by hand (e.g. the `request_changes` fix cycle, or a human-operated slot).
 - **Ideation loops** — `bclaw_coordinate(intent="ideate", preset="bootstrap")` opens an ideation loop from a preset.
 
 Custom phase lists (`LoopPhase[]`) and bespoke `StopCondition` logic exist in the loop engine internally, but are **not** exposed through the MCP facade today: `CoordinateRequestSchema` accepts only `open_loop`, `review_mode`, `preflight`, `ref`, and `preset` — no `phases` or `stop_condition` — and the standalone `bclaw_loop` tool does not expose an `open` intent. Programmatic construction of ad-hoc loops is therefore internal / future work until the facade is extended.

package/docs/concepts/troubleshooting.md

@@ -206,7 +206,7 @@ brainclaw stale resolve <plan_id>            # → dropped (default for stale)
 
 **Symptom**: a dispatched assignment shows `running` indefinitely, and `bclaw_assignment_events` shows `run_running` but no further progress.
 
-**Why**: the spawned worker process either (a) crashed before reading its inbox, (b) read the inbox but couldn't acknowledge (e.g., MCP unavailable inside the spawned sandbox — common with codex `--sandbox workspace-write`), or (c) is genuinely still working but slow.
+**Why**: the spawned worker process either (a) crashed before reading its inbox, (b) started but the brief-ack sentinel never fired (spawn wrapper died, wrong CODEX_HOME/auth, or the CLI exited early — NOT because the sandbox blocks MCP: dec#133 shows a sandboxed codex reaches MCP fine), or (c) is genuinely still working but slow.
 
 **Diagnostic order**:
 

package/docs/integrations/codex.md

@@ -1,13 +1,13 @@
 # Codex Integration
 
-brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools, shared instruction files, and native lifecycle hooks. Codex has MCP access, universal skills support, headless CLI spawn capability, and a native lifecycle hook surface (added upstream in 2026 — [developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks)).
 
 ## Auto-setup
 
 Codex setup is split across machine and project scope:
 
 - `brainclaw setup-machine --agents codex --yes` writes the machine-level MCP config at `~/.codex/config.toml`
-- `brainclaw init` creates or refreshes the current project's Brainclaw state and writes `AGENTS.md`
+- `brainclaw init` creates or refreshes the current project's Brainclaw state, writes `AGENTS.md`, and writes project-level lifecycle hooks to `.codex/hooks.json` (git-ignored)
 
 If the project already has `.brainclaw/`, rerunning `brainclaw init` is safe and refreshes the managed Brainclaw/Codex files for the current machine.
 
@@ -43,7 +43,7 @@ Codex is CLI-spawnable for parallel lanes and dispatched workflows. The canonica
 codex exec -c approval_policy="never" --sandbox workspace-write "{prompt}"
 ```
 
-The `--sandbox workspace-write` setting is required, **not `read-only`** — the read-only sandbox blocks the MCP filesystem writes that brainclaw needs (worktree handoffs, session files, etc.) and forces fallback to GitHub connectors which fail for local-only commits.
+The `--sandbox workspace-write` setting is required, **not `read-only`** — the worker needs to write files in its own worktree (the edits it produces, plus its `LANE-RESULT.json`) so the coordinator has a harvestable diff. This is about the worker's *file* writes, not MCP: the brainclaw MCP server runs out-of-sandbox and is reachable under either sandbox mode (dec#133). What the sandbox does block is `git commit` (`.git` is outside the writable root), so the coordinator commits the worktree diff at harvest.
 
 ### Prompt delivery: stdin_pipe (preferred)
 
@@ -53,7 +53,7 @@ When you (or the dispatcher) calls Codex with no positional `[PROMPT]`, Codex re
 
 ### Brief-ack handshake
 
-Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started` once the wrapping shell touches a brief-ack sentinel at `.brainclaw/coordination/runtime/ack/<assignmentId>.ack`. This proves the spawn actually executed and decouples the handshake from MCP availability inside the worker — important because Codex spawned in `--sandbox workspace-write` may not have brainclaw MCP wired in its session.
+Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started` once the wrapping shell touches a brief-ack sentinel at `.brainclaw/coordination/runtime/ack/<assignmentId>.ack`. This proves the spawn actually executed and decouples the handshake from whatever the worker does next — the spawn is confirmed even before the worker makes its first MCP call. (Note — dec#133: a sandboxed Codex run **does** reach brainclaw MCP; the server runs out-of-sandbox and `approval_policy=never` auto-approves. The sentinel is about confirming the spawn, not about MCP being unavailable.)
 
 ## Capability profile
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | no |
+| Hooks | yes (`.codex/hooks.json`, project scope) |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |
@@ -70,9 +70,25 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 | MCP config scope | machine |
 | Prompt delivery | `stdin_pipe` (preferred), `inline_arg` (fallback) |
 
+## Lifecycle hooks
+
+`brainclaw init` writes project-level hooks to `.codex/hooks.json` (git-ignored, machine-specific command paths). Codex reads hooks from `hooks.json` or an inline `[hooks]` table at user (`~/.codex/`) and project (`<repo>/.codex/`) scope ([Codex hooks docs](https://developers.openai.com/codex/hooks)). brainclaw wires three events:
+
+| Event | brainclaw command | Purpose |
+|-------|-------------------|---------|
+| `SessionStart` | `brainclaw session-start --include-context` | Load shared context (constraints, decisions, traps, plans, handoffs) when a session begins |
+| `UserPromptSubmit` | `brainclaw context-diff` | Surface what changed since the last turn |
+| `Stop` | `brainclaw session-end --auto-release --reflect --reflect-handoff --dispatch-review` | Release claims, reflect, and dispatch review at turn end |
+
+The file shape is `{ "hooks": { "<Event>": [ { "matcher": "", "hooks": [ { "type": "command", "command": "…" } ] } ] } }` (`matcher: ""` = match all occurrences). brainclaw **owns** these three event arrays: reruns overwrite them (idempotent, no cross-upgrade pile-up) — the same contract as the Cursor / Antigravity hook writers. A user's own hook placed on one of these three events is replaced on the next `init`; hooks on any **other** event are left untouched.
+
+**Scope — interactive sessions, not headless dispatch.** These hooks serve an *interactive* Codex session. Non-managed command hooks require a one-time trust in Codex (`/hooks` — inspect and trust) before they run, so a fresh `.codex/hooks.json` is inert until the user trusts it. Headless dispatched workers (`codex exec`, used by `bclaw_dispatch` / `bclaw_coordinate`) do **not** rely on these hooks at all — they receive their context in the dispatch brief and report via `LANE-RESULT.json`; an untrusted project hook is simply skipped there, which is harmless. (A "managed" hook path via `requirements.toml`/MDM could bypass the trust step for fleets — a possible future enhancement.)
+
+**Per-event output contract.** `SessionStart` and `UserPromptSubmit` emit their stdout as **model-visible context** — that is exactly the point (inject shared brainclaw state / the context diff). `Stop`, by contrast, expects a **JSON** response from Codex to shape turn-end behavior; brainclaw's `session-end` runs mainly for its side effects (release claims, reflect, dispatch review) and does not emit that JSON, so it does not gate the turn. Emitting a conformant per-event JSON response (notably for `Stop`) is a planned follow-up.
+
 ## Caveats
 
-- **Sandbox blocks MCP writes**: when running with strict sandbox, the spawned Codex cannot write to `.brainclaw/` directly. Use the brief-ack file plus filesystem-direct candidate writes (the dispatcher harvests them).
+- **Sandbox blocks `git commit`, not MCP** (dec#133): a sandboxed Codex run reaches brainclaw MCP (the server is a separate out-of-sandbox process; `approval_policy=never` auto-approves). What the sandbox *does* block is direct writes to paths outside the worktree root — notably `.git`, so the worker cannot `git commit`. Leave fixes uncommitted; the coordinator integrates + commits the worktree diff at harvest. A LANE-RESULT.json / filesystem-direct candidate write remains a valid fallback for reporting.
 - **Windows quoting**: long prompts containing backticks or `#` fail when passed as inline args through `cmd.exe`. The default stdin_pipe path avoids this.
 - **Sandbox vs review parity**: review runs use the same `workspace-write` sandbox as execution runs (older templates forced `read-only` on reviews; that path blocked PowerShell exec on Windows).
 - **No always-allow**: each MCP tool call still respects per-call approval policy unless explicitly set with `-c approval_policy="never"`.

package/docs/integrations/overview.md

@@ -103,7 +103,7 @@ The developer can dial back individual surfaces if needed, but the default is fu
 
 brainclaw's store mutations are serialized (MCP single-writer queue + file-based lock), so memory writes are safe even under contention.
 
-For **parallel work**, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own auto-worktree under `~/.brainclaw/worktrees/<project-hash>/`, and the coordinator integrates with an octopus merge. For **review-fix loops**, `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. These are the supported parallel paths today.
+For **parallel work**, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own auto-worktree under `~/.brainclaw/worktrees/<project-hash>/`, and the coordinator integrates with an octopus merge. For **review-fix loops**, `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions — and the loop **auto-closes on reviewer approve** (the verdict is harvested from `LANE-RESULT.json`, no manual drive). These are the supported parallel paths today.
 
 For **sequential work** in the same project, let one agent claim at a time and rely on handoffs to keep continuity across sessions.
 

package/docs/mcp-schema-changelog.md

@@ -10,6 +10,112 @@ guarantees this changelog follows.
 
 ## Unreleased
 
+**Added — `LaneResultSchema.review_verdict` / `review_summary` (pln#628 Focus 4B)**
+- `LANE-RESULT.json` (the worktree-root file a dispatched worker writes) gains two
+  optional fields: `review_verdict` (`approve` | `request_changes`) and
+  `review_summary` (one-line rationale). Absent on non-review lanes.
+- Consumed by `brainclaw harvest` (report path + `--integrate`): a review lane
+  carrying a `review_verdict` is mapped onto its review loop — a `verdict` artifact
+  is recorded and the loop advances, auto-closing on `reviewer_green` for
+  `approve`. Additive + backward-compatible; no tool added/removed/renamed and no
+  surface-fingerprint change (LaneResultSchema is not part of the read/write
+  contract fingerprint).
+
+**Added — `bclaw_update(entity='handoff')` incl. review/contract (pln#625 Phase 3)**
+- The handoff update path is now wired. Previously `bclaw_update(entity='handoff')`
+  fell through to "not yet wired" (the field check passed for narrative/tags but
+  there was no handler case). `handoff.updatable` now also includes `review` and
+  `contract`, each validated against `HandoffReviewSchema` / `HandoffContractSchema`
+  and merged onto the record.
+- This **restores the review-state write capability lost at v1.0** when
+  `bclaw_update_handoff` was removed: an agent can write a review verdict via
+  `bclaw_update(entity='handoff', data={ review: { verdict, summary, … } })`.
+  A verdict auto-stamps `review.reviewed_at`. The review loop's core
+  (`applyHandoffUpdates`) is unchanged — this is the canonical-grammar front door
+  onto the same record.
+- Tip guard: a superseded (tombstoned) handoff is refused, pointing at the tip.
+- No tool added/removed/renamed; `updatable` is not part of the surface
+  fingerprint, so no fingerprint change.
+
+**Removed — `bclaw_list_agents` (pln#625; migrate to `bclaw_find(entity='agent')`)**
+- `bclaw_list_agents` — the last surviving `bclaw_list_*` tool — is retired into
+  `REMOVED_IN_V1_TOOLS`: hidden from every `tools/list`, with a direct-call
+  deprecation warning pointing at `bclaw_find(entity='agent')`. The handler
+  stays as a redacted read escape-hatch (`LEGACY_READ_TOOL_HANDLERS`), same as
+  its `list_*` siblings.
+- To preserve its one unique capability, `bclaw_find(entity='agent')` gains an
+  agent-only `includeReputation` filter that attaches the public reputation
+  summary per agent (same join the CLI `list-agents --with-reputation` uses).
+- Net surface coherence: `agent` reads now flow through one grammar path with a
+  single redacted projection (`projectAgentForRead`), closing the divergent
+  double-surface (the old tool leaked raw `identity_key`/`invoke.env`).
+
+**Changed — governance guard now covers grammar entities AND the filter contract (pln#625)**
+- `tests/unit/mcp-governance.test.ts` folds two free-form parts of the callable
+  contract into the public-surface fingerprint: the set of addressable grammar
+  entities (`ENTITY_NAMES`) and the find/get filter grammar
+  (`GRAMMAR_FILTER_CONTRACT` — accepted keys, entity-scoping, constrained
+  values). Both were previously invisible (the `entity` and `filter` args are
+  free-form and their enumerating descriptions are stripped), so wiring a new
+  `bclaw_find/get(entity='…')` target or adding/re-scoping/re-valuing a filter
+  key (e.g. the Phase 2c `scope`) could ship without a changelog entry.
+- `GRAMMAR_FILTER_CONTRACT` (exported from `entity-operations.ts`) is now the
+  single source of truth for the handler's filter validation AND the
+  fingerprint, so the two can never drift. A mutation test proves the
+  fingerprint reacts to an added entity, key, re-scope, and new value.
+- Closes the blind spot surfaced by the Phase 2c ideation loop; the filter-grammar
+  extension came from the Codex review of PR #82.
+
+**Added — read-only `agent` entity in the canonical grammar (pln#625 Phase 2c)**
+- `bclaw_find/get(entity='agent')` are now wired. They return a REDACTED,
+  read-only projection: `id`, `name`, `kind`, `trust_level`, `capabilities`,
+  `fingerprint` (full sha256(PEM) — the public canonical key id), `model`,
+  `context_profile`, `created_at`. The private key material (`identity_key`,
+  `public_key` PEM) and `invoke` (unpopulated dead field; would leak
+  `invoke.command`) are never surfaced. Writes (`create/update/remove/transition`)
+  return the `SystemManagedError` boundary — agents are managed via
+  `bclaw_setup` / `enable-agent`, not the grammar.
+- New agent-only filter `scope`: `bclaw_find(entity='agent')` defaults to the
+  current project's registry; `filter.scope='global'` additionally unions the
+  static dispatchable catalog (`getSpawnableAgents`) and annotates each entry
+  with `dispatchable` (canBeSpawnedCli) + `registered`. `scope` is rejected for
+  any other entity, and its value must be `project` (default) or `global`.
+- `bclaw_list_agents` now redacts through the SAME projection (one source of
+  truth). It previously spread the raw identity document, leaking
+  `identity_key.public_key` and `invoke.env` in the clear — a pre-existing
+  disclosure, now closed. `includeReputation` still attaches the reputation
+  add-on.
+- This supersedes the Phase 1a stopgap that reported `agent` as "not addressable
+  via the canonical grammar" (never released; last tag v1.15.0).
+
+**Fixed — `bclaw_transition(entity='handoff')` wired (pln#625 Phase 2a)**
+- The handoff lifecycle (`open→accepted|closed`, `accepted→closed`) is now
+  wired. It previously fell to the "not yet wired" default, which also broke
+  `brainclaw stale resolve <handoff-id>` (that command routes through the
+  canonical transition). A tip guard refuses to transition a handoff carrying
+  `superseded_by` (an immutable correction tombstone) and points at the tip.
+- No tool was added, removed, or renamed; no required argument changed.
+
+**Fixed — `bclaw_coordinate` published-schema parity (pln#622 PR0b)**
+- The published inputSchema of `bclaw_coordinate` now declares `preset`
+  (loop preset selector, valid only with `intent='ideate'`; v1 ships the
+  single preset `bootstrap`; unknown names are rejected with
+  `unknown_preset`, other intents with `preset_kind_mismatch`) and
+  `client_request_id` (caller-minted ULID/UUIDv7 for idempotent retries,
+  observed on `intent='review'` + `open_loop=true`, safe elsewhere). Both
+  were already accepted by `CoordinateRequestSchema` and used by the
+  handler — and `next_actions` literally recommended
+  `bclaw_coordinate(intent='ideate', preset='bootstrap')` — but the catalog
+  never declared them, so strict MCP clients could not follow the product's
+  own recommendation.
+- New guard: `tests/unit/mcp-facade-structural-parity.test.ts` asserts
+  bidirectional structural parity (keys + shared enum values) between the
+  hand-written facade schemas (`bclaw_work`, `bclaw_coordinate`) and their
+  zod sources, with an explicit allowlist for adapter-envelope fields
+  (`agent`, `agentId`).
+- No tool was added, removed, or renamed; no required argument changed.
+- Surface fingerprint bumped in the `(current)` section below.
+
 **Changed — MCP model selection parity (pln#520/#606)**
 - `bclaw_dispatch` and `bclaw_coordinate` gain an optional `model` string that
   selects the spawned worker's model (e.g. `sonnet`, `gpt-5-codex`), decoupled
@@ -132,8 +238,37 @@ will still succeed. A follow-up PR will strip the dead handler code.
   changelog records the published MCP surface fingerprint. When a tool
   name, tier, category, or input schema changes, the test fails until
   this section is updated.
-- MCP public surface fingerprint: `sha256:b53eb56d4391b5a6`
-  (updated 2026-07-15 for pln#520/#606: optional `model` string added to
+- MCP public surface fingerprint: `sha256:468f0103414e97e8`
+  (updated 2026-07-18 for pln#625 PR #83 + Codex review: `bclaw_list_agents`
+  retired and `bclaw_find(entity='agent')` gains `includeReputation` — now typed
+  as a boolean in `GRAMMAR_FILTER_CONTRACT.booleanKeys` and validated at the MCP
+  front door, so a non-boolean value is rejected instead of silently coercing to
+  a no-op. The added boolean-type declaration moves the fingerprint.)
+  Previous: `sha256:be0df1e4cc33936f`
+  (updated 2026-07-17 for pln#625 PR #83: `bclaw_list_agents` retired from the
+  published surface — migrated to `bclaw_find(entity='agent')` which gains an
+  agent-only `includeReputation` filter. Both the removed tool and the new
+  filter key move the fingerprint via the guard now covering PUBLISHED_TOOLS +
+  ENTITY_NAMES + GRAMMAR_FILTER_CONTRACT.)
+  Previous: `sha256:e12fd2f34dae1ac0`
+  (updated 2026-07-17 for pln#625 Phase 2c + PR #82: the fingerprint now folds in
+  two parts of the callable contract that the tool inputSchema cannot express —
+  the set of grammar-addressable entities (`ENTITY_NAMES`) and the find/get
+  filter grammar (`GRAMMAR_FILTER_CONTRACT`: accepted keys, entity-scoping, and
+  constrained values such as `scope=project|global`). Both were invisible to the
+  fingerprint before (`entity` and `filter` are free-form and their enumerating
+  descriptions are stripped), so wiring a new addressable entity — or adding /
+  re-scoping / re-valuing a filter key like the Phase 2c `scope` — slipped past
+  this guard. Additive: no tool added, removed, or renamed.)
+  Previous: `sha256:45c02576aff36244`
+  (updated 2026-07-15 for pln#622 PR0b: `preset` and `client_request_id` added
+  to the published `bclaw_coordinate` input schema. Both were already accepted
+  by `CoordinateRequestSchema` and used by the handler — and `next_actions`
+  recommended `bclaw_coordinate(intent='ideate', preset='bootstrap')` — but
+  the catalog never declared them. Additive: no tool added, removed, or
+  renamed; no required argument changed.
+  Previous: `sha256:b53eb56d4391b5a6`
+  updated 2026-07-15 for pln#520/#606: optional `model` string added to
   `bclaw_dispatch` and `bclaw_coordinate` input schemas — selects the spawned
   worker's model, decoupled from agent identity (CLI/MCP parity with
   `dispatch run --model`). Additive: no tool added, removed, or renamed; no

package/docs/playbooks/orchestration.md

@@ -24,7 +24,7 @@ With the plan and sequences established, assign the work to execution agents.
 
 - **Sequence-driven execution:** Use `bclaw_dispatch(intent="execute")` to parallelize plans across your defined sequence lanes automatically.
 - **Direct orchestration:** For ad-hoc delegation, use `bclaw_coordinate(intent="assign")` to assign specific tasks to target agents. This seamlessly generates the necessary claims and dispatch briefs.
-- **Reviews & Loops:** To open a structured review process on completed work, use `bclaw_coordinate(intent="review", open_loop=true)`.
+- **Reviews & Loops:** To open a structured review process on completed work, use `bclaw_coordinate(intent="review", open_loop=true)`. The reviewer's verdict is harvested from its `LANE-RESULT.json` (`review_verdict`) and the loop **auto-closes on approve** — no manual `complete_turn`/`advance` round-trip to close the approve path (pln#628 Focus 4B).
 - Use `bclaw_dispatch_status` to verify worker liveness, examine log tails, and ensure dispatches are progressing healthily.
 
 ## Step 4: Manage the Inbox

package/docs/product/entity-model-audit.md

@@ -84,8 +84,9 @@ load-bearing; simplifications cannot break them.
     "never init --force"). Strongest concept; drives hook injection
     to remind agents of the process.
   - **Trap**: environmental or process pitfall to avoid (e.g., "git
-    merge wipes node_modules", "sandbox X blocks MCP writes"). May
-    trigger a corrective plan when resolvable.
+    merge wipes node_modules", "a sandboxed worker's `.git` is read-only
+    → it cannot `git commit`"). May trigger a corrective plan when
+    resolvable.
   All three drive different agent behaviours (decisions = retrieve for
   context, constraints = enforce, traps = warn + resolve).
 

package/docs/security.md

@@ -45,7 +45,28 @@ matches block the write.
 
 When `security.block_sensitive_paths: true` (default), content that
 references paths like `.env`, `secrets/`, `.git/`, or `node_modules/`
-emits a warning.
+is flagged. `block_sensitive_paths` is the **enable-gate** for this layer;
+the flagged level follows the same rule as every other signal — a `warn`
+normally, escalating to `block` under `strict_redaction: true` (mode:
+strict). It is not a standalone block toggle: in warn mode a sensitive-path
+mention warns; in strict mode it blocks, uniformly with redaction, structural,
+and entropy matches.
+
+### Signal layers and levels
+
+`scanText` runs four independent layers, each with its own enable-gate, and
+they all share one level rule:
+
+| Layer | Enable-gate | Level (warn mode / strict) |
+|-------|-------------|----------------------------|
+| Redaction patterns | `redaction.enabled` | warn / block |
+| Structural detectors | `security.token_detection.enabled` | warn / block |
+| Entropy detector | `security.token_detection.entropy.enabled` | warn / block |
+| Sensitive paths | `security.block_sensitive_paths` | warn / block |
+
+`strict_redaction: true` escalates **every** matched signal to `block`
+uniformly; there is no per-layer level override. Excerpts in messages are
+always irreversibly masked.
 
 ### Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "repository": {
@@ -62,6 +62,8 @@
     "test:coverage:check": "npm run build:test && c8 --all --check-coverage --lines 55 --functions 60 --branches 65 --statements 55 --src dist-test/src --reporter=text-summary --exclude=dist-test/tests/** --exclude=dist-test/scripts/** node scripts/run-tests.mjs default",
     "bench": "npm run build:test && node scripts/bench.mjs",
     "bench:check": "node scripts/bench-check.mjs",
+    "bench:cold-start": "node scripts/bench-cold-start.mjs",
+    "bench:cold-start:check": "node scripts/bench-cold-start.mjs --check",
     "prepublishOnly": "npm run build:release && npm run pack:check"
   },
   "keywords": [