fix(brains): stop claiming automatic capture on claude.ai, document the real behavior [BRNS-MCPWEB-018]

[olegshmuelov]

Five public surfaces in this repo advertised conversation capture — and the inbox — as things that just happen. Both run only through the bundled hooks, and both are off without a credential, so the claims were false in two shipped configurations: claude.ai web (no hooks at all, on either install path) and any CLI install with no capture token (brains-turn.sh exits early; the token is required: false).

Two more of the same class — the /install/claude-web DoneCard and the walkthrough's paste step — live in ssvlabs/brains and were fixed in ssvlabs/brains#1230, not here.

core.md was the worst of them, because it is injected into a model's context rather than read by a human: it told the model capture was automatic and that it should not call save_chat_session — suppressing the only mechanism that works where the hooks don't run.

What changed

• core.md — the capture rule is now conditional on a credential resolving, and the prohibition is narrowed to "routinely". The blanket form suppressed save_chat_session even when the user asked for it outright, which on claude.ai is the one path measured to work. Marker v=5 → v=6.
• Four prose surfaces — hook-driven turn-by-turn capture and inbox delivery replaces the unqualified phrasing in the plugin manifest, the marketplace catalog card (a distinct surface: a fix touching only the manifest leaves the card lying to anyone browsing), the Codex manifest's longDescription, and the README blurb.
• New ## Install for claude.ai web — the README had no web section at all, so a web reader had nowhere to learn that the capture the rest of the page describes does not reach them. Names both install paths, links the install guide rather than forking its 23k-character instruction block, and states what capture actually does there.
• Self-hosting promoted to a top-level section — it was nested under Install for Claude Code while its last paragraph instructs Codex users (BRAINS_ENDPOINT is the only lever Codex has). A reader on the Codex path never saw it, and their capture would keep posting to the wrong host silently. Body moved byte-for-byte.
• Guard work (see below) — the copy is pinned verbatim, and the hook event map is now asserted whole. Closes plugin-contract: hook-map assertions pass when an event is removed or left empty #14.
• A bump convention, documented in generated-artifact-guard.sh's header — fix(…) is a patch, feat(…) a minor, a declared breaking change to the plugin's contract a major. The guard only ever required forward SemVer movement, on any digit, so which digit to move was never written down. The header says plainly that it is a convention rather than something the script enforces, and that past bumps in this repo do not follow it — going forward, not a description of history.
• Post-review hardening — two adversarial review rounds against this PR's own guards found 16 further evasions, all demonstrated by execution; closing them also rewrote the trust-prompt sentence in both install sections (capture and the inbox are no longer named as things that run on trust alone) and retired the stale brains-turn.sh header comment that still said "No save_chat_session call needed".

What capture actually does on claude.ai — measured, not inferred

Verified live on a real account, both tool-access modes, checked against list_pages rather than the chat UI. All of it measured on 2026-08-05 — before carrier B landed, so these are the rates the tool description had to improve on, not the rates after it:

Explicit ask — "save this chat to brains" — works, reliably.

Unprompted capture is unreliable, and the rate depends on which block was in the Instructions field, so the conditions are kept apart rather than pooled:

Instructions field	Passive trials that saved
the install guide's full block (23,068 chars)	1 of 3 — and a direct replication of that success failed
an abbreviated block	0 of 2
empty (baseline)	0 of 1

Pooled across both blocks that is 1 of 5, but the pooled figure understates the real carrier and the split is the honest form. Deliberately not expressed as a percentage: n=3 and n=5 do not support one.

One trial said "Now saving this to brains" and never called the tool. That is why the README tells the reader how to verify a save rather than only disclaiming — from the chat alone, a real save and a claimed one look identical.

The README copy says exactly this, in two separate paragraphs. Collapsing them into one reassuring sentence would be technically defensible and would leave a user believing unprompted capture is dependable; please treat that as a regression.

Guards

Keyword assertions proved evadable twice during review, both times demonstrated rather than argued — a rewrite opening "Capture is handled automatically for you" passed every signal check while reversing the meaning. So the load-bearing copy is now pinned verbatim, the pattern this file's own doctrine already prescribes for this claim class — and after review probes kept finding unpinned text beside every partial pin, the pin unit became the whole artifact:

• CORE_BODY — core.md entire, its delivery execution-proven: deleting brains-start.sh's cat line now fails the suite
• README_REGIONS — the README as the ordered composition of ten pinned regions; text added anywhere in the file fails composition
• all four manifest/marketplace JSONs pinned whole by canonical JSON, so a copy field nobody inventoried (interface.shortDescription was one) cannot ship unread

Hook event map (#14). Three separate holes let published behaviour reach zero users with every suite green: an event could be deleted (only 2 of Claude's 5 were asserted — deleting SessionStart, the only delivery path for core.md, passed both suites), gutted (includes("PostToolUseFailure") is satisfied by the key existing, so [] passed with its own assertion intact), or mis-mapped (SessionStart → brains-end.sh passed). Codex carried all three identically. Replaced with a per-client constant pinning each event's complete declared shape — matcher (or its required absence), exact command strings, group count, and the whole group array by canonical JSON — so a narrowed matcher, a rider command, or a stray timeout fails too.

Worth stating plainly: those holes sat directly under this PR's own work. The verbatim pins proved core.md's text was correct while nothing proved it ever loads.

Also widened the README bash -n sweep to the whole file — promoting Self-hosting had moved its block outside every checked slice, and the six Codex blocks were never swept at all.

Verification

• Three suites + delivery guard + hygiene green; 2.7.0 → 2.7.1 on both manifests (patch-shaped).
• Every guard was mutation-tested in three rounds: the original matrix, then two adversarial review rounds whose every surviving evasion became a red row. Final matrix: 55 mutations plus 9 regression re-checks, 0 survivors; two rows are recorded as already caught at base rather than claimed as new.

This does not close BRNS-MCPWEB-018 — but no PR is outstanding

The ticket closes on claims matching reality. The code for that is all merged:

• this PR (brains-plugins) — the five surfaces above, plus the guards;
• ssvlabs/brains#1230 — the /install/claude-web DoneCard and walkthrough copy, and carrier B: save_chat_session's eager tool description now carries the capture rule itself, the last always-on surface that had never been tried;
• ssvlabs/brains#1243 — converted six FIRST RULE pins in the pasted bodies from keyword-shaped to verbatim. Same defect class as this PR's CORE_CAPTURE_REGION work, found independently, which is the strongest evidence that the evadable-keyword-pin problem was not a one-off here.

Both monorepo PRs are on stage, neither on main yet.

What remains is verification, not another PR. Once stage promotes, the passive rate has to be re-measured on prod — 8–10 passive trials per tool-access mode, not 3. At a 1-in-3 base rate a three-trial run cannot distinguish a real improvement from noise, which is the same pooling-and-small-n mistake that would make this PR's own copy wrong in the reassuring direction.

If that measurement shows carrier B raises the passive rate, the README's "only sometimes" paragraph becomes wrong and should be retracted; whoever runs the verification should re-read that paragraph against the result.

BRNS-MCPWEB-021, after this publishes: core.md's marker moved to v=6, which needs a companion db/init/NNN_catalog_core_v6.sql in ssvlabs/brains, modeled on 338_catalog_core_v5.sql. Ordering is fixed by that migration's own header — the release must exist first, or devices are told to update to a marker the marketplace does not serve.

BRNS-MCPWEB-020, deliberately deferred: the full install-path documentation. It is blocked on two things nobody has measured — what a paid user with both the plugin and the older pasted block active actually gets, and whether a Team or Enterprise member can add a marketplace by URL at all, which is the mechanism that whole path depends on. Writing that section now would mean publishing install guidance ahead of its own verification, which is the defect this PR exists to remove.

Known, and not addressed here: brains-turn.sh reuses Codex's persisted MCP Authorization header as a capture credential when no capture token is set; brains-inbox.sh does not. A Codex user with header auth and no BRAINS_API_TOKEN therefore has capture on and the inbox off — so the two are credential-gated but not by the same credential set. Too fine a distinction to carry in card copy, and worth its own ticket if that configuration turns up in practice.

[nir-ssvlabs]

LGTM. No other reviews on this one, so I went after the things that would actually be critical rather than the prose: the publish mechanics, the one runtime file, and whether the new guards are as total as they claim.

Verified, not assumed:

• Publish is well-formed. Both manifests move 2.7.0 → 2.7.1, aligned and forward, and patch-shaped matches the convention this PR itself documents (fix(…) → patch). core.md is not one of the digest-pinned artifacts (only the two SKILL.md files are), so generated/capability-catalog.json being untouched is correct here rather than an omission — worth stating because a reviewer pattern-matching on "artifact changed, manifest didn't" would flag it wrongly.
• The only runtime file is comment-only. brains-turn.sh changes its header block and nothing else — no gate, no payload, no exit path moved. So the behavioural surface of this PR really is copy plus tests.
• The README composition pin is genuinely total, which is the load-bearing claim given this file's history of evadable pins. normalizeRegion(readme) === README_REGIONS.join("\n\n") is whole-file equality, not a set of includes — so there is no inter-region seam to write into, and the failure mode the two adversarial rounds kept finding is structurally gone rather than patched. The per-region pins staying ahead of it purely as locators is the right call.
• Ordering for v=6 is the safe direction, and this PR is the correct first step. db/init/338_catalog_core_v5.sql's own header states the rule verbatim — the public release must exist before the catalog migration deploys, or devices are told to update to a marker the marketplace does not serve. No catalog_core_v6 migration or PR exists yet, which is right.

One consequence worth stating plainly, because it bears on when this fix actually lands for users: publishing 2.7.1 fixes the claim for new installs, but existing devices keep serving core.md v=5 — with the "Capture is automatic … do not call save_chat_session" text — until the companion catalog_core_v6 migration ships and the SessionStart drift check starts emitting the update command. Since suppressing save_chat_session on claude.ai is the specific harm this PR exists to remove, the fix is only half-delivered at merge. BRNS-MCPWEB-021 is named in the description, but it's the step that makes this reach the installed base — worth filing as soon as this publishes rather than treating it as cleanup.

The measured-rate section is the right way to report n=3/n=5, and keeping the two Instructions-field conditions unpooled is the honest form. Agreed that collapsing those two README paragraphs into one reassuring sentence should be treated as a regression.

Approving.