interface ForkedSubAgentSubAgentBaseSpecification for a subagent that inherits the parent's conversation instead of starting from just the task description.
Always forks: it inherits the parent's full message history and its exact
system prompt (there's no own prompt to fall back to). Mirrored middleware
is only added when its model matches the parent's, since that's the only
case with a cache benefit to protect. Deliberately has no systemPrompt
of its own: since its system slot always carries the parent's prompt,
there's nothing of its own to put there. If you need a subagent with a
distinguishing system prompt, use SubAgent without forking instead.
Description shown to the model for subagent selection
Human-in-the-loop configuration for specific tools. Requires a checkpointer.
Additional middleware to append after default_middleware
Always "fork". Required (not defaulted) so this can't structurally
collapse into a plain SubAgent — see isForkedSubAgent below.
The model for the agent. Defaults to defaultModel
Identifier used to select this subagent in the task tool
Filesystem permission rules for this subagent.
When specified, these rules replace the parent agent's permissions for all tool calls made by this subagent. When omitted, the subagent inherits the parent agent's permissions.
Subagent permissions are a full replacement, not a merge.
Structured output response format for the subagent.
When specified, the subagent will produce a structuredResponse conforming to the
given schema. The structured response is JSON-serialized and returned as the
ToolMessage content to the parent agent, replacing the default last-message extraction.
Accepts any format supported by createAgent: Zod schemas, JSON schema objects,
toolStrategy(schema), providerStrategy(schema), etc.
Skill source paths for SkillsMiddleware.
List of paths to skill directories (e.g., ["/skills/user/", "/skills/project/"]).
When specified, the subagent will have its own SkillsMiddleware that loads skills
from these paths. This allows subagents to have different skill sets than the main agent.
Note: Custom subagents do NOT inherit skills from the main agent by default. Only the general-purpose subagent inherits the main agent's skills.
A ForkedSubAgent never has its own system prompt — always the parent's.
The tools to use for the agent (tool instances, not names). Defaults to defaultTools
const researcher: ForkedSubAgent = {
name: "researcher",
description: "Continues the current investigation with full context",
mode: "fork",
tools: [webSearchTool],
};// Parent denies /restricted/**; this subagent can read it.
const reader: SubAgent = {
name: "reader",
permissions: [
{ operations: ["read"], paths: ["/restricted/**"] },
],
};import { z } from "zod"
const analyzer: SubAgent = {
name: "analyzer",
description: "Analyzes data and returns structured findings",
systemPrompt: "Analyze the data and return your findings.",
responseFormat: z.object({
findings: z.string(),
confidence: z.number(),
}),
};const researcher: SubAgent = {
name: "researcher",
description: "Research assistant",
systemPrompt: "You are a researcher.",
skills: ["/skills/research/", "/skills/web-search/"],
};