Repository navigation
Conversation
agentTool(agent, {fork: true}) starts the sub-agent from the parent's
conversation instead of a fresh one: the messages of the parent's latest model
request, after its beforeStep hooks, followed by the task. A sub-agent with the
parent's instructions and tools then reuses the provider's cached prefix. A
fork cannot fork again; its delegate call returns a fork_nested error.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
ℹ️ One concurrency edge case worth addressing inline.
Reviewed changes This review covers the fork implementation, its integration into run/history/tool execution, and the accompanying examples, tests, and documentation.
- Forked runs.
forkTool()starts a copy from the call's branch point, inheriting the active agent, policies, tools, skills, and history while returning only a plain-text reply. - Execution and history. Forks preserve preview/compaction context, participate in approvals and progress, contribute usage, support replay, and enforce one-level delegation and concurrency limits.
- Coverage and docs. The PR adds unit and integration tests, an example lesson, and updates the README and Restate Agents skill.
Important
This run used your free trial credits ($9.34 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.
gpt-6-luna (free trial credits) | 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes This incremental review covers the fork-tool API rename and per-tool concurrency behavior added since the prior Pullfrog review.
- Renamed the public tool. Renamed
forkTool()toforkAgentTool()across exports, examples, tests, README, and the Restate Agents skill. - Scoped concurrency limits per tool. Counted active forks by fork-tool instance, updated the documentation, and added tests for independent limits across instances.
Important
This run used your free trial credits ($9.30 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.
gpt-6-luna (free trial credits) | 𝕏

Add forkTool: forked sub-agents that copy the running agent
forkTool()starts a copy of the running agent to do one task. A sub-agent fromagentToolstarts with only its task; a fork starts from the conversation up to the step that called the tool, so it builds on what the run already found instead of rediscovering it. Its first request repeats that step's request plus the task, so the provider serves the shared part from its prompt cache.Why
On Terminal-Bench (
telecom-entity-resolution,gpt-6.1-solat max effort), forks made a large difference against sub-agents that start from a brief:forkTool)agentTool)An earlier prototype of forks (
agentTool(agent, {fork: true})) passed the same task in 39 minutes for $2.91, so the redesign below keeps the gain. Each number is one run.Design: a fork is a copy of the run
The first prototype started a new run of an agent definition, seeded with the parent's messages. Tests showed that the messages depend on run state they don't contain, which caused six problems:
read_tool_resultin the fork returned the preview's JSON instead of the result the parent saw as a preview, without an error.run(input, {tools})) were missing.beforeStepran again on messages that had already been through it.Now the run records a branch point before each tool batch: where its history stands, the active agent, the loaded deferred tools, and the input token count the provider reported. A fork call copies the run from the branch point of its step:
Forks run in the parent's invocation and read this state from memory, not from the journal or Restate state. A replay rebuilds it by running the same steps.
Rules
result.usage, its approval requests reach the run's handlers once, and interrupting the parent interrupts it.forkToolandagentToolcalled from a fork return afork_nestederror. This matches Codex's default depth, Claude Code's forks, and Deep Agents' forks.maxConcurrent(default 6) bounds the forks of one run that run at once. A call past it returns afork_limiterror.beforeRunandafterRun, because its input and answer are a tool call of the parent and its result.beforeStep,beforeTool, andafterToolapply as in the parent.Changes
packages/core:forkTool(fork.ts), the shared fork link and nesting check (fork-source.ts), history branching (run-history.ts), branch points and fork runs (agent-run.ts), the nesting check inagentTool(tool.ts), and the export.packages/examples: lesson 20, an incident investigator that checks hypotheses in parallel forks.CONTEXT.md, and therestate-agentsskill (task table, a forks section inmulti-agent.md, and notes on policies, progress, steering, and usage).Tests
fork.test.ts,fork-tools.test.ts,fork-replay.test.ts: 36 tests covering what a fork copies, previews and compaction, deferred and run-level tools, background and approved forks, handoffs and policies, hooks, structured output, conversation, usage (including forks that fail), the nesting rule, the concurrency limit, and the Anthropic request format of a fork's first request.examples.integration.tsagainst Restate with every step replayed.All 307 unit tests and all 69 integration tests (AG-UI, coding agent, examples, runtime) pass. Typecheck, lint, and format are clean.
Known limits
beforeStepand aninstructionsfunction see the fork's own step numbers and run name. If they depend on them, the fork's request misses the cache.Not verified
Follow-ups
🤖 Generated with Claude Code