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

package/dist/tools/pipeline.js

@@ -7,11 +7,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { ToolError, validateInputForm, validateToolDisplay, } from "@capybara-hq/plugin-sdk";
+import { parseToolKey, ToolError, validateInputForm, validateToolDisplay, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable, Optional } from "@nestjs/common";
-import { normalizeStoredDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
 import { ToolViewSchema } from "../conversations/events.js";
+import { ApiError } from "../errors.js";
+import { EffectiveConfigs, NEEDS_CONFIG_REASON } from "../extensions/effective-config.js";
 import { clipText } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { ExtensionUnloadedError, PLUGIN_UNLOADED_TOOL_ERROR } from "../extensions/inflight.js";
@@ -23,20 +24,26 @@ import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { UNKNOWN_RESULT_TEXT } from "../runtime/context/pairing.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookScope, } from "../runtime/hook-calls.js";
-import { subagentsWait, subagentWaitingIdemKey, } from "../runtime/loop.js";
+import { subagentWaitingIdemKey } from "../runtime/loop.js";
 import { assistantIdemKey, MAX_MODEL_ATTEMPTS, modelCallIdemKey } from "../runtime/model-call.js";
-import { TERMINAL_STATUSES } from "../runtime/run-finish.js";
-import { childResult, dispatchOfCall, finishedEvent, } from "../runtime/subagents/child.js";
-import { forkSeqOfCall, pairStoppedForks } from "../runtime/subagents/skill-fork.js";
+import { rootSurfaceOf } from "../runtime/subagents/child.js";
+import { SubagentMessages } from "../runtime/subagents/messages.js";
+import { pairStoppedForks } from "../runtime/subagents/skill-fork.js";
 import { SubagentsService } from "../runtime/subagents/subagents.service.js";
 import { skillLoadOfferedIn } from "../skills/catalog.js";
 import { ApprovalsService } from "./approvals.service.js";
 import { Breaker, breakerOpenMessage } from "./breaker.js";
-import { AGENT_STOPPED_WITH_RUN_TEXT, AGENT_TOOL, AgentToolInput, } from "./builtins/agent.js";
+import { SEND_MESSAGE, SUBAGENT_HANDBACK, TOOL_SEARCH } from "./builtin-names.js";
+import { AGENT_TOOL, AgentToolInput } from "./builtins/agent.js";
+import { HandbackInput } from "./builtins/handback.js";
+import { SendMessageInput } from "./builtins/send-message.js";
 import { isAlwaysLoaded, notLoadedText } from "./builtins/tool-search.js";
+import { canonicalJson } from "./canonical-json.js";
 import { CredentialMissing, Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
 import { ElicitationSession } from "./elicitation.js";
+import { legacyHint, legacyToolInput, legacyToolKey } from "./legacy-keys.js";
+import { OrgToolSwitches, toolTurnedOffReason } from "./org-tool-switches.js";
 import { renderResult, resolveOutputRefs, spillIfLarge, ToolOutputs } from "./outputs.js";
 import { createDecidePolicy } from "./policy.js";
 import { QuestionsService } from "./questions.service.js";
@@ -59,18 +66,61 @@ export const approvalExpiredText = (hours) => `Approval timed out after ${hours}
 export const APPROVAL_CANCELLED_TEXT = "The run was stopped while waiting for approval.";
 /** 等待用户输入期间 run 被中止。 */
 export const INPUT_CANCELLED_TEXT = "The run was stopped while waiting for user input.";
+/**
+ * The result of an `AskUserQuestion` call whose question the user skipped by sending a message
+ * (reply-while-question spec §7.1): the message follows in the log as an ordinary user message.
+ */
+export const QUESTION_SKIPPED_TEXT = "The user did not answer this question and sent a message instead; read it below and continue.";
+/** The result of any other tool's input request (extension `input_required`, MCP elicitation) skipped by a message. */
+export const INPUT_SKIPPED_TEXT = "The user did not provide the requested input and sent a message instead; read it below and continue. Call the tool again only if it is still needed.";
 /** 同一调用连续请求输入超过上限。 */
 export const TOO_MANY_INPUT_REQUESTS_TEXT = "Tool requested user input too many times.";
 /** run 已被中止 / 到达截止时间，调用尚未开始执行。 */
 export const RUN_STOPPED_TEXT = "The run was stopped before this tool call was executed.";
 /** 调用执行中 run 被中止 / 到达截止时间。 */
 export const RUN_STOPPED_DURING_TEXT = "The run was stopped while this tool call was running; its outcome is unknown. Verify before retrying.";
+/** The fixed result of a call whose input request was skipped by a message (spec §7.1). */
+const skippedResult = (toolKey) => toolKey === "AskUserQuestion"
+    ? {
+        content: QUESTION_SKIPPED_TEXT,
+        isError: false,
+        display: {
+            summary: {
+                zh: "用户没有回答，直接发了消息",
+                en: "User sent a message instead of answering",
+            },
+        },
+    }
+    : {
+        content: INPUT_SKIPPED_TEXT,
+        isError: true,
+        display: {
+            summary: { zh: "用户没有提供输入，直接发了消息", en: "User sent a message instead" },
+        },
+    };
 const timeoutText = (key, ms) => `Tool ${key} timed out after ${ms / 1000}s. The operation may or may not have completed; verify before retrying.`;
 const failedText = (key, errName) => `Tool ${key} failed (${errName}). The operation may not have completed; check before retrying or try another approach.`;
-const unknownToolText = (name, keys, toolSearch) => `Unknown tool "${name}". Available tools: ${keys.length === 0 ? "(none)" : keys.join(", ")}.` +
-    (toolSearch ? " Use tool_search to load other tools." : "");
+/** The connector slugs and extension names among the run's tools (to read old `<x>__<tool>` keys). */
+const legacyScopeOf = (tools) => {
+    const connectorSlugs = new Set();
+    const extensionNames = new Set();
+    for (const t of tools) {
+        const p = parseToolKey(t.key);
+        if (p?.kind === "connector")
+            connectorSlugs.add(p.slug);
+        else if (p?.kind === "extension")
+            extensionNames.add(p.plugin);
+    }
+    return { connectorSlugs, extensionNames };
+};
+const unknownToolText = (name, keys, toolSearch, hint = null) => `Unknown tool "${name}". Available tools: ${keys.length === 0 ? "(none)" : keys.join(", ")}.` +
+    (toolSearch ? " Use ToolSearch to load other tools." : "") +
+    (hint === null ? "" : ` ${hint}`);
 const unavailableText = (name, reason) => `Tool "${name}" is unavailable: ${reason}.`;
-const deniedText = (key) => `Tool ${key} is denied by policy.`;
+/** With a per-call policy key (`Platform:<operation>`), the text names it. */
+const deniedText = (key, policyKey) => policyKey === undefined || policyKey === key
+    ? `Tool ${key} is denied by policy.`
+    : `Tool ${key} is denied by policy for ${policyKey}.`;
 /** Longest hook reason quoted in {@link hookDeniedText}. */
 const HOOK_REASON_MAX = 500;
 /**
@@ -84,8 +134,6 @@ const personalMissingText = (connectorName) => `The user has not connected ${con
 const orgMissingText = (connectorName) => `${connectorName} has no organization credential configured; ask an organization admin to set it up.`;
 /** Optional provider: the pipeline's {@link ToolPipelineHooks} (tests). */
 export const TOOL_PIPELINE_HOOKS = Symbol("TOOL_PIPELINE_HOOKS");
-/** `runCall` dispatched a sub-agent: the call stays open until the child run finishes. */
-const OPEN = "open";
 const approvalAuthorization = (a) => ({
     approvalId: a.id,
     approvedByAccountId: a.decidedBy,
@@ -159,10 +207,12 @@ let ToolPipeline = class ToolPipeline {
     decide;
     deps;
     constructor(kdb, eventLog, 
-    /** The `agent` tool's sub-agent dispatch; absent (tests): `agent` calls are refused. */
-    subagents, registry, credentials, breaker, outputs, approvals, questions, config, log, 
+    /** The `Agent` tool's sub-agent dispatch; absent (tests): `Agent` calls are refused. */
+    subagents, 
+    /** The message tools between agents; absent (tests): their calls are refused. */
+    messages, registry, credentials, breaker, outputs, approvals, questions, config, log, 
     /** Plugin hooks and inline ui contributions; absent (tests): no hooks, cards dropped. */
-    host, drift, txHost, hooks) {
+    host, drift, effective, switches, txHost, hooks) {
         this.config = config;
         this.txHost = txHost;
         this.deps = {
@@ -181,15 +231,19 @@ let ToolPipeline = class ToolPipeline {
             get pluginHooks() {
                 return host?.hooks;
             },
-            inlineViews: (plugin) => new Set((host?.current(plugin)?.manifest.ui ?? [])
-                .filter((c) => c.place === "inline" && c.aliasOf === undefined)
-                .map((c) => c.id)),
+            effective,
+            switches,
+            inlineViews: (plugin) => new Set((host?.current(plugin)?.ui ?? [])
+                .filter((r) => r.slot.id === "conversation.tool-result.card" &&
+                r.contribution.aliasOf === undefined)
+                .map((r) => r.contribution.id)),
             onToolsChanged: (orgId, connectorId) => {
                 void drift?.onToolsChanged(orgId, connectorId);
             },
             get subagents() {
                 return subagents ? { dispatch: (a) => subagents.dispatch(a) } : undefined;
             },
+            messages,
         };
         const decide = hooks?.decidePolicy;
         // the default policy reads live, on the context's handle
@@ -213,322 +267,43 @@ let ToolPipeline = class ToolPipeline {
             // 每步实时解析（连接器 / 插件状态可能在模型调用之后变化）
             if (!resolved) {
                 // the request builder's rule: a skills catalog snapshot (even an empty one) or a person's
-                // skill invocation in the log → skill_load is offered (see skillLoadOffered)
+                // skill invocation in the log → Skill is offered (see skillLoadOffered)
                 const skillLoad = await skillLoadOfferedIn(this.deps.db, this.deps.eventLog, ctx.conversationId);
                 resolved = await this.deps.registry.forAgent(ctx.orgId, {
-                    tools: ctx.agent.tools ?? [],
+                    disabledTools: ctx.agent.disabledTools,
+                    subagentTools: ctx.agent.subagentTools,
                     skillLoad,
                     subagents: ctx.agent.subagents,
+                    child: ctx.parent !== undefined,
+                    forkChild: ctx.parent?.forSkill === true,
+                    sandboxConversationId: ctx.parent?.rootConversationId ?? ctx.conversationId,
+                    replay: ctx.conversationKind === "eval",
                 });
             }
             return resolved;
         };
-        // `agent` calls whose sub-agent still runs (spec §7.1): a dispatch never blocks later calls;
-        // once every call was handled, the step waits for them
-        let open = 0;
+        // an `Agent` call's dispatch writes its result (the sub-agent runs in the background, agent
+        // map spec §4.1), so no call keeps the step waiting on a sub-agent
         for (const call of calls) {
             if (await eventLog.findByIdem(ctx.conversationId, idem.result(ctx.runId, call.id)))
                 continue;
-            if (call.name === AGENT_TOOL) {
-                const row = await dispatchOfCall(this.deps.db, ctx.runId, call.id);
-                if (row) {
-                    if (!(await this.finishAgentCall(ctx, row, call, resolve)))
-                        open++;
-                    continue;
-                }
-            }
             const waitingFor = await this.processCall(ctx, call, resolve);
-            if (waitingFor === OPEN)
-                open++;
-            else if (waitingFor)
+            if (waitingFor)
                 return { kind: "suspended", waitingFor };
         }
-        if (open > 0) {
-            // the run is being stopped (a person, its deadline): it does not wait for its sub-agents;
-            // their calls get their results now, and the children are stopped after the run's terminal
-            // commit (spec §12)
-            if (ctx.signal.aborted) {
-                const stopped = await this.stopOpenAgentCallsNow(ctx.runId, ctx.agent);
-                if (stopped.toSeq !== null) {
-                    await eventLog.notify(ctx.conversationId, stopped.toSeq);
-                }
-                stopped.fire();
-                return { kind: "done" };
-            }
-            return {
-                kind: "suspended",
-                waitingFor: subagentsWait(ctx.runId, ctx.step, this.config.get()),
-            };
-        }
         return { kind: "done" };
     }
     /**
-     * An `agent` call that was dispatched (spec §7.1 "already dispatched"): when its child run is
-     * terminal, writes the parent's `subagent_finished` (if the child's finisher did not) and the
-     * call's `tool_result` from the child's log, and returns true; else false (still open).
-     *
-     * The call ran like any tool, so the result is audited `tool.called` (duration = the child's;
-     * the authorization is known only when an approval let it run: a policy or remembered grant at
-     * dispatch time is not recorded, so nothing is guessed) and fires `tool.postExecute` with the
-     * result, from the replica that writes it (spec §11).
-     */
-    async finishAgentCall(ctx, row, call, resolve) {
-        const modelGiven = typeof call.input === "object" &&
-            call.input !== null &&
-            call.input.model !== undefined;
-        const r = await childResult(this.deps.eventLog, row, { modelGiven });
-        if (!r)
-            return false;
-        // No spec-hash check as in processCall: an `agent` call writes no tool_call_started holding
-        // the executed definition's hash, and its description changes with the roster and limits
-        // while the child runs. The call's approval (forCall: its latest) is by construction the one
-        // that let this dispatch start, since a dispatch happens only after an approved decision.
-        const approval = await this.deps.approvals.forCall(ctx.runId, call.id);
-        await this.writeResult(ctx, row.parentCallId, AGENT_TOOL, { content: r.content, isError: r.isError }, [finishedEvent(row, r.finished)], {
-            durationMs: r.finished.durationMs,
-            connectorId: null,
-            ...(approval?.status === "approved" && {
-                authorization: approvalAuthorization(approval),
-            }),
-        });
-        const hooks = this.deps.pluginHooks;
-        const scope = hookScope(hooks, ctx);
-        if (hooks && scope && hooks.has("tool.postExecute")) {
-            const tool = (await resolve()).tools.find((t) => t.key === AGENT_TOOL);
-            if (tool) {
-                fireObserve(hooks, "tool.postExecute", {
-                    ...scope,
-                    step: ctx.step,
-                    callId: call.id,
-                    toolKey: AGENT_TOOL,
-                    specHash: tool.specHash,
-                    input: call.input,
-                    isError: r.isError,
-                    content: r.content,
-                    durationMs: r.finished.durationMs,
-                }, ctx.signal, this.deps.log);
-            }
-        }
-        return true;
-    }
-    /** {@link stopOpenAgentCalls} in a transaction of its own (a stop seen by the tools node). */
-    async stopOpenAgentCallsNow(runId, agent) {
-        return this.stopOpenAgentCalls(runId, agent);
-    }
-    /**
-     * Writes, in the caller's transaction (`mandatory`), the `tool_result` of every open `agent` call
-     * of a run that is being stopped
-     * (sub-agents spec §12: a person stopped it while it waited on sub-agents, or its deadline or a
-     * stop hit its tools node after a dispatch). A call whose child already ended gets the child's
-     * result (and the missing `subagent_finished`); one whose child is still active gets
-     * {@link AGENT_STOPPED_WITH_RUN_TEXT}. The caller stops those children after its commit.
-     *
-     * Like every `agent` result (see {@link finishAgentCall}), each is audited `tool.called` in it
-     * (duration: the child's, or the time since the dispatch) and fires `tool.postExecute`, through
-     * `fire()`, which the caller runs after its commit. Returns the steps and calls written (the
-     * caller must not write a "not executed" result for them) and the highest seq written.
+     * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
+     * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
+     * (phase D, `pairStoppedForks`; a still active fork child is stopped by the caller after its
+     * commit). An `Agent` call has its result from its dispatch (agent map spec §4.1), so there is
+     * nothing to write for it. Returns the fork's call id (the caller must not write a "not executed"
+     * result for it), the highest seq written, and `fire`, a no-op kept for the callers' hook phase.
      */
-    async stopOpenAgentCalls(runId, agent) {
-        const t = this.deps.db;
-        // phase D: the run's fork invocation without a report gets one (a fork has no tool call)
-        const forks = await pairStoppedForks(t, this.deps.eventLog, runId);
-        const none = {
-            steps: [],
-            callIds: new Set(forks.callIds),
-            toSeq: forks.toSeq,
-            fire: () => { },
-        };
-        const all = await t
-            .selectFrom("subagent_dispatches")
-            .select([
-            "parent_run_id",
-            "parent_call_id",
-            "parent_conversation_id",
-            "child_conversation_id",
-            "child_run_id",
-            "step",
-            "created_at",
-        ])
-            .where("parent_run_id", "=", runId)
-            .orderBy("step")
-            .orderBy("created_at")
-            .execute();
-        const dispatches = all.filter((d) => forkSeqOfCall(d.parent_call_id, d.step) === null);
-        if (dispatches.length === 0)
-            return none;
-        const run = await t
-            .selectFrom("runs as r")
-            .innerJoin("conversations as c", "c.id", "r.conversation_id")
-            .select([
-            "r.conversation_id",
-            "r.trigger_account_id",
-            "r.agent_version",
-            "c.org_id",
-            "c.agent_id",
-            "c.kind",
-        ])
-            .where("r.id", "=", runId)
-            .executeTakeFirst();
-        if (!run)
-            return none;
-        const conversationId = run.conversation_id;
-        const inputs = new Map();
-        const events = [];
-        const calls = [];
-        for (const d of dispatches) {
-            const written = await t
-                .selectFrom("conversation_events")
-                .select("seq")
-                .where("conversation_id", "=", conversationId)
-                .where("idem_key", "=", idem.result(runId, d.parent_call_id))
-                .executeTakeFirst();
-            if (written)
-                continue;
-            if (!inputs.has(`step:${d.step}`)) {
-                inputs.set(`step:${d.step}`, true);
-                const msg = await t
-                    .selectFrom("conversation_events")
-                    .select("payload")
-                    .where("conversation_id", "=", conversationId)
-                    .where("idem_key", "=", assistantIdemKey(runId, d.step))
-                    .executeTakeFirst();
-                const content = msg?.payload?.content ?? [];
-                for (const b of content) {
-                    if (b.type === "tool_call" && b.id !== undefined)
-                        inputs.set(b.id, b.input);
-                }
-            }
-            const input = inputs.get(d.parent_call_id);
-            const row = {
-                parentRunId: d.parent_run_id,
-                parentCallId: d.parent_call_id,
-                parentConversationId: d.parent_conversation_id,
-                childConversationId: d.child_conversation_id,
-                childRunId: d.child_run_id,
-            };
-            const child = await t
-                .selectFrom("runs")
-                .select("status")
-                .where("id", "=", d.child_run_id)
-                .executeTakeFirst();
-            // a child that already ended keeps its own result (its log is committed)
-            const ended = child !== undefined && TERMINAL_STATUSES.has(child.status)
-                ? await childResult(this.deps.eventLog, row, {
-                    modelGiven: typeof input === "object" &&
-                        input !== null &&
-                        input.model !== undefined,
-                })
-                : null;
-            if (ended)
-                events.push(finishedEvent(row, ended.finished));
-            const r = ended
-                ? { content: ended.content, isError: ended.isError, durationMs: ended.finished.durationMs }
-                : {
-                    content: AGENT_STOPPED_WITH_RUN_TEXT,
-                    isError: true,
-                    durationMs: Math.max(0, Date.now() - new Date(d.created_at).getTime()),
-                };
-            events.push({
-                type: "tool_result",
-                runId,
-                idemKey: idem.result(runId, d.parent_call_id),
-                payload: {
-                    step: d.step,
-                    callId: d.parent_call_id,
-                    toolKey: AGENT_TOOL,
-                    content: r.content,
-                    isError: r.isError,
-                },
-            });
-            calls.push({ step: d.step, callId: d.parent_call_id, input, r });
-        }
-        if (calls.length === 0)
-            return none;
-        const written = await this.deps.eventLog.appendIn(conversationId, events);
-        for (const c of calls) {
-            const approval = await t
-                .selectFrom("approvals")
-                .select(["id", "status", "decided_by", "scope"])
-                .where("run_id", "=", runId)
-                .where("call_id", "=", c.callId)
-                .orderBy("attempt", "desc")
-                .limit(1)
-                .executeTakeFirst();
-            await audit(t, {
-                actorAccountId: run.trigger_account_id,
-                orgId: run.org_id,
-                action: "tool.called",
-                target: conversationId,
-                detail: {
-                    toolKey: AGENT_TOOL,
-                    isError: c.r.isError,
-                    durationMs: c.r.durationMs,
-                    agentId: run.agent_id,
-                    agentVersion: run.agent_version,
-                    conversationId,
-                    runId,
-                    callId: c.callId,
-                    ...(approval?.status === "approved" && {
-                        approvalId: approval.id,
-                        approvedByAccountId: approval.decided_by,
-                        scope: approval.scope,
-                    }),
-                },
-            });
-        }
-        const fire = () => {
-            const hooks = this.deps.pluginHooks;
-            const scope = hookScope(hooks, {
-                conversationKind: run.kind,
-                orgId: run.org_id,
-                accountId: run.trigger_account_id,
-                agentId: run.agent_id,
-                agentVersion: run.agent_version,
-                conversationId,
-                runId,
-            });
-            if (!hooks || !scope || !hooks.has("tool.postExecute"))
-                return;
-            void (async () => {
-                const def = agent ??
-                    normalizeStoredDefinition((await this.deps.db
-                        .selectFrom("agent_versions")
-                        .select("definition")
-                        .where("agent_id", "=", run.agent_id)
-                        .where("version", "=", run.agent_version)
-                        .executeTakeFirstOrThrow()).definition);
-                const skillLoad = await skillLoadOfferedIn(this.deps.db, this.deps.eventLog, conversationId);
-                const resolved = await this.deps.registry.forAgent(run.org_id, {
-                    tools: def.tools ?? [],
-                    skillLoad,
-                    subagents: def.subagents,
-                });
-                const tool = resolved.tools.find((x) => x.key === AGENT_TOOL);
-                if (!tool)
-                    return;
-                // the run is over: nothing aborts these observe hooks but their own timeouts
-                const signal = new AbortController().signal;
-                for (const c of calls) {
-                    fireObserve(hooks, "tool.postExecute", {
-                        ...scope,
-                        step: c.step,
-                        callId: c.callId,
-                        toolKey: AGENT_TOOL,
-                        specHash: tool.specHash,
-                        input: c.input,
-                        isError: c.r.isError,
-                        content: c.r.content,
-                        durationMs: c.r.durationMs,
-                    }, signal, this.deps.log);
-                }
-            })().catch((err) => this.deps.log.warn("cannot fire tool.postExecute for stopped agent calls", { runId, err }));
-        };
-        return {
-            steps: [...new Set(calls.map((c) => c.step))],
-            callIds: new Set([...forks.callIds, ...calls.map((c) => c.callId)]),
-            toSeq: Math.max(forks.toSeq ?? 0, ...written.map((e) => e.seq)),
-            fire,
-        };
+    async stopOpenAgentCalls(runId) {
+        const forks = await pairStoppedForks(this.deps.db, this.deps.eventLog, runId);
+        return { steps: [], callIds: new Set(forks.callIds), toSeq: forks.toSeq, fire: () => { } };
     }
     /**
      * 处理一个尚无结果的调用。先看输入请求的轮次：最近一轮仍 pending → 继续等；否则本次是第
@@ -540,6 +315,12 @@ let ToolPipeline = class ToolPipeline {
         const last = rounds.at(-1);
         if (last?.status === "pending")
             return inputWait(last);
+        // skipped by the starter's message: the kernel writes the result, the tool is not called again
+        // (spec D6: an extension would only see `answer: null`, an MCP call would be re-sent)
+        if (last?.status === "skipped") {
+            await this.writeResult(ctx, call.id, last.toolKey, skippedResult(last.toolKey));
+            return undefined;
+        }
         const attempt = rounds.length + 1;
         const started = await this.deps.eventLog.findByIdem(ctx.conversationId, idem.started(ctx.runId, call.id, attempt));
         if (started?.type === "tool_call_started") {
@@ -578,36 +359,49 @@ let ToolPipeline = class ToolPipeline {
             await this.writeResult(ctx, call.id, key, { content, isError: true });
             return undefined;
         };
-        const tool = resolved.tools.find((t) => t.key === call.name);
+        let tool = resolved.tools.find((t) => t.key === call.name);
+        // A call logged before the tool keys were renamed (spec 8.1): the request that issued it offered
+        // the old key. It runs as the current tool with translated input; the result keeps the logged key.
+        let legacy = false;
+        if (!tool) {
+            const next = legacyToolKey(call.name, legacyScopeOf(resolved.tools));
+            const current = next === null ? undefined : resolved.tools.find((t) => t.key === next);
+            if (current && (await this.requestToolKeys(ctx))?.has(call.name) === true) {
+                tool = current;
+                legacy = true;
+            }
+        }
         if (!tool) {
             const why = resolved.unavailable.find((u) => u.ref === call.name) ??
                 resolved.hidden?.find((u) => u.ref === call.name);
             if (why)
                 return fail(unavailableText(call.name, why.reason));
             let keys = resolved.tools.map((t) => t.key);
-            // tool_search 模式：目录可能很大，只列内置工具与发出本次调用的请求里带了定义的工具
+            // ToolSearch 模式：目录可能很大，只列内置工具与发出本次调用的请求里带了定义的工具
             if (resolved.toolSearch === true) {
                 const sent = await this.sentTools(ctx);
                 if (sent !== null)
                     keys = keys.filter((k) => isAlwaysLoaded(k) || sent.has(k));
             }
             keys.sort();
-            return fail(unknownToolText(call.name, keys, keys.includes("tool_search")));
+            return fail(unknownToolText(call.name, keys, keys.includes(TOOL_SEARCH), legacyHint(call.name)));
         }
-        // tool_search 模式下，模型只能调用请求里带了完整定义的工具：目录里有、但发出本次调用的请求没加载 →
-        // 明确错误，不自动加载（spec 5.5 / 6.3）。同一步里先 tool_search 再调用刚加载的工具同样报错。
-        if (resolved.toolSearch === true && !isAlwaysLoaded(tool.key)) {
+        const outKey = legacy ? call.name : tool.key;
+        // ToolSearch 模式下，模型只能调用请求里带了完整定义的工具：目录里有、但发出本次调用的请求没加载 →
+        // 明确错误，不自动加载（spec 5.5 / 6.3）。同一步里先 ToolSearch 再调用刚加载的工具同样报错。
+        if (!legacy && resolved.toolSearch === true && !isAlwaysLoaded(tool.key)) {
             const sent = await this.sentTools(ctx);
             if (sent !== null && !sent.has(tool.key))
-                return fail(notLoadedText(tool.key), tool.key);
+                return fail(notLoadedText(tool.key), outKey);
         }
+        const rawInput = legacy ? legacyToolInput(call.name, call.input) : call.input;
         let input;
         try {
-            input = await resolveOutputRefs(call.input, (id) => this.deps.outputs.load({ orgId: ctx.orgId, conversationId: ctx.conversationId }, id));
+            input = await resolveOutputRefs(rawInput, (id) => this.deps.outputs.load({ orgId: ctx.orgId, conversationId: ctx.conversationId }, id));
         }
         catch (e) {
             if (e instanceof ToolError)
-                return fail(e.message, tool.key);
+                return fail(e.message, outKey);
             throw e;
         }
         // 连接器工具的 schema 来自连接器（不受信任）：去掉有风险的关键字并限制大小 / 层数
@@ -616,7 +410,23 @@ let ToolPipeline = class ToolPipeline {
             log: this.deps.log,
         });
         if (invalid !== null)
-            return fail(invalid, tool.key);
+            return fail(invalid, outKey);
+        // the per-call policy key (Platform tool spec §6.2): key and summary come from the resolved
+        // input, while the approval binding below compares the raw call.input
+        const callPolicy = (await tool.callPolicy?.(input, {
+            orgId: ctx.orgId,
+            accountId: ctx.accountId,
+            agentId: ctx.agentId,
+            conversationId: ctx.conversationId,
+            runId: ctx.runId,
+            rawInput,
+            signal: ctx.signal,
+        })) ?? null;
+        // a deny with a reason (e.g. an unavailable operation): the reason is the tool error
+        if (callPolicy?.policy === "deny" && callPolicy.denyReason !== undefined) {
+            return fail(callPolicy.denyReason, outKey);
+        }
+        const policyKey = callPolicy?.key ?? tool.key;
         const decision = await this.decide(tool, ctx.agent, {
             orgId: ctx.orgId,
             accountId: ctx.accountId,
@@ -625,19 +435,29 @@ let ToolPipeline = class ToolPipeline {
             runId: ctx.runId,
             ...(ctx.parent !== undefined && {
                 parentConversationId: ctx.parent.conversationId,
+                rootConversationId: ctx.parent.rootConversationId,
                 ...(ctx.parent.otherAgent !== undefined && { parentAgentDiffers: ctx.parent.otherAgent }),
             }),
+            callPolicy,
         });
         if (decision === "deny")
-            return fail(deniedText(tool.key), tool.key);
+            return fail(deniedText(tool.key, callPolicy?.key), outKey);
         if (typeof decision === "object" && "unavailable" in decision) {
-            return fail(unavailableText(tool.key, decision.unavailable), tool.key);
+            return fail(unavailableText(tool.key, decision.unavailable), outKey);
         }
         // 该调用已有审批（续跑）→ 按审批结果；没有且策略为 ask → 建审批并等待
         // （不写 tool_call_started：此时尚未开始执行）。
         let approval = await this.deps.approvals.forCall(ctx.runId, call.id);
         // 批准的是旧定义（等待期间工具定义变了）：原批准不适用于当前定义，策略仍需审批时按新定义重新审批。
-        const stale = approval?.status === "approved" && approval.specHash !== tool.specHash;
+        // An in-flight rc call (spec §9) is the exception: its approval was asked under the rc definition
+        // of the same call, and the rename changed every builtin's definition; the person approved this
+        // very call, so the approval stands.
+        // An approval binds the exact input it showed (Platform tool spec §6.3): an approved record
+        // whose stored input differs from the call's is not used.
+        const approvedHere = approval?.status === "approved" &&
+            (legacy || approval.specHash === tool.specHash) &&
+            canonicalJson(approval.input) === canonicalJson(call.input ?? {});
+        const stale = approval?.status === "approved" && !approvedHere;
         if ((!approval || stale) && typeof decision === "object" && "ask" in decision) {
             approval = await this.deps.approvals.request({
                 attempt: (approval?.attempt ?? 0) + 1,
@@ -646,21 +466,23 @@ let ToolPipeline = class ToolPipeline {
                 runId: ctx.runId,
                 step: ctx.step,
                 callId: call.id,
-                toolKey: tool.key,
+                toolKey: policyKey,
                 specHash: decision.ask.specHash,
                 connectorId: decision.ask.connectorId,
                 input: call.input,
                 requestedFor: decision.ask.requestedFor,
                 approverRole: decision.ask.approverRole,
                 policy: decision.ask.policy,
+                ...(callPolicy?.summary !== undefined && { summary: callPolicy.summary }),
+                ...(callPolicy !== null && !callPolicy.remember && { scopes: ["once"] }),
             });
         }
         if (approval && approval.status !== "approved") {
             const refused = this.refusalText(approval);
-            return refused === null ? approvalWait(approval) : fail(refused, tool.key);
+            return refused === null ? approvalWait(approval) : fail(refused, outKey);
         }
         // 走到这里即放行：在（与当前定义一致的）审批下执行，否则是授权或策略放行
-        const authorization = approval?.status === "approved" && approval.specHash === tool.specHash
+        const authorization = approval?.status === "approved" && approvedHere
             ? approvalAuthorization(approval)
             : typeof decision === "object" && "grant" in decision
                 ? { grant: decision.grant }
@@ -675,7 +497,7 @@ let ToolPipeline = class ToolPipeline {
             // written with the call's tool_result, so a call with a logged denial never runs again anyway.
             const prior = await this.deps.eventLog.findByIdem(ctx.conversationId, idem.hookDenied(ctx.runId, call.id));
             if (prior?.type === "hook_denied") {
-                return fail(hookDeniedText(prior.payload.plugin, prior.payload.reason), tool.key);
+                return fail(hookDeniedText(prior.payload.plugin, prior.payload.reason), outKey);
             }
         }
         // payload only built when a tool hook is registered (zero overhead otherwise)
@@ -697,7 +519,7 @@ let ToolPipeline = class ToolPipeline {
             catch (e) {
                 // run() rejects only when the run's signal aborted: an abort, never a deny
                 if (ctx.signal.aborted)
-                    return fail(RUN_STOPPED_TEXT, tool.key);
+                    return fail(RUN_STOPPED_TEXT, outKey);
                 throw e;
             }
             if (!verdict.allowed) {
@@ -715,20 +537,76 @@ let ToolPipeline = class ToolPipeline {
                     step: ctx.step,
                     callId: call.id,
                 });
-                await this.writeResult(ctx, call.id, tool.key, { content: hookDeniedText(verdict.plugin, verdict.reason), isError: true }, [event], undefined, [hookDeniedAudit(site, event.payload, verdict)]);
+                await this.writeResult(ctx, call.id, outKey, { content: hookDeniedText(verdict.plugin, verdict.reason), isError: true }, [event], undefined, [hookDeniedAudit(site, event.payload, verdict)]);
                 return undefined;
             }
         }
-        // `agent` (sub-agents spec §7.1): no tool_call_started; the dispatch is made durable in one
-        // transaction (its marker is the subagent_dispatches row) and the call stays open
+        // `Agent` (sub-agents spec §7.1, agent map spec §4.1): no tool_call_started; one transaction
+        // makes the dispatch durable (its marker is the subagent_dispatches row) and writes the call's
+        // immediate result, while the sub-agent runs in the background
         const dispatcher = this.deps.subagents;
         if (tool.source.kind === "builtin" && tool.key === AGENT_TOOL && dispatcher) {
             const parsed = AgentToolInput.safeParse(input);
             if (!parsed.success) {
-                return fail("Invalid agent call: pass description and prompt, and optionally subagent_type, model or resume.", tool.key);
+                return fail("Invalid agent call: pass description and prompt, and optionally subagent_type and model.", outKey);
             }
-            const r = await dispatcher.dispatch({ ctx, callId: call.id, input: parsed.data });
-            return r.kind === "refused" ? fail(r.content, tool.key) : OPEN;
+            const r = await dispatcher.dispatch({
+                ctx,
+                callId: call.id,
+                input: parsed.data,
+                call: { toolKey: outKey, authorization, startedAt: Date.now() },
+            });
+            if (r.kind === "refused")
+                return fail(r.content, outKey);
+            if (hooks && hookBase) {
+                fireObserve(hooks, "tool.postExecute", {
+                    ...hookBase,
+                    isError: false,
+                    content: r.content,
+                    durationMs: 0,
+                }, ctx.signal, this.deps.log);
+            }
+            return undefined;
+        }
+        // `SendMessage` and `SubagentHandback` (agent map spec §4.2, §4.3): no tool_call_started; each
+        // write is idempotent by the call (the message in the sub-agent's log, the delivery in the
+        // parent's), so a call retried after a crash sends nothing twice. A send that starts an idle
+        // sub-agent writes its result with the dispatch, like `Agent`
+        const messenger = this.deps.messages;
+        if (tool.source.kind === "builtin" &&
+            (tool.key === SEND_MESSAGE || tool.key === SUBAGENT_HANDBACK) &&
+            messenger) {
+            const t0 = Date.now();
+            let r;
+            if (tool.key === SEND_MESSAGE) {
+                const parsed = SendMessageInput.safeParse(input);
+                if (!parsed.success) {
+                    return fail("Invalid SendMessage call: pass to and message.", outKey);
+                }
+                r = await messenger.toChild(ctx, call.id, parsed.data.to, parsed.data.message, {
+                    authorization,
+                });
+            }
+            else {
+                const parsed = HandbackInput.safeParse(input);
+                if (!parsed.success)
+                    return fail("Invalid SubagentHandback call: pass message.", outKey);
+                r = await messenger.toParent(ctx, "report", parsed.data.message, call.id);
+            }
+            if (r.isError)
+                return fail(r.content, outKey);
+            const durationMs = Date.now() - t0;
+            if (r.logged !== true) {
+                await this.writeResult(ctx, call.id, outKey, { content: r.content, isError: false }, [], {
+                    durationMs,
+                    connectorId: null,
+                    authorization,
+                });
+            }
+            if (hooks && hookBase) {
+                fireObserve(hooks, "tool.postExecute", { ...hookBase, isError: false, content: r.content, durationMs }, ctx.signal, this.deps.log);
+            }
+            return undefined;
         }
         await this.deps.eventLog.append(ctx.conversationId, [
             {
@@ -751,7 +629,7 @@ let ToolPipeline = class ToolPipeline {
         const rendered = outcome.kind === "result"
             ? renderResult(outcome.result)
             : { text: outcome.message, contentTypes: [], isError: true };
-        // 内置工具（tool_search）报告的已加载工具：只认本步可用、非内置的 key，写进 tool_result（日志即事实源）
+        // 内置工具（ToolSearch）报告的已加载工具：只认本步可用、非内置的 key，写进 tool_result（日志即事实源）
         const loadedTools = outcome.kind === "result" && tool.source.kind === "builtin"
             ? loadedFrom(outcome.result, resolved.tools)
             : [];
@@ -795,7 +673,7 @@ let ToolPipeline = class ToolPipeline {
                 },
             ]
             : [];
-        await this.writeResult(ctx, call.id, tool.key, {
+        await this.writeResult(ctx, call.id, outKey, {
             content: spilled.content,
             isError: rendered.isError,
             ...(spilled.outputId !== undefined && { outputId: spilled.outputId }),
@@ -809,24 +687,11 @@ let ToolPipeline = class ToolPipeline {
             connectorId: tool.source.kind === "connector" ? tool.source.connectorId : null,
             authorization,
         });
-        // a sub-agent that needs a personal connection: mirrored in the parent for display (spec §9;
-        // not a wait, the child got the connect text as its result)
+        // a sub-agent that needs a personal connection: mirrored in the root conversation of its tree
+        // for display (sub-agents spec §9, agent map spec §7; not a wait, the child got the connect
+        // text as its result)
         if (outcome.kind === "connection_required" && ctx.parent !== undefined) {
-            await this.deps.eventLog
-                .append(ctx.parent.conversationId, [
-                {
-                    type: "subagent_waiting",
-                    runId: ctx.parent.runId,
-                    idemKey: subagentWaitingIdemKey(ctx.runId, `connect-${call.id}`),
-                    payload: {
-                        subagentId: ctx.conversationId,
-                        childRunId: ctx.runId,
-                        kind: "connect",
-                        toolKey: tool.key,
-                    },
-                },
-            ])
-                .catch((err) => this.deps.log.warn("cannot surface a sub-agent's connect card in its parent", {
+            await this.surfaceConnectInRoot(ctx, ctx.parent, call.id, tool.key).catch((err) => this.deps.log.warn("cannot surface a sub-agent's connect card in its root conversation", {
                 runId: ctx.runId,
                 err,
             }));
@@ -836,9 +701,44 @@ let ToolPipeline = class ToolPipeline {
         }
         return undefined;
     }
+    /** Appends a sub-agent's connect card to its root conversation ({@link rootSurfaceOf}). */
+    async surfaceConnectInRoot(ctx, parent, callId, toolKey) {
+        const target = await rootSurfaceOf(this.deps.db, ctx.conversationId, ctx.runId, parent);
+        if (!target)
+            return;
+        await this.deps.eventLog.append(target.conversationId, [
+            {
+                type: "subagent_waiting",
+                runId: target.runId,
+                idemKey: subagentWaitingIdemKey(ctx.runId, `connect-${callId}`),
+                payload: {
+                    subagentId: ctx.conversationId,
+                    childRunId: ctx.runId,
+                    path: target.path,
+                    kind: "connect",
+                    toolKey,
+                },
+            },
+        ]);
+    }
+    /**
+     * Every tool key the request that issued this step's calls offered (`request.tools` plus the
+     * `catalog` keys), in any mode; null when its model_call is not found. Used to tell a call to an
+     * old key that was offered (in flight across the rename) from one that never was.
+     */
+    async requestToolKeys(ctx) {
+        for (let attempt = MAX_MODEL_ATTEMPTS; attempt >= 1; attempt--) {
+            const e = await this.deps.eventLog.findByIdem(ctx.conversationId, modelCallIdemKey(ctx.runId, ctx.step, attempt));
+            if (e?.type !== "model_call")
+                continue;
+            const { tools, catalog } = e.payload.request;
+            return new Set([...(tools ?? []), ...(catalog ?? [])].map((t) => t.key));
+        }
+        return null;
+    }
     /**
      * 发出本步调用的请求里带了完整定义的工具 key：本步最后一次尝试的 `model_call.request.tools`
-     * （`assistant_message` 来自最后一次尝试）。该请求不在 tool_search 模式（没有 `catalog`，工具全部发送）
+     * （`assistant_message` 来自最后一次尝试）。该请求不在 ToolSearch 模式（没有 `catalog`，工具全部发送）
      * 或找不到 model_call 时返回 null（不做加载检查）。已加载集合由此从日志得出，不放进程内存。
      */
     async sentTools(ctx) {
@@ -912,7 +812,7 @@ let ToolPipeline = class ToolPipeline {
         const handler = this.deps.registry.handler(tool.source);
         if (!handler)
             return { kind: "error", message: `Tool ${tool.key} is no longer available.` };
-        // 插件处理函数只拿到 SDK 的 ToolCallContext；内置工具另外拿到本步解析出的工具（tool_search 用）
+        // 插件处理函数只拿到 SDK 的 ToolCallContext；内置工具另外拿到本步解析出的工具（ToolSearch 用）
         const base = {
             orgId: ctx.orgId,
             accountId: ctx.accountId,
@@ -924,14 +824,48 @@ let ToolPipeline = class ToolPipeline {
             ...(tool.source.kind === "builtin" && { runId: ctx.runId }),
             ...(tool.source.kind === "builtin" &&
                 ctx.deadline !== undefined && { runDeadline: ctx.deadline }),
-            // a sub-agent works in its parent conversation's sandbox (spec §10.1)
+            // a sub-agent works in its root conversation's sandbox (spec §10.1, at every depth)
+            ...(tool.source.kind === "builtin" &&
+                ctx.parent !== undefined && { sandboxConversationId: ctx.parent.rootConversationId }),
             ...(tool.source.kind === "builtin" &&
-                ctx.parent !== undefined && { sandboxConversationId: ctx.parent.conversationId }),
+                ctx.parent !== undefined && { parentRunId: ctx.parent.runId }),
+            ...(tool.source.kind === "builtin" &&
+                ctx.parent?.budgetRunId !== undefined && { budgetRunId: ctx.parent.budgetRunId }),
+            // the hook scope of a builtin's own model call (the WebFetch extraction)
+            ...(tool.source.kind === "builtin" && {
+                step: ctx.step,
+                agentVersion: ctx.agentVersion,
+                ...(ctx.conversationKind !== undefined && { conversationKind: ctx.conversationKind }),
+                ...(ctx.parent !== undefined && {
+                    parent: {
+                        conversationId: ctx.parent.conversationId,
+                        runId: ctx.parent.runId,
+                        callId: ctx.parent.callId,
+                    },
+                }),
+            }),
         };
         // 内置工具可按输入给自己的时限（沙箱 bash 按命令超时加余量）；缺省 tools.timeoutMs
         const timeoutMs = tool.timeoutMs?.(input) ?? this.config.get().tools.timeoutMs;
         try {
-            const r = await this.bounded(ctx.signal, (signal) => handler(input, { ...base, signal }), undefined, timeoutMs);
+            // a plugin tool runs with the extension's effective config for the org, never without it
+            // (layering spec A §6): one read per call, cached by EffectiveConfigs
+            let config = {};
+            if (tool.source.kind === "plugin") {
+                // turned off in the org since the step resolved its tools (spec A §7)
+                if (await this.deps.switches.isToolOff(ctx.orgId, tool.source.plugin, tool.source.name)) {
+                    return { kind: "error", message: `${toolTurnedOffReason(tool.key)}.` };
+                }
+                const effective = await this.deps.effective.get(ctx.orgId, tool.source.plugin);
+                if (!effective.ok) {
+                    // unloaded or disabled since the step resolved its tools: the documented unloaded error
+                    if (effective.notRunning)
+                        return { kind: "error", message: PLUGIN_UNLOADED_TOOL_ERROR };
+                    return { kind: "error", message: unavailableText(tool.key, NEEDS_CONFIG_REASON) };
+                }
+                config = { config: effective.config };
+            }
+            const r = await this.bounded(ctx.signal, (signal) => handler(input, { ...base, ...config, signal }), undefined, timeoutMs);
             if (r === "timeout") {
                 return { kind: "error", message: timeoutText(tool.key, timeoutMs) };
             }
@@ -1116,6 +1050,11 @@ let ToolPipeline = class ToolPipeline {
     thrown(key, e) {
         if (e instanceof ToolError)
             return { kind: "error", message: e.message };
+        // an extension tool's ctx.models.embed denied by a policy hook (spec B §5.4): the model sees the
+        // deny text (sanitized reason), as for a denied tool call, not a generic failure
+        if (e instanceof ApiError && e.code === "model.hook_denied") {
+            return { kind: "error", message: e.message };
+        }
         // 提供工具的插件实例在调用进行中被撤销（停用 / 升级），排空时限到后中止（C17）
         if (e instanceof ExtensionUnloadedError) {
             this.deps.log.warn("tool call aborted: plugin unloaded", { toolKey: key, plugin: e.plugin });
@@ -1286,9 +1225,6 @@ let ToolPipeline = class ToolPipeline {
         return out;
     }
 };
-__decorate([
-    Transactional()
-], ToolPipeline.prototype, "stopOpenAgentCallsNow", null);
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ToolPipeline.prototype, "stopOpenAgentCalls", null);
@@ -1300,18 +1236,21 @@ ToolPipeline = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(EventLog)),
     __param(2, Inject(SubagentsService)),
-    __param(3, Inject(ToolRegistry)),
-    __param(4, Inject(Credentials)),
-    __param(5, Inject(Breaker)),
-    __param(6, Inject(ToolOutputs)),
-    __param(7, Inject(ApprovalsService)),
-    __param(8, Inject(QuestionsService)),
-    __param(9, Inject(KernelConfigService)),
-    __param(10, Inject(KERNEL_LOGGER)),
-    __param(11, Inject(ExtensionHost)),
-    __param(12, Inject(ToolDrift)),
-    __param(13, Inject(TransactionHost)),
-    __param(14, Optional()),
-    __param(14, Inject(TOOL_PIPELINE_HOOKS))
+    __param(3, Inject(SubagentMessages)),
+    __param(4, Inject(ToolRegistry)),
+    __param(5, Inject(Credentials)),
+    __param(6, Inject(Breaker)),
+    __param(7, Inject(ToolOutputs)),
+    __param(8, Inject(ApprovalsService)),
+    __param(9, Inject(QuestionsService)),
+    __param(10, Inject(KernelConfigService)),
+    __param(11, Inject(KERNEL_LOGGER)),
+    __param(12, Inject(ExtensionHost)),
+    __param(13, Inject(ToolDrift)),
+    __param(14, Inject(EffectiveConfigs)),
+    __param(15, Inject(OrgToolSwitches)),
+    __param(16, Inject(TransactionHost)),
+    __param(17, Optional()),
+    __param(17, Inject(TOOL_PIPELINE_HOOKS))
 ], ToolPipeline);
 export { ToolPipeline };