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.