@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/tools/approvals.service.d.ts

@@ -1,3 +1,4 @@
+import { type LocalizedName } from "@capybara-hq/plugin-sdk";
 import { EventLog } from "../conversations/event-log.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -31,6 +32,16 @@ export interface ApprovalRecord {
     decidedAt: string | null;
     /** The reason given with a denial (null otherwise). */
     denyReason: string | null;
+    /** The kernel-rendered summary of the call (a per-call policy's; null otherwise). */
+    summary: {
+        zh: string;
+        en: string;
+    } | null;
+    /**
+     * The scopes the decider may choose: stored with the approval (a per-call policy that may not
+     * be remembered stores `["once"]`), else derived: only "once" for a role escalation.
+     */
+    scopes: ApprovalScope[];
     expiresAt: string;
     createdAt: string;
 }
@@ -43,13 +54,19 @@ export interface ApprovalView extends ApprovalRecord {
         name: string;
         slug: string;
     } | null;
+    /** An extension tool's plugin (`plugin__<plugin>__<tool>`) and its display name (display only). */
+    extension: {
+        name: string;
+        displayName: LocalizedName;
+    } | null;
     agent: {
         id: string;
         name: string;
     };
     /**
-     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval links to its parent conversation
-     * with the sub-agent open: `/chat/<parent>?subagent=<child>`.
+     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval, at any depth, links to the root
+     * conversation of its tree with the sub-agent open: `/chat/<root>?subagent=<child>` (agent map
+     * spec §7).
      */
     conversationPath: string;
     /** Set when the approval belongs to a sub-agent: the conversation it was dispatched from. */
@@ -76,6 +93,13 @@ export interface ApprovalRequestInput {
     attempt?: number;
     /** Which rule asked (written to `approval_requested.policy`; display only). */
     policy?: ApprovalPolicySource;
+    /** The kernel-rendered summary of the call (per-call policies). */
+    summary?: {
+        zh: string;
+        en: string;
+    };
+    /** The scopes the decider may choose; unset: derived (see {@link ApprovalRecord.scopes}). */
+    scopes?: ApprovalScope[];
 }
 export interface DecisionInput {
     decision: "approve" | "deny";

package/dist/tools/approvals.service.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
+import { connectorToolKey, parseToolKey } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { EventLog } from "../conversations/event-log.js";
@@ -19,12 +20,16 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { ORG_ROLES, roleAtLeast } from "../orgs/roles.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+import { pluginDisplayNames } from "./display-names.js";
 export { APPROVAL_DENY_REASON_MAX_CHARS } from "../conversations/events.js";
 /** `list` 一次最多返回的审批数（收件箱据此判断这个来源是否取满）。 */
 export const APPROVALS_LIST_MAX = 100;
 const notFound = () => new ApiError("approval.not_found", "Approval not found");
 const iso = (v) => new Date(v).toISOString();
 const isRole = (v) => v !== null && ORG_ROLES.includes(v);
+/** The scopes of an approval without stored ones: a role escalation is approved only once. */
+const derivedScopes = (requestedFor) => requestedFor === null ? ["once"] : ["once", "session", "always"];
 function toRecord(r) {
     return {
         id: r.id,
@@ -44,6 +49,8 @@ function toRecord(r) {
         decidedBy: r.decided_by,
         decidedAt: r.decided_at === null ? null : iso(r.decided_at),
         denyReason: r.deny_reason,
+        summary: r.summary ?? null,
+        scopes: r.scopes ?? derivedScopes(r.requested_for),
         expiresAt: iso(r.expires_at),
         createdAt: iso(r.created_at),
     };
@@ -123,6 +130,8 @@ let ApprovalsService = class ApprovalsService {
             input: JSON.stringify(input.input ?? {}),
             requested_for: input.requestedFor,
             approver_role: input.approverRole,
+            summary: input.summary === undefined ? null : JSON.stringify(input.summary),
+            scopes: input.scopes ?? null,
             scope: null,
             decided_by: null,
             expires_at: sql `now() + ${hours}::integer * interval '1 hour'`,
@@ -149,6 +158,8 @@ let ApprovalsService = class ApprovalsService {
                     toolKey: rec.toolKey,
                     expiresAt: rec.expiresAt,
                     ...(input.policy !== undefined && { policy: input.policy }),
+                    requestedFor: rec.requestedFor,
+                    approverRole: rec.approverRole,
                 },
             },
         ]);
@@ -263,6 +274,11 @@ let ApprovalsService = class ApprovalsService {
         if (scope !== null && scope !== "once" && before.requestedFor === null) {
             throw new ApiError("validation_failed", 'Only scope "once" is allowed for role-escalated approvals', [{ path: "scope", message: 'Only "once" is allowed for role-escalated approvals' }]);
         }
+        // the scopes stored with the approval (an org / platform operation: "once" only), whatever
+        // the client offered
+        if (scope !== null && !before.scopes.includes(scope)) {
+            throw new ApiError("approval.scope_not_allowed", `Scope "${scope}" is not allowed for this approval; allowed: ${before.scopes.join(", ")}`);
+        }
         const updated = await t
             .updateTable("approvals")
             .set({
@@ -279,12 +295,14 @@ let ApprovalsService = class ApprovalsService {
         const hash = before.specHash;
         const connectorId = before.connectorId;
         if (scope === "session") {
-            // a sub-agent's grant is its parent conversation's (sub-agents spec §9): its siblings and
-            // the parent itself are not asked again for the same call
+            // a sub-agent's grant is the root conversation's (agent map spec §7): the root and every
+            // agent of its tree, at any depth, are not asked again for the same call
             await t
                 .insertInto("conversation_tool_grants")
                 .values({
-                conversation_id: ctx.parent_conversation_id ?? before.conversationId,
+                conversation_id: ctx.parent_conversation_id === null
+                    ? before.conversationId
+                    : await rootConversationOf(t, ctx.parent_conversation_id),
                 tool_key: before.toolKey,
                 spec_hash: hash,
                 connector_id: connectorId,
@@ -567,6 +585,11 @@ let ApprovalsService = class ApprovalsService {
             .where("runs.id", "in", [...new Set(recs.map((r) => r.runId))])
             .execute();
         const ctx = new Map(ctxRows.map((r) => [r.id, r]));
+        // a sub-agent's approval links to the root conversation of its tree (agent map spec §7)
+        const roots = new Map();
+        for (const p of new Set(ctxRows.flatMap((r) => r.parent_conversation_id ?? []))) {
+            roots.set(p, await rootConversationOf(db.db, p));
+        }
         const names = await this.agentNames([...new Set(ctxRows.map((r) => r.agent_id))]);
         const connectorIds = [
             ...new Set(recs.flatMap((r) => (r.connectorId === null ? [] : [r.connectorId]))),
@@ -579,12 +602,22 @@ let ApprovalsService = class ApprovalsService {
                 .where("id", "in", connectorIds)
                 .execute();
         const connectorById = new Map(apps.map((a) => [a.id, a]));
+        const pluginOf = (r) => {
+            if (r.connectorId !== null)
+                return null;
+            const p = parseToolKey(r.toolKey);
+            return p?.kind === "extension" ? p.plugin : null;
+        };
+        const displayNames = await pluginDisplayNames(db.db, recs.flatMap((r) => {
+            const p = pluginOf(r);
+            return p === null ? [] : [p];
+        }));
         return recs.flatMap((r) => {
             const c = ctx.get(r.runId);
             if (!c)
                 return [];
             const app = r.connectorId === null ? undefined : connectorById.get(r.connectorId);
-            const prefix = app ? `${app.slug}__` : undefined;
+            const prefix = app ? connectorToolKey(app.slug, "") : undefined;
             return [
                 {
                     ...r,
@@ -592,10 +625,16 @@ let ApprovalsService = class ApprovalsService {
                         ? r.toolKey.slice(prefix.length)
                         : r.toolKey,
                     connector: app ? { id: app.id, name: app.name, slug: app.slug } : null,
+                    extension: (() => {
+                        const p = pluginOf(r);
+                        return p === null
+                            ? null
+                            : { name: p, displayName: displayNames.get(p) ?? { zh: p, en: p } };
+                    })(),
                     agent: { id: c.agent_id, name: names.get(c.agent_id) ?? "" },
                     ...(c.parent_conversation_id !== null
                         ? {
-                            conversationPath: `/chat/${c.parent_conversation_id}?subagent=${r.conversationId}`,
+                            conversationPath: `/chat/${roots.get(c.parent_conversation_id) ?? c.parent_conversation_id}?subagent=${r.conversationId}`,
                             parentConversationId: c.parent_conversation_id,
                         }
                         : { conversationPath: `/chat/${r.conversationId}` }),

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

@@ -0,0 +1,104 @@
+import type { ToolKind } from "./info.js";
+/**
+ * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
+ * spec §4.1). Plain constants: `BuiltinTools`, the tool factories, the registry, policy and the
+ * runtime import them from here. The web keeps its own copy (`apps/web/src/lib/agents.ts`,
+ * `lib/timeline.ts`), checked equal by `test/tools/builtin-names.test.ts`. The release-candidate
+ * names are in `legacy-keys.ts`, never here.
+ */
+export declare const BUILTIN: {
+    readonly Bash: "Bash";
+    readonly Read: "Read";
+    readonly Write: "Write";
+    readonly Edit: "Edit";
+    readonly Glob: "Glob";
+    readonly Grep: "Grep";
+    readonly Deliver: "Deliver";
+    readonly Skill: "Skill";
+    readonly AskUserQuestion: "AskUserQuestion";
+    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";
+    readonly CurrentTime: "CurrentTime";
+};
+export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
+/**
+ * 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[];
+/** 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 turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
+ * 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).
+ * `CurrentTime` reads the clock (the run context carries only the date).
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
+/**
+ * Is `key` a builtin-shaped key (a bare name, no `mcp__` / `plugin__` prefix) that names no
+ * builtin the kernel has now, e.g. the removed `SkillWrite`? Saving an agent or an org template
+ * drops such a `toolPolicies` key instead of refusing the save: a stored definition may still
+ * carry it, and the web sends the whole definition back.
+ */
+export declare function isRemovedBuiltinKey(key: string): boolean;
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export declare const SKILL_LOAD: "Skill";
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+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>;
+/**
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child) and `Deliver` (delivering files is the parent's job). `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ */
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver"];
+/**
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
+ */
+export declare const AGENT_BUILTIN_NAMES: readonly BuiltinName[];
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+/**
+ * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
+ * tool: display-only arguments the model writes that do not change what the tool does. `Bash`'s
+ * `description` became required in UI refresh B, so a recording without it and a replayed call
+ * with one (or a different wording) still match.
+ */
+export declare const MATCH_IGNORED_FIELDS: Readonly<Record<string, readonly string[]>>;

package/dist/tools/builtin-names.js

@@ -0,0 +1,164 @@
+import { parseToolKey } from "@capybara-hq/plugin-sdk";
+/**
+ * The names (model-visible keys) of the kernel's builtin tools, following Claude Code (tool naming
+ * spec §4.1). Plain constants: `BuiltinTools`, the tool factories, the registry, policy and the
+ * runtime import them from here. The web keeps its own copy (`apps/web/src/lib/agents.ts`,
+ * `lib/timeline.ts`), checked equal by `test/tools/builtin-names.test.ts`. The release-candidate
+ * names are in `legacy-keys.ts`, never here.
+ */
+export const BUILTIN = {
+    Bash: "Bash",
+    Read: "Read",
+    Write: "Write",
+    Edit: "Edit",
+    Glob: "Glob",
+    Grep: "Grep",
+    Deliver: "Deliver",
+    Skill: "Skill",
+    AskUserQuestion: "AskUserQuestion",
+    ReadToolOutput: "ReadToolOutput",
+    ToolSearch: "ToolSearch",
+    Agent: "Agent",
+    SendMessage: "SendMessage",
+    SubagentHandback: "SubagentHandback",
+    TaskOutput: "TaskOutput",
+    TaskStop: "TaskStop",
+    WebSearch: "WebSearch",
+    WebFetch: "WebFetch",
+    Platform: "Platform",
+    CurrentTime: "CurrentTime",
+};
+/**
+ * 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,
+    BUILTIN.Write,
+    BUILTIN.Edit,
+    BUILTIN.Glob,
+    BUILTIN.Grep,
+    BUILTIN.Deliver,
+    BUILTIN.TaskOutput,
+    BUILTIN.TaskStop,
+];
+/** 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,
+    BUILTIN.Edit,
+    BUILTIN.Deliver,
+]);
+/**
+ * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
+ * what is registered now, so the order the implementations land in never affects a saved
+ * definition. `ToolSearch` and `Skill` are added
+ * 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).
+ * `CurrentTime` reads the clock (the run context carries only the date).
+ */
+export const BUILTIN_TOOL_NAMES = [
+    BUILTIN.AskUserQuestion,
+    BUILTIN.ReadToolOutput,
+    BUILTIN.ToolSearch,
+    BUILTIN.Skill,
+    ...SANDBOX_TOOL_NAMES,
+    BUILTIN.Agent,
+    BUILTIN.SendMessage,
+    BUILTIN.SubagentHandback,
+    ...WEB_TOOL_NAMES,
+    BUILTIN.Platform,
+    BUILTIN.CurrentTime,
+];
+const BUILTIN_NAME_SET = new Set(Object.values(BUILTIN));
+/**
+ * Is `key` a builtin-shaped key (a bare name, no `mcp__` / `plugin__` prefix) that names no
+ * builtin the kernel has now, e.g. the removed `SkillWrite`? Saving an agent or an org template
+ * drops such a `toolPolicies` key instead of refusing the save: a stored definition may still
+ * carry it, and the web sends the whole definition back.
+ */
+export function isRemovedBuiltinKey(key) {
+    return parseToolKey(key)?.kind === "builtin" && !BUILTIN_NAME_SET.has(key);
+}
+/** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
+export const SKILL_LOAD = BUILTIN.Skill;
+/** The builtin that searches the tool catalog (added by the registry by org setting and threshold). */
+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,
+]);
+/**
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child) and `Deliver` (delivering files is the parent's job). `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ */
+export const CHILD_REMOVED_TOOLS = [BUILTIN.AskUserQuestion, BUILTIN.Deliver];
+/**
+ * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
+ * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
+ * `Skill`, `SendMessage`, `SubagentHandback`) and without `TaskOutput` / `TaskStop`, which come
+ * with `Bash` ({@link BASH_COMPANION_TOOLS}). These are also the builtins an agent can turn off.
+ */
+export const AGENT_BUILTIN_NAMES = BUILTIN_TOOL_NAMES.filter((n) => n !== BUILTIN.ToolSearch &&
+    n !== BUILTIN.Skill &&
+    n !== BUILTIN.SendMessage &&
+    n !== BUILTIN.SubagentHandback &&
+    !BASH_COMPANION_TOOLS.includes(n));
+/** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */
+export const BUILTIN_TOOL_KINDS = {
+    [BUILTIN.Bash]: "command",
+    [BUILTIN.Read]: "read",
+    [BUILTIN.Write]: "edit",
+    [BUILTIN.Edit]: "edit",
+    [BUILTIN.Glob]: "search",
+    [BUILTIN.Grep]: "search",
+    [BUILTIN.Deliver]: "tool",
+    [BUILTIN.TaskOutput]: "read",
+    [BUILTIN.TaskStop]: "command",
+    [BUILTIN.ToolSearch]: "meta",
+    [BUILTIN.Skill]: "meta",
+    [BUILTIN.ReadToolOutput]: "meta",
+    [BUILTIN.AskUserQuestion]: "meta",
+    [BUILTIN.SendMessage]: "meta",
+    [BUILTIN.SubagentHandback]: "meta",
+    [BUILTIN.WebSearch]: "search",
+    [BUILTIN.WebFetch]: "read",
+    [BUILTIN.Platform]: "tool",
+    [BUILTIN.CurrentTime]: "tool",
+};
+/**
+ * Input fields left out when matching a replayed call with a recorded one (full-run replay), per
+ * tool: display-only arguments the model writes that do not change what the tool does. `Bash`'s
+ * `description` became required in UI refresh B, so a recording without it and a replayed call
+ * 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,17 +1,17 @@
 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.
  */
-export declare const AGENT_TOOL = "agent";
-/** 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). */
+/** The input of an `Agent` call (§4.2). */
 export declare const AgentToolInput: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
@@ -22,11 +22,10 @@ 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>;
 /**
- * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * The `Agent` tool definition of a parent agent version (§4.3): the fixed text with
  * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
  * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
  */
@@ -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,19 +70,14 @@ 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;
 };
 /**
  * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
- * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * each under its own policy. The tool pipeline dispatches `Agent` calls itself; `run` answers only
  * when a call reaches it anyway.
  */
 export declare const agentTool: BuiltinTool;