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

package/dist/tools/pipeline.js

@@ -9,9 +9,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 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 { 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,22 +23,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 { TOOL_SEARCH } from "./builtin-names.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";
@@ -69,11 +73,6 @@ export const RUN_STOPPED_TEXT = "The run was stopped before this tool call was e
 export const RUN_STOPPED_DURING_TEXT = "The run was stopped while this tool call was running; its outcome is unknown. Verify before retrying.";
 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.`;
-/**
- * Is a logged call key the `Agent` tool: the current key, or the rc `agent` of a call dispatched
- * before the rename (spec §9; a builtin maps without a scope)?
- */
-const isAgentCallKey = (key) => key === AGENT_TOOL || legacyToolKey(key) === AGENT_TOOL;
 /** The connector slugs and extension names among the run's tools (to read old `<x>__<tool>` keys). */
 const legacyScopeOf = (tools) => {
     const connectorSlugs = new Set();
@@ -91,7 +90,10 @@ const unknownToolText = (name, keys, toolSearch, hint = null) => `Unknown tool "
     (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;
 /**
@@ -105,8 +107,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,
@@ -181,9 +181,11 @@ let ToolPipeline = class ToolPipeline {
     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, 
+    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 = {
@@ -202,6 +204,8 @@ let ToolPipeline = class ToolPipeline {
             get pluginHooks() {
                 return host?.hooks;
             },
+            effective,
+            switches,
             inlineViews: (plugin) => new Set((host?.current(plugin)?.manifest.ui ?? [])
                 .filter((c) => c.place === "inline" && c.aliasOf === undefined)
                 .map((c) => c.id)),
@@ -211,6 +215,7 @@ let ToolPipeline = class ToolPipeline {
             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
@@ -240,322 +245,34 @@ let ToolPipeline = class ToolPipeline {
                     tools: ctx.agent.tools ?? [],
                     skillLoad,
                     subagents: ctx.agent.subagents,
+                    child: ctx.parent !== undefined,
+                    forkChild: ctx.parent?.forSkill === true,
                 });
             }
             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 (isAgentCallKey(call.name)) {
-                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).
+     * 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 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);
-        // the result keeps the logged key (`agent` for a call dispatched before the rename, spec §9)
-        await this.writeResult(ctx, row.parentCallId, call.name, { 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.
-     */
-    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();
-        // the logged key of each call (`agent` for a call dispatched before the rename, spec §9)
-        const names = 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);
-                        if (b.name !== undefined)
-                            names.set(b.id, b.name);
-                    }
-                }
-            }
-            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: names.get(d.parent_call_id) ?? 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 → 继续等；否则本次是第
@@ -640,9 +357,10 @@ let ToolPipeline = class ToolPipeline {
             if (sent !== null && !sent.has(tool.key))
                 return fail(notLoadedText(tool.key), outKey);
         }
+        const rawInput = legacy ? legacyToolInput(call.name, call.input) : call.input;
         let input;
         try {
-            input = await resolveOutputRefs(legacy ? legacyToolInput(call.name, call.input) : 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)
@@ -656,6 +374,21 @@ let ToolPipeline = class ToolPipeline {
         });
         if (invalid !== null)
             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,
+        })) ?? 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,
@@ -664,11 +397,13 @@ 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), outKey);
+            return fail(deniedText(tool.key, callPolicy?.key), outKey);
         if (typeof decision === "object" && "unavailable" in decision) {
             return fail(unavailableText(tool.key, decision.unavailable), outKey);
         }
@@ -679,7 +414,11 @@ let ToolPipeline = class ToolPipeline {
         // 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.
-        const approvedHere = approval?.status === "approved" && (legacy || approval.specHash === tool.specHash);
+        // 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({
@@ -689,13 +428,15 @@ 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") {
@@ -762,16 +503,72 @@ let ToolPipeline = class ToolPipeline {
                 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.", outKey);
+                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,
+                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);
             }
-            const r = await dispatcher.dispatch({ ctx, callId: call.id, input: parsed.data });
-            return r.kind === "refused" ? fail(r.content, outKey) : OPEN;
+            return undefined;
         }
         await this.deps.eventLog.append(ctx.conversationId, [
             {
@@ -852,24 +649,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,
             }));
@@ -879,6 +663,26 @@ 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
@@ -982,14 +786,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.conversationId }),
+                ctx.parent !== undefined && { sandboxConversationId: ctx.parent.rootConversationId }),
+            ...(tool.source.kind === "builtin" &&
+                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) };
             }
@@ -1344,9 +1182,6 @@ let ToolPipeline = class ToolPipeline {
         return out;
     }
 };
-__decorate([
-    Transactional()
-], ToolPipeline.prototype, "stopOpenAgentCallsNow", null);
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ToolPipeline.prototype, "stopOpenAgentCalls", null);
@@ -1358,18 +1193,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 };