docs: guidance audit — refusals up front, version anchors, failure modes, resolution order, drift guards

Apply 7 proposed edits from guidance improver audit:
- CLAUDE.md: refusal rails up front, version anchor, resolution order
- BOOCHAT.md: resolution order section
- BOOCODER.md: tool reliability callouts
- data/AGENTS.md: tool list drift guard, failure modes preamble

data/AGENTS.md

@@ -1,4 +1,8 @@
-# Agents
+# Agents — v2.7.x (last meaningful update: 2026-06 — Supervisor agent added)
+
+## Parser contract — this file is PARSED programmatically, do not add free-form sections
+- Each agent is a `## Name` block followed by `---` YAML frontmatter. Content before the first `##` is discarded. Free-form `##` sections (not followed by `---`) break `agents.ts:splitSections` — the parser throws and no agents load. Cross-cutting agent rules belong in CLAUDE.md, not here.
+- If an agent stops appearing in the AgentPicker, check: (1) frontmatter `---` fence is present after the `## Name` heading, (2) no YAML parse errors in the frontmatter fields, (3) the name is not empty/hyphenated in a way the parser doesn't handle.
 
 Operating rules for every agent in this registry. Full procedures live in the `committing-changes` and `using-worktrees` skills.
 
@@ -10,6 +14,15 @@ Operating rules for every agent in this registry. Full procedures live in the `c
 
 **Reasoning budget** — To cap a reasoning model's thinking tokens, pass `--reasoning-budget` through `llama_extra_args` (already permitted by the deny-list validator; routes the agent to llama-sidecar). Example frontmatter line: `llama_extra_args: ["--reasoning-budget", "2048"]`. This is a sidecar process flag, not a chat-completion body param — distinct from the sampling knobs above.
 
+## Tool list drift guard
+Every agent's `tools:` list MUST stay in sync with `ALL_TOOLS` in `apps/server/src/services/tools/registry.ts`. Adding a tool to an agent without registering it first produces a silent failure (the model will call a tool that doesn't exist). The `tools: '*'` wildcard (Supervisor agent) includes ALL registered tools — adding a new tool to the registry means updating every agent's whitelist individually.
+
+## Failure modes (applies to all agents)
+- Tools can return empty results. Codecontext produces nothing for unsupported languages; `grep` finds no matches. This is not a system failure — fall back to a different tool.
+- `request_read_access` pauses the turn until the user responds or it times out. If it returns "denied", do not retry — use a different approach.
+- `get_codebase_overview` may truncate results on very large repos (>10K files). Cross-check with `get_hot_files` and `list_dir`.
+- Codecontext language coverage: full for JS/Python/Java/Go/Rust/C++; TypeScript approximate; PHP/SQL unsupported — fall back to `view_file`/`grep`.
+
 ## Code Reviewer
 ---
 temperature: 0.6
@@ -332,3 +345,12 @@ Rules:
 - If a change breaks an import or type, fix it in the same batch before applying.
 - Use rewind if a batch of changes is wrong. Do not apply broken changes.
 - When done, state what changed and what the user should verify (type check, test, manual check)
+
+## Supervisor
+---
+description: Dynamically routes requests to the best agent for the task
+tools: '*'
+temperature: 0.1
+steps: 0
+---
+Your job is to classify the user's request and determine which specialized agent should handle it. Available agents are provided in the system prompt. Choose the best fit.