@ouro.bot/cli 0.1.0-alpha.810 → 0.1.0-alpha.812

package/dist/repertoire/tools.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.surfaceToolDef = exports.speakTool = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
-exports.resetMcpDefinitions = resetMcpDefinitions;
-exports.getSanctuaryRelationshipTools = getSanctuaryRelationshipTools;
+exports.ToolSelectionError = exports.surfaceToolDef = exports.speakTool = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = exports.SANCTUARY_OWNER_ADDITIONS = void 0;
+exports.toolSelectionSchemas = toolSelectionSchemas;
+exports.selectToolsForChannel = selectToolsForChannel;
 exports.getToolsForChannel = getToolsForChannel;
+exports.reduceToolSelection = reduceToolSelection;
 exports.resolveToolDefinition = resolveToolDefinition;
 exports.approvalPolicyForToolName = approvalPolicyForToolName;
 exports.classifyApprovalForInvocation = classifyApprovalForInvocation;
@@ -11,9 +12,12 @@ exports.approvalPolicyForInvocation = approvalPolicyForInvocation;
 exports.shellRiskProfile = shellRiskProfile;
 exports.riskProfileForTool = riskProfileForTool;
 exports.riskProfileForToolName = riskProfileForToolName;
+exports.preflightToolCall = preflightToolCall;
+exports.executeTool = executeTool;
 exports.execTool = execTool;
 exports.summarizeArgs = summarizeArgs;
 exports.buildToolResultSummary = buildToolResultSummary;
+const node_util_1 = require("node:util");
 const tools_base_1 = require("./tools-base");
 const tools_teams_1 = require("./tools-teams");
 const tools_bluebubbles_1 = require("./tools-bluebubbles");
@@ -26,12 +30,14 @@ const identity_1 = require("../heart/identity");
 const store_1 = require("../commerce/store");
 const tools_surface_1 = require("./tools-surface");
 const mcp_tools_1 = require("./mcp-tools");
+const tool_arguments_1 = require("./tool-arguments");
 const tools_voice_1 = require("./tools-voice");
 const shell_sessions_1 = require("./shell-sessions");
 const tools_unraid_1 = require("./tools-unraid");
 const tools_flow_1 = require("./tools-flow");
 const tools_steward_policy_1 = require("./tools-steward-policy");
 const steward_policy_1 = require("../heart/steward-policy");
+const tool_approval_1 = require("../heart/tool-approval");
 function safeGetAgentRoot() {
     try {
         return (0, identity_1.getAgentRoot)();
@@ -40,14 +46,6 @@ function safeGetAgentRoot() {
         return undefined;
     }
 }
-function isSanctuaryAgent() {
-    try {
-        return (0, identity_1.getAgentName)() === "sanctuary";
-    }
-    catch {
-        return false;
-    }
-}
 const SANCTUARY_RELATIONSHIP_BASE_TOOLS = new Set([
     "external_event_disposition",
     "query_active_work",
@@ -63,23 +61,10 @@ const SANCTUARY_RELATIONSHIP_BASE_TOOLS = new Set([
     "describe_image",
     "send_message",
 ]);
-const SANCTUARY_TELEGRAM_SURFACE = new Set([
-    "query_active_work",
-    "save_friend_note",
-    "telegram_contact_manage",
-    "query_cares",
-    "care_manage",
-    "await_condition",
-    "resolve_await",
-    "cancel_await",
-    "list_recent_attachments",
-    "materialize_attachment",
-    "describe_image",
-    ...tools_unraid_1.unraidToolDefinitions.map((definition) => definition.tool.function.name),
-    "steward_policy_manage",
-    "ponder",
-    "settle",
-    "speak",
+exports.SANCTUARY_OWNER_ADDITIONS = new Set([
+    "shell", "shell_status", "shell_tail", "read_file", "write_file", "edit_file", "glob", "grep",
+    "web_search", "search_facts", "consult_diary", "consult_notes", "get_friend_note",
+    "session_summary", "query_session", "set_reasoning_effort", "restart_runtime", "revive_sense",
 ]);
 // Re-export types and constants used by the rest of the codebase
 var tools_base_2 = require("./tools-base");
@@ -93,44 +78,26 @@ Object.defineProperty(exports, "speakTool", { enumerable: true, get: function ()
 var tools_surface_2 = require("./tools-surface");
 Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });
 // All tool definitions in a single registry
-const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, tools_surface_1.surfaceToolDefinition];
+const additionalDefinitions = [...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, ...tools_voice_1.voiceToolDefinitions, ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, tools_surface_1.surfaceToolDefinition];
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
-// MCP tool definitions — populated each time getToolsForChannel() is called with an mcpManager.
-// Kept separate from allDefinitions so execTool can find them.
-let mcpDefinitions = [];
-/** Exported for testing — reset the MCP definitions cache. */
-function resetMcpDefinitions() {
-    mcpDefinitions = [];
-}
-function baseToolsForCapabilities() {
-    // Use baseToolDefinitions at call time so dynamically-added tools are included
-    return tools_base_1.baseToolDefinitions.map((d) => d.tool);
+class ToolSelectionError extends Error {
 }
-function uniqueToolSchemas(tools) {
+exports.ToolSelectionError = ToolSelectionError;
+function assertUniqueToolSchemas(tools) {
     const seen = new Set();
-    return tools.filter((tool) => {
-        if (seen.has(tool.function.name))
-            return false;
+    for (const tool of tools) {
+        if (seen.has(tool.function.name)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error", component: "tools", event: "tool.selection_collision",
+                message: "tool selection contains an ambiguous name", meta: { name: tool.function.name },
+            });
+            throw new ToolSelectionError(`tool selection collision: ${tool.function.name}`);
+        }
         seen.add(tool.function.name);
-        return true;
-    });
+    }
 }
-/**
- * Resolve Sanctuary relationship tools from one canonical definition pool.
- * Durable relationship profiles can only reduce this surface; they cannot
- * introduce an arbitrary base tool by naming it in configuration.
- */
-function getSanctuaryRelationshipTools(advertisedToolNames) {
-    const advertised = new Set(advertisedToolNames);
-    return uniqueToolSchemas([
-        ...tools_base_1.baseToolDefinitions.filter((definition) => SANCTUARY_RELATIONSHIP_BASE_TOOLS.has(definition.tool.function.name)).map((definition) => definition.tool),
-        ...tools_unraid_1.unraidToolDefinitions.map((definition) => definition.tool),
-        tools_steward_policy_1.stewardPolicyToolDefinition.tool,
-        tools_flow_1.ponderTool,
-        tools_flow_1.restTool,
-        tools_flow_1.settleTool,
-        tools_flow_1.speakTool,
-    ]).filter((tool) => advertised.has(tool.function.name));
+function toolSelectionSchemas(selection) {
+    return [...selection.ordinary.map((definition) => definition.tool), ...selection.engine];
 }
 // Apply a single tool preference to a tool schema, returning a new object.
 function applyPreference(tool, pref) {
@@ -142,78 +109,96 @@ function applyPreference(tool, pref) {
         },
     };
 }
-// Filter out tools whose requiredCapability is not in the provider's capability set.
-// Uses baseToolDefinitions at call time so dynamically-added tools are included.
-// Only base tools can have requiredCapability (integration tools do not).
-function filterByCapability(toolList, providerCapabilities) {
-    return toolList.filter((tool) => {
-        const def = tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === tool.function.name);
-        if (!def?.requiredCapability)
-            return true;
-        return providerCapabilities?.has(def.requiredCapability) === true;
-    });
-}
-// Return the appropriate tools list based on channel capabilities.
-// Base tools (no integration) are always included.
-// Teams/integration tools are included only if their integration is in availableIntegrations.
-// When toolPreferences is provided, matching preferences are appended to tool descriptions.
-// When providerCapabilities is provided, tools with requiredCapability are filtered.
-function getToolsForChannel(capabilities, toolPreferences, _context, providerCapabilities, mcpManager, _chatModel) {
-    if (capabilities?.channel === "telegram" && isSanctuaryAgent()) {
-        return getSanctuaryRelationshipTools([...SANCTUARY_TELEGRAM_SURFACE]);
-    }
-    const baseTools = baseToolsForCapabilities();
-    const bluebubblesTools = capabilities?.channel === "bluebubbles"
-        ? tools_bluebubbles_1.bluebubblesToolDefinitions.map((d) => d.tool)
-        : [];
-    const voiceTools = capabilities?.channel === "voice"
-        ? tools_voice_1.voiceToolDefinitions.map((d) => d.tool)
-        : [];
-    let result;
-    if (!capabilities || capabilities.availableIntegrations.length === 0) {
-        result = [...baseTools, ...bluebubblesTools, ...voiceTools];
+function selectToolsForChannel(capabilities, toolPreferences, _context, providerCapabilities, mcpManager, _chatModel, context) {
+    const relationship = context?.relationshipAuthorization;
+    const profileId = relationship?.profileId;
+    const sanctuary = (context?.agentName === "sanctuary" && (relationship !== undefined || capabilities?.channel === "telegram"))
+        || profileId?.startsWith("sanctuary-") === true;
+    const owner = profileId === "sanctuary-owner";
+    const knownSanctuaryProfile = relationship !== undefined && (owner || profileId === "sanctuary-household" || profileId === "sanctuary-event");
+    const mcp = mcpManager ? (0, mcp_tools_1.mcpToolsAsDefinitions)(mcpManager) : [];
+    const native = [...tools_base_1.baseToolDefinitions, ...additionalDefinitions];
+    assertUniqueToolSchemas([
+        ...native.map((definition) => definition.tool), ...mcp.map((definition) => definition.tool),
+        tools_flow_1.ponderTool, tools_flow_1.restTool, tools_flow_1.observeTool, tools_flow_1.settleTool, tools_flow_1.speakTool,
+    ]);
+    let ordinary;
+    if (sanctuary) {
+        ordinary = knownSanctuaryProfile
+            ? [
+                ...tools_base_1.baseToolDefinitions.filter((definition) => SANCTUARY_RELATIONSHIP_BASE_TOOLS.has(definition.tool.function.name)
+                    || (owner && exports.SANCTUARY_OWNER_ADDITIONS.has(definition.tool.function.name))),
+                ...tools_unraid_1.unraidToolDefinitions, tools_steward_policy_1.stewardPolicyToolDefinition, ...(owner ? mcp : []),
+            ]
+            : [];
     }
     else {
-        const available = new Set(capabilities.availableIntegrations);
-        const channelDefs = [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
-        // Include tools whose integration is available, plus channel tools with no integration gate (e.g. teams_send_message)
-        const integrationDefs = channelDefs.filter((d) => d.integration ? available.has(d.integration) : capabilities.channel === "teams");
-        if (!toolPreferences || Object.keys(toolPreferences).length === 0) {
-            result = [...baseTools, ...bluebubblesTools, ...voiceTools, ...integrationDefs.map((d) => d.tool)];
+        const available = new Set(capabilities?.availableIntegrations ?? []);
+        const integrations = available.size === 0 ? [] : [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions]
+            .filter((definition) => definition.integration ? available.has(definition.integration) : capabilities?.channel === "teams")
+            .map((definition) => {
+            const preference = definition.integration ? toolPreferences?.[definition.integration] : undefined;
+            return preference ? { ...definition, tool: applyPreference(definition.tool, preference) } : definition;
+        });
+        ordinary = [
+            ...tools_base_1.baseToolDefinitions,
+            ...(capabilities?.channel === "bluebubbles" ? tools_bluebubbles_1.bluebubblesToolDefinitions : []),
+            ...(capabilities?.channel === "voice" ? tools_voice_1.voiceToolDefinitions : []),
+            ...integrations, ...mcp,
+        ];
+    }
+    const inner = capabilities?.channel === "inner";
+    const habit = context?.habitSession;
+    if (inner) {
+        const canSend = habit?.toolPolicy.outwardMessagingAllowed === true && habit.toolPolicy.grantedTools.includes("send_message");
+        ordinary = ordinary.filter((definition) => canSend || definition.tool.function.name !== "send_message");
+        if (!habit || (habit.toolPolicy.outwardMessagingAllowed && habit.toolPolicy.grantedTools.includes("surface"))) {
+            ordinary.push(tools_surface_1.surfaceToolDefinition);
         }
-        else {
-            // Build a map of integration -> preference text for fast lookup
-            const prefMap = new Map();
-            for (const [key, value] of Object.entries(toolPreferences)) {
-                prefMap.set(key, value);
-            }
-            // Apply preferences to matching integration tools (new objects, no mutation)
-            // d.integration is guaranteed truthy -- integrationDefs are pre-filtered above
-            const enrichedIntegrationTools = integrationDefs.map((d) => {
-                const pref = prefMap.get(d.integration);
-                return pref ? applyPreference(d.tool, pref) : d.tool;
+    }
+    ordinary = ordinary.filter((definition) => (!relationship || relationship.advertisedToolNames.includes(definition.tool.function.name))
+        && (!definition.requiredCapability || providerCapabilities?.has(definition.requiredCapability) === true));
+    const engine = [
+        ...(context?.noSend ? [] : [tools_flow_1.ponderTool]),
+        ...(inner ? [tools_flow_1.restTool] : [tools_flow_1.observeTool, tools_flow_1.settleTool]),
+        ...(capabilities?.chatStyle ? [tools_flow_1.speakTool] : []),
+    ].filter((tool) => (!sanctuary || (knownSanctuaryProfile && tool.function.name !== "observe"))
+        && (!relationship || relationship.advertisedToolNames.includes(tool.function.name)));
+    return Object.freeze({
+        ordinary: Object.freeze(ordinary.map((definition) => Object.freeze({
+            ...definition,
+            tool: (0, tool_arguments_1.freezeToolValue)(structuredClone(definition.tool)),
+            ...(definition.riskProfile && typeof definition.riskProfile !== "function"
+                ? { riskProfile: (0, tool_arguments_1.freezeToolValue)(structuredClone(definition.riskProfile)) } : {}),
+            ...(definition.terminalProjection ? { terminalProjection: (0, tool_arguments_1.freezeToolValue)(structuredClone(definition.terminalProjection)) } : {}),
+        }))),
+        engine: Object.freeze(engine.map((tool) => (0, tool_arguments_1.freezeToolValue)(tool))),
+    });
+}
+function getToolsForChannel(...args) {
+    return toolSelectionSchemas(selectToolsForChannel(...args));
+}
+function reduceToolSelection(selection, requested) {
+    assertUniqueToolSchemas(requested);
+    const canonical = toolSelectionSchemas(selection);
+    for (const tool of requested) {
+        const match = canonical.find((candidate) => candidate.function.name === tool.function.name);
+        if (!match || !(0, node_util_1.isDeepStrictEqual)(match, tool)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", component: "tools", event: "tool.selection_rejected",
+                message: "tool override is not an exact canonical reduction", meta: { name: tool.function.name },
             });
-            result = [...baseTools, ...bluebubblesTools, ...voiceTools, ...enrichedIntegrationTools];
+            throw new ToolSelectionError(`tool selection is not a canonical reduction: ${tool.function.name}`);
         }
     }
-    // Append first-class MCP tools when mcpManager is provided
-    if (mcpManager) {
-        mcpDefinitions = (0, mcp_tools_1.mcpToolsAsDefinitions)(mcpManager);
-        const mcpSchemas = mcpDefinitions.map((d) => d.tool);
-        result = [...result, ...mcpSchemas];
-    }
-    return filterByCapability(result, providerCapabilities);
+    const names = new Set(requested.map((tool) => tool.function.name));
+    return Object.freeze({ ordinary: Object.freeze(selection.ordinary.filter((definition) => names.has(definition.tool.function.name))), engine: selection.engine });
 }
-// Look up a tool definition from the live combined registry (native + MCP).
-// The base registry is intentionally consulted at call time so tests and
-// runtime extensions cannot leave execution metadata behind a stale snapshot.
-function resolveToolDefinition(toolName) {
-    return tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === toolName)
-        ?? allDefinitions.find((d) => d.tool.function.name === toolName)
-        ?? mcpDefinitions.find((d) => d.tool.function.name === toolName);
+function resolveToolDefinition(toolName, selection) {
+    return (selection?.ordinary ?? [...tools_base_1.baseToolDefinitions, ...additionalDefinitions]).find((definition) => definition.tool.function.name === toolName);
 }
-function approvalPolicyForToolName(name, args) {
-    return resolveToolDefinition(name)?.approvalPolicy?.(args) ?? { kind: "not_required" };
+function approvalPolicyForToolName(name, args, selection) {
+    return resolveToolDefinition(name, selection)?.approvalPolicy?.(args) ?? { kind: "not_required" };
 }
 async function routineActionInvocation(name, args, ctx) {
     const target = typeof args.container === "string" ? args.container : "";
@@ -236,7 +221,7 @@ async function routineActionInvocation(name, args, ctx) {
     return decision.allowed ? { key, target, expectedPolicyVersion: decision.policyVersion } : null;
 }
 async function classifyApprovalForInvocation(name, args, ctx) {
-    const fallback = approvalPolicyForToolName(name, args);
+    const fallback = approvalPolicyForToolName(name, args, ctx?.toolSelection);
     if (name !== "unraid_restart_container" || fallback.kind !== "required")
         return { policy: fallback };
     const routineActionSelection = await routineActionInvocation(name, args, ctx);
@@ -246,9 +231,6 @@ async function approvalPolicyForInvocation(name, args, ctx) {
     return (await classifyApprovalForInvocation(name, args, ctx)).policy;
 }
 const findDefinition = resolveToolDefinition;
-function normalizeGuardArgs(_name, args) {
-    return args;
-}
 const READ_ONLY_OURO_SHELL_COMMANDS = new Set([
     "help",
     "-h",
@@ -321,8 +303,8 @@ function riskProfileForTool(def, name, args) {
         return def.riskProfile(args);
     return def.riskProfile ?? { mutates: "none", risk: "low" };
 }
-function riskProfileForToolName(name, args) {
-    const def = findDefinition(name);
+function riskProfileForToolName(name, args, selection) {
+    const def = findDefinition(name, selection);
     return def ? riskProfileForTool(def, name, args) : null;
 }
 function orientationHoldMessage(name, profile, reason) {
@@ -337,73 +319,105 @@ function orientationPolicyBlocks(profile, blockedMutationKinds) {
         return false;
     return mutationKindsFor(profile).some((kind) => blockedMutationKinds.includes(kind));
 }
-async function execTool(name, args, ctx) {
-    (0, runtime_1.emitNervesEvent)({
-        event: "tool.start",
-        component: "tools",
-        message: "tool execution started",
-        meta: { name, ...(name === "shell" && args.command ? { command: args.command } : {}) },
-    });
-    // Look up from combined registry (native + MCP)
-    const def = findDefinition(name);
-    if (!def) {
-        (0, runtime_1.emitNervesEvent)({
-            level: "error",
-            event: "tool.error",
-            component: "tools",
-            message: "unknown tool requested",
-            meta: { name },
-        });
-        return `unknown: ${name}`;
-    }
-    const relationshipDecision = await ctx?.relationshipAuthorization?.authorizeTool(name, args);
-    if (relationshipDecision && !relationshipDecision.allowed) {
-        (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "tool.relationship_authorization_block",
-            component: "tools",
-            message: "relationship authorization blocked tool execution",
-            meta: { name, reason: relationshipDecision.reason },
-        });
-        return `relationship authorization required: ${relationshipDecision.reason}`;
-    }
-    const riskProfile = riskProfileForTool(def, name, args);
-    const orientationPolicy = ctx?.orientationFrame?.actionPolicy;
-    if (orientationPolicy?.mode === "correction_hold"
-        && orientationPolicyBlocks(riskProfile, orientationPolicy.blockedMutationKinds)) {
-        const reason = orientationPolicy.reason;
-        const message = orientationHoldMessage(name, riskProfile, reason);
-        (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "tool.orientation_hold_block",
-            component: "tools",
-            message: "orientation hold blocked high-risk tool execution",
-            meta: { name, mutates: mutationKindsFor(riskProfile), reason },
-        });
-        return message;
+async function preflightToolCall(name, args, ctx) {
+    try {
+        const selection = ctx?.toolSelection;
+        const def = findDefinition(name, selection);
+        const schema = def?.tool ?? selection?.engine.find((tool) => tool.function.name === name);
+        if (!schema) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", event: "tool.error", component: "tools", message: "unknown or unselected tool requested", meta: { name } });
+            return { kind: "rejected_before_handler", text: `unknown: ${name}` };
+        }
+        if (selection || ctx?.relationshipAuthorization) {
+            const validation = (0, tool_arguments_1.validateAdvertisedToolArguments)(JSON.stringify(args), schema.function.parameters ?? {});
+            if (!validation.ok)
+                return { kind: "rejected_before_handler", text: `invalid tool arguments: ${validation.reason}` };
+        }
+        (0, tool_arguments_1.assertRelationshipToolOwner)(ctx);
+        const relationship = ctx?.relationshipAuthorization;
+        const decision = await relationship?.authorizeTool(name, args);
+        if (decision && (!decision.allowed || !relationship.advertisedToolNames.includes(name)
+            || (decision.profileId !== undefined && decision.profileId !== relationship.profileId))) {
+            const reason = decision.allowed ? "current relationship selection changed" : decision.reason;
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "tool.relationship_authorization_block", component: "tools",
+                message: "relationship authorization blocked tool execution", meta: { name, reason },
+            });
+            return { kind: "rejected_before_handler", text: `relationship authorization required: ${reason}` };
+        }
+        const currentSelection = ctx?.selectCurrentTools?.()
+            ?? (relationship?.profileId?.startsWith("sanctuary-") || (relationship && ctx?.agentName === "sanctuary")
+                ? selectToolsForChannel(undefined, undefined, undefined, undefined, undefined, undefined, ctx)
+                : undefined);
+        const current = currentSelection ? findDefinition(name, currentSelection) : def?.mcpBinding ? def : findDefinition(name);
+        const currentSchema = current?.tool ?? currentSelection?.engine.find((tool) => tool.function.name === name)
+            ?? (!currentSelection ? selection?.engine.find((tool) => tool.function.name === name) : undefined);
+        if (!currentSchema || !(0, node_util_1.isDeepStrictEqual)(schema, currentSchema)
+            || (def && (!current || (def.mcpBinding
+                ? !current.mcpBinding || current.mcpBinding.manager !== def.mcpBinding.manager || !(0, node_util_1.isDeepStrictEqual)(current.mcpBinding, def.mcpBinding)
+                : current.handler !== def.handler)))) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "tool.selection_rejected", component: "tools",
+                message: "selected tool is no longer current", meta: { name },
+            });
+            return { kind: "rejected_before_handler", text: `rejected: ${name} changed or is no longer available in the current tool selection` };
+        }
+        if (def?.mcpBinding) {
+            if (!ctx?.agentName || !ctx.agentRoot)
+                throw new mcp_tools_1.McpCallRejectedError("MCP requires an explicit owner");
+            await def.mcpBinding.manager.validateToolBinding(def.mcpBinding, { agentName: ctx.agentName, agentRoot: ctx.agentRoot });
+        }
+        if (!def)
+            return { kind: "ready" };
+        const risk = riskProfileForTool(def, name, args);
+        const orientationPolicy = ctx?.orientationFrame?.actionPolicy;
+        if (orientationPolicy?.mode === "correction_hold" && orientationPolicyBlocks(risk, orientationPolicy.blockedMutationKinds)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "tool.orientation_hold_block", component: "tools",
+                message: "orientation hold blocked high-risk tool execution",
+                meta: { name, mutates: mutationKindsFor(risk), reason: orientationPolicy.reason },
+            });
+            return { kind: "rejected_before_handler", text: orientationHoldMessage(name, risk, orientationPolicy.reason) };
+        }
+        const group = ctx?.context && "isGroupChat" in ctx.context ? ctx.context.isGroupChat : undefined;
+        const guardContext = {
+            readPaths: tools_base_1.editFileReadTracker, trustLevel: ctx?.context?.friend?.trustLevel,
+            agentRoot: ctx?.agentRoot ?? safeGetAgentRoot(), friendId: ctx?.context?.friend?.id,
+            ...(def?.mcpServer ? { mcpServerName: def.mcpServer } : {}),
+            ...(typeof group === "boolean" ? { isGroupChat: group } : {}),
+        };
+        const guard = (0, guardrails_1.guardInvocation)(name, args, guardContext);
+        if (!guard.allowed) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "tool.guardrail_block", component: "tools",
+                message: "guardrail blocked tool execution", meta: { name, reason: guard.reason },
+            });
+            return { kind: "rejected_before_handler", text: guard.reason };
+        }
+        return { kind: "ready", definition: def, agentRoot: guardContext.agentRoot, friendId: guardContext.friendId };
     }
-    // Guardrail check: structural + trust-level
-    const mcpDef = mcpDefinitions.find((d) => d.tool.function.name === name);
-    const guardContext = {
-        readPaths: tools_base_1.editFileReadTracker,
-        trustLevel: ctx?.context?.friend?.trustLevel,
-        agentRoot: ctx?.agentRoot ?? safeGetAgentRoot(),
-        friendId: ctx?.context?.friend?.id,
-        ...(mcpDef?.mcpServer ? { mcpServerName: mcpDef.mcpServer } : {}),
-        ...(ctx?.context?.isGroupChat !== undefined ? { isGroupChat: (ctx?.context).isGroupChat } : {}),
-    };
-    const guardArgs = normalizeGuardArgs(name, args);
-    const guardResult = (0, guardrails_1.guardInvocation)(name, guardArgs, guardContext);
-    if (!guardResult.allowed) {
+    catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
         (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "tool.guardrail_block",
-            component: "tools",
-            message: "guardrail blocked tool execution",
-            meta: { name, reason: guardResult.reason },
+            level: "warn", event: "tool.selection_rejected", component: "tools",
+            message: "tool preflight failed before execution", meta: { name, reason: text.slice(0, 2000) },
         });
-        return guardResult.reason;
+        return { kind: "rejected_before_handler", text: `rejected: ${text.slice(0, 2000)}`, error };
     }
+}
+async function executeTool(name, args, ctx, executor) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "tool.start", component: "tools", message: "tool execution started",
+        meta: { name, ...(name === "shell" && args.command ? { command: args.command } : {}) },
+    });
+    const prepared = await preflightToolCall(name, args, ctx);
+    if (prepared.kind !== "ready")
+        return prepared;
+    const def = prepared.definition;
+    if (!def)
+        return { kind: "rejected_before_handler", text: `rejected: ${name} is owned by the engine` };
+    const guardContext = prepared;
+    const guardArgs = args;
     const commerceReservation = COMMERCE_AUTHORITY_TOOLS.has(name) && guardContext.agentRoot
         ? (0, store_1.reserveCommerceAuthority)({
             agentRoot: guardContext.agentRoot,
@@ -421,7 +435,7 @@ async function execTool(name, args, ctx) {
             message: "guardrail blocked tool execution",
             meta: { name, reason: commerceReservation.reason },
         });
-        return `commerce authority required: ${commerceReservation.reason}`;
+        return { kind: "rejected_before_handler", text: `commerce authority required: ${commerceReservation.reason}` };
     }
     const authorizedContext = ctx;
     const toolContext = commerceReservation?.ok
@@ -435,14 +449,14 @@ async function execTool(name, args, ctx) {
         }
         : authorizedContext;
     try {
-        const result = await def.handler(args, toolContext);
+        const result = await (executor ? executor(name, args, toolContext) : def.handler(args, toolContext));
         (0, runtime_1.emitNervesEvent)({
             event: "tool.end",
             component: "tools",
             message: "tool execution finished",
             meta: { name, success: true },
         });
-        return result;
+        return { kind: "handler_succeeded", text: result };
     }
     catch (error) {
         (0, runtime_1.emitNervesEvent)({
@@ -452,7 +466,14 @@ async function execTool(name, args, ctx) {
             message: error instanceof Error ? error.message : String(error),
             meta: { name },
         });
-        throw error;
+        const text = error instanceof Error ? error.message : String(error);
+        return {
+            kind: error instanceof mcp_tools_1.McpCallRejectedError ? "rejected_before_handler"
+                : error instanceof mcp_tools_1.McpToolExecutionError ? error.kind
+                    : error instanceof tool_approval_1.ApprovalExecutionFailedError ? "handler_failed"
+                        : riskProfileForTool(def, name, args).risk === "high" ? "handler_indeterminate" : "handler_failed",
+            text: text.slice(0, 2000), error,
+        };
     }
     finally {
         if (commerceReservation?.ok && guardContext.agentRoot) {
@@ -471,6 +492,13 @@ async function execTool(name, args, ctx) {
         }
     }
 }
+async function execTool(name, args, ctx, executor) {
+    // Keep the legacy handler type without coercing schema-validated JSON values.
+    const result = await executeTool(name, args, ctx, executor);
+    if ("error" in result && !(result.error instanceof mcp_tools_1.McpToolExecutionError))
+        throw result.error;
+    return result.text;
+}
 function summarizeKeyValues(args, keys, maxValueLength = 60) {
     const parts = [];
     for (const key of keys) {
@@ -491,8 +519,8 @@ function summarizeUnknownArgs(args) {
         return "";
     return summarizeKeyValues(args, keys);
 }
-function summarizeArgs(name, args) {
-    const def = findDefinition(name);
+function summarizeArgs(name, args, selection) {
+    const def = findDefinition(name, selection);
     if (def && def.summaryKeys !== undefined) {
         return summarizeKeyValues(args, def.summaryKeys);
     }
@@ -503,12 +531,11 @@ function summarizeArgs(name, args) {
  * For recognized tools, includes result-derived info (diff stats, exit codes, etc.).
  * Falls back to arg-based summary for unrecognized tools.
  */
-function buildToolResultSummary(name, args, _result, success) {
-    /* v8 ignore start -- branches: ?? fallbacks and ternaries in tool summary formatting @preserve */
+function buildToolResultSummary(name, args, _result, success, selection) {
     switch (name) {
         case "edit_file": {
             if (!success)
-                return summarizeArgs(name, args);
+                return summarizeArgs(name, args, selection);
             const addedLines = (args.new_string ?? "").split("\n").length;
             const removedLines = (args.old_string ?? "").split("\n").length;
             return `+${addedLines} -${removedLines} lines in ${args.path ?? "unknown"}`;
@@ -532,7 +559,6 @@ function buildToolResultSummary(name, args, _result, success) {
             return `${taskRef} -> ${status}`;
         }
         default:
-            return summarizeArgs(name, args);
+            return summarizeArgs(name, args, selection);
     }
-    /* v8 ignore stop */
 }

package/dist/senses/bluebubbles/index.js

@@ -1571,9 +1571,10 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     return { handled: true, notifiedAgent: false, kind: event.kind, reason: "superseded" };
                 }
                 options.lifecycleSignal?.throwIfAborted();
+                const mcpOwner = { agentName, agentRoot: (0, identity_1.getAgentRoot)(agentName) };
                 const liveTurnId = (0, active_turns_1.beginBlueBubblesActiveTurn)(agentName, event);
                 activeTurnId = liveTurnId;
-                const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)() ?? undefined;
+                const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)(mcpOwner) ?? undefined;
                 if (event.chat.isGroup) {
                     await (0, friends_1.upsertGroupContextParticipants)({
                         store,
@@ -1847,6 +1848,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                                     /* v8 ignore next -- default no-op signin; pipeline provides the real one @preserve */
                                     signin: async () => undefined,
                                     ...safeToolContext,
+                                    ...mcpOwner,
                                     summarize,
                                     bluebubblesReplyTarget: {
                                         setSelection: (selection) => replyTarget.setSelection(selection),
@@ -1880,7 +1882,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                             orientationFrame,
                             toolContext: {
                                 signin: async () => undefined,
-                                agentRoot: (0, identity_1.getAgentRoot)(),
+                                ...mcpOwner,
                                 currentIngressEvidence: options.currentIngressEvidence,
                             },
                         },