/** * Per-tool-call executor with the agent-loop middleware chain. * * Extracted from agent-loop.ts (PR-C, 2026-05-27) — was ~130L inlined in * the for-each-tool-call loop. Lifting it makes the chain explicit and * lets `runAgentLoop` read as the conversation loop it conceptually is. * * Middleware order (preserve Review C2 hook-ordering invariant): * 1. JSON.parse args (early return on parse error — no sanitize, no post-hooks) * 2. onToolUse callback * 3. Governance.blockedTools — early return on block (fires onToolResult) * 4. pre:tool hook — early return on cancel * 4b. state-change approval floor — deny confirmation-required ops that reach * here without explicit authorization (defense-in-depth; independent of hooks) * 5. pre:memory-write hook (save_memory only) — early return on cancel * 6. LoopGuard.check — produces error result if duplicate * 7. Execute (or capability-router fallback or unknown-tool error) * 8. evaluateExternalMemoryIngress — REVIEW C2: BEFORE onToolResult / post-hooks * 9. onToolResult callback (sanitized content) * 10. post:memory-write hook (save_memory only, sanitized) * 11. post:tool hook (sanitized) * 12. compress model-facing result (subtractive; observers keep full fidelity) * * Critical invariant (Review C2): steps 8 → 9 → 10 → 11 must stay in this * order. Canonically guarded output is what flows into both model context AND * every downstream observer (audit / telemetry / team-sync / UI). Step 12 is * subtractive-only and applies ONLY to the returned (model-facing) content — * observers at 9–11 still receive the full guarded result. */ import type { ToolDefinition } from './tools.js'; import type { HookRegistry } from './hooks.js'; import type { CapabilityRouter } from './capability-router.js'; import type { LoopGuard } from './loop-guard.js'; import { evaluateExternalMemoryIngress } from '@waggle/core'; import { isCriticalNeverAutopass, needsConfirmation } from './confirmation.js'; import { compressToolOutput } from './tool-output-compressor.js'; import { logTurnEvent } from './turn-context.js'; import { untrustedContextWrapper } from './untrusted-context.js'; const QUARANTINED_TOOL_OUTPUT = '[SECURITY] Tool output quarantined.'; /** * Never reflect rejected external content (or guard details) beyond this boundary. * The canonical ingress guard includes legacy scanning plus normalization-aware checks. */ function guardExternalToolOutput(result: string): string { return evaluateExternalMemoryIngress({ content: result }).action === 'allow' ? result : QUARANTINED_TOOL_OUTPUT; } export interface ToolExecutorDeps { toolMap: ReadonlyMap; guard: LoopGuard; hooks?: HookRegistry; capabilityRouter?: CapabilityRouter; /** Governance policy: tool names blocked at the team level */ blockedTools?: readonly string[]; /** * Defense-in-depth approval callback for CRITICAL_NEVER_AUTOPASS operations * (`isCriticalNeverAutopass`: rm -rf ~, sudo, mkfs, dd of=/dev, git push * --force main, delete_skill, connector deletes, high-risk installs). When * provided, executeToolCall calls it for any critical-destructive tool BEFORE * executing and denies on a false return. When ABSENT, executeToolCall falls * back to requiring a `pre:tool` approval gate (`hooks`) to be wired — * otherwise it fail-closes (denies). This guarantees that no spawn path * (sub-agent / workflow / worker / future) can run a terminal-destructive * command unconfirmed, regardless of whether hooks are wired. */ confirmCriticalAction?: (name: string, args: Record) => Promise | boolean; onToolUse?: (name: string, args: Record) => void; onToolResult?: (name: string, args: Record, result: string) => void; /** H-AUDIT-1: per-turn trace ID for structured event logging */ turnId?: string; } export interface ToolExecResult { /** Sanitized content to push as the tool-role message in the conversation */ content: string; /** Tool call ID for message threading */ toolCallId: string; /** * True iff the caller should append the tool name to its `toolsUsed` * array. Pre-execution rejections (parse error, governance block, hook * cancel) return false; only attempted executes (success OR thrown error * inside the tool) return true. Matches the prior inline semantics. */ countedAsUsed: boolean; /** Tool name resolved from the call (for caller's toolsUsed bookkeeping) */ toolName: string; /** * Set by the tiered loop-guard (T3-critical) when a tool has failed enough * consecutive times that continuing is futile. The agent loop must terminate * the run and surface `abortReason` as a user-facing give-up message. */ abort?: boolean; /** User-facing give-up copy — only present when `abort` is true. */ abortReason?: string; } export async function executeToolCall( toolCall: { id: string; function: { name: string; arguments: string } }, deps: ToolExecutorDeps, ): Promise { const { toolMap, guard, hooks, capabilityRouter, blockedTools, confirmCriticalAction, onToolUse, onToolResult, turnId } = deps; const fnName = toolCall.function.name; // ── Step 1: safely parse tool arguments ── let fnArgs: Record; try { fnArgs = JSON.parse(toolCall.function.arguments || '{}'); } catch { return { content: `Error: Invalid arguments for ${fnName}. The arguments were not valid JSON.`, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName, }; } // ── Step 2: onToolUse callback ── if (onToolUse) onToolUse(fnName, fnArgs); // ── Step 3: governance block — early return + fire onToolResult ── if (blockedTools?.includes(fnName)) { const policyMsg = `Tool "${fnName}" is blocked by your team's governance policy. Contact your team admin to request access, or use the request_team_capability tool to submit a request.`; if (onToolResult) onToolResult(fnName, fnArgs, policyMsg); return { content: policyMsg, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName }; } const existingTool = toolMap.get(fnName); if (!existingTool) { let result: string; if (capabilityRouter) { const routes = capabilityRouter.resolve(fnName); const routeInfo = routes .map(r => `- [${r.source}] ${r.name}: ${r.description} (${r.available ? 'available' : 'not wired yet'})`) .join('\n'); const ACQUIRE_TOOL = 'acquire_capability'; const hasMissing = routes.some(r => r.source === 'missing'); const acquireHint = hasMissing && toolMap.has(ACQUIRE_TOOL) ? `\n\nTip: Use ${ACQUIRE_TOOL} to search for installable skills that might help.` : ''; result = `Tool "${fnName}" not found. Here are alternatives:\n${routeInfo}${acquireHint}\n\nAvailable tools: ${Array.from(toolMap.keys()).join(', ')}`; } else { result = `Error: Unknown tool "${fnName}". Available tools: ${Array.from(toolMap.keys()).join(', ')}`; } result = guardExternalToolOutput(result); if (onToolResult) onToolResult(fnName, fnArgs, result); return { content: result, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName }; } // ── Step 4: pre:tool hook ── let approvedByHook = false; if (hooks) { const hookResult = await hooks.fire('pre:tool', { toolName: fnName, args: fnArgs, riskLevel: existingTool.riskLevel, }); if (hookResult.cancelled) { return { content: `[BLOCKED] ${hookResult.reason ?? 'No reason given'}`, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName, }; } approvedByHook = hookResult.authorized === true; } // ── Step 4b: state-change approval floor (defense-in-depth) ── // Every confirmation-required operation must carry an explicit authorization // across this final execution boundary. Interactive chat supplies it through // its request-local pre:tool hook; saved grants and elevated autonomy do the // same after their policy checks. Background paths without an approval // provider therefore fail closed instead of silently mutating state. const critical = isCriticalNeverAutopass(fnName, fnArgs, existingTool.riskLevel); if (critical || needsConfirmation(fnName, fnArgs, existingTool.riskLevel)) { const approvedOutOfBand = confirmCriticalAction && critical ? await confirmCriticalAction(fnName, fnArgs) : false; // Only an explicit successful hook authorization or approval callback can // cross the hard floor. Registry presence or a swallowed hook error is not // proof that a human or policy gate approved the call. if (!approvedOutOfBand && !approvedByHook) { const denyMsg = critical ? `[BLOCKED] "${fnName}" is a critical, irreversible operation that requires ` + `explicit human approval. It was denied because this execution context ` + `(such as a sub-agent or automated workflow) has no approval gate. ` + `Terminal-destructive commands never run unconfirmed.` : `[BLOCKED] "${fnName}" changes state and requires explicit approval. ` + `It was denied because this execution context (such as a sub-agent or ` + `automated workflow) did not provide an authorization decision.`; if (onToolResult) onToolResult(fnName, fnArgs, denyMsg); return { content: denyMsg, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName }; } } // ── Step 5: pre:memory-write hook (save_memory only) ── if (hooks && fnName === 'save_memory') { const memoryHookResult = await hooks.fire('pre:memory-write', { toolName: fnName, args: fnArgs, memoryContent: fnArgs.content as string | undefined, memoryType: fnArgs.type as string | undefined, }); if (memoryHookResult.cancelled) { return { content: `[BLOCKED] Memory write blocked: ${memoryHookResult.reason ?? 'No reason given'}`, toolCallId: toolCall.id, countedAsUsed: false, toolName: fnName, }; } } // ── Steps 6-7: LoopGuard check + execute / capability route / unknown ── // `result` is assigned in every branch; the empty-string init exists as a // defense against future early-continues that might slip in (the // surrounding `let` is preserved from the original Review H3 rationale). let result = ''; let countedAsUsed = false; let abort = false; let abortReason: string | undefined; const tool = toolMap.get(fnName); // Graduated failure tiers (steal #9) are consulted BEFORE the identical-args // heuristic: a critical failure streak aborts, and any tier block short- // circuits execution without advancing check()'s window/consecutive state. const tiered = guard.checkTiered(fnName, fnArgs); if (tiered.action === 'abort') { abort = true; abortReason = tiered.reason; result = tiered.reason; } else if (tiered.action === 'block') { result = tiered.reason; // A blocked attempt still counts as a failed attempt — without this the // same-tool failure tail freezes at T4's threshold (6) and T3's hard abort // (8) is unreachable: the model can hammer a broken tool forever, eating // one nudge per turn until maxTurns. guard.record(fnName, fnArgs, false); } else if (!guard.check(fnName, fnArgs)) { result = `Error: Loop detected — called ${fnName} with identical arguments too many times. Try a different approach.`; guard.record(fnName, fnArgs, false); } else if (tool) { logTurnEvent(turnId, { stage: 'agent-loop.tool.enter', toolName: fnName, argsKeys: Object.keys(fnArgs) }); try { const rawResult = await tool.execute(fnArgs); // Tools in this codebase report many failures by RETURNING an // "Error: ..." string rather than throwing — count those as failures // too, or the failure tiers never see them. guard.record(fnName, fnArgs, !/^Error\b/.test(rawResult)); result = guardExternalToolOutput(rawResult); logTurnEvent(turnId, { stage: 'agent-loop.tool.exit', toolName: fnName, resultChars: result.length, error: false }); } catch (err) { result = guardExternalToolOutput(`Error executing ${fnName}: ${(err as Error).message}`); guard.record(fnName, fnArgs, false); logTurnEvent(turnId, { stage: 'agent-loop.tool.exit', toolName: fnName, error: true, errorMessage: result }); } countedAsUsed = true; } else if (capabilityRouter) { const routes = capabilityRouter.resolve(fnName); const routeInfo = routes .map(r => `- [${r.source}] ${r.name}: ${r.description} (${r.available ? 'available' : 'not wired yet'})`) .join('\n'); const ACQUIRE_TOOL = 'acquire_capability'; const hasMissing = routes.some(r => r.source === 'missing'); const acquireHint = hasMissing && toolMap.has(ACQUIRE_TOOL) ? `\n\nTip: Use ${ACQUIRE_TOOL} to search for installable skills that might help.` : ''; result = `Tool "${fnName}" not found. Here are alternatives:\n${routeInfo}${acquireHint}\n\nAvailable tools: ${Array.from(toolMap.keys()).join(', ')}`; } else { result = `Error: Unknown tool "${fnName}". Available tools: ${Array.from(toolMap.keys()).join(', ')}`; } // ── Step 8: canonical guard BEFORE post-hooks + onToolResult (Review C2) ── // The guarded output is what flows into both model context on the next turn // AND every downstream observer (audit sinks, telemetry, team-sync, UI). // Non-allows become an opaque marker; guard details and normalized attacker // content must never cross this boundary. Order is load-bearing. result = guardExternalToolOutput(result); // ── Step 9: onToolResult callback (guarded content) ── if (onToolResult) onToolResult(fnName, fnArgs, result); // ── Step 10: post:memory-write hook (save_memory only, sanitized) ── if (hooks && fnName === 'save_memory') { await hooks.fire('post:memory-write', { toolName: fnName, args: fnArgs, result, memoryContent: fnArgs.content as string | undefined, memoryType: fnArgs.type as string | undefined, }); } // ── Step 11: post:tool hook (sanitized) ── if (hooks) { await hooks.fire('post:tool', { toolName: fnName, args: fnArgs, result }); } // ── Step 12: compress, then fence genuine tool output as untrusted data ── // Observers above (9–11) received the full sanitized result; only the content // returned into the model's next-turn context is compressed + fenced. // Order is load-bearing: compress FIRST (subtractive — could otherwise truncate // the closing marker), then wrap. We fence ONLY actual tool-execution output // (`countedAsUsed`), including a thrown tool's error string (it can echo // attacker-controlled bytes from a malicious tool/MCP server). First-party // orchestration messages (loop-guard, capability-router recovery guidance, // unknown-tool) are NOT fenced — they are trusted guidance the model SHOULD act // on, and fencing them as "do not obey" would defeat recovery. §C / untrusted-context.ts. const compressed = compressToolOutput(result); const modelFacing = countedAsUsed ? untrustedContextWrapper(fnName, compressed) : compressed; return { content: modelFacing, toolCallId: toolCall.id, countedAsUsed, toolName: fnName, abort, abortReason }; }