Gate delegated discovery behind a KB lookup

[bguidolim]

Why

Claude reliably searches the project knowledge base before starting work — and then spawns discovery sub-agents in the same batch, handing them bare prompts. Sub-agents can't see the parent's search results, so they rediscover the same architecture from scratch: tens of thousands of tokens per agent, and occasionally conclusions that contradict what a memory already recorded.

This makes the KB lookup a prerequisite for delegating. A spawn whose prompt carries no KB findings is flagged or blocked, and any discovery agent that starts without them is told the knowledge base exists and to spend one search on it before touching files. Strictness is chosen per project at sync time and defaults to warning only, so installing this never starts blocking work unasked.

The escape hatch

Enforce mode must never wedge a session, so denials are budgeted — but a single per-turn counter can't do that job. Sized at one denial per turn it fails in both directions: a batch of parallel spawns is denied only once and the rest run blind before Claude has read the denial, and any denial leaves the gate disabled for the remainder of the turn even after Claude complies.

Each denial is therefore stamped with the number of KB searches recorded when it was written, and the same append-only file is counted two ways: denials since the last search (resets when Claude searches, so complying re-arms the gate, and wide enough that a fan-out is denied in full) and denials this turn (never resets, so termination is unconditional). Both stay keyed by phase. Appends only, never a read-modify-write — a batch can run these hooks concurrently and only an append is atomic.

Sized by cost asymmetry rather than symmetry: a denial is one cheap round-trip, an un-primed discovery agent is tens of thousands of tokens, so a generous budget errs in the cheap direction. Worst case is a bounded number of denials in a single turn, all of them cheap, and only in a turn where Claude is already failing to comply repeatedly.

Test plan

tests/kb-gate-test.sh drives every branch with crafted JSON — deterministic, no live session, no clock — and CI runs it twice per push, since a regression to timestamp-based scoping shows up as the second run behaving differently from the first. The fan-out and gate-survives-a-denial cases fail against the pre-budget implementation, which is what makes them regression tests rather than decoration.

• Fan-out — three spawns in one turn with no findings → all three denied, not just the first.
• Complying mid-turn — denied spawn, then search + KB context: block → allowed; a later spawn without a block in the same turn is denied again.
• Budgets — denials with no search in between → released once the no-progress budget is spent; denials with a search between each → released by the per-turn ceiling. Neither path can hang.
• Turn boundary — a search from the previous turn no longer satisfies the barrier.
• Skips — nested sub-agent calls, non-discovery agent types, projects with no .claude/memories/, empty payloads.
• Modes — warn advises without denying; observe and off never block.

The suite asserts a non-zero count of real denials before reporting success. Without that, a fixture missing .claude/memories/ would take the skip path on every call and the whole run would pass while testing nothing.

Against a real install: sync with the gate at enforce, spawn a discovery sub-agent whose prompt has no KB context: block → expect a denial naming the missing prerequisite; search the KB, re-issue the same spawn → expect it to run. Sync with the gate off → expect no blocking, no reminders, and no sub-agent briefing.

Decisions are recorded to .claude/.kb-gate.log in every mode; comparing its line count against the sub-agent spawns in a session transcript is the way to confirm the hooks are actually matching.