docs: hand-off note for the next session

Records the state of the tree, the one step not taken (the stream-json
runtime image is built and never deployed, so no mission has confirmed
tool.call rows end to end), the ordered next steps, the decisions that are
the operator's, and what was deliberately left undone with reasons.

Also records the two corrections made this session — "missions can't call
tools" was wrong, and raw test counts are a bad coverage metric — because
both were confidently stated here before being checked.

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/NEXT-SESSION.md

@@ -0,0 +1,104 @@
+# Where this left off — 2026-08-20
+
+Read `CAPABILITY-REVIEW.md` for the system picture,
+`TOOL-CALL-ARCHITECTURE.md` for the current investigation, and
+`SKILL-USE-BASELINE.md` for the measurement.
+
+## State of the tree
+
+**11 unpushed commits on `main`** (`origin/main` is 11 behind). Nothing has been
+pushed and nothing is deployed to gw-04. Full suite green: 106 test binaries,
+zero build errors, frontend builds.
+
+**1 unpushed commit in the fork** at `/Users/quantum/projects/zeroclaw`, branch
+`merge/upstream-v0.8.4`: `db1c50966 feat(claude_cli): stream-json …`.
+
+## The thing to do first
+
+**A runtime image with the `stream-json` fix is built and NOT deployed.**
+
+```
+clawmates-runtime:streamjson     # built 2026-08-19, never run
+```
+
+Nothing has yet confirmed end to end that real `tool.call` rows land in
+`mission_events` from a live mission. That confirmation is the whole point of
+the change and it is the one step not taken. Until it runs, treat the fix as
+plausible rather than proven — the parser is unit-tested against a captured
+real stream, but no mission has driven it.
+
+To do it: deploy the image as the mission runtime, launch a mission, then
+
+```sql
+SELECT kind, target, count(*) FROM mission_events
+ WHERE mission_id = '<id>' GROUP BY 1,2;
+```
+
+Expect `tool.call` rows on the container tier for the first time. If they do not
+appear, the next suspects are `topology_exec`'s frame parser and whether the
+gateway forwards the provider's `tool_calls` at all — neither has been exercised
+with a non-empty list.
+
+## Then, in order
+
+1. **Prove the PreToolUse gate in a real VM.** `vm_tool_gate` is unit-tested and
+   shell-tested on the host; it has never run in a guest. Four of its bugs were
+   found only by executing the generated script, and two of them (syntax error,
+   `IFS`) produce a gate that looks installed while being fully closed or fully
+   open. Check `/root/toolgate/denied.jsonl` after a mission that tries
+   something denied.
+
+2. **Give the direct-session tier a tap.** It is the one tier with no
+   observability at all — `session_executor::run_session` is a single
+   `container_exec::exec` returning a string. Same settings document, written
+   into a container instead of a VM.
+
+3. **Deploy the door we already built** (`docs/TOOL-CALL-ARCHITECTURE.md` §3).
+   Create `/zeroclaw-data/clawmates-mcp.json`, add a door-shaped provider alias,
+   bind mission claws to it. This is config, not code — the provider feature is
+   ours and shipped. It would also make `clawmates_skills` genuinely reachable,
+   which is the precondition for moving skills from inlined bodies to
+   progressive disclosure and making Skill-Use **Trigger** measurable the way
+   the paper defines it.
+
+4. **Pull upstream's egress policy** — `0db7d999a feat(plugins): add shared
+   egress policy foundation (#9137)`. We are 218 commits behind; this is the one
+   item identified as worth taking, and it is defence for a problem we have not
+   solved.
+
+## Open decisions that are yours
+
+- **Self-authoring scope.** Agents now apply their own `skill_candidate` items
+  with no human click (`CLAWMATES_SKILL_SELF_AUTHORING=0` restores the gate).
+  `identity_refinement` and `brain_consolidation` still wait for a human,
+  because they change what an agent IS rather than adding a procedure it can
+  consult. Say if you want those autonomous too.
+- **Skill-Use Compliance coverage.** Most skills still score `not_applicable` —
+  we cannot tell whether they changed anything. `small-focused-commits` and
+  `tdd-red-green-refactor` are the next candidates and both need the repository
+  diff rather than the turn text.
+
+## Deliberately not done
+
+- **The mission executor swap** (running turns through `ProviderExecutor` or the
+  chat `Runtime`). The blockers are structural, not wiring: `cm-runtime`'s
+  `files` tool rejects absolute paths *by construction*, `shell` runs in a
+  per-agent sandbox with no mission mount, `ToolContext` carries no path or VM
+  handle, and approvals key on `(session_id, message_id)`. The cheap fixes
+  deliver what it was wanted for.
+- **`cm-brain` offline tests** — 6 of 9 need live `clawbrainhub.com`. Stubbing
+  means reproducing an external registry protocol we have no spec for.
+- **Graph memory / `clawhdf5-agent`** — in the workspace manifest, used by no
+  crate. Measure against a baseline before migrating.
+
+## Two corrections made this session, worth remembering
+
+- **"Missions can't call tools at all" was wrong.** They call `Bash` and `Write`
+  with permissions pre-accepted. The gap was observing and gating, not having.
+- **Raw test counts are a bad coverage metric.** They pointed at `cm-safety`,
+  whose seven tests already covered its critical paths, and missed a Slack
+  replay hole that let one captured request authenticate forever.
+
+The recurring shape, now seven times over: **a claim in a comment or a doc,
+believed and never checked.** Every significant finding this session came from
+running the thing rather than reading about it.