epic(agent): roadmap for interactive coding agents

[gold-silver-copper]

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 feat(agent): add push_notification to inject messages during multi-turn prompts #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 feat: Checkpoint and manual interrupt/resume operations #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 feat(core): expose a normalized finish reason / stop status on CompletionResponse #2090 with Expose streaming terminal metadata #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 Improve hook ergonomics for structured tool failures and call-scoped state #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 feat: host-facing ToolRegistry with typed native and MCP catalog entries #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 feat: add ToolDefinition#output_schema #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 feat: support provider-hosted tools in AgentBuilder end-to-end #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 feat: add durable database-backed ConversationMemory backends #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 feat: Claude Skills #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 feat: Add a "Code Mode" tool to Rig #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 feat: add code-mode-ready tool lifecycle, nested dispatch, and rich outputs #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 feat(agent): add push_notification to inject messages during multi-turn prompts #1858 and specify feat: Checkpoint and manual interrupt/resume operations #2116.
2. Consolidate terminal metadata in feat(core): expose a normalized finish reason / stop status on CompletionResponse #2090/Expose streaming terminal metadata #1886.
3. Split feat: add code-mode-ready tool lifecycle, nested dispatch, and rich outputs #2095 and land RunContext plus scoped nested execution.
4. Land the call-scoped portions of Improve hook ergonomics for structured tool failures and call-scoped state #2094.
5. Evolve feat: host-facing ToolRegistry with typed native and MCP catalog entries #1906 into an introspectable dynamic tool catalog.
6. Add output schemas and structured rich results through feat: add ToolDefinition#output_schema #1613/feat: add code-mode-ready tool lifecycle, nested dispatch, and rich outputs #2095.
7. Complete provider-hosted tools through feat: support provider-hosted tools in AgentBuilder end-to-end #1890.
8. Add durable session/event storage alongside feat: add durable database-backed ConversationMemory backends #1968.
9. Add provider-independent skills and subagent APIs.
10. Implement feat: Add a "Code Mode" tool to Rig #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.

[linear-code]

RIG-1404

[gold-silver-copper]

I did a source-level pass over Rig and two open-source coding harnesses (Pi and Codex), plus Claude Code's public docs. A few concrete findings may help turn this epic into smaller contracts.

What Rig already has

This roadmap should build on the current runtime rather than introduce a second agent engine:

• drive_agent is already the common streaming/non-streaming state machine. TurnSource isolates the medium-specific model/tool mechanics, so run control belongs around this loop rather than in separate run and stream implementations.
• HookContext already gives each run a stable process-scoped correlation ID, turn number, surface flag, agent name, and scratchpad. RunId is explicitly not globally unique across restarts, so RunContext will also need a host/durable conversation or session identity, plus cancellation, deadline, and call ancestry.
• RequestPatch is explicitly per-turn/non-sticky, and Flow is fail-closed. Those are good semantics for policy and turn-local steering, but an out-of-band run-control handle should not be encoded as another Flow variant.
• Tool batches already have useful transactional semantics: drive_tool_calls bounds concurrency, stops launching siblings after termination, drains in-flight work, deterministically selects the lowest-index error, and commits results only after the batch succeeds.
• ToolServerHandle already supports shared add/replace/remove and clones a tool under a short read lock before awaiting it. This implies snapshot semantics: removal affects future lookup, not a call that already cloned the tool. A host-facing catalog can expose and formalize this instead of replacing the server.
• ToolExecutionResult already separates model-visible output, structured outcome, and host-only extensions; ToolFailureKind already includes timeout/cancelled/permission/network classifications.
• Rig also already has a minimal subagent primitive: Agent<M>: Tool, including propagation of ToolCallExtensions. The missing layer is therefore orchestration—identity, bounds, cancellation, status, and typed handoff—not the ability to call an agent at all.
• ConversationMemory is deliberately only load/append/clear over messages. Its compaction contract also notes that delivery watermarks are process-local and may replay after restart (Compactor). This supports keeping conversation memory separate from a durable session/event store.

What the other harnesses make concrete

Pi provides a particularly crisp queue contract. Its loop polls steering messages at turn boundaries, processes follow-ups only when the agent would otherwise stop, and keeps the two paths distinct (agent-loop.ts). Its host API separately exposes steer, followUp, and nextTurn (agent-harness.ts); abort clears steer/follow-up queues, preserves next-turn input, signals the active run, and waits for idle (same file).

Pi's persistence model is also useful evidence for the proposed session-store split. Session records are typed tree entries with id, parentId, and timestamps; compaction, branch summaries, labels, custom records, and leaf movement are records rather than destructive transcript rewrites (types, JSONL append/leaf implementation).

Codex makes the control protocol explicit. Op::Interrupt has a documented scope and produces TurnAborted; notably, it does not terminate background terminal processes (protocol). Its terminal event carries a typed reason and timing metadata (TurnAbortedEvent), and review/compaction are explicitly non-steerable turn kinds (NonSteerableTurnKind). This suggests Rig should specify cancellation domains and safe/non-steerable phases rather than promise that every operation can always be interrupted or steered.

Codex also keeps approval policy separate from execution isolation: AskForApproval decides when requests may be approved, while SandboxPolicy independently describes read-only/workspace-write/external/full-access execution and network/writable-root constraints. That separation maps well to Rig hooks for policy plus a host-selected execution backend.

For child agents, Codex's spawn path enforces a depth limit, supports fresh versus forked context, records the parent thread, and emits lifecycle items (spawn implementation). This is a useful target contract for a future Rig orchestration layer, not necessarily an API to copy.

Claude Code publicly documents the same broad product surfaces—hooks, permissions and sandboxing, skills, and isolated subagents—but its harness implementation is not open source, so I would use those only as behavioral references, not as evidence for internal architecture.

Suggested contract boundaries for the child issues

1. RunContext + RunControlHandle: a process-scoped run correlation ID plus durable host/session identity, cancellation token, optional deadline, parent/call ancestry, status subscription, and cancel/steer/follow_up. Define queue ownership and idempotence explicitly. Poll steering at documented safe boundaries; mark phases such as compaction non-steerable where needed.
2. Cancellation domains: specify separately whether cancellation reaches the provider future, not-yet-started tools, in-flight native/MCP tools, subprocess trees, nested dispatch, and child agents. ToolFailureKind::Cancelled is an outcome vocabulary, not propagation by itself.
3. Terminal semantics: keep provider completion metadata separate from the agent-level RunOutcome. Today CompletionResponse has no normalized finish reason, while AgentRun only has Done and Failed terminal states. Define an explicit mapping/precedence rule from provider finish reason and runtime events into completed/cancelled/paused/failed/exhausted.
4. Session store, separate from ConversationMemory: append-only typed records, parent IDs/active leaf, interrupted-turn recovery, compaction records, usage/config metadata, and import/export. Derive model context from this log; do not force the log itself through Vec<Message>.
5. Catalog vs executor: evolve ToolServerHandle into an introspectable catalog while keeping one context-aware execution path. Document whether each turn snapshots definitions and what remove/replace means for in-flight calls.
6. Policy vs execution backend: hooks decide allow/deny/approval and path/resource rules; local/SSH/container/sandbox adapters enforce them. Do not make “approved” synonymous with “unsandboxed.”
7. Subagent orchestration over existing Agent: Tool: add parent/child IDs, fresh/inherited context choice, depth/concurrency budgets, cancellation propagation, progress/status, and typed completion. Route child tool use through the same scoped executor so policy/tracing cannot be bypassed.

For validation, I would make the run-control and cancellation suites black-box tests against both run() and stream(), with a fake model and blocking tool that expose each boundary deterministically. That would preserve the strongest property Rig already has: one behavioral contract across both surfaces.

[nazq]

Opened #2246 as a Phase 1 child issue: a live tool-execution start item on the multi-turn stream (host observability without hook re-merging). Implementation PR is linked there.