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 hardcoded provider names, and no HTTP anywhere in this file.

1.2 The transcript validator

crates/llm/src/integrity.rs

Write validate_transcript(&[Message], allow_pending_tail: bool) -> Result<(), String>. 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.

The reference uses a string error to keep the algorithm visible. In your implementation, replace it with a thiserror enum carrying the message index, block kind and offending ID. Check uniqueness while scanning original blocks, before collecting sets; require calls on Assistant and results on User.

• 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".

01.B Build the boundary contract

Add tests for calls on User, results on Assistant, duplicate IDs within a single message, duplicate IDs across steps, empty IDs, duplicate results and orphan results. Run validation before each request and after each committed tool batch. Make the pending-tail flag a property of execution state, not a default callers can forget.

• Two calls sharing an ID and one result fail validation.
• A legal temporary pending tail becomes a legal request only after results are appended.
• Malformed block roles fail even when the IDs match.

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]) -> Result<Vec<SseEvent>, String> and finish(self) -> Vec<SseEvent> (discards incomplete events at EOF; never invents 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".

02.B Build the boundary contract

Use fixtures for BOM + data, LF, CRLF, lone CR, comments, empty data, multiline data and incomplete EOF. Test every two-chunk split and bytewise input. Add separate configurable limits for a line and an accumulated event. Use a finite request deadline and a configurable idle deadline; close stalled bodies without claiming server billing has stopped.

• A BOM-prefixed data field is retained.
• An event ending without its blank line is discarded.
• Oversized inputs fail without unbounded allocation.
• A stalled body ends through a tested deadline.

3.1 MessageBuilder

crates/llm/src/builder.rs

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

• 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.

03.B Build the boundary contract

Make builder transitions fallible. Check starts before reserving slots, require a slot before accepting a delta, and forbid content after Finish. Add a committed-response boundary: truncated, refused or failed samples cannot execute provisional calls. For protocols with interleaved reasoning/text, extend events with block identities and preserve opaque state at the correct block.

• A delta before a start returns Decode.
• A conflicting duplicate start returns Decode.
• An abnormal finish executes zero tools.
• Two interleaved calls retain the original order and arguments.

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

Prefer parametersJsonSchema on verified GenerateContent targets. For legacy parameters, write gemini_schema(&Value) -> Result<Value, String> as a deliberately limited compiler. Preserve property names, support the stated subset, and reject references or unsupported unions with a path. Resolve references in a separate bounded pass if legacy targets need them.

• 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 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.

05.B Build the boundary contract

Add a target capability table for images, tool JSON schema dialect, signed reasoning, max-token field, temperature and replay support. Prefer a verified full-JSON-Schema field; for legacy schemas support a documented subset and reject everything else. Add a fixture manifest with provider, endpoint family, API revision, model, capture date and enabled features. Keep GenerateContent and Interactions fixtures separate.

• A property named title remains present and required.
• References are preserved in supported full-schema mode or explicitly rejected in legacy mode.
• String-or-integer is never silently narrowed to string.
• Switching providers during a signed tool chain either passes conformance or creates a deliberate handoff.

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 instruction/data keys win; executable, credential and security settings require the trusted loader defined below. 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.

06.B Build the boundary contract

Separate InstructionConfig from TrustedRuntimeConfig. Mark the source and trust level of every merged key. Require an explicit workspace trust grant before enabling repository commands, env passthrough, endpoint changes or permission expansion. Bind provider credentials to approved endpoint origins. Record the trusted-config digest; changing executable authority invalidates the grant. Add a total retry deadline and honor Retry-After within that deadline.

• A repository cannot redirect a trusted provider credential to an unapproved host.
• An untrusted MCP or hook command is listed but not spawned.
• Changing an executable config digest requires a new trust decision.
• A retry delay beyond the total deadline stops rather than sleeping indefinitely.

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 | ProtocolStopped.

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.

08.B Build the boundary contract

Use a bounded event channel or a bounded progress buffer that coalesces adjacent text deltas. Preserve terminal lifecycle events. Define delivery policy when the renderer disappears. Add StepFailed and VerificationFailed events, plus explicit turn outcomes for abnormal provider completion. Require each tool to state cancellation behavior and effect type. Run tools with a cleanup owner that outlives a cancelled dispatch future.

• A deliberately slow renderer does not cause unbounded memory growth.
• Every turn sends one terminal outcome including error cases.
• Dropping a UI does not silently grant an approval.
• Cancellation reports uncertain effects when completion cannot be established.

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> (request a provider switch after validating imported history; use an explicit text handoff when replay is unsupported). 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.

09.B Build the boundary contract

At end of a headless turn, drop all event senders, await renderer EOF, flush stdout and then choose the exit code. On broken pipes cancel work and reap tools. For text mode buffer only the committed final answer; intermediate reasoning and tool progress go elsewhere. Reuse the signal listener with a turn-scoped token or abort and await a per-turn listener.

• The last stream-json line is TurnFinished and parses after a slow-reader test.
• Error, refusal, truncation and protocol-stop exits cannot be mistaken for Done.
• A closed stdout pipe cancels and cleans up child processes.

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.

10.B Build the boundary contract

Create FileAccess with explicit readable/writable roots and protected paths. All native tools use it, including search. For a first implementation canonicalize existing paths and the nearest existing parent of new files, then reject outside or protected destinations. Document the check/open race. For stronger enforcement use descriptor-relative capabilities or a sandboxed file worker. Freshness should compare content hashes; reject empty old_string and refresh the tracker after successful edits.

• A workspace symlink pointing outside cannot be written through.
• A new file validates its existing parent chain.
• Search cannot expose denied credential files.
• Protected .git and executable .anvil config cannot be mutated without a separate grant.
• Two consecutive agent edits work, while an intervening user edit fails freshness.

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.

11.B Build the boundary contract

Define Effects { reads, writes, network, subprocess, unknown } and resolve them per call. Hard denies and plan mode run first. Outside paths and network/full-access expansions require a separate grant. Then apply ask/allow rules and mode defaults. Implement explicit wildcard matching for tool selectors such as mcp__github__*, separate from subject globs. Empty parses and unknown syntax cannot vacuously satisfy all_allowed.

• Plan mode plus an allow(edit_file) rule still denies writes.
• A broad allow rule does not bypass an outside-path grant.
• Deny plus requested escalation remains Deny.
• A task selecting a write-capable child is classified as mutating.
• MCP wildcard selectors match names and do not match unrelated servers.

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.

12.B Build the boundary contract

Implement drain_bounded for each pipe: retain a fixed head/tail and discard excess while continuing reads. The process supervisor owns Child, group identity, reader tasks and cleanup deadline. Kill group members on timeout/cancel, await leader exit, and bound reader joins when inherited pipes remain open. Sandbox hooks and MCP processes according to separately approved grants; mask secrets and writable authority-bearing config paths. Use a child env allowlist for stronger isolation, with explicit trusted passthrough.

• An unlimited-output command stays within the configured capture bound.
• Timeout/cancel reaps the leader and terminates owned readers.
• A detached child retaining a pipe cannot hang a turn forever.
• Missing sandbox support fails closed.
• Native file escape tests run alongside bash escape tests.

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 a useful baseline for the next request, not an exact measurement after replay filtering or context mutation, so only estimate what was added after it (bytes/4 is fine). Expose should_compact() for ch14.

13.B Build the boundary contract

Track a context revision and the request revision associated with usage. Reuse the usage baseline only when the prefix is unchanged; estimate additions plus a safety margin and reserve output. Recompute after context mutations using token counting when available or a conservative estimate. Cache checks must account for provider/model minimum lengths; a short fixture can correctly have zero cache reads.

• Model switching invalidates the old usage baseline.
• Compaction and tool discovery advance context revision.
• Short prompts do not fail solely for a missing cache hit.
• Zero token values and unknown token values remain distinguishable.

14.1 SessionStore

crates/agent/src/session.rs

Store sessions at dirs::data_dir()/anvil/sessions/<sanitized-cwd>/<uuid>.jsonl. Define a versioned Record enum with Meta, MessageAppended, MessageExtended, ContextReplaced, ModelChanged, TodosChanged, ToolStarted, ToolFinished, Usage and CheckpointRecorded. Apply records through one reducer in live execution and loading. Write SessionWriter::append(&Record) and load(path) -> Session { meta, messages }, which applies compactions while replaying. Hook the writer and reducer into every session mutation, including extending an existing message and context clearing.

• Kill anvil mid-turn with kill -9, then anvil --continue resumes with a valid transcript. If the last message has unanswered tool calls, synthesize results describing unknown execution outcome on load, reconcile side effects, and never blindly repeat them.
• 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.

14.B Build the boundary contract

Define versioned records: SessionStarted, MessageAppended, MessageExtended, ContextReplaced, ModelChanged, TodosChanged, ToolStarted, ToolFinished and CheckpointRecorded. Implement one reducer used by live execution and loading. Give records monotonic sequence numbers. Recover only a torn final line; reject malformed interior records. Sync ToolStarted before side effects and ToolFinished after results according to a documented durability policy. A started call without a durable finish becomes UnknownOutcome, not an automatic retry.

• Replaying records equals live state after each mutation.
• Merged user text survives restart exactly once.
• Clearing and compaction replay the same active context.
• A malformed interior line is rejected.
• A crash between external success and ToolFinished does not repeat the action automatically.

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.

15.B Build the boundary contract

Map remote identity (server, original name) to a stable exposed name with a short hash suffix when needed. Reject collisions before registration. Keep a reverse map for dispatch. Give startup, calls and shutdown explicit timeouts; cancellation cleans up the owned client/process. Separate approved remote token passthrough from provider credentials. Treat non-text content as typed data or a declared unsupported capability, not silently complete output.

• Two long names with the same first 64 characters remain distinct.
• Sanitization collisions are deterministic across starts.
• A readOnlyHint cannot auto-allow an unknown tool.
• Cancelled startup/calls do not leave an owned process indefinitely running.

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 advisory mode proceeds with a warning; required-verifier mode records verification failure.
• 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.

16.B Build the boundary contract

Give hooks an advisory/required purpose and a trust origin. Required stop-verifier failure, spawn error or timeout records VerificationFailed and prevents a verified-success outcome. Cap model continuations separately from verification status. Add a verifier revision tied to the workspace state: after edits invalidate its previous success. Execute repository hooks only through the trusted loader; record a changed generated init script as a proposed command.

• A required verifier timeout does not produce verified success.
• A later edit invalidates an earlier passing test result.
• An advisory failure is visible but need not block completion.
• Repository-supplied commands cannot silently activate.

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). Classify each task call with effects(args) after resolving the selected definition. A static read_only() cannot represent argument-dependent authority. Treat unknown definitions/effects conservatively.

• 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.

17.B Build the boundary contract

Resolve the definition before classifying effects; filter tools and inherit grants without broadening them. Add a session-wide semaphore for child concurrency and a shared budget ledger. Reserve a conservative request cost before admitting a child step, reconcile actual usage afterward, and keep unknown usage outstanding. Set child deadlines and step caps. Persist todo changes through the session reducer.

• A task call cannot select tools outside the trusted definition.
• Child requests obey the global concurrency cap.
• Two children cannot each spend the same remaining reserved budget.
• Unknown pricing/usage is reported as unknown and blocks a promised hard dollar cap.

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.

18.B Build the boundary contract

Represent accounting as Reported, Estimated or Unknown with provider/request identity. Export total input to the appropriate standard field and uncached/cache partitions under anvil fields. Redact known secrets at tool, hook, log, error and session boundaries; avoid logging raw request payloads. Report whether a budget is soft or admission-controlled and retain unresolved reservations from interrupted requests.

• Cached input is not omitted from total-input telemetry.
• A failed stream cannot be recorded as known zero cost.
• Child cost is counted once in the shared session ledger.
• Fixture secrets are absent from all captured output and log sinks.

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.

19.B Build the boundary contract

Keep grader scripts and hidden tests outside the agent-writable tree; copy trusted tests into a separate grading environment after the run. Record task, grader and dependency digests, model/config revision, trial outcome, infrastructure errors and accounting status. Validate 0 < k <= n and c <= n. Aggregate per-task metrics before averaging tasks. Compare paired task/model sets with uncertainty intervals rather than treating one small difference as proof.

• Editing visible tests cannot make a broken implementation pass the protected grader.
• Invalid estimator inputs return an error.
• Infrastructure failures are reported separately and never silently dropped.
• Baseline reports include trial counts and uncertainty.
• Task fixtures and grading dependencies have recorded revisions.

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).

20.B Build the boundary contract

Record snapshot file hashes and the agent’s resulting hashes. On restore, compare snapshot, agent result and current contents. Restore only when the current file still matches the recorded agent result; otherwise present a conflict and require direction. Preserve modes/symlinks and protected/ignored paths. Snapshot before any mutating batch, including bash and hooks. Keep feature acceptance criteria and grader outside model write authority; changing generated init scripts requires trust revalidation.

• Undo does not overwrite a user edit made after the agent change.
• Agent-created files are deleted only when their content still matches the recorded result.
• Ignored secrets and build outputs are not snapshotted or restored.
• Bash mutations are covered by snapshots.
• A feature flag cannot become verified solely because the model toggled it.