epic(agent): roadmap for interactive coding agents

## Summary

Track the roadmap for making Rig a strong foundation for production-grade, interactive coding agents: agents that can be steered while running, execute tools safely, preserve and resume sessions, compose child agents and tools, and support extensible host-defined workflows.

Rig already has many of the right building blocks:

- a shared streaming/non-streaming agent drive loop;
- `AgentHook`, `HookStack`, `StepEvent`, and fail-closed `Flow` semantics;
- dynamic `ToolServerHandle` registration;
- structured `ToolExecutionResult`, `ToolFailure`, and typed tool extensions;
- `ConversationMemory`, memory policies, demotion, and compaction;
- per-request tool selection and tool concurrency.

The remaining work is mostly about connecting these pieces into a coherent host/runtime contract. This epic coordinates existing issues and identifies missing child issues. It is not intended to land as one PR.

## Motivation

Good coding agents need more than a ReAct loop. Interactive harnesses such as Pi demonstrate the value of a small core with strong host control:

- steering and follow-up messages during an active run;
- cancellation that reaches model requests, tools, and child work;
- resumable, branchable sessions with compaction;
- dynamically registered and selected tools;
- lifecycle interception for policy, approvals, context, and observability;
- safe local, remote, and sandboxed execution;
- progressive-disclosure skills;
- subagent and composite-tool orchestration.

Rig should provide provider-agnostic primitives for these capabilities without hard-coding one TUI, sandbox, scripting language, storage backend, or orchestration style.

## Design principles

1. **Host control over product opinion.** `rig-core` should expose lifecycle and execution primitives; applications decide UI, permissions, storage, and workflow.
2. **One runtime contract.** Streaming and non-streaming paths must preserve the same control-flow and tool semantics.
3. **Cancellation is end-to-end.** Model calls, native tools, MCP tools, nested dispatch, and child agents should observe one run-scoped cancellation/deadline contract.
4. **Native tools remain first-class.** MCP and provider-hosted tools should integrate without forcing in-process Rust tools through an external protocol.
5. **Structured internally, serialized only at boundaries.** Host metadata and rich tool outputs should not depend on magic JSON string conventions.
6. **Concurrency must be explicit.** Call-scoped state, file mutations, output ordering, and parent/child relationships must remain correct under parallel execution.
7. **Persistence should preserve history, not only the latest prompt.** Durable sessions must support recovery and branching without requiring every host to reinvent an event log.
8. **Large changes land as focused PRs.** Each item below should have its own issue, acceptance criteria, tests, and migration plan where applicable.

## Phase 1: interactive run control

### Steering and follow-up messages

- [ ] Review, rebase, and complete #1858.
- [ ] Define separate delivery semantics for:
- **steer**: deliver after the current safe boundary/tool batch and before the next model call;
- **follow-up**: deliver only after the active run settles;
- **next turn**: queue without interrupting or starting a run.
- [ ] Prevent messages from leaking across runs or conversations.
- [ ] Cover concurrent injection and streaming/non-streaming parity.

### Cancellation, interruption, and resume

- [ ] Clarify and decompose #2116.
- [ ] Introduce a cloneable run-control handle with at least run ID, status, `cancel`, `steer`, and `follow_up` operations.
- [ ] Propagate cancellation/deadlines through completion requests, tool execution, nested dispatch, and child work.
- [ ] Define safe pause/checkpoint boundaries. Do not attempt to serialize or suspend arbitrary Rust futures.
- [ ] Distinguish completed, cancelled, paused, failed, and exhausted runs.

### Terminal status

- [ ] Reconcile #2090 with #1886 so streaming and non-streaming responses use one normalized terminal-reason vocabulary.
- [ ] Make truncation, natural completion, tool handoff, filtering, cancellation, and provider failure available to retry/recovery policy.

## Phase 2: run-scoped execution and composition

The umbrella issue for this phase is #2095. It should be split into focused child issues.

### Run context and lifecycle

- [ ] Add a `RunContext` carrying stable run/conversation identity, cancellation, deadline, and current call ancestry.
- [ ] Make relevant context available to tools without requiring applications to manually populate every `ToolCallExtensions` value.
- [ ] Add run-scoped tool/toolset factories with deterministic cleanup for stateful shells, REPLs, sandboxes, and connections.

### Scoped/nested tool execution

- [ ] Add a public scoped executor that dispatches nested calls through normal lookup, hooks, policy, tracing, and structured outcomes.
- [ ] Preserve inherited call extensions while generating child internal IDs.
- [ ] Record `parent_internal_call_id` and expose parent/child relationships to hooks and telemetry.
- [ ] Add allowlists, depth limits, and recursion guards.
- [ ] Ensure cancellation propagates into nested calls.

### Call-scoped policy state

- [ ] Implement the call-scoped state and structured error-reporting portions of #2094.
- [ ] Make concurrent tool calls unable to overwrite or consume one another's policy state accidentally.
- [ ] Add a public hook test harness capable of exercising event ordering, rewrites, failures, and correlated concurrent calls.
- [ ] Evaluate graceful successful termination separately from cancellation (`Flow::Finish` or equivalent).

## Phase 3: host-facing tool platform

### Dynamic and introspectable tool catalog

- [ ] Refine and decompose #1906 around the existing `ToolServerHandle` rather than creating a competing registry.
- [ ] Expose catalog enumeration, tool kind, source/provenance, schemas, and host-only metadata.
- [ ] Support dynamic add/remove/replace and per-run/per-turn activation.
- [ ] Represent native, MCP, dynamic, and provider-hosted tools without erasing their operational differences.
- [ ] Keep one context-aware dispatch path and preserve registration order.

### Structured definitions and results

- [ ] Implement #1613 with a clear distinction between model-facing output schema and host-only metadata.
- [ ] Replace magic string envelopes with a structured tool-output channel supporting text and rich content parts.
- [ ] Preserve a compatibility path for existing string-returning tools.
- [ ] Add execution metadata needed by hosts, such as parallel-safe/sequential policy and terminating/final-result behavior.
- [ ] Add bounded retry/repair semantics for tool executions that need the model to regenerate arguments.

### Provider-hosted tools

- [ ] Implement #1890 end-to-end through `AgentBuilder`, request construction, and provider serialization.
- [ ] Merge native and provider-hosted tool definitions without duplicate wire keys.
- [ ] Keep provider-hosted execution semantics distinct from client-executed tools.

### Coding-tool operational safety

Create focused child issues for:

- [ ] output truncation with an artifact/reference to the complete output;
- [ ] per-resource mutation queues, including per-file serialization to prevent lost concurrent edits;
- [ ] cancellation-aware shell execution and process-tree termination;
- [ ] pluggable local, SSH, container, and sandbox operation backends;
- [ ] progress updates for long-running tools;
- [ ] permission, path-protection, and project-trust policy examples.

## Phase 4: sessions, memory, and reusable capabilities

### Durable sessions

- [ ] Implement a narrowly scoped durable `ConversationMemory` backend from #1968.
- [ ] Create a separate session/event-store issue covering:
- append-only messages, model calls, tool calls/results, and custom host entries;
- parent IDs and branch navigation;
- bookmarks/checkpoints;
- compaction summaries while retaining full history;
- model/config/usage metadata;
- recovery from interrupted turns;
- import/export and backend-neutral storage traits.

`ConversationMemory` and a durable session store solve different problems and should not be conflated.

### Provider-independent skills

- [ ] Split #1264 into provider-hosted skills and host-loaded Agent Skills.
- [ ] Define a provider-independent skill catalog using progressive disclosure: advertise names/descriptions, then load full instructions and assets on demand.
- [ ] Keep filesystem discovery and project trust in optional host/companion layers rather than forcing them into every `Agent`.
- [ ] Support the Agent Skills standard where practical and preserve provenance/tool restrictions.

### Subagents

Create a focused child issue after scoped execution is available:

- [ ] spawn child agents with fresh or inherited context;
- [ ] bounded concurrency and depth;
- [ ] cancellation and deadline propagation;
- [ ] progress/status observation;
- [ ] typed handoff results;
- [ ] parent/child trace and session correlation.

## Phase 5: code mode and sandbox runtimes

- [ ] Build #1439 only after the run-context, nested-execution, structured-output, and cancellation contracts above exist.
- [ ] Keep the framework primitives runtime/language agnostic as proposed in #2095.
- [ ] Treat JavaScript, Python/Monty, Lua, shell, or WebAssembly runtimes as adapters/companion crates where their dependencies are substantial.
- [ ] Require resource limits, cancellation, recursion protection, explicit host-function allowlists, and security documentation.
- [ ] Allow code mode to transform a selected tool catalog without accidentally exposing both wrapped and unwrapped tools.

## Cross-cutting validation

Every child issue that changes the agent runtime should cover, where applicable:

- streaming and non-streaming parity through the shared drive loop;
- WASM-compatible bounds and futures;
- concurrent tool calls and deterministic correlation;
- cancellation and cleanup;
- tool/server mutation during active runs;
- transcript and memory behavior;
- hooks before and after rewrites/skips/failures;
- no leakage of host-only metadata to the model;
- focused unit tests plus cassette/provider coverage when wire behavior changes.

## Suggested implementation order

1. Finish steering semantics from #1858 and specify #2116.
2. Consolidate terminal metadata in #2090/#1886.
3. Split #2095 and land `RunContext` plus scoped nested execution.
4. Land the call-scoped portions of #2094.
5. Evolve #1906 into an introspectable dynamic tool catalog.
6. Add output schemas and structured rich results through #1613/#2095.
7. Complete provider-hosted tools through #1890.
8. Add durable session/event storage alongside #1968.
9. Add provider-independent skills and subagent APIs.
10. Implement #1439 code mode on the resulting foundation.

## Non-goals

- Building a terminal UI in `rig-core`.
- Standardizing on one scripting language or sandbox runtime.
- Requiring MCP for in-process tools.
- Making one database the mandatory session backend.
- Implementing every item in a single PR or release.
- Weakening existing fail-closed hook behavior for convenience.

## Completion criteria for this epic

This epic can be considered complete when a downstream host can, using stable public Rig APIs:

1. start an agent run and obtain a run-control handle;
2. steer, follow up, cancel, observe, and safely resume the run;
3. register and select tools dynamically;
4. run native tools locally or through a host-selected sandbox/remote backend;
5. compose nested tools and child agents with cancellation and correlation;
6. receive structured rich results and machine-readable failures;
7. persist, compact, branch, and restore sessions;
8. load reusable skills through a provider-independent catalog;
9. optionally install a code-mode runtime without changing the core agent loop.

This is a large roadmap epic coordinating many existing issues. Start by reading the linked issues (#1858, #2116, #2090, #1886, #2095, #2094, #1906, #1613, #1890, #1968, #1264, #1439) to understand the specific components. The work is about connecting primitives in rig-core, such as AgentHook, ToolServerHandle, and ConversationMemory, into a coherent runtime contract. Implementation should follow the suggested order, beginning with steering semantics and run control.

由索引模型根据 Issue 内容生成。