@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/tools/builtin-names.d.ts

@@ -21,17 +21,40 @@ export declare const BUILTIN: {
     readonly ReadToolOutput: "ReadToolOutput";
     readonly ToolSearch: "ToolSearch";
     readonly Agent: "Agent";
+    readonly SendMessage: "SendMessage";
+    readonly SubagentHandback: "SubagentHandback";
+    readonly TaskOutput: "TaskOutput";
+    readonly TaskStop: "TaskStop";
+    readonly WebSearch: "WebSearch";
+    readonly WebFetch: "WebFetch";
+    readonly Platform: "Platform";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
-/** The builtin tools that run in the conversation's sandbox. */
+/**
+ * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ */
 export declare const SANDBOX_TOOL_NAMES: readonly BuiltinName[];
-/** Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the read-only ones). */
+/** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
+export declare const WEB_TOOL_NAMES: readonly BuiltinName[];
+/**
+ * The tools offered with `Bash` whenever it is offered (background Bash: a model that can start a
+ * background task can read and stop it). `ToolRegistry` adds them; an explicit ref is harmless.
+ */
+export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
+/**
+ * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
+ * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
  * registered now, so the order the implementations land in never affects a saved definition.
  * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
- * by the registry; `Agent` dispatches sub-agents and its description is built per agent.
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
+ * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
+ * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
  */
 export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
@@ -40,6 +63,16 @@ export declare const SKILL_LOAD: "Skill";
 export declare const TOOL_SEARCH: "ToolSearch";
 /** The builtin that dispatches sub-agents. */
 export declare const AGENT_TOOL: "Agent";
+/** The builtin that sends a message to one of the caller's sub-agents or to its parent. */
+export declare const SEND_MESSAGE: "SendMessage";
+/** The builtin that hands a sub-agent's report back to its parent (sub-agents only). */
+export declare const SUBAGENT_HANDBACK: "SubagentHandback";
+/**
+ * The tools between the agents of one tree (agent map spec §4.2, §4.3), added by the registry
+ * whatever a definition names: `SendMessage` to an agent that has `Agent` or a parent, and
+ * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
+ */
+export declare const SUBAGENT_MESSAGE_TOOLS: ReadonlySet<string>;
 /**
  * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
  * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
@@ -52,14 +85,15 @@ export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
  */
 export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
 /**
- * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `Agent` (depth 1), `AskUserQuestion`
- * (the person does not see the child), `Deliver` (delivering files is the parent's job) and
- * `SkillWrite`.
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child), `Deliver` (delivering files is the parent's job) and `SkillWrite`. `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
-export declare const CHILD_REMOVED_TOOLS: readonly ["Agent", "AskUserQuestion", "Deliver", "SkillWrite"];
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "SkillWrite"];
 /**
  * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
  * by a definition). Only for create requests; updates and stored versions get no defaults.
+ * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
  */
 export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */

package/dist/tools/builtin-names.js

@@ -19,8 +19,18 @@ export const BUILTIN = {
     ReadToolOutput: "ReadToolOutput",
     ToolSearch: "ToolSearch",
     Agent: "Agent",
+    SendMessage: "SendMessage",
+    SubagentHandback: "SubagentHandback",
+    TaskOutput: "TaskOutput",
+    TaskStop: "TaskStop",
+    WebSearch: "WebSearch",
+    WebFetch: "WebFetch",
+    Platform: "Platform",
 };
-/** The builtin tools that run in the conversation's sandbox. */
+/**
+ * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
+ * stop the background tasks `Bash` started (background Bash spec §2.2, §2.3).
+ */
 export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Bash,
     BUILTIN.Read,
@@ -29,8 +39,21 @@ export const SANDBOX_TOOL_NAMES = [
     BUILTIN.Glob,
     BUILTIN.Grep,
     BUILTIN.Deliver,
+    BUILTIN.TaskOutput,
+    BUILTIN.TaskStop,
 ];
-/** Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the read-only ones). */
+/** The builtin tools that reach the web through the org's web-search / web-fetch providers. */
+export const WEB_TOOL_NAMES = [BUILTIN.WebSearch, BUILTIN.WebFetch];
+/**
+ * The tools offered with `Bash` whenever it is offered (background Bash: a model that can start a
+ * background task can read and stop it). `ToolRegistry` adds them; an explicit ref is harmless.
+ */
+export const BASH_COMPANION_TOOLS = [BUILTIN.TaskOutput, BUILTIN.TaskStop];
+/**
+ * Sandbox tools that need approval when the org setting `sandboxToolPolicy` is `ask` (not the
+ * read-only ones). Not `TaskOutput` or `TaskStop`: they only read or stop a task whose launch
+ * already went through `Bash`'s policy (background Bash spec §4.5).
+ */
 export const SANDBOX_ASK_TOOL_NAMES = new Set([
     BUILTIN.Bash,
     BUILTIN.Write,
@@ -41,7 +64,9 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
  * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
  * registered now, so the order the implementations land in never affects a saved definition.
  * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
- * by the registry; `Agent` dispatches sub-agents and its description is built per agent.
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
+ * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
+ * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
  */
 export const BUILTIN_TOOL_NAMES = [
     BUILTIN.AskUserQuestion,
@@ -51,6 +76,10 @@ export const BUILTIN_TOOL_NAMES = [
     BUILTIN.SkillWrite,
     ...SANDBOX_TOOL_NAMES,
     BUILTIN.Agent,
+    BUILTIN.SendMessage,
+    BUILTIN.SubagentHandback,
+    ...WEB_TOOL_NAMES,
+    BUILTIN.Platform,
 ];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
 export const SKILL_LOAD = BUILTIN.Skill;
@@ -58,6 +87,19 @@ export const SKILL_LOAD = BUILTIN.Skill;
 export const TOOL_SEARCH = BUILTIN.ToolSearch;
 /** The builtin that dispatches sub-agents. */
 export const AGENT_TOOL = BUILTIN.Agent;
+/** The builtin that sends a message to one of the caller's sub-agents or to its parent. */
+export const SEND_MESSAGE = BUILTIN.SendMessage;
+/** The builtin that hands a sub-agent's report back to its parent (sub-agents only). */
+export const SUBAGENT_HANDBACK = BUILTIN.SubagentHandback;
+/**
+ * The tools between the agents of one tree (agent map spec §4.2, §4.3), added by the registry
+ * whatever a definition names: `SendMessage` to an agent that has `Agent` or a parent, and
+ * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
+ */
+export const SUBAGENT_MESSAGE_TOOLS = new Set([
+    SEND_MESSAGE,
+    SUBAGENT_HANDBACK,
+]);
 /**
  * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
  * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
@@ -72,12 +114,11 @@ export const R3_SHARED_AGENT_ONLY_TOOL_KEYS = new Set([
     BUILTIN.SkillWrite,
 ]);
 /**
- * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `Agent` (depth 1), `AskUserQuestion`
- * (the person does not see the child), `Deliver` (delivering files is the parent's job) and
- * `SkillWrite`.
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child), `Deliver` (delivering files is the parent's job) and `SkillWrite`. `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
 export const CHILD_REMOVED_TOOLS = [
-    BUILTIN.Agent,
     BUILTIN.AskUserQuestion,
     BUILTIN.Deliver,
     BUILTIN.SkillWrite,
@@ -85,10 +126,12 @@ export const CHILD_REMOVED_TOOLS = [
 /**
  * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
  * by a definition). Only for create requests; updates and stored versions get no defaults.
+ * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
  */
 export const DEFAULT_AGENT_TOOLS = [
     { kind: "builtin", name: BUILTIN.AskUserQuestion },
     { kind: "builtin", name: BUILTIN.ReadToolOutput },
+    { kind: "builtin", name: BUILTIN.Platform },
 ];
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
 export const BUILTIN_TOOL_KINDS = {
@@ -99,11 +142,18 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.Glob]: "search",
     [BUILTIN.Grep]: "search",
     [BUILTIN.Deliver]: "tool",
+    [BUILTIN.TaskOutput]: "read",
+    [BUILTIN.TaskStop]: "command",
     [BUILTIN.ToolSearch]: "meta",
     [BUILTIN.Skill]: "meta",
     [BUILTIN.SkillWrite]: "meta",
     [BUILTIN.ReadToolOutput]: "meta",
     [BUILTIN.AskUserQuestion]: "meta",
+    [BUILTIN.SendMessage]: "meta",
+    [BUILTIN.SubagentHandback]: "meta",
+    [BUILTIN.WebSearch]: "search",
+    [BUILTIN.WebFetch]: "read",
+    [BUILTIN.Platform]: "tool",
 };
 /**
  * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
@@ -112,5 +162,7 @@ export const BUILTIN_TOOL_KINDS = {
  * with one (or a different wording) still match.
  */
 export const MATCH_IGNORED_FIELDS = {
+    // `run_in_background` is matched on purpose: it changes what the call did (a launch that
+    // returns at once instead of the command's output; background Bash spec §4.4)
     [BUILTIN.Bash]: ["description"],
 };

package/dist/tools/builtins/agent.d.ts

@@ -1,16 +1,16 @@
 import type { ToolSpec } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import type { EventPayload } from "../../conversations/events.js";
 import { type RosterEntry } from "../../runtime/subagents/roster.js";
+import { type SubagentAbortedBy, type SubagentStatus } from "../../runtime/subagents/status.js";
 import type { BuiltinTool } from "../registry.js";
 export { AGENT_TOOL } from "../builtin-names.js";
 /**
- * The `Agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
- * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
- * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
+ * The `Agent` builtin tool (sub-agents spec §4, agent map spec §4.1): dispatches a sub-agent in
+ * the background. Its description is built per parent agent version from the roster
+ * ({@link agentToolSpec}); the tool pipeline handles the call itself (the dispatch writes the
+ * call's result, {@link agentStartedText}), so {@link agentTool}'s `run` is only a guard. The
+ * sub-agent's reports and its finish reach the parent as `subagent_delivery` events.
  */
-/** How a sub-agent's run ended (`subagent_finished.status`). */
-export type SubagentStatus = EventPayload<"subagent_finished">["status"];
 /** The input of an `Agent` call (§4.2). */
 export declare const AgentToolInput: z.ZodObject<{
     description: z.ZodString;
@@ -22,7 +22,6 @@ export declare const AgentToolInput: z.ZodObject<{
         inherit: "inherit";
         standard: "standard";
     }>>;
-    resume: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type AgentToolInputT = z.infer<typeof AgentToolInput>;
 /**
@@ -37,21 +36,29 @@ export declare const AGENT_REFUSALS: {
     readonly tooManyConcurrent: (n: number) => string;
     readonly tooManyDispatches: (n: number) => string;
     readonly budget: (n: number) => string;
-    readonly noSuchAgent: (id: string) => string;
-    readonly stillRunning: (id: string) => string;
-    readonly resumeWithType: "resume cannot be combined with subagent_type or model.";
+    readonly depthLimit: (maxDepth: number) => string;
     readonly notAvailableHere: "Sub-agents are not available in this conversation.";
     readonly agentNotAvailable: (name: string) => string;
 };
 /**
- * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
- * parent's open `Agent` call, and the text of a child stopped with its parent.
+ * The run was stopped while this sub-agent worked (§4.4, §12): the report of a stopped run's fork
+ * invocation whose sub-agent was still active (it is stopped with the run).
  */
 export declare const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /**
- * The tool result of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
- * the status line with its `agentId`. `ownModel`: an org agent dispatched with a `model` that was
- * ignored. `abortedBy: "parent"`: stopped together with the parent run (seen only in logs).
+ * The immediate result of an `Agent` call (agent map spec §4.1): the sub-agent runs in the
+ * background, its reports and its finish arrive later as notifications (`subagent_delivery`).
+ * `ownModel`: an org agent dispatched with a `model`, which runs on its own model instead.
+ */
+export declare const agentStartedText: (agentId: string, opts?: {
+    ownModel?: boolean;
+}) => string;
+/**
+ * The result text of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
+ * the status line with its `agentId`. Used for a fork invocation's report (phase D); a background
+ * `Agent` call's sub-agent reports through `subagent_delivery` instead. `ownModel`: an org agent
+ * dispatched with a `model` that was ignored. `abortedBy: "parent"`: stopped together with the
+ * parent run.
  */
 export declare function agentResultText(r: {
     reply: string;
@@ -63,12 +70,7 @@ export declare function agentResultText(r: {
     durationMs: number;
     tokens: number;
     ownModel?: boolean;
-    abortedBy?: "user" | "parent";
-    /**
-     * Phase D: the report of a person's fork invocation, whose parent need not have the `Agent`
-     * tool: the status line leaves out the resume hint (batch 3 review m2).
-     */
-    noResumeHint?: boolean;
+    abortedBy?: SubagentAbortedBy;
 }): {
     content: string;
     isError: boolean;

package/dist/tools/builtins/agent.js

@@ -1,7 +1,15 @@
 import { z } from "zod";
 import { ROSTER_DESCRIPTION_MAX } from "../../runtime/subagents/roster.js";
+import { subagentStatusText, } from "../../runtime/subagents/status.js";
 import { AGENT_TOOL } from "../builtin-names.js";
 export { AGENT_TOOL } from "../builtin-names.js";
+/**
+ * The `Agent` builtin tool (sub-agents spec §4, agent map spec §4.1): dispatches a sub-agent in
+ * the background. Its description is built per parent agent version from the roster
+ * ({@link agentToolSpec}); the tool pipeline handles the call itself (the dispatch writes the
+ * call's result, {@link agentStartedText}), so {@link agentTool}'s `run` is only a guard. The
+ * sub-agent's reports and its finish reach the parent as `subagent_delivery` events.
+ */
 /** The input of an `Agent` call (§4.2). */
 export const AgentToolInput = z
     .object({
@@ -9,7 +17,6 @@ export const AgentToolInput = z
     prompt: z.string().min(1).max(100_000),
     subagent_type: z.string().min(1).max(130).optional(),
     model: z.enum(["inherit", "fast", "standard", "capable"]).optional(),
-    resume: z.string().max(64).optional(),
 })
     .strict();
 /** Display only (UI refresh B): the task name, then the type; never sent to the model. */
@@ -28,7 +35,7 @@ const INPUT_SCHEMA = {
             minLength: 1,
             maxLength: 100000,
             description: "The complete task for the sub-agent. It sees nothing else of this conversation: include " +
-                "every fact, file path and constraint it needs, and say what its final reply must contain.",
+                "every fact, file path and constraint it needs, and say what its report must contain.",
         },
         subagent_type: {
             type: "string",
@@ -44,25 +51,22 @@ const INPUT_SCHEMA = {
                 "integration and judgment, capable for design and final reviews. Defaults to the agent " +
                 "type's own setting, else your model.",
         },
-        resume: {
-            type: "string",
-            maxLength: 64,
-            description: "The agentId from an earlier result of this tool: sends prompt to that sub-agent as a " +
-                "follow-up, with its earlier context intact. Leave subagent_type and model unset.",
-        },
     },
     required: ["description", "prompt"],
     additionalProperties: false,
 };
-/** The text before the roster (§4.3), with the concurrency limit. */
-const head = (maxConcurrent) => "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
-    "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
-    "include everything it needs and say what its final reply must contain. It shares your sandbox " +
-    "files. You wait until it finishes. To run several at once, call this tool several times in the " +
-    `same response (at most ${maxConcurrent} at a time); their commands run in the sandbox at the ` +
-    "same time, so give parallel sub-agents separate files or directories. Sub-agents cannot " +
-    "dispatch sub-agents or ask the user questions. To send a finished sub-agent a follow-up while " +
-    "keeping its context, pass the agentId from its result as resume.\n" +
+/** The text before the roster (§4.3, agent map spec §4.1), with the concurrency limit. */
+const head = (maxConcurrent) => "Dispatch a sub-agent: a fresh agent with its own context that works on one task in the " +
+    "background. This tool returns at once with the sub-agent's agentId; keep working or end your " +
+    "turn, and do not wait for it. When the sub-agent hands back a report or finishes, its result " +
+    "arrives in this conversation as a notification. The sub-agent sees only your prompt, not this " +
+    "conversation, so include everything it needs and say what its report must contain. It shares " +
+    "your sandbox files. To run several at once, call this tool several times (at most " +
+    `${maxConcurrent} of your sub-agents run at a time); their commands run in the sandbox at the ` +
+    "same time, so give parallel sub-agents separate files or directories. To give a sub-agent more " +
+    "instructions while it works, or a follow-up after it finished, use SendMessage with its " +
+    "agentId. Sub-agents can dispatch sub-agents of their own up to the nesting limit; they cannot " +
+    "ask the user questions.\n" +
     "\n" +
     "Agent types (subagent_type):\n";
 /**
@@ -96,20 +100,23 @@ export function agentToolSpec(roster, maxConcurrent) {
 }
 /**
  * The static definition: the rendering for a roster of only general-purpose at the default
- * `subagents.maxConcurrentPerRun` (what an agent without `subagents` gets under the defaults).
+ * `subagents.maxConcurrentPerConversation` (what an agent without `subagents` gets under the defaults).
  * Written out as a literal for the tool design check; a test pins it equal to
  * `agentToolSpec([general-purpose], 4)`.
  */
 const SPEC = {
     name: "Agent",
-    description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
-        "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
-        "include everything it needs and say what its final reply must contain. It shares your sandbox " +
-        "files. You wait until it finishes. To run several at once, call this tool several times in the " +
-        "same response (at most 4 at a time); their commands run in the sandbox at the same time, so give " +
-        "parallel sub-agents separate files or directories. Sub-agents cannot dispatch sub-agents or ask " +
-        "the user questions. To send a finished sub-agent a follow-up while keeping its context, pass the " +
-        "agentId from its result as resume.\n" +
+    description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task in the " +
+        "background. This tool returns at once with the sub-agent's agentId; keep working or end your " +
+        "turn, and do not wait for it. When the sub-agent hands back a report or finishes, its result " +
+        "arrives in this conversation as a notification. The sub-agent sees only your prompt, not this " +
+        "conversation, so include everything it needs and say what its report must contain. It shares " +
+        "your sandbox files. To run several at once, call this tool several times (at most 4 of your " +
+        "sub-agents run at a time); their commands run in the sandbox at the same time, so give " +
+        "parallel sub-agents separate files or directories. To give a sub-agent more instructions " +
+        "while it works, or a follow-up after it finished, use SendMessage with its agentId. " +
+        "Sub-agents can dispatch sub-agents of their own up to the nesting limit; they cannot ask the " +
+        "user questions.\n" +
         "\n" +
         "Agent types (subagent_type):\n" +
         "- general-purpose: a copy of you with your tools and skills, for multi-step work.",
@@ -119,18 +126,16 @@ const SPEC = {
 /** Refusals (§4.5): `isError` results written without starting anything (model-visible). */
 export const AGENT_REFUSALS = {
     unknownType: (x, roster) => `Unknown subagent_type "${x}". Available: ${roster.join(", ")}.`,
-    tooManyConcurrent: (n) => `At most ${n} sub-agents can run at once in this run; dispatch the remaining tasks after these finish.`,
-    tooManyDispatches: (n) => `This run has dispatched ${n} sub-agents, the limit; do the remaining work yourself.`,
-    budget: (n) => `Sub-agents of this run have used their token budget (${count(n)} tokens); do the remaining work yourself.`,
-    noSuchAgent: (id) => `No sub-agent with agentId "${id}" in this conversation.`,
-    stillRunning: (id) => `Sub-agent "${id}" is still running; wait for its result before sending a follow-up.`,
-    resumeWithType: "resume cannot be combined with subagent_type or model.",
+    tooManyConcurrent: (n) => `At most ${n} of your sub-agents can run at once in this conversation; dispatch the remaining tasks after one of them finishes.`,
+    tooManyDispatches: (n) => `${n} sub-agents have been dispatched since the user's latest message, counted across all levels of sub-agents; that is the limit, so do the remaining work yourself.`,
+    budget: (n) => `Sub-agents have used their token budget since the user's latest message (${count(n)} tokens, counted across all levels of sub-agents); do the remaining work yourself.`,
+    depthLimit: (maxDepth) => `Sub-agents can be nested at most ${maxDepth} levels deep, and you are at the deepest level; do this task yourself.`,
     notAvailableHere: "Sub-agents are not available in this conversation.",
     agentNotAvailable: (name) => `The agent "${name}" is not available to the person who started this conversation; do this task yourself or use another agent type.`,
 };
 /**
- * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
- * parent's open `Agent` call, and the text of a child stopped with its parent.
+ * The run was stopped while this sub-agent worked (§4.4, §12): the report of a stopped run's fork
+ * invocation whose sub-agent was still active (it is stopped with the run).
  */
 export const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
 /** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
@@ -145,46 +150,50 @@ function duration(ms) {
     return `${Math.floor(s / 3600)}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
 }
 /**
- * The tool result of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
- * the status line with its `agentId`. `ownModel`: an org agent dispatched with a `model` that was
- * ignored. `abortedBy: "parent"`: stopped together with the parent run (seen only in logs).
+ * The immediate result of an `Agent` call (agent map spec §4.1): the sub-agent runs in the
+ * background, its reports and its finish arrive later as notifications (`subagent_delivery`).
+ * `ownModel`: an org agent dispatched with a `model`, which runs on its own model instead.
+ */
+export const agentStartedText = (agentId, opts = {}) => `agentId: ${agentId} (running in the background)\n` +
+    "The sub-agent is working on the task. Its result arrives in this conversation as a " +
+    "notification when it hands back a report or finishes; keep working or end your turn. To send " +
+    "it more instructions, use SendMessage with this agentId." +
+    (opts.ownModel === true ? " It runs on its own model; the model you passed was ignored." : "");
+/**
+ * The result text of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
+ * the status line with its `agentId`. Used for a fork invocation's report (phase D); a background
+ * `Agent` call's sub-agent reports through `subagent_delivery` instead. `ownModel`: an org agent
+ * dispatched with a `model` that was ignored. `abortedBy: "parent"`: stopped together with the
+ * parent run.
  */
 export function agentResultText(r) {
     const reply = r.reply.trim();
-    let status;
+    const status = subagentStatusText(r.status, r);
     let text;
     let isError = true;
     switch (r.status) {
         case "completed":
-            [status, text, isError] = ["completed", reply, false];
+            [text, isError] = [reply, false];
             break;
         case "max_steps":
-            [status, text, isError] = [
-                "stopped at the step limit; the reply may be partial",
-                reply,
-                false,
-            ];
+            [text, isError] = [reply, false];
             break;
         case "max_duration":
-            status = "stopped at the time limit; the reply may be partial";
             text = reply === "" ? "The sub-agent produced no reply before the time limit." : reply;
             isError = false;
             break;
         case "budget":
-            [status, text] = ["stopped: token budget used up", reply];
+            text = reply;
             break;
         case "aborted":
-            [status, text] =
-                r.abortedBy === "parent"
-                    ? ["stopped with this run", AGENT_STOPPED_WITH_RUN_TEXT]
-                    : ["stopped by the user", "The user stopped this sub-agent."];
+            text =
+                r.abortedBy === "parent" ? AGENT_STOPPED_WITH_RUN_TEXT : "The user stopped this sub-agent.";
             break;
         case "timed_out":
             // the parent's sub-agents wait timed out (§7.2) and stopped it; the parent goes on
-            [status, text] = ["timed out", "stopped: the sub-agent wait timed out"];
+            text = "stopped: the sub-agent wait timed out";
             break;
         case "failed":
-            status = r.errorCode === undefined ? "failed" : `failed (${r.errorCode})`;
             text =
                 r.errorMessage === undefined
                     ? "The sub-agent failed."
@@ -197,9 +206,7 @@ export function agentResultText(r) {
         ...(r.ownModel === true ? ["model: the agent's own"] : []),
         `${r.toolCalls} tool ${r.toolCalls === 1 ? "call" : "calls"}`,
         duration(r.durationMs),
-        r.noResumeHint === true
-            ? `${count(r.tokens)} tokens.`
-            : `${count(r.tokens)} tokens. Pass the agentId as resume to send this sub-agent a follow-up.`,
+        `${count(r.tokens)} tokens.`,
     ];
     const line = `[${parts.join(" · ")}]`;
     return { content: text === "" ? line : `${text}\n\n${line}`, isError };

package/dist/tools/builtins/builtin-tools.d.ts

@@ -1,12 +1,26 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { BackgroundTaskFinisher } from "../../background/finish.js";
+import { BackgroundTaskStopper } from "../../background/stop.js";
+import { BackgroundTaskStore } from "../../background/store.js";
 import { AttachmentsService } from "../../conversations/attachments.service.js";
 import { EventLog } from "../../conversations/event-log.js";
+import { ConversationEnvironments } from "../../environments/conversation-environments.js";
+import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
 import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { PlatformActor } from "../../platform/actor.js";
+import { AgentDocs } from "../../platform/agent-docs.js";
+import { PlatformOperations } from "../../platform/registry.js";
+import type { HookRunner } from "../../runtime/hook-calls.js";
+import { StepLog } from "../../runtime/step-log.js";
+import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
 import { SkillChangesService } from "../../skills/changes.service.js";
 import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import type { BuiltinTool } from "../registry.js";
+import { WebPages } from "./web/index.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
  * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
@@ -15,7 +29,11 @@ import type { BuiltinTool } from "../registry.js";
  */
 export declare class BuiltinTools {
     private readonly tools;
-    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService);
+    constructor(db: KernelDb, config: KernelConfigService, outputs: ToolOutputs, storage: StorageService, skillChanges: SkillChangesService, attachments: AttachmentsService, eventLog: EventLog, sandbox: SandboxService, environments: ConversationEnvironments, points: ExtensionPointDefaults, webPages: WebPages, 
+    /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
+    purposes: ModelPurposesService, host: {
+        readonly hooks?: HookRunner;
+    } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs);
     /** The builtin tools, in a fixed order. */
     list(): readonly BuiltinTool[];
 }