fix(security): gate brain-emitted tool calls on the local chat path

docs/CONTRACTS.md

@@ -8,7 +8,7 @@ bug.
 
 ---
 
-## 1. AetherCode ↔ Brain bridge event protocol  ·  `PROTOCOL_VERSION = 2`
+## 1. AetherCode ↔ Brain bridge event protocol  ·  `PROTOCOL_VERSION = 3`
 
 The event seam between the headless brain (decides) and the TS host (renders +
 executes). Full prose + rationale: [`BRIDGE_PROTOCOL.md`](./BRIDGE_PROTOCOL.md).
@@ -43,6 +43,28 @@ History:
   (old consumers ignore the new event + optional fields); the integer was bumped
   to 2 alongside the schema rev so the conformance fixture stays in lockstep
   across both repos.
+- **v3** — the `web_search`/`web_fetch` tools joined `TOOLS` (see Invariant 2).
+  Separately, and never recorded here until now: the workflow swarm frames —
+  `workflow_start`, `phase_start`, `phase_done`, `agent_spawn`,
+  `agent_progress`, `agent_done`, `workflow_done` (the CODEPRO/HIGH+-effort
+  multi-agent workflow view) — also landed in `brain_protocol.ts` during the
+  v2->v3 window. Per the versioning rule above they're purely additive and
+  didn't need their own bump; this doc's silence on them until now was a
+  drift, not a deliberate omission, closed by this change per this doc's own
+  rule ("if code and this doc disagree, this doc wins and the code is the
+  bug"). Also additive, layered on top of the now-documented v3 baseline:
+  `agent_done` gained optional `tokens`/`tool_calls`/`duration_ms` (Tier-2/3
+  per-agent metrics for the terminal/desktop workflow panels —
+  `docs/specs/2026-07-10-workflow-viewer-agent-panel-design.md`); absent on
+  the wire, these decode to `undefined`, never a fabricated `0`.
+- **Known gap:** `test/fixtures/bridge_conformance.json` (this repo) does not
+  yet include any of the v3 workflow-swarm frames in its `events` array, so
+  the conformance/drift-detector tests below don't exercise them. Extending
+  the fixture requires an identical update to the Unlimited-Context mirror's
+  copy (`tests/fixtures/bridge_conformance.json`, a separate repo) to avoid
+  creating the exact cross-repo drift this fixture exists to prevent —
+  flagged here, deliberately left for a coordinated cross-repo change rather
+  than fixed unilaterally in this PR.
 
 ### Messages (wire = NDJSON, one JSON object per line, keys snake_case, ASCII-safe)
 
@@ -60,6 +82,13 @@ History:
 | `checkpoint` | `git_sha` | a verified step was committed |
 | `done` | `ok, result, remaining, reason` | run finished; `ok` from a real final test run (see invariant 5) |
 | `error` | `msg` | run aborted |
+| `workflow_start` | `workflow_id, phases[{n, type, agents}], total_agents` | a CODEPRO/HIGH+ multi-agent workflow began |
+| `phase_start` | `phase_n, phase_type, agent_count` | a workflow phase began |
+| `phase_done` | `phase_n, artifact_summary` | a workflow phase completed |
+| `agent_spawn` | `agent_id, phase_n, brief` | one swarm agent started |
+| `agent_progress` | `agent_id, delta` | streamed output from one swarm agent (emitter not confirmed on the shared backend — see `docs/specs/2026-07-10-workflow-viewer-agent-panel-design.md` Finding E) |
+| `agent_done` | `agent_id, phase_n, summary, tokens?, tool_calls?, duration_ms?` | one swarm agent finished; the last 3 fields are optional Tier-2/3 metrics, absent on older brains |
+| `workflow_done` | `synthesis, total_phases, total_agents` | the multi-agent workflow finished |
 
 **host → brain (commands)**
 
@@ -76,9 +105,14 @@ History:
    does not match the outstanding call is a protocol violation → the brain emits
    `error` and aborts (it does NOT skip — skipping mis-pairs results to calls).
 2. **One tool implementation, host-side.** `read_file · write_file · run_shell ·
-   run_tests · repo_search · git_commit`. A single path-guard canonicalizes
-   (realpath: resolves `..`, absolute paths, and symlinks) BEFORE the workspace
-   allowlist check. Output is `[exit N]\n…`, capped, with stderr captured.
+   run_tests · repo_search · git_commit · web_search · web_fetch` (the full
+   canonical `TOOLS` set, `src/core/brain_protocol.ts`; this row previously
+   listed only the first 6 — pre-existing drift, closed by this change). A
+   single path-guard canonicalizes (realpath: resolves `..`, absolute paths,
+   and symlinks) BEFORE the workspace allowlist check for the filesystem/shell
+   tools; `web_search`/`web_fetch` have no repo path to canonicalize and are
+   guarded separately (SSRF/loopback/redirect checks, `src/core/web.ts`).
+   Output is `[exit N]\n…`, capped, with stderr captured.
 3. **Encoding is lossless, codec-boundary only.** The wire is ASCII-escaped
    (`ensure_ascii`) so it survives a Windows cp1252 pipe; decode restores exact
    UTF-8. Rendered frames are real UTF-8 — escaping never touches them.