yoyo-evolve

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Is

A self-evolving coding agent CLI built on [yoagent](https://github.com/yologdev/yoagent). The agent spans multiple Rust source files under `src/`. A GitHub Actions cron job (`scripts/evolve.sh`) runs the agent on a schedule using a 3-phase pipeline (plan → implement → respond), which reads its own source, picks improvements, implements them, and commits — if tests pass. **The cadence and the model are parameters, not facts about this project, and they are deliberately not written down here.** The schedule lives in `.github/workflows/evolve.yml` (`schedule.cron`) and the provider, model and their knobs in `.yoyo.toml` only — every script and workflow reads the model from there (a `MODEL` env var overrides one run; there is no `MODEL` secret, and `tests/harness_logic.sh` fails if a model id is hardcoded anywhere else, because provider in one place and model in another is how Days 210-211 sent a DeepSeek id to Anthropic). Read those rather than this file, because a value copied into prose goes stale silently while the config keeps working. Two things about that config are *not* derivable from reading it, so they are recorded here instead:

- **The provider-key line in every workflow is load-bearing, not tidiness.** yoyo's key lookup falls back to `ANTHROPIC_API_KEY` and then `API_KEY` when the configured provider's own variable is unset, so a workflow that forgets to export the provider's key does not fail loudly — it sends the wrong provider's token and gets a 401. Every workflow that runs yoyo must export the key for whichever provider `.yoyo.toml` names.
- **`thinking = "high"` is still the top rung yoyo sends, but now by yoyo's choice, not yoagent's limit.** Superseded claim (yoagent 0.24.0 upgrade, Day 218, #987), recorded rather than erased: this bullet said yoagent 0.18.1 had nothing above `High`. Since 0.19 `ThinkingLevel` has `XHigh` and `Max` (`#[non_exhaustive]`), and on OpenAI-compatible providers `Max` can go out as `max`. yoyo itself still folds `max` to `High` in `src/cli.rs`/`src/config.rs`; sending a higher tier is a priced decision that has not been made <!-- yoagent-version-claim: 0.24.2 -->.

### Changing the model

The loop's provider and model are the two top-level keys `provider` and `model` in `.yoyo.toml`, and nowhere else: every script reads `model` from there, the workflows set no `MODEL`, and there is no `MODEL` secret. A change is one reviewed commit:

1. **Edit `provider` and `model` together in `.yoyo.toml`**, as top-level keys above any `[section]` (the scripts stop reading at the first section). Never change one without checking the other; a model id sent to the wrong provider fails on every call (Days 210-211: 404s).
2. **Check the knobs in the same file against the new model's documented limits.** `max_tokens` must not exceed the model's output maximum, or every call is a 400 (131072 against a 128000 cap, 2026-09-27). Remember that an OpenAI-compatible arm without its own preset gets `max_tokens = 4096` and a 128K window from the base config, which silently caps reasoning plus answer. `context_window` must fit the model's window with margin (see the comment on that key). `thinking` must be a level the model accepts.
3. **If the provider changes, export its API key** in every workflow under `.github/workflows/` that runs yoyo (today: evolve, social, dream, skill-evolve and synthesize). See the provider-key bullet above for why a missing key fails as a 401 rather than loudly.
4. **Know what may lag a brand-new id:** yoyo's known-model list and `/cost` pricing (a warning, and possibly wrong cost figures, not a failure). Nothing else needs touching: even the commitment scanner makes its call through yoyo, so it follows the same provider, model and credentials.
5. **Verify before relying on the cron:** `bash tests/harness_logic.sh` (fails on any hardcoded model id and checks both keys are present), `cargo test` (some tests read the repo's own `.yoyo.toml`), and `yoyo config get model`. Then push and run `gh workflow run evolve.yml`. The log prints `model: <id>` in plain text. A bad id or bad knob stops the session at assessment with `API error in assessment agent`, and a green run that commits nothing is the signal to read the log.

To try a model for one run without committing, set `MODEL` in the environment of a local run; nothing in CI sets it.

Sponsors get benefit tiers (issue priority, shoutout issues) but no run-frequency speedup. Every sponsor, any amount, is listed in README.md permanently — listings never expire and are never pruned (creator decision 2026-07-13; the old accelerated-run credits and the 90-day listing/grace windows are retired).

**Sponsor benefit tiers:**

All sponsors (any amount, recurring or one-time): permanent README listing.

Monthly recurring:
- $5/mo: Issue priority (💖)
- $10/mo: Priority + shoutout issue

One-time (cumulative):
- $5: Issue priority (14 days)
- $10: Above + shoutout issue (30 days)
- $1,000 💎 Genesis: Permanent priority + top billing + journal acknowledgment

## Build & Test Commands

```bash
cargo build              # Build
cargo test               # Run tests
cargo clippy --all-targets -- -D warnings   # Lint (CI treats warnings as errors)
cargo fmt -- --check     # Format check
cargo fmt                # Auto-format
```

CI runs all four checks (build, test, clippy with -D warnings, fmt check) on PR to main. A separate Pages workflow builds and deploys the website on push to main.

**Pre-push hook** (`.githooks/pre-push`, tracked, opt-in per clone — `git config core.hooksPath .githooks`): lints the **tip commit of each pushed ref** with `scripts/lint_evolve_heredocs.py` and refuses the push if it fails. The rule: no apostrophe inside a `${VAR:+...}` / `${VAR:-...}` block in `scripts/evolve.sh`, because bash interprets single quotes in a parameter-expansion word and one apostrophe yields `bad substitution: no closing }`. `evolve.sh` then dies **at that heredoc, mid-session** — agents before it have already spent their budget and every phase after it never runs (`d93e4f65` broke the Phase A2 planner prompt, so the A1 assessment agent had already run; `9847db2`'s instance was in the journal prompt near the end). It has **landed twice** — `988975d9` introduced it and `9847db2` fixed it after two symptom-chasing attempts (`cb9d9b0`, `25f4e90`); `d93e4f65` landed it again and `050e300c` fixed it. `scripts/lint_evolve_heredocs.py`'s docstring is the authoritative history — that count has already drifted once, so correct it there and point here.

Why a hook when CI runs the same lint: CI only runs *after* the push, which is the event this prevents; and because the lint is CI's first check step, a failure there means nothing else in the job ran on that commit either — not the harness tests, not build/test/clippy/fmt. (On a branch that is neither `main` nor a PR to `main`, CI does not run at all.) `bash -n` does **not** catch it — the expansion only fails at runtime. It checks pushed commits rather than the working tree because the tree-based first version passed a push whose commit was broken while the tree was already fixed but unstaged — exactly the state you occupy while fixing this bug. Failures are separated: a real violation says "fix the above, or `--no-verify`", while a missing linter or `python3` says the file is **UNVERIFIED** and that `--no-verify` would push it unchecked ("could not check" must not read as "checked; clean"). **Covers local pushes by whoever ran the opt-in — not the bot**, which pushes from CI with no `hooksPath`; that is tolerable only because `scripts/evolve.sh` is a protected file the agent cannot modify, with CI as the backstop. Keep the hook to checks well under a second (currently ~80ms) — everything slow stays in CI.

**The eleven invariant gates and the per-file notes now live in [ARCHITECTURE.md](ARCHITECTURE.md), not here.** They were moved out on 2026-09-15 for a measured reason: this file is appended to the system prompt of **every** invocation of every loop (`load_project_context`, `src/cli.rs`), and it had reached **1.4 MB — about 352K tokens — of which 97.6% was accumulated per-file history**. That crowded the prompt of every session, and it is the measured cause of the Day-199 DeepSeek session that compacted on its first turn and lost its own task (no assessment, 0 planned tasks, an evaluator that never wrote its verdict file — #925). Nothing was deleted: the move was contiguous and byte-preserving.

**Read ARCHITECTURE.md's entry for any file you are about to change.** It carries the gate rules and remedies, the superseded-claim record, and the per-file history — and it is the only place that has them. A gate you trip without knowing it existed is exactly what that file prevents, so opening it is part of touching a file, not optional.

**New history goes in ARCHITECTURE.md, never here.** Keep CLAUDE.md to what every session needs *before* it knows which file it is touching: what this project is, how to build and test it, the safety rules, the two audiences, and the MCP/yoagent/RLM notes. If you find yourself appending a measurement, a positive control, a census or a superseded claim to this file, it belongs in ARCHITECTURE.md under the file it is about. This file growing back past ~40 KB is itself the defect.

## RLM substrate

yoyo has shared-state recursive sub-agent dispatch — the [Recursive Language Model](https://alexzhang13.github.io/blog/2025/rlm/) pattern, scaled down to one yoagent primitive plus skill-level conventions. The substrate is in place; specific skills opt into it.

**What's available:**
- `build_sub_agent_tool` in `src/tools.rs` returns `(SubAgentTool, SharedState)`. Parent agents get a handle to pre-populate; sub-agents automatically receive a `shared_state` tool that reads/writes the same yoagent::SharedState key-value store. (Skills opt into this by adding `sub_agent` and `shared_state` to their `tools:` frontmatter.)
- Artifacts are stored once and read by reference rather than re-pasted into every sub-agent prompt. Namespace convention: `<skill>.<key>` (e.g., `trajectory.run-12345`, `research.topic.source-3`).
- `shared_state` is in `BUILTIN_TOOL_NAMES` (MCP collision guard).
- Canonical example: `skills/analyze-trajectory/SKILL.md` — see its "Handle large artifacts" section for chunking, "Dispatch a sub-agent" section for the JSON contract, and "Recurse" section for the depth cap.

**When to reach for RLM:**
- The artifact is too large for one prompt (>5KB triggers sub-agent dispatch; chunk if >30KB).
- The work is decomposable — different focused questions over the same artifact, each independently answerable.
- Fidelity loss is acceptable — sub-agents return summaries, not raw text. (Use direct read when exact diffs matter.)
- Cross-piece reasoning is light — each sub-question can be answered locally.

**When NOT to reach for RLM:**
- The artifact is small (≤5KB; if exactly 5KB, prefer direct read) — sub-agent overhead exceeds the savings.
- The task needs *precise* control (writing code, surgical edits) — fidelity-loss in sub-agent summaries is fatal here.
- The work is sequential with strong mutual context — refactoring needs to see all pieces at once.
- You're already inside a sub-agent and depth=3 is reached — stop, return what you have, do not dispatch further.

**Established pattern in yoyo:**
1. Parent fetches the artifact via `bash`, then stores it under `<skill>.<key>` via the `shared_state` tool's `set` op. The parent gets `shared_state` exactly when it gets `sub_agent` — both are pushed together in `agent_builder.rs` and are absent together under `--no-tools` (#715; before Day 163 only sub-agents had the tool, so this step silently did nothing at the top level).
2. Parent calls the `sub_agent` tool with a *focused question* and a *reference* to the shared-state key — never the artifact itself in the prompt.
3. Sub-agent reads via `shared_state.get`, returns a JSON-shaped summary (see `analyze-trajectory`'s "Dispatch a sub-agent" section for the schema).
4. Parent recurses on `deeper_question` if confidence is low. Hard depth cap = 3 (counts each sub_agent dispatch toward the budget).
5. On sub-agent failure / non-JSON response, fall back to direct read of a slice and produce a low-confidence diagnosis.

For the broader capability roadmap (codebase archaeology, semantic git bisect, multi-source research synthesis, large-scale refactor coordination, etc.), see issue #341.

## MCP gotchas

**Tool-name collisions (Day 39):** If an MCP server exposes a tool whose name matches one of yoyo's builtins (`bash`, `read_file`, `write_file`, `edit_file`, `list_files`, `search`, `rename_symbol`, `ask_user`, `todo`, `web_search`, `sub_agent`, `shared_state`), the Anthropic API will reject the first turn with `"Tool names must be unique"` and the session dies. The flagship reference server `@modelcontextprotocol/server-filesystem` collides on `read_file` AND `write_file`, so the common case was broken until the guard landed.

yoyo now runs a pre-flight tool listing (via a short-lived `yoagent::mcp::McpClient`) before every `with_mcp_server_stdio` call. If any MCP tool name appears in `BUILTIN_TOOL_NAMES` (defined in `src/agent_builder.rs`), the whole server is skipped with a clear stderr warning naming the colliding tool(s). Non-colliding servers connect normally.

**Superseded claim, recorded rather than erased (Day 180, #841).** This paragraph used to end: *"If the pre-flight itself fails (e.g. server can't spawn), we fall through to yoagent's connect so the user sees the real diagnostic."* That sentence was true **only for the one case it was written for** — a server that cannot spawn at all — and it reads far wider than it is, because it silently assumes *pre-flight failure implies connect failure*. The pre-flight and the real connect are **two separate spawns** with different timing, so a slow start, a transient env problem or a `list_tools` timeout can fail the pre-flight while the real connect **succeeds**. In that branch the fall-through disabled the guard **completely** for that server, and it failed **open**: the colliding tools were registered and the session died on turn one with the exact `Tool names must be unique` rejection the guard exists to prevent — with the only clue a DIM line that scrolled past during startup. Named instance: a `@modelcontextprotocol/server-filesystem`-shaped server (collides on `read_file` **and** `write_file`) whose pre-flight errs once. **The guard itself was never wrong; the defect was the placement of the fall-through.**

**What replaced it, in two parts.** (1) The pre-flight is **retried once** before anything falls through — `MCP_PREFLIGHT_ATTEMPTS = 2`, looped inside `fetch_mcp_tool_names_retrying` — so a single transient failure, which is the realistic case and the one that produced the silent fail-open, is recovered and the guard runs normally. **The stated tradeoff, written into the const's doc comment rather than left to be discovered:** this costs one extra spawn **on the failure path only**, so a genuinely dead server pays a second fast failure before yoagent's real diagnostic appears. That is the price of the guard running at all, and it is named so the next reader does not "simplify" the retry away. A healthy server returns on attempt 1 and is byte-identical to before. (2) Only after the last attempt fails does the code fall through — **kept deliberately**, because a genuinely dead server *should* still reach `with_mcp_server_stdio` so the user sees yoagent's real diagnostic; that is the branch the old sentence was written for and it is correct there. What changed is that the branch now says what is true, via the pure, table-tested `collision_guard_skipped_message(server_cmd, err, plain)`, which states three things the old text did not: that the collision guard **did not run** for this server, naming the server command (a user cannot act on a server they cannot identify); the error that stopped it; and **the symptom to expect** — if this server exposes a builtin name, the session will die on turn one with `Tool names must be unique`. Glyph-free under `is_plain_output()` (bullets *and* em dashes), matching `project_mcp_refusal_message`; the existing quiet-gating is unchanged. **Day 184 (#873): BOTH interpolated strings are sanitized through `cli::sanitize_for_display` before they reach the terminal, and this site deliberately has NO CAP — stated plainly rather than implied, because it is the one asymmetry with its three siblings.** The two strings have **different provenance and the same terminal**, which is why neither is trusted: `server_cmd` is the resolved MCP server command from a project-local `.yoyo.toml`, i.e. repository-authored exactly like the strings `cli.rs` already escapes, while `err` is a pre-flight failure string from a **spawned subprocess** — not repo-authored, and not obviously safe either. **Adding a cap here was deliberately declined rather than overlooked:** this message has never had one, so bundling a length budget with an escaping fix would have widened a verified narrow change into an unverified one, and it is a separate judgment call about how much of a subprocess error is worth showing. Sanitizing without capping is still a strict improvement. **Superseded claim, recorded rather than erased: this bullet read "naming the server command **verbatim**" until Day 184.** The three pre-existing tests (`collision_guard_skipped_message_names_server_guard_and_symptom`, `..._no_longer_claims_connect_will_fail`, `..._is_glyph_free_when_plain`) were **not** edited or weakened and stayed green throughout, which is the regression evidence; the new tests assert on **bytes** at the emission point (`!out.as_bytes().contains(&0x1b)` on the string a caller receives, never an eyeballed terminal), carry an **anti-vacuous** assertion that each fixture really does contain the hostile byte so a transcription slip cannot make a test pass by agreeing with itself, and sit beside the **near-miss guard that matters** — an ordinary control-free command and error render **byte-identically** via full-string `assert_eq!` rather than a `contains`, which is every user whose config carries no control bytes and is the whole regression surface. **The limit is the same one the `cli.rs` refusals carry and it is worth repeating rather than cross-referencing: this makes an untrusted string LEGIBLE, not SAFE.** Bidi overrides (U+202E) and zero-width characters are **not** escaped — they are not `Cc`, and widening to them would break the byte-identical pass-through that is the function's own near-miss guard. The boundary still answers *who wrote this*, never *is this safe*.

**Both loops share one statement of each.** The `--mcp` flag loop and the `[mcp_servers.*]` config loop each carry their own copy of this `match`, and both call the same `fetch_mcp_tool_names_retrying` and the same `collision_guard_skipped_message` — never two copies that agree today. Fixing one would have been the "two doors, one policy, one deaf" shape this repo has now shipped six times (#745, #767, #769, #816, `/config show`, sub-agent fallback). The message is pinned at the **emission point** (the exact string a caller receives, in both plain and non-plain form), `detect_mcp_collisions`'s pre-existing tests are untouched and green, and the retry loop — which is `async` and spawns real processes — carries only a deliberately **weak** source-level guard that the `Err` path consults `MCP_PREFLIGHT_ATTEMPTS`: it proves the const is *referenced*, never that the retry works, and its doc comment says so.

**Day 181 (#842) — the count a failed connect leaves behind is now honest, and the servers are still gone.** `connect_external_servers` returns `(agent, mcp_count, openapi_count)`, and on a connect failure yoagent has **consumed** the agent, so every `Err` arm rebuilds it with `agent_config.build_agent()` — a **fresh** agent carrying **zero** external connections, which the pre-existing comment already said outright. Neither counter was reset, so with three MCP servers whose *last* one is misconfigured the user lost **all three** and was told `mcp_count == 3`; the only notice was one DIM line reading `previous MCP connections lost`, which does not say *how many*, and the count is the thing that was wrong. `main.rs` receives that tuple as `mc` and reports it. **The fix is a reset plus a number, not a reconnection:** each rebuild arm resets the counter it just invalidated and prints the pure, table-tested `connections_lost_note(kind, lost, plain) -> Option<String>`, which names **how many** were dropped and what to do about it. **`None` when `lost == 0` is the whole regression surface** — a *first*-server failure drops nothing, which is the common case, and that path stays byte-identical to before (pinned by the table's zero rows, for both `plain` values and both kinds). Singular/plural agree, the `kind` is carried so an OpenAPI failure cannot report as `mcp`, and it is glyph-free under `is_plain_output()` (marker *and* em dash), matching `project_mcp_refusal_message` and `collision_guard_skipped_message`; the existing quiet gating at the call site is unchanged, and the note is built **before** the reset or it would faithfully report zero.

**Superseded claim, recorded rather than erased — and it is #842's own text that was wrong, which is why step 1 of the task was to settle it rather than trust it.** The issue asserted the OpenAPI loop "does not rebuild the agent, so its count stays honest". **Read at HEAD, it does rebuild** — `agent = agent_config.build_agent()` sits in its `Err` arm exactly as in the two MCP loops — so it carried the identical defect and was fixed in the same diff; fixing two of three doors would have been the "two doors, one policy, one deaf" shape this repo has now shipped six times. That arm resets **both** counters, and the asymmetry is the point rather than an over-reach: the rebuilt agent drops the MCP connections made **earlier in the same function** too, so an OpenAPI failure invalidates `mcp_count` as well, while an MCP failure cannot invalidate `openapi_count` because the OpenAPI loop has not run yet. Both notes are emitted, each naming its own kind.

**`connect_external_servers` is `async` and spawns real processes, so it gets only a deliberately weak source-level guard** (`every_rebuild_arm_resets_the_counter_it_invalidated`), and its doc comment says so: it slices this one function's body — `build_agent()` has other callers in the file — and asserts **exactly three** rebuild sites, **three** `mcp_count = 0` resets, **one** `openapi_count = 0` reset, and **four** `connections_lost_note(` call sites, with every needle assembled at runtime so the test cannot match itself. **It proves each reset is *present*, never that it fires** — the same discipline the `format/mod.rs` wrapper guards state about themselves — and the exact-count form is deliberate: a fourth rebuild site fails the test, forcing whoever adds it to decide what it invalidates. **Positive control run rather than assumed:** neutering `connections_lost_note` to always return `None` reddens the table test, and deleting one counter reset reddens the source guard; restoring returns green.

**The residue, stated plainly rather than implied: the count is now honest and the servers are still dropped.** Nothing reconnects the survivors — a user whose third server is misconfigured still loses the first two, and now gets told so. Reconnection is the better and much larger fix, it interacts with the fail-open pre-flight guard above (#841's option 2), and it is a **separate issue**; #842 filed the honest-count half separately *because* it is small and strictly an improvement either way.

**Deliberately not done, named rather than smuggled in:** reconnecting the survivors after a rebuild (above); **option 2 of #841**, a post-connect collision re-check, which collides with that same rebuild-drops-servers behaviour and is a larger change; and the **double-spawn disclosure** (every configured stdio MCP server is started twice per session — once by the pre-flight, once by the real connect; the second spawn is inherent, since a stdio server cannot be enumerated without running it) remains measured and unfiled, so only its disclosure half is actionable.

**Day 181 (#843's sibling; self-discovered, transferred class) — a connect failure now reaches the MODEL, and it is the THIRD door of a class I had been counting as two.** Days 180–181 spent two whole tasks on this exact subsystem — **#841** (the collision-guard-skipped message) and **#842** (the honest `mcp_count`) — and **both write to the user's stderr**. I fixed the user's view twice and never noticed the model had no view at all: `compose_system_prompt(base, provider, model)` takes exactly three arguments and `connect_external_servers` returned two *counts* and no names, so **nothing anywhere handed the model an error — it was handed an absence.** That is the whole severity of it: a model that cannot see a tool does not conclude *that server is down*, it concludes **the capability does not exist**, and then silently works around it — reimplements the thing by hand, or reports the task impossible — while the user sees a dim startup line they have already scrolled past. So the "two doors, one policy, one deaf" count was itself wrong: the third door is not a code path, it is **a prompt**. Independently confirmed by a rival the same week: Claude Code v2.1.247 (2026-08-26) shipped verbatim *"Claude is now told when a configured MCP server failed to connect, instead of concluding its tools don't exist."*

**The system prompt is the wrong seam, and the reason is mechanical rather than stylistic — a comment in `connect_external_servers` says so, so a later reader does not "simplify" it back.** The system prompt is composed inside `build_agent()`, which runs **before** `connect_external_servers` is ever called (`src/main.rs` passes the already-built agent *in*), so at composition time the failure does not exist yet. And it cannot be fixed by recomposing afterwards: `AgentConfig::build_agent()` returns an agent carrying **zero** external connections — that is precisely the #842 finding fixed the previous day — so a rebuild to add a sentence would **drop every server that did connect**, trading a missing sentence for missing tools. The seam that works is the one `[Effort: …]` already uses: **prepend to the turn**.

**Both prompt seams are wired, because wiring one is the failure this task is about, one layer down.** `src/prompt.rs` has two deliberately un-unified paths, and each gets the note in its own idiom: the **text path** via `apply_external_failure_note_with(note, input)` (prefix + `\n\n` + input), and the **image/content path** via `prepend_external_failure_block_with(note, blocks)`, which inserts a **new leading `Content::Text` block** rather than splicing into an existing one — `content` may carry non-text blocks and rewriting one would mangle them. **`None` returns the input unchanged, byte-identically, on both paths**, which is every user whose servers all connect *and* every user who configured none — the entire regression surface, pinned with `assert_eq!` rather than a `contains`.

**The record is written where the user-facing note is already composed, and `main.rs` needed no edit.** All three `Err` arms of `connect_external_servers` already know which server failed and already build `connections_lost_note`, so each also calls `record_failed_server(kind, id)` into a module-level store — the resolved command string for MCP, the spec path/URL for OpenAPI. Threading a return value out would have touched a third file for nothing. **The kind is carried, never inferred** — a note that misattributes the source is worse than none, the same rule `connections_lost_note` already follows. The composer `external_tool_failure_note(&[FailedServer]) -> Option<String>` is pure and table-tested, **returns `None` for an empty slice**, and **invents nothing**: a failed connect means yoyo never learned which tools that server exposes, so it names the *server* and never guesses a tool name — claiming "the `read_file` tool is missing" when we do not know is the confident-wrong-diagnosis defect. What it *does* say is the half the model cannot infer from an absence: the capability was **configured**, the gap is a **connection failure**, and the honest move is to report the tool unavailable **and name the server** rather than substituting a hand-rolled implementation. The interpolated identifier is capped at `EXTERNAL_FAILURE_ID_MAX_BYTES = 200` on a **char** boundary with the cut marked in band (never a raw byte index, #250 — the discipline `goal_verify_refusal_message` already uses), and the reported dropped-byte count agrees with what was actually dropped.

**It fires once per session, and both seams share the same one-shot.** `take_external_failure_note()` **drains** the store, so the first prompt of the session carries the note and later turns are byte-identical to the no-failure case — a note repeated every turn is context spend with no new information, and it would go stale the moment a later `/mcp` reconnects. Two seams reading two separate flags is how the content path re-fires what the text path already consumed, so there is exactly one. The drain is tested through `drain_failure_note(&store)`, which takes the store as a **parameter** so tests drive a local `Mutex` instead of the process-global one (the `context_budget_warning_with` seam, and the remedy `tests/global_state_races.rs` names as its best).

**The collision-guard skip is deliberately NOT recorded, and the omission is written at the branch rather than left ambiguous.** A server refused for exposing a builtin name is a **refusal working as designed**, not a connection failure: the capability is not missing at all — the builtin is right there in the tool list — so telling the model it is unavailable would be the confident-wrong-diagnosis defect, and dressing a guard working as designed as a malfunction is the same short-circuit `RecoveryHintTool` and `DiagnosticSubAgentTool` already make for `REFUSAL_STEM_*` (#710).

**Out of scope, named rather than implied: no reconnection and no change to the stderr notes.** A failed server stays failed — this makes the failure *legible to the model*, nothing more; reconnection is #841 option 2 and collides with the rebuild-drops-servers behaviour. `connections_lost_note` and `collision_guard_skipped_message` are byte-identical: this **adds a second audience, it does not move the first**. Tested at the **emission point** — the string/blocks the model actually receives, never the composer one layer below — in both directions: no failures → both paths byte-identical (`assert_eq!`); one MCP failure → named verbatim and reported unavailable-not-nonexistent; one OpenAPI failure → same, reporting `openapi` and not `mcp`; two consecutive prompts → the second is byte-identical to the no-failure case. **Positive control run rather than assumed, and serially** (a parallel pair of file-mutating controls raced once and one falsely passed): neutering `external_tool_failure_note` to always return `None` fails exactly the failure-path tests while every near-miss guard stays green.

Keep `BUILTIN_TOOL_NAMES` in sync with `tools::build_tools` and the sub-agent's `SharedStateTool` whenever a new builtin is added — the pure helper `detect_mcp_collisions` is unit-tested in `src/agent_builder.rs` against the filesystem server's known tool set as a regression guard. **Day 192 (#892) — the const gained a THIRD cross-module consumer, and the count is stated precisely because the task that added it asserted a wrong one.** Its readers are now: the two in-file MCP-collision-guard sites; `src/cli.rs:597` (`compute_lite_disallowed_tools`, the `--lite` path) and `src/cli.rs:2665` (the `--no-tools` disallow list), both of which predate Day 192; and `src/hooks.rs`'s `unknown_hook_tool_warning`, which asks *does any builtin have this name?* of a hook config key. **No visibility edit was made or needed** — the const has been `pub(crate)` since Day 191 (`53ee8d7a`), so #892's task file specifying *"→ `pub(crate)`, with its consumer landing in the same diff"* was describing work already done, which is why that diff touched one file. **This is exactly the drift the Day-180 guards were built to protect, and the stake rises with each reader:** the superset guard (every name `build_tools` registers must be listed) and its near-miss twin (the three names `build_tools` does *not* register — `ask_user`, `sub_agent`, `shared_state` — must stay listed) now defend four consumers rather than one, and a name silently dropped from the const would no longer merely un-guard an MCP collision; it would also drop a tool from `--lite`'s disallow computation and make `hooks.rs` warn about a **real** builtin, which is the cry-wolf direction that trains a reader to paste past the warning. The const stays the single authority: **every consumer reads it, none copies it.**

## yoagent: Don't Reinvent the Wheel

yoyo is built on [yoagent](https://github.com/yologdev/yoagent). Before implementing any agent-related or low-level agent feature, **check if yoagent already provides it**. Past examples of reinvented wheels:
- Manual context compaction (`compact_agent`, `auto_compact_if_needed`) — yoagent has `ContextConfig`, `CompactionStrategy`, and built-in 3-level compaction
- Hardcoded token limits — yoagent has `ExecutionLimits` (max_turns, max_total_tokens, max_duration)
- Ignoring `MessageStart`/`MessageEnd` events — yoagent streams these for agent stop messages

**Before building agent infrastructure in src/:**
1. Search yoagent's source (`~/.cargo/registry/src/*/yoagent-*/src/`) for existing features
2. Check yoagent's `Agent` builder methods, tool traits, callbacks (`on_before_turn`, `on_after_turn`, `on_error`), and examples
3. If yoagent has it → use it. If yoagent almost has it → file an issue on yoagent. If yoagent doesn't have it → build it in yoyo.

Key yoagent features available: `SubAgentTool`, `SharedState`, `SharedStateTool`, `ContextConfig`, `ExecutionLimits`, `CompactionStrategy`, `AgentEvent` stream, `default_tools()`, `SkillSet`, `with_sub_agent()`. For `SharedState` / sub-agent recursion details and decision trees, see the **RLM substrate** section above.

**yoagent 0.7.x prompt lifecycle gotcha (Issue #258):** `agent.prompt()` / `agent.prompt_messages()` spawns the agent loop into a tokio task and returns the event receiver immediately. The agent's internal `self.messages` is NOT updated until `agent.finish().await` is called. If you read `agent.messages()` (or `total_tokens(agent.messages())`) right after draining the event stream WITHOUT calling `finish()` first, you will see the stale pre-prompt state — which silently breaks anything that depends on message count (e.g., the context-window usage bar). Always call `agent.finish().await` between event drain and message read.

## Two Audiences: product vs evolve

yoyo serves two different customers, and every task must know which one it's for:

- **product** — people who install yoyo and use it on *their* projects: any
  language, any setup, local models, no CI. Product surface (defaults, CLI
  flags, setup wizard, startup behavior, docs) must be safe for all of them.
- **evolve** — yoyo's own evolution loop: always this Rust repo, fast tests,
  CI. Conveniences built for this loop are fine — but they must be **opt-in**
  the moment they touch anything a product user sees.

The rule: **defaults must be product-safe; evolution-loop conveniences are
opt-in.** Issue #448 is the canonical failure — auto-watch was built for the
evolve loop and shipped as a product default, breaking non-Rust users. Every
planned task declares `Kind: product` or `Kind: evolve` in its task file; the
evaluator rejects evolve-kind changes to product surface that aren't opt-in.

## Safety Rules

These are enforced by the `evolve` skill and `evolve.sh`:
- Never modify `IDENTITY.md`, `PERSONALITY.md`, `ECONOMICS.md`, `scripts/evolve.sh`, `scripts/format_issues.py`, `scripts/build_site.py`, or `.github/workflows/`
- Every code change must pass `cargo build && cargo test`
- If build fails after changes, revert with `git checkout -- src/ Cargo.toml Cargo.lock`
- Never delete existing tests
- Multiple tasks per evolution session, each verified independently
- Write tests before adding features
- **Every deliberate sabotage of a guard, function or classifier must carry a marker, and the tree cannot be green until it is removed.** Running a positive control has two halves — break the guard and watch it fail *by name*, then **restore it and watch it pass**. The second half is the one with no natural owner, and skipping it once cost ~22 hours of red `main` plus four reverted sessions (`src/cli.rs`'s `sanitize_for_display` shipped with `return s.to_string(); // NEUTERED POSITIVE CONTROL` above its real body). So when you neuter anything — for a positive control or any other reason — put `NEUTERED`, `DO NOT COMMIT`, `SABOTAGE` or `TEMPORARILY DISABLED` on the line, and `tests/neutered_guards.rs` will refuse to pass until you take it out or name it in `REGISTERED_MARKERS`. Best practice is stronger than the marker: issue the mutate→run→restore as **one atomic command** so the restore cannot be forgotten, and run file-mutating controls **serially** (two in one parallel block raced once and one falsely *passed*). Three limits, so this is not over-trusted: it does **not** cover the `session wrap-up` sweep (`scripts/evolve.sh` commits with `git add -A` and no build/test check, and that file is protected); it is **redundant with `unreachable_code`** for a `return` placed above a live body, which clippy already makes fatal; and the genuinely new coverage is the **silent** case — a neutered branch no test covers, and a neutered helper in `scripts/*.py`, where `cargo test` gives zero coverage.
- **Never use byte indexing on strings.** `s[..n]`, `s.truncate(n)`, and `s.split_at(n)` panic if `n` falls inside a multi-byte UTF-8 character. Use `is_char_boundary()` to find a safe boundary first:
  ```rust
  // BAD: panics on multi-byte chars like ✓ (3 bytes)
  acc.truncate(max_bytes);
  // GOOD: find nearest char boundary
  let mut b = max_bytes;
  while b > 0 && !acc.is_char_boundary(b) { b -= 1; }
  acc.truncate(b);
  ```
  This caused planning agent crashes in production (#250).
- **`run_git()` has a `#[cfg(test)]` destructive-command guard.** During `cargo test`, calling `run_git()` with a destructive subcommand (commit, revert, reset, push, checkout, etc.) from the project root panics. Tests that need destructive git operations must use a temp directory. This prevents tests from accidentally mutating the real repo (which caused a 6-session deadlock across Days 42-44).
- **Never add a definition without its consumer in the same edit.** A new `fn`, `let`, or enum variant that nothing reads breaks the build, and the gate reverts the *whole* task — including the correct work sitting beside it. Dead functions and unread variables fail clippy under `-D warnings` (`-D dead-code`, `-D unused-variables`, `-D unused-assignments`); a new enum variant fails `cargo build` outright with `E0004 non-exhaustive patterns`. So: add a helper → add its call site. Add a variable → add the code that reads it. Add an enum variant → update every `match` on that enum. If you genuinely need the definition before the consumer, don't leave it dangling for a later step — inline the logic at the call site instead, or finish both halves before ending the turn. Three reverts in fourteen days from this one shape: #618 (functions), #653 (functions), #658 (variable), plus sibling #647 (enum variant).
- **Before declaring any task complete, run `cargo clippy --all-targets -- -D warnings` explicitly** rather than relying on auto-watch. The last edit of a task is the one most likely to be unlinted: watch runs mid-turn, skips when nothing changed, and the task can end before anything re-lints.

More agent context in yologdev/yoyo-evolve

14 other files this repository gives its agents.