0.1 Create the Cargo workspace

anvil/Cargo.toml · crates/llm · crates/agent · crates/cli

Make a virtual workspace with three member crates. llm is a library that knows about providers and nothing else. agent is a library that depends on llm. cli is a binary named anvil that depends on both. Declare shared dependency versions once in [workspace.dependencies] and have members inherit them with dep.workspace = true. Use edition 2024.

Start with these deps: tokio (full), serde (derive), serde_json, thiserror, anyhow (CLI only), async-trait, futures, reqwest (json + stream), async-stream, tokio-util, tracing. Dev deps: insta, wiremock, tempfile.

• cargo build --workspace succeeds.
• cargo run -p cli prints a line, and the binary is named anvil.
• llm does not depend on agent. Check with cargo tree -p llm. This direction is a hard rule.
• The repo is under git with a .gitignore for target/.

1.1 Core types

crates/llm/src/types.rs

Write these serde-serializable types:

• Role: User | Assistant. Two variants only, with no system and no tool role.
• ProviderMeta: provider: String, data: serde_json::Value.
• ContentBlock, an internally tagged enum (#[serde(tag = "type")]) with variants Text, Image (media type + base64 data), Reasoning (text + optional meta), ToolCall (id, name, arguments: Value, optional meta), ToolResult (call_id, content string, is_error defaulting to false).
• Message { role, content: Vec<ContentBlock> } with constructors user_text and assistant_text, plus accessors text() (concatenate text blocks) and tool_calls() (iterate over id/name/args).
• ToolSpec { name, description, input_schema: Value }.
• ChatRequest { model, system, messages, tools, max_tokens: u32, temperature: Option<f32> }. Derive Default.

• Optional meta is omitted from JSON when None (skip_serializing_if).
• A JSON round-trip of a message holding every block type is lossless. Snapshot it with insta::assert_json_snapshot!.
• No reqwest, no provider names, and no HTTP anywhere in this file.

1.2 The transcript validator

crates/llm/src/integrity.rs

Write validate_transcript(&[Message]) -> Result<(), IntegrityError>. It checks that:

1. the first message is from the user,
2. roles strictly alternate,
3. every ToolCall id in assistant message i has exactly one matching ToolResult in message i+1,
4. no ToolResult refers to an id that wasn't called in the previous message,
5. tool-call ids are unique across the whole transcript.

Make IntegrityError a thiserror enum whose variants carry the message index and offending id, so a failing test tells you exactly where it broke.

• Tests cover each rule with one passing and one failing transcript.
• The final assistant message may have unanswered calls only if you pass allow_pending_tail: true. That's the state between "model asked" and "tools ran".

2.1 Stream vocabulary & errors

crates/llm/src/stream.rs · crates/llm/src/error.rs

Define StreamEvent exactly as in the table, plus Usage (input, output, cache_read, cache_write as u64) with an absorb(&mut self, other: &Usage) that overwrites only the non-zero fields. Define FinishReason.

Define LlmError with variants Http { status, body, retry_after: Option<Duration> }, Transport(reqwest::Error), Api { kind, message }, Decode(String), UnexpectedEof and Config(String). Add is_retryable(): 408, 429, 5xx (which includes Anthropic's 529), transport timeout or connect errors, and API kinds overloaded_error/rate_limit_error.

Add an async helper check_status(resp) -> Result<Response, LlmError> that turns a non-2xx into Http, reads the body for the message and parses retry-after seconds.

• A 401 is not retryable, while 429 and 529 are.
• Usage::absorb keeps input_tokens from an earlier event when a later one reports only output.

2.2 The Provider trait

crates/llm/src/provider.rs

Define pub type EventStream = Pin<Box<dyn Stream<Item = Result<StreamEvent, LlmError>> + Send>> and an object-safe trait Provider: Send + Sync with fn name(&self) -> &str and async fn stream(&self, req: &ChatRequest) -> Result<EventStream, LlmError>. Use #[async_trait] so Arc<dyn Provider> works.

• let p: Arc<dyn Provider> = … compiles. Write a dummy impl in a test to prove object safety.
• The returned stream is 'static. It owns everything it needs and borrows nothing from req.

2.3 SseDecoder (sans-IO) + async adapter

crates/llm/src/sse.rs

Write SseEvent { event: Option<String>, data: String } and SseDecoder with push(&mut self, chunk: &[u8]) -> Vec<SseEvent> and finish(&mut self) -> Vec<SseEvent> (flushes a final event if the stream ends without a blank line). Then write sse_events(resp: reqwest::Response) -> impl Stream<Item = Result<SseEvent, LlmError>> + Send using async_stream::try_stream! over resp.bytes_stream().

• The chunking test. Take a fixture with three events (one multi-line data, one comment, one with \r\n endings, one emoji). Split it at every byte offset into two chunks and assert you get identical events each time.
• An event with no data: lines is not dispatched.
• data:x (no space) and data: x both yield "x".

3.1 MessageBuilder

crates/llm/src/builder.rs

Write MessageBuilder::push(&mut self, &StreamEvent) and finish(self) -> Completion. Also write async fn collect(stream: EventStream) -> Result<Completion, LlmError>, which returns UnexpectedEof if the stream ends with no Finish.

• Events Text("Hel"), Text("lo"), ToolStart(0), ToolDelta(0,"{\"a\""), ToolDelta(0,":1}"), Finish(ToolUse) produce exactly one text block "Hello" followed by one tool call with {"a":1}.
• A tool call with zero deltas gets {} as its arguments.
• Two interleaved tool calls (indices 0 and 1, deltas alternating) both parse correctly.
• A truncated stream gives Err(UnexpectedEof).

3.2 Request → wire

crates/llm/src/providers/anthropic.rs

Write fn to_wire(req: &ChatRequest) -> serde_json::Value. Map each canonical block to its Anthropic form (see the wire-format reference). Reasoning is replayed as {type:"thinking", thinking, signature} only if its meta provider is "anthropic", and dropped otherwise. Set stream: true.

• insta snapshot of a request with a system prompt, a tool, a tool call, a tool result and a foreign-meta reasoning block (which must be absent from the output).
• Empty text blocks are filtered out.

3.3 Wire → StreamEvent (sans-IO)

Write struct StreamState with fn on_sse(&mut self, &SseEvent) -> Result<Vec<StreamEvent>, LlmError> implementing the table above. Then record two real fixtures with curl and test against them.

• Replaying two_tools.sse through SseDecoder, then StreamState, then MessageBuilder produces two tool calls with parsed city args and FinishReason::ToolUse.
• An event: error fixture yields Err(Api { kind: "overloaded_error", .. }).
• An invented {"type":"brand_new_event"} is ignored without error.

3.4 HTTP glue + example

Write pub struct Anthropic { http, api_key, base_url } with new(api_key) and with_base_url (you'll point it at wiremock in tests and at proxies in production). Implement Provider::stream: POST to {base}/v1/messages with headers x-api-key and anthropic-version: 2023-06-01, run check_status, then return a try_stream! that feeds sse_events through a StreamState it owns. Add crates/llm/examples/chat.rs, which streams text deltas to stdout.

• A wiremock test serves your fixture with content-type: text/event-stream and asserts on the collected Completion.
• cargo run -p llm --example chat -- "Write a haiku about Rust" streams live.

4.1 Request → wire

crates/llm/src/providers/openai_chat.rs

Write OpenAiChat { http, base_url, api_key: Option<String>, legacy_max_tokens: bool, name: String } and its to_wire. Put the system prompt first as a system message. For each canonical user message, emit its ToolResults as tool messages first, then the remaining text and images as one user message (images as image_url data URLs). For assistant messages, set content to the text (or null) and tool_calls only when there are some. Drop reasoning blocks, because Chat Completions can't replay them.

• Snapshot: one assistant message with two tool calls, followed by one user message with two results, gives 1 assistant message plus 2 tool messages, in order.
• An error result's content starts with ERROR: .
• The Authorization header is omitted when api_key is None (local Ollama).

4.2 Chunk → StreamEvent, with the quirks

Write a ChatStreamState with on_sse and on_end. Track which tool indices have started, the pending finish reason, and whether any tool was seen. Implement every row of the quirks table. Add uuid (feature v4) to llm for id synthesis.

• An OpenAI fixture with two parallel tool calls collects to two tool calls with parsed args.
• An Ollama fixture (record it from http://localhost:11434/v1/chat/completions) collects correctly.
• A hand-written fixture with no ids, finish_reason:"stop" and no [DONE] still gives FinishReason::ToolUse and unique ids.
• Usage from the final chunk is normalized to uncached input.

5.1 Schema sanitizer

crates/llm/src/schema.rs

Write fn gemini_schema(v: &Value) -> Value. It walks the schema recursively, drops the unsupported keys, rewrites nullable type arrays, and recurses into properties, items and anyOf.

• Feed it a schemars schema for a struct with an Option<String> field and a Vec<u32>, and snapshot the output.

5.2 Gemini adapter

crates/llm/src/providers/gemini.rs

to_wire: build the call_id → name map first. Map Text to {text}, Image to {inlineData}, and ToolCall to {functionCall:{name,args}} plus thoughtSignature when the meta is Gemini's. Map ToolResult to {functionResponse:{name, response:{result|error: content}}}. Skip reasoning. Stream: handle text parts, thought: true parts (reasoning), functionCall parts, usageMetadata (normalize: subtract cachedContentTokenCount, and add thoughtsTokenCount to output), and finishReason. Emit Finish from on_end.

• A recorded two-step fixture (call → result → answer) replays with the signature preserved in meta, and to_wire of the follow-up request puts it back on the right part.
• STOP + function call gives ToolUse. SAFETY gives Refusal.
• Two parallel calls in one response get distinct ids.

5.3 Stretch: OpenAI Responses adapter

crates/llm/src/providers/openai_responses.rs

Write to_wire (instructions, an input item list, flat tools entries {type:"function", name, description, parameters}, store:false, include, max_output_tokens) and a state machine keyed on output_index. A reasoning item from response.output_item.done becomes ReasoningDone { meta: {provider:"openai-responses", data: item} }, and to_wire pushes meta.data back verbatim.

• A recorded fixture with reasoning plus a function call replays. The follow-up request contains the reasoning item, the function_call and the function_call_output, in that order.
• response.incomplete with reason max_output_tokens gives FinishReason::MaxTokens.

6.1 Config + registry

crates/llm/src/config.rs

Write serde types for the TOML below (kind as a kebab-case enum: anthropic, openai-chat, openai-responses, gemini). Load and merge user config (dirs::config_dir()/anvil/config.toml) with project config (.anvil/config.toml), where project keys win. Write Registry::resolve(&self, name: &str) -> Result<ResolvedModel, LlmError>, which returns the provider (wrapped in Retry), the model id and the limits.

• A missing env var gives LlmError::Config("ANTHROPIC_API_KEY is not set (needed by provider 'anthropic')"), an error message a human can act on.
• resolve("ollama:qwen3:8b") works with no [models] entry and uses conservative default limits.
• Unknown alias: the error lists the available aliases.

6.2 Retry decorator

crates/llm/src/retry.rs

Write Retry { inner: Arc<dyn Provider>, max_attempts, base, cap } implementing Provider. Log each retry with tracing::warn! (status, attempt, delay).

• Wiremock returns 529 twice, then a valid stream, and the test passes in under a second (use a tiny base in tests).
• A 401 is attempted exactly once.
• retry-after: 2 results in roughly a 2 s wait. Test it with tokio::time::pause() so it's instant.

6.3 The conformance suite

crates/llm/tests/conformance.rs

Write async fn conformance(p: Arc<dyn Provider>, model: &str) that runs these scenarios and asserts on canonical output only:

1. Text: "Reply with exactly: pong" gives text containing pong, with EndTurn.
2. Single tool: with a get_weather(city) tool, "Weather in Oslo?" gives one call whose arguments are an object with a string city, and ToolUse.
3. Round trip: append the call and a result "-3°C, snow", then call again. The text should mention -3 or snow, and validate_transcript passes.
4. Parallel: "Weather in Oslo and Lima?" gives two calls with distinct ids (allowed to soft-fail on models that serialize calls).
5. Usage: input_tokens > 0 and output_tokens > 0.

Add one #[tokio::test] #[ignore] per configured provider that skips gracefully when its key is unset.

• cargo test -p llm --test conformance -- --ignored passes for every provider you have keys for, including local Ollama.

7.1 Tool, TypedTool, ToolError, ToolContext

crates/agent/src/tool.rs

ToolContext holds cwd: PathBuf and cancel: CancellationToken (you'll add more later). ToolError has InvalidArgs(String), Failed(String) and Cancelled. Write both traits and the blanket impl. In input_schema(), strip the top-level $schema and title keys that schemars adds.

Then write a Calculator TypedTool whose args are { a: f64, b: f64, op: Op }, with Op an enum (add|sub|mul|div) and a doc comment on each field. schemars turns doc comments into schema descriptions.

• Snapshot of Calculator.input_schema() shows the enum values and field descriptions.
• call(json!({"a":1})) gives InvalidArgs, and the message names the missing field.
• Division by zero gives Failed("Division by zero. Use a non-zero b.").

7.2 ToolRegistry + dispatch

crates/agent/src/registry.rs

Write ToolRegistry { tools: BTreeMap<String, Arc<dyn Tool>>, max_output_chars: usize } with:

• register, which rejects duplicate names and names that don't match ^[a-zA-Z0-9_-]{1,64}$ (the strictest common provider rule),
• specs() -> Vec<ToolSpec>,
• dispatch(&self, call_id, name, args: &Value, ctx) -> ContentBlock, which always returns a ToolResult,
• truncate_middle(s, max), which keeps the head and the tail (that's where errors and summaries usually are) and inserts a note saying how many characters were cut and how to see more.

• Unknown tool: the error lists the available tool names.
• args = "not json" (a Value::String left by MessageBuilder) gives an error saying arguments must be a JSON object and echoing what was received.
• truncate_middle never panics on multi-byte UTF-8. Test it with a string of emoji.

8.1 ScriptedProvider

crates/llm/src/testing.rs (behind a testing cargo feature)

Write ScriptedProvider::new(Vec<Vec<StreamEvent>>) with Mutex-guarded state, a requests() accessor and helper constructors script::text("hi") and script::tool_call("id", "name", json!(...)) that return complete event sequences ending with Finish. If the script runs out, return Err(LlmError::Config("script exhausted")) so tests fail loudly. Derive Clone on ChatRequest if you haven't yet.

8.2 AgentEvent + Agent::run_turn

crates/agent/src/agent.rs

Define AgentEvent (serde-serializable, tagged): StepStarted{step}, TextDelta, ReasoningDelta, ToolCallStarted{id,name,args}, ToolCallFinished{id,name,is_error,preview}, Usage, TurnFinished{outcome}. Define TurnOutcome: Done | MaxSteps | MaxTokens | Refused | Cancelled.

Write Agent { provider, tools, cfg: AgentConfig, messages, events: mpsc::UnboundedSender<AgentEvent>, cwd } with run_turn(&mut self, input: Vec<ContentBlock>, cancel: CancellationToken) -> Result<TurnOutcome, AgentError>, following the algorithm above. Sampling is a private method that streams, forwards deltas and builds the Completion. Tools run sequentially for now.

• Test: script [tool_call(calculator), text("4")] gives Done, 4 messages, validate_transcript OK, and the 2nd recorded request contains the tool result.
• Test: unknown tool, then text: the loop continues, and the result is is_error.
• Test: a script of 30 tool calls with max_steps = 5 gives MaxSteps after exactly 5 requests.
• Test: a slow tool (sleeps 5 s, respects cancel) with the token cancelled after 50 ms gives Cancelled in <1 s, and the transcript is valid.
• Test: cancelling mid-sample, then calling run_turn again, leaves no two consecutive user messages.

8.3 Stretch: parallel read-only tools

When every call in a batch is read_only(), run them concurrently with futures::future::join_all, and keep the results in the original call order. Mixed batches stay sequential: a write followed by a read has to observe the write.

• Three 200 ms read-only tools complete in ~200 ms, not ~600 ms, and the results stay in order.

9.1 Args + wiring

crates/cli/src/main.rs, args.rs

Use clap (derive) to define -p/--print <PROMPT>, -m/--model, --output-format text|json|stream-json, --max-steps and -C/--cwd. Load the config, resolve the model, register tools (only Calculator for now), build the Agent with a base system prompt string, and pick headless or interactive mode.

9.2 Renderer task

crates/cli/src/render.rs

Spawn a task that consumes AgentEvents. In interactive mode, stream TextDelta straight to stdout (flushing each time), print tool calls as a dim one-liner (⏺ calculator(a=2, op=add, b=2)), print results as an indented preview ( ⎿ 4, red when it's an error), and print usage after each turn on stderr. In stream-json mode, print serde_json::to_string(&event) per line.

• Long tool args are shortened to one line (~80 chars) in the one-liner.
• Output is clean when piped (| cat): no ANSI codes when stdout isn't a TTY (std::io::IsTerminal).

9.3 REPL + Ctrl-C

crates/cli/src/repl.rs

Read lines with rustyline (history saved under the data dir). Handle slash commands /help, /exit, /clear (reset messages) and /model <name> (swap provider mid-session: thanks to ch01 this just works). For each turn, create a fresh CancellationToken and spawn a tokio::signal::ctrl_c() listener that cancels it.

• Asking "what is 17.5 × 4 − 3?" makes the model call calculator twice and answer 67.
• /model local mid-conversation continues on Ollama with the full history.
• Ctrl-C during a long answer stops streaming immediately, and the next prompt works.

9.4 Headless mode

With -p, run exactly one turn and print according to --output-format. Exit with the documented codes. If stdin isn't a TTY, read it and append it to the prompt, so that git diff | anvil -p "review this" works.

• anvil -p "2+2 using the calculator" --output-format json | jq .outcome prints "done".
• --max-steps 1 on a tool task exits with code 2.

10.1 FileTracker + path resolution

crates/agent/src/tools/tracker.rs

Write FileTracker (Mutex<HashMap<PathBuf, SystemTime>>) with record_read(path) and check_fresh(path) -> Result<(), ToolError>. Add a resolve(cwd, user_path) -> PathBuf helper that makes paths absolute and normalizes ... Share one tracker between the fs tools through an Arc.

• Editing an unread file gives "You must read_file before editing it."
• Read the file, change it externally, then edit: "File changed on disk since you last read it. Read it again."

10.2 read_file · write_file · edit_file

crates/agent/src/tools/fs.rs

read_file takes {file_path, offset?, limit? = 2000}. It outputs numbered lines ({:>6}\t), cuts lines longer than 2000 chars, rejects binary files (NUL byte in the first 8 KB), adds a footer when more lines exist, and is read-only. write_file takes {file_path, content}. For existing files it requires a fresh read, creates parent dirs, and writes atomically (temp file + rename). edit_file takes {file_path, old_string, new_string, replace_all?}. It requires a fresh read, enforces the uniqueness rules, rejects old == new, and returns about four numbered lines of context around the edit.

Write the descriptions carefully. They're prompts. For example, edit_file's should state the uniqueness rule and say to include enough surrounding lines to make old_string unique.

• Edit with 0 matches: the error suggests checking whitespace and indentation and re-reading the file.
• Edit with 3 matches and no replace_all: the error reports "3 matches" and tells the model to add context or set replace_all.
• CRLF files keep their CRLF line endings after an edit.
• tempfile::TempDir-based tests for each tool.

10.3 glob · grep

crates/agent/src/tools/search.rs

glob takes {pattern, path?}. It walks with ignore::WalkBuilder, matches with globset, sorts by mtime (newest first) and caps at 200 results. grep takes {pattern, path?, glob?, case_insensitive?, mode: files|content}. It uses the regex crate, skips binary files, and in content mode prints path:line:text capped at ~200 lines. Both are read-only. A regex compile error is InvalidArgs and includes the regex error text.

• target/ and anything in .gitignore never show up.
• Searching for fn main across this repo returns crates/cli/src/main.rs.

10.4 bash

crates/agent/src/tools/bash.rs

Takes {command, timeout_ms? = 120000 (max 600000)}. Spawn bash -c <command> in ctx.cwd with stdin null and piped outputs, in a new process group (process_group(0)). select! on completion, timeout and ctx.cancel, and on the last two kill the whole group (nix::sys::signal::killpg). Format the output as Exit code: N followed by labelled stdout and stderr, with the middle truncated at ~30 k chars. A non-zero exit is an Ok result, because grep returning 1 is information. A timeout or spawn failure is an Err.

The description should say that each call runs in a fresh shell (so cd doesn't persist) and should steer the model toward the dedicated read, grep and edit tools instead of cat, grep and sed.

• sleep 100 & sleep 100; echo done with timeout_ms: 500 returns within ~1 s, and pgrep sleep shows no orphans.
• yes | head -c 10000000 doesn't deadlock and gets truncated.
• Ctrl-C during sleep 30 stops it immediately.

11.1 Rule parsing + matching

crates/agent/src/permissions.rs

Add fn permission_subject(&self, args: &Value) -> Option<String> (default None) and fn is_edit(&self) -> bool to Tool, and implement them for your tools. Parse rule strings into Rule { tool, pattern: Option<Pattern> }, where Pattern is Prefix(String) | Exact(String) | Glob(GlobMatcher). Write split_shell(cmd) -> Vec<String>.

• Table-driven tests: cargo test --lib allowed, cargo test && rm -rf / denied, echo $(cat ~/.ssh/id_rsa) asks, git push origin main asks.
• Invalid rule syntax fails config loading with a precise message.

11.2 Policy::decide

Write Policy { mode, allow, ask, deny, session_allow, workspace_root } with decide(&self, tool: &dyn Tool, args) -> Decision, where Decision is Allow | Ask { reason } | Deny { reason }.

11.3 Approver round-trip

crates/agent/src/approval.rs · crates/cli/src/approve.rs

Define #[async_trait] trait Approver: Send + Sync { async fn approve(&self, req: ApprovalRequest) -> ApprovalDecision; }. In run_tools, call policy.decide before dispatch. On Deny, or on an Ask that's refused, produce the error result without running the tool. Implement:

• Interactive approver (CLI): pauses rendering, shows the tool, the args and the reason, and reads y / a (always) / n plus optional feedback.
• Headless approver: denies with "This action requires approval, which isn't available in headless mode. Re-run with --permission-mode accept-edits or add an allow rule."
• Test approver: scripted decisions, for loop tests.

• Loop test: ask → deny with feedback gives a tool result containing the feedback, and the tool's call was never invoked (assert with an AtomicBool).
• "Always" on cargo test --lib adds bash(cargo test:*) to the session rules, and the next cargo test doesn't prompt.
• Ctrl-C while the approval prompt is open cancels the turn cleanly.

12.1 Policy + Seatbelt backend

crates/agent/src/sandbox/{mod.rs, seatbelt.rs, profile.sb}

Define SandboxPolicy { ReadOnly, WorkspaceWrite { network: bool }, FullAccess } and fn wrap(policy, workspace, cmd: &str) -> (program, args). Embed the profile with include_str!. Add sandbox to ToolContext and use wrap in the bash tool.

12.2 bubblewrap backend

crates/agent/src/sandbox/bwrap.rs

Build the bwrap argument list from the policy. If bwrap isn't installed, fail closed: the bash tool returns an error explaining how to install it or how to opt into FullAccess explicitly.

12.3 Env scrubbing + redaction

crates/agent/src/secrets.rs

Write child_env() -> Vec<(String, String)> (use env_clear() plus envs() on the Command) and a Redactor built at startup from the values of the scrubbed variables (ignore values shorter than 8 chars to avoid false positives). Apply redaction in ToolRegistry::dispatch.

12.4 Escape tests

crates/agent/tests/sandbox_escape.rs

Integration tests that run the real bash tool under WorkspaceWrite { network: false } and assert that each attack fails:

• touch ~/anvil_escape fails, and touch ./ok succeeds.
• cat ~/.ssh/id_* fails (macOS: deny rule. Linux: tmpfs home).
• curl -sS https://example.com fails. With network: true it succeeds.
• env | grep -i api_key prints nothing.
• ln -s ~ link && touch link/escape fails, because a symlink doesn't get around the policy.

13.1 PromptBuilder + AGENTS.md discovery

crates/agent/src/context/prompt.rs

Write fn discover_instructions(cwd) -> Vec<(PathBuf, String)> (walk up to the git root, collect, then reverse so the root comes first; also include ~/.config/anvil/AGENTS.md; cap each at ~20 KB with a truncation note) and PromptBuilder::build(&self) -> String, which emits the layers in order under clear headers. Write the base instructions yourself, and keep them under ~60 lines.

• Snapshot test of the assembled prompt for a fixture repo with nested AGENTS.md files.
• Building twice in the same session gives byte-identical output.

13.2 Cache hints in adapters

Add cache to ChatRequest. In the Anthropic adapter, when it's set, send system as [{type:"text", text, cache_control:{type:"ephemeral"}}] and add cache_control to the last content block of the last message. In OpenAI adapters, send prompt_cache_key (and verify your target server accepts it, or make it configurable). Gemini needs nothing for implicit caching.

• Anthropic wire snapshot shows exactly two breakpoints.
• Live: a three-step tool session shows cache_read_tokens > 0 from the second request on. Print the hit rate after each turn.

13.3 Token budget

crates/agent/src/context/budget.rs

Write ContextBudget { window, reserve_output, compact_at: f32 } and estimate(&self, last_usage: Option<Usage>, new_messages: &[Message]) -> u64. The last response's input + cache_read + cache_write + output is the true size of the context so far, so only estimate what was added after it (bytes/4 is fine). Expose should_compact() for ch14.

14.1 SessionStore

crates/agent/src/session.rs

Store sessions at dirs::data_dir()/anvil/sessions/<sanitized-cwd>/<uuid>.jsonl. Define a Record enum (serde-tagged) with Meta, Message, Usage, Compaction { summary }. Write SessionWriter::append(&Record) and load(path) -> Session { meta, messages }, which applies compactions while replaying. Hook the writer into Agent wherever a message is pushed.

• Kill anvil mid-turn with kill -9, then anvil --continue resumes with a valid transcript. If the last message has unanswered tool calls, synthesize "interrupted" results on load.
• A Gemini session round-trips with its thought signatures intact (snapshot the JSONL).
• anvil sessions lists recent sessions for this cwd with their first prompt and age.

14.2 Tool-result clearing

Write fn clear_old_tool_results(messages: &mut [Message], keep_last_steps: usize) -> usize (returns the number of bytes freed). Call it from the loop when budget.estimate() crosses a soft threshold (~60%).

14.3 Summarization compaction

crates/agent/src/context/compact.rs

Write async fn compact(&mut self, focus: Option<&str>) -> Result<(), AgentError>. It sends the transcript plus a summary instruction as the last user message (no tools, so the model can't wander off), collects the text, replaces the messages, writes a Compaction record and emits an AgentEvent::Compacted { before_tokens, after_tokens }. Run it from the loop before sampling when should_compact() is true, and from /compact.

• ScriptedProvider test with a tiny window (e.g. 2,000 tokens): a long tool session triggers compaction, the summary request has an empty tools list, and the next request contains the summary and passes validate_transcript.
• Live: /compact focus on the failing test produces a summary you'd be happy to hand to a colleague.

15.1 Config + connect

crates/agent/src/mcp.rs

Add rmcp = { version = "3.5", features = ["client", "transport-child-process"] }. For each server, spawn it with TokioChildProcess (scrubbed env plus passthrough), call ().serve(transport), then list_all_tools(). Run all servers with futures::future::join_all, each wrapped in tokio::time::timeout.

15.2 McpTool

Write McpTool { full_name, server, remote: rmcp::model::Tool, client: Arc<…RunningService…> } implementing Tool. Name and description come from the remote tool, prefixed with [server]. The schema is the remote input_schema as a Value. call converts the result content: join text items, and render non-text items as a short placeholder ([image: image/png, 34 KB]). If is_error is true, return Err(Failed(text)). Make permission_subject return the full name so rules like mcp__github__* work.

• With the filesystem server configured, "list files in this directory using the MCP tool" works, and the call shows up as mcp__fs__list_directory.
• A misconfigured server (bad command) gives a startup warning, and anvil still starts.
• /mcp lists the servers, their status and their tool counts.
• Snapshot the tool-spec list: names are sorted and stable between runs, so the cache prefix stays stable.

15.3 Stretch: deferred tool loading

When there are more than ~30 tools, don't send every MCP schema. Send a single tool_search tool whose description lists only the names of the deferred tools. When the model calls tool_search("github issues"), return the matching schemas and add those tools to the active set for the rest of the session. Watch the token savings in your usage numbers.

16.1 Hook runner

crates/agent/src/hooks.rs

Write HookRunner::run(event, payload: &Value) -> HookOutcome { Continue { stdout } | Block { stderr } | Failed }. Wire it in at the five points of the loop. The stop handling goes where calls.is_empty() would end the turn.

• Loop test (ScriptedProvider + a hook script that exits 2 once, then 0): the turn continues once with the hook's stderr as a user message, then ends.
• A hook that sleeps past its timeout is killed and logged, and the turn proceeds.
• Live: ask for a change that breaks compilation. The post-edit hook surfaces the error and the model fixes it unprompted.

16.2 Skills loader + skill tool

crates/agent/src/skills.rs

Discover SKILL.md files in .anvil/skills/*/, .agents/skills/*/ and ~/.config/anvil/skills/*/. Parse the frontmatter (split on the leading --- lines, then deserialize with a maintained YAML crate such as serde-saphyr, since serde_yaml is deprecated). Validate it: the name is lowercase-hyphenated and matches the directory, and the description isn't empty. Add a "Skills" section to the prompt builder (ch13) that lists name: description. Add a read-only skill tool, {name}, that returns the body plus the skill's absolute directory path, so relative references and scripts resolve.

• Invalid skills are skipped with a warning that names the file and the problem.
• Write a release-notes skill that tells the agent to read git log since the last tag and format it in your style. Then "write release notes" activates it, and "fix this test" doesn't.

17.1 Agent definitions + task tool

crates/agent/src/subagent.rs

Load definitions (same frontmatter parser as skills). Ship two built-ins: explore (read, glob, grep; "search broadly, report precisely") and review (read, grep, bash restricted by rules to git diff:* and cargo test:*; "review the diff for bugs; cite lines"). Implement TaskTool, which holds what it needs to build a child Agent (provider, the parent's registry, policy, approver, event sender). Its read_only() is true only if the selected definition's tools are all read-only.

• ScriptedProvider test: the parent calls task → the child runs 2 steps → the parent receives only the child's final text, and the parent transcript contains none of the child's tool calls.
• A definition that lists task in its tools fails to load, with a clear error.
• Ctrl-C during a subagent cancels the child and the parent cleanly.
• Live: "Use two explore subagents in parallel: one maps the llm crate, one maps the agent crate" shows two concurrent nested progress streams.

17.2 todo_write

Store the list in shared session state (Arc<Mutex<Vec<Todo>>>), validate it (at most one in_progress, no empty content), emit AgentEvent::TodosUpdated and persist a session record. In compact(), append "Current todo list:" plus the list to the summary.

• The CLI renders the list (☐ ◐ ☑) whenever it changes.
• After /compact, the next request still contains the list.

18.1 Instrumentation

Add spans with tracing::info_span! / #[instrument(skip_all, fields(...))]. Declare fields that aren't known yet as tracing::field::Empty and fill them with Span::current().record(..) when usage arrives. Measure TTFT from request start to the first TextDelta or ToolCallStart.

18.2 Subscribers

JSON logs to data_dir/anvil/logs/anvil.log (tracing-appender for non-blocking writes), with the filter from ANVIL_LOG (EnvFilter). Behind a cargo feature otel, add a tracing-opentelemetry layer exporting OTLP when OTEL_EXPORTER_OTLP_ENDPOINT is set. Run Jaeger locally and look at a real session's trace.

• No log output ever reaches stdout or stderr in headless mode (run your ch09 jq test again).
• A Jaeger trace shows nested turn → step → chat/tool spans with token attributes.

18.3 Cost model + budgets + /cost

Write Pricing, fn cost(&Usage, &Pricing) -> f64 and a SessionMeter that accumulates usage and cost per model (subagents included). /cost prints tokens, cache hit rate and USD. Unknown pricing shows "n/a", never a guess.

• Loop test: max_cost_usd = 0.0001 with a pricey fake pricing gives BudgetExceeded after the first step.

18.4 anvil replay <session>

Render a session JSONL as a readable transcript: messages, tool calls with args, results (collapsed past N lines), usage, and cost per step. You'll live in this view during eval error analysis.

19.1 Golden transcripts

crates/evals/tests/golden.rs

For 3–5 scenarios (edit-and-test, unknown tool recovery, permission denial with feedback, compaction), run the full Agent with real tools in a TempDir and a ScriptedProvider. Snapshot provider.requests() (what the model saw) with insta, redacting temp paths and generated ids.

• Change one word in the edit_file error message, and the snapshot diff shows it.

19.2 Task format + runner

evals/tasks/<name>/{task.toml, repo/, check.sh} · crates/evals/src/main.rs

The runner takes --models a,b,c --trials k --tasks glob --concurrency n. For each (task, model, trial): copy repo/ into a temp dir, git init and commit, run anvil -p … -m … --output-format json --permission-mode bypass (still sandboxed!) with a timeout, then run check.sh. Append a JSONL record: task, model, trial, pass, outcome, steps, tokens, cost, duration, session path, anvil git sha.

• Start with ~10 tasks from your own work: fix a failing test, add a CLI flag, rename across a crate, implement a function from a doc comment, explain-then-fix from a stack trace, and one safety task (the prompt tempts it to modify files outside the workspace, and the check verifies nothing outside changed).
• A run of 10 tasks × 2 models × 3 trials completes unattended.

19.3 Report

Write anvil-evals report results.jsonl [--baseline old.jsonl]: a per-model table of pass@1, pass@k, pass^k, mean steps, mean cost and p50 duration, plus per-task cells, and a diff against the baseline that flags regressions.

19.4 Your first harness experiment

Pick one hypothesis, for example "adding 'verify with tests before finishing' to the base prompt raises pass^3", or "the stop hook beats the prompt line". Run baseline and variant on the same tasks, models and k. Write the result in your repo's EXPERIMENTS.md with the numbers. Keep the change only if the data supports it.

20.1 anvil auto <spec.md>

Write the orchestrator as a plain loop of headless sessions. If features.json doesn't exist, run the initializer prompt. Otherwise run worker sessions until every feature passes, or until --max-sessions or --max-cost-usd is reached. Put the initializer and worker instructions in two built-in skills (ch16), and add a stop hook that runs init.sh's test command. Validate after every session that only passes fields changed in features.json (diff the JSON). If anything else changed, revert the file and log it. That validation is a sensor too.

• Given a small spec (e.g. "a CLI todo app with add/list/done and persistence, with tests"), anvil auto completes it across several sessions with a clean git history.
• Kill it mid-run and restart: it resumes from the progress file and the git log.

20.2 Shadow-git checkpoints

crates/agent/src/checkpoint.rs

Write Checkpoints::snapshot(label) -> Option<CommitId> (it's a no-op if nothing changed), restore(id) and list(). Shell out to git with explicit --git-dir/--work-tree and the scrubbed env. Snapshot before any turn that contains an edit-capable tool call, and record the checkpoint id in the session log.

• /undo after a bad multi-file edit restores every file. The user's git status is unchanged by the checkpointing itself.
• Files created by the agent are removed on undo. Ignored files (e.g. target/) are never touched.

20.3 CI + release

CI matrix (macOS + Linux): cargo fmt --check, clippy -D warnings, all tests including sandbox escape tests and golden transcripts. Run a nightly job with live conformance and task evals against at least two providers, posting the report as an artifact. Release with dist (cargo-dist), which builds binaries and generates install scripts. Write the README: install, configure a provider (including local Ollama), safety model, extending (MCP, hooks, skills, agents).