Skip to content

Tool fork - #54

Merged
gvdongen merged 6 commits into
mainfrom
tool-fork
Nov 17, 2026
Merged

gvdongen merged 6 commits into
mainfrom
tool-fork

Conversation

@gvdongen

Copy link
Copy Markdown
Contributor

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 from agentTool starts 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.

const investigator = agent({
  model,
  tools: {
    readLogs,
    investigate: forkTool({
      description: "Check one hypothesis with a copy of yourself that sees this conversation.",
    }),
  },
});

Why

On Terminal-Bench (telecom-entity-resolution, gpt-6.1-sol at max effort), forks made a large difference against sub-agents that start from a brief:

Forks (forkTool) Blank workers (agentTool)
Result pass pass
Model calls 160 379
Tokens 7.2M 26.7M
Cached input 96.2% 97%
Time 38 min 77 min
Cost $2.32 $7.83

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_result in the fork returned the preview's JSON instead of the result the parent saw as a preview, without an error.
  • Deferred tools the parent had loaded with search were missing from the fork's tool list, which also missed the prompt cache.
  • Run-level tools (run(input, {tools})) were missing.
  • A background fork that waited for approval started from a later step and saw its own call as pending.
  • beforeStep ran again on messages that had already been through it.
  • A fork of a handed-off specialist ran without the lead's policies.

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:

  • the full history, with the same compaction note and preview settings, so every result behind a preview or folded into a note stays readable;
  • the same root and active agent, policies, configuration, run-level tools, and skill list;
  • the parent's reported token count, so the fork sizes its view as the parent would and does not compact when the parent would not.

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

  • Only the reply returns. The fork's answer becomes the tool result; its own tool calls stay out of the parent's history, and it saves nothing to the conversation. Its usage counts toward the parent's result.usage, its approval requests reach the run's handlers once, and interrupting the parent interrupts it.
  • One level. A fork cannot start forks or sub-agents: forkTool and agentTool called from a fork return a fork_nested error. This matches Codex's default depth, Claude Code's forks, and Deep Agents' forks.
  • Concurrency. maxConcurrent (default 6) bounds the forks of one run that run at once. A call past it returns a fork_limit error.
  • Hooks. A fork skips the root's beforeRun and afterRun, because its input and answer are a tool call of the parent and its result. beforeStep, beforeTool, and afterTool apply as in the parent.
  • The forked subagent responds in plain text

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 in agentTool (tool.ts), and the export.
  • packages/examples: lesson 20, an incident investigator that checks hypotheses in parallel forks.
  • Docs: README capabilities row, a Fork entry in CONTEXT.md, and the restate-agents skill (task table, a forks section in multi-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.
  • A replay test resumes a run with parallel forks from every journal entry and checks that each fork starts from the same view.
  • Lesson 20 runs in examples.integration.ts against 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

  • A fork sees the parent's pending background calls but cannot cancel them or receive their results.
  • Steering reaches only the parent; a foreground fork finishes its task first.
  • beforeStep and an instructions function see the fork's own step numbers and run name. If they depend on them, the fork's request misses the cache.
  • A fork's steps add to the parent's journal. Very long forks may be better as separate invocations later.

Not verified

  • Prompt cache reuse is checked on Anthropic request bodies, not on OpenAI, Gemini, or Bedrock, or against measured cache hits beyond the benchmark run.
  • Approval inside a fork under real suspension has no integration test.

Follow-ups

  • A run-wide token or cost budget across a run and its forks. This needs forks to add usage as each call finishes, not when the fork ends.

🤖 Generated with Claude Code

gvdongen and others added 5 commits November 16, 2026 15:00
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>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ 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.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using gpt-6-luna (free trial credits) | 𝕏

Comment thread packages/core/src/agent-run.ts Resolved

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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() to forkAgentTool() 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.

Pullfrog  | View workflow run | Using gpt-6-luna (free trial credits) | 𝕏

@gvdongen
gvdongen merged commit c2605cc into main Nov 17, 2026
4 checks passed
@gvdongen
gvdongen deleted the tool-fork branch November 17, 2026 09:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant