feat(agent): hand-drive a configured Agent — AgentDriver + DriveStep/TurnTools

[gold-silver-copper]

Round 2 note: the first commit shipped Agent::prepare_turn + PreparedTurn. A verified multi-agent review found ten defects, five of which were symptoms of one missing abstraction (the run/turn pairing living in every caller). Since nothing had shipped, round 2 (da8f620a) fixes the architecture instead of the symptoms: prepare_turn/PreparedTurn are gone, replaced by the driver below. The findings and their disposition are listed at the end.

Problem

An Agent is a configuration bundle, but AgentRunner was the only thing that could read it. Hand-driving the sans-IO AgentRun state machine is a documented supported use case (custom provider transport, durable suspend/resume — the run state is Serialize + Deserialize), yet a hand-driver had to re-derive everything: our own agent_run_stepping example registered its tool twice, copy-pasted the preamble, hand-assembled the 5-argument ModelTurn with two transposable BTreeSets, and restated max_turns the agent already knew.

What this adds

Agent::drive(prompt) / Agent::drive_run(run) → AgentDriver — a sans-IO shell that owns the run/turn pairing and nothing else:

let mut driver = agent.drive("What is 2 + 5?");
loop {
    match driver.next_step().await? {
        DriveStep::SendRequest { request, turn, .. } => {
            let response = request.send().await?;      // caller owns provider IO
            driver.model_response(&response)?;         // sets assembled internally
        }
        DriveStep::ExecuteTools { calls, tools } => {  // paired by construction
            let mut ctx = ToolContext::new();
            let mut results = Vec::new();
            for call in &calls { results.push(tools.execute_call(call, &mut ctx).await); }
            driver.tool_results(results)?;
        }
        DriveStep::Done(response) => break,
    }
}

• Seeded from the agent — default_max_turns, tool_choice, and the output schema flow into the run; nothing is restated (per-run overrides via .history() / .max_turns() or a custom AgentRun through drive_run).
• Advertise/dispatch consistency by construction — ExecuteTools carries the TurnTools snapshot of the turn that advertised the calls; registry mutations between advertise and dispatch cannot skew a turn.
• Structured output just works — the driver arms the run's output-tool intercept and threads the committed name through every turn exactly as the runner does (bug: output_schema is applied to every agent turn, suppressing tool calls in tool + structured-output agents #1928 pinning), so a Tool-mode agent driven by the documented pattern finalizes with its structured answer, and the mode can't flip or re-pick a name mid-run.
• Durable resume, honestly — serialize driver.run(), rebuild the agent in a fresh process, drive_run the deserialized run: the driver re-derives a fresh dispatch snapshot (implementations are live objects) and surfaces missing pending tools as an error before dispatch rather than silently feeding not-found to the model (allow_missing_resumed_tools() to opt out). Prior-art note: openai-agents' RunState resumes exactly this way and raises on missing tools by default; langgraph and pydantic-ai degrade silently — we take the loud behavior.
• Not a second execution path — the driver performs no provider IO, no dispatch, and runs no hooks/memory/retrieval/telemetry (AgentRunner remains the only path with those). It is built strictly on AgentRun's own step methods and the same build_agent_run/build_prepared_completion_request the runner uses — no duplicated turn-decision logic.

TurnTools (cheap Clone, Arc-shared) — the turn's executable/allowed name sets, output_tool_name(), execute() (snapshot-pinned, mirrors ToolServerHandle::execute), and execute_call(&PendingToolCall) handling preresolved results and result assembly.

ToolErrorKind::NotExecutable (rig-core, #[non_exhaustive] enum, additive) — dispatching the synthetic output tool is now machine-readably distinct from a hallucinated tool name. No inspected framework ships this discriminator; all of them route around it upstream.

Internals

• The clear → dispatch → publish result-metadata sequence is single-sourced (ToolDispatch::publish_to, ToolRegistrySnapshot::execute); the previously-triplicated wrapper had already diverged once (a rejection path skipping clear_dispatch_result — regression-tested now).
• PreparedCompletionRequest composes TurnTools directly; the internal/public mirror struct and its repack are gone. ToolRegistrySnapshot stays private.
• Runner and streaming paths behaviorally unchanged — all 518 pre-existing rig-agent tests pass as-is.

Examples

Both agent_run_stepping and agent_with_durable_approval are rewritten with zero pairing logic — no Option<TurnTools> juggling, no ModelTurn assembly, no restated configuration; the tools arm is decision logic (approve/deny/edit) plus execute_call. Both demonstrate genuine fresh-driver resume from serialized state.

Tests

15 new tests: full drive loop with registry mutation between advertise and dispatch; Tool-mode finalization via the intercept; two-turn committed-name pinning across a tool-set change; resume from serialized state alone; loud drift on a missing resumed tool + the opt-out; seeding from agent config (incl. the implicit budget of one); local tool_choice validation with zero provider requests; output tool allowed-but-NotExecutable; stale-context regression on the rejection path.

cargo clippy --all-features --all-targets clean, cargo doc zero warnings, both examples compile.

Review findings → disposition (round 1 → round 2)

#	Finding	Disposition
1	Documented pattern never armed the output-tool intercept	structural: driver arms it every turn
2	committed_output_tool hardcoded None; pin lost	structural: driver threads it like the runner
3	Examples bailed on cross-process resume	structural: drive_run re-derives dispatch; drift is loud
4	Rejection path skipped clear_dispatch_result	fixed + regression test; wrapper single-sourced
5	Rejection was ambiguous NotFound	ToolErrorKind::NotExecutable
6	"No telemetry" doc overclaim	doc corrected; opt-out documented on SendRequest
7	Third copy of the dispatch wrapper	single-sourced via publish_to
8	5-arg ModelTurn incantation	structural: assembled inside model_response
9	TurnTools mirrored PreparedCompletionRequest 1:1	composed; repack deleted
10	Dead tools() accessor; false "cheap to clone"	PreparedTurn removed entirely; sets Arcd, claim now true
11	Run construction restated agent config (found in round 2 review)	structural: drive seeds from the agent