@sunshinelife83/hearth 1.0.0

package/dist/task-tools.js

@@ -0,0 +1,455 @@
+import * as z from "zod/v4";
+import { TaskTransitionError } from "./task-store.js";
+import { detectVerificationGates, tailOutput } from "./verification.js";
+import { classifyCommand, decideExecution } from "./policy/command-policy.js";
+import { commandListVerdict, resolveExecutionForWorkspace } from "./policy/workspace-profiles.js";
+import { logEvent, commandPreview } from "./logger.js";
+import { logToolCall, resultOutputSchema, sandboxDecision, textBlock } from "./tool-surfaces/shared.js";
+import { workspaceIdDescription } from "./tool-surfaces/types.js";
+/**
+ * Task tools: the Agent Runtime's MCP surface. The driving AI client moves a
+ * durable task through plan → execute → verify → repair; completion is a
+ * system verdict (verified_complete), never just a model claim.
+ */
+const DEFAULT_TASK_BUDGET_MS = 30 * 60 * 1000;
+const GATE_POLL_MS = 30_000;
+const MAX_GATE_WALL_MS = 10 * 60 * 1000;
+/** Repair loops are bounded: after this many failed verify rounds the task fails instead of repairing forever. */
+const MAX_REPAIR_CYCLES = 5;
+export function registerTaskTools(target, context) {
+    const { config, workspaces, processSessions, taskStore } = context;
+    const taskOutputSchema = resultOutputSchema({
+        taskId: z.string(),
+        status: z.string(),
+        completionState: z.string().optional(),
+    });
+    const evidenceLines = (entries, limit = 8) => entries.slice(-limit).map((entry) => `- [${entry.kind}] ${entry.summary}`).join("\n");
+    const taskText = (record, extra) => {
+        const lines = [
+            `Task ${record.id} — ${record.status}${record.completionState ? ` (${record.completionState})` : ""}.`,
+            `Goal: ${record.goal}`,
+            record.plan?.length ? `Plan:\n${record.plan.map((step, index) => `${index + 1}. ${step}`).join("\n")}` : undefined,
+            record.error ? `Error: ${record.error}` : undefined,
+            record.evidence.length > 0 ? `Evidence:\n${evidenceLines(record.evidence)}` : undefined,
+            extra,
+        ].filter(Boolean);
+        return lines.join("\n\n");
+    };
+    const structuredTask = (record) => ({
+        result: taskText(record),
+        taskId: record.id,
+        status: record.status,
+        ...(record.completionState ? { completionState: record.completionState } : {}),
+    });
+    const assertBudget = (taskId) => {
+        const record = taskStore.get(taskId);
+        if (!record)
+            throw new Error(`Unknown task: ${taskId}`);
+        const age = Date.now() - Date.parse(record.createdAt);
+        if (age > DEFAULT_TASK_BUDGET_MS) {
+            taskStore.transition(taskId, "failed", {
+                error: `Task budget exceeded (${Math.round(age / 60000)} minutes).`,
+            });
+            throw new Error(`Task ${taskId} exceeded its wall-clock budget and was marked failed.`);
+        }
+    };
+    /** Run one gate command under the policy gate, waiting for completion. */
+    const runGate = async (workspaceId, cwd, gate) => {
+        const startedAt = performance.now();
+        const resolved = resolveExecutionForWorkspace(config, cwd);
+        const classification = classifyCommand(gate.command);
+        // Workspace command lists apply to verification gates too: a denied gate
+        // command fails closed rather than running outside the profile.
+        const listVerdict = commandListVerdict(resolved, gate.command);
+        if (!listVerdict.allowed) {
+            return {
+                name: gate.name,
+                command: gate.command,
+                kind: gate.kind,
+                passed: false,
+                outputTail: `Blocked by workspace policy: ${listVerdict.rule}`,
+                durationMs: Math.round(performance.now() - startedAt),
+            };
+        }
+        const decision = decideExecution({ mode: resolved.mode, tier: classification.tier });
+        logEvent(config.logging, decision.decision === "allow" ? "info" : "warn", "policy_decision", {
+            tool: "task_verify",
+            workspaceId,
+            tier: classification.tier,
+            rules: classification.rules,
+            decision: decision.decision,
+            mode: resolved.mode,
+            commandPreview: commandPreview(gate.command),
+        });
+        if (decision.decision !== "allow") {
+            return {
+                name: gate.name,
+                command: gate.command,
+                kind: gate.kind,
+                passed: false,
+                outputTail: `Policy ${decision.decision}: ${decision.reason}`,
+                durationMs: Math.round(performance.now() - startedAt),
+            };
+        }
+        let snapshot = await processSessions.start({
+            workspaceId,
+            command: gate.command,
+            cwd,
+            workspaceRoot: cwd,
+            sandbox: sandboxDecision(config, classification.tier, cwd).enabled,
+            yieldTimeMs: GATE_POLL_MS,
+            maxOutputTokens: 4000,
+        });
+        const deadline = Date.now() + MAX_GATE_WALL_MS;
+        while (snapshot.running && Date.now() < deadline) {
+            snapshot = await processSessions.write({
+                workspaceId,
+                sessionId: snapshot.sessionId,
+                chars: "",
+                yieldTimeMs: GATE_POLL_MS,
+                maxOutputTokens: 4000,
+            });
+        }
+        const failedToFinish = snapshot.running;
+        if (failedToFinish) {
+            processSessions.terminate(workspaceId, snapshot.sessionId);
+        }
+        return {
+            name: gate.name,
+            command: gate.command,
+            kind: gate.kind,
+            exitCode: snapshot.exitCode,
+            signal: snapshot.signal,
+            passed: !failedToFinish && snapshot.exitCode === 0,
+            outputTail: tailOutput(snapshot.output || (failedToFinish ? "gate timed out and was terminated" : "")),
+            durationMs: Math.round(performance.now() - startedAt),
+        };
+    };
+    const runVerification = async (input) => {
+        const gates = input.explicitGates?.length
+            ? input.explicitGates
+            : detectVerificationGates(input.workspaceRoot);
+        const results = [];
+        for (const gate of gates) {
+            const result = await runGate(input.workspaceId, input.workspaceRoot, gate);
+            results.push(result);
+            taskStore.appendEvidence(input.taskId, {
+                ts: new Date().toISOString(),
+                kind: "verification",
+                summary: `gate ${result.name}: ${result.passed ? "passed" : "FAILED"} (exit ${result.exitCode ?? "signal"})`,
+                details: { command: result.command, outputTail: result.outputTail },
+            });
+        }
+        return { passed: results.length > 0 && results.every((result) => result.passed), gates: results };
+    };
+    const failuresOf = (result) => result.gates.filter((gate) => !gate.passed)
+        .map((gate) => ({ gate: gate.name, exitCode: gate.exitCode, outputTail: gate.outputTail }));
+    /** Repair loops are bounded: count prior verify→repairing moves from evidence. */
+    const repairCyclesUsed = (taskId) => {
+        const record = taskStore.get(taskId);
+        if (!record)
+            return 0;
+        return record.evidence.filter((entry) => entry.kind === "note" && entry.summary.includes("verifying → repairing")).length;
+    };
+    const workspaceOf = (workspaceId) => workspaces.getWorkspace(workspaceId);
+    /**
+     * Anti-bypass rule: once a gate has failed for a task it stays in the
+     * verification set until it passes, so a completion claim can never
+     * satisfy itself with a narrower or easier gate list.
+     */
+    function mergeWithPreviouslyFailedGates(current, explicit) {
+        const failed = new Map();
+        for (const entry of current.evidence) {
+            if (entry.kind !== "verification" || !entry.summary.includes("FAILED"))
+                continue;
+            const details = entry.details;
+            const command = details?.command;
+            const name = entry.summary.slice("gate ".length).split(":")[0]?.trim();
+            if (command && name)
+                failed.set(command, { name, command });
+        }
+        if (failed.size === 0)
+            return explicit;
+        const merged = new Map(failed);
+        for (const gate of explicit ?? [])
+            merged.set(gate.command, gate);
+        return [...merged.values()];
+    }
+    target.registerTool("task_create", {
+        title: "Create task",
+        description: "Create a durable engineering task for this workspace with a goal contract. The task state machine (planning → executing → verifying → repair → completed) is the system's source of truth; completion requires verification evidence, not just a model claim.",
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            goal: z.string().min(1).max(8000).describe("What must be true when this task is done."),
+        },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ workspaceId, goal }) => {
+        const workspace = workspaceOf(workspaceId);
+        const resolved = resolveExecutionForWorkspace(config, workspace.root);
+        const record = taskStore.create({
+            workspaceId,
+            workspaceRoot: workspace.root,
+            goal,
+            mode: resolved.mode,
+        });
+        logToolCall(config, { tool: "task_create", workspaceId, success: true, durationMs: 0 });
+        return {
+            content: [textBlock(taskText(record))],
+            structuredContent: structuredTask(record),
+        };
+    });
+    target.registerTool("task_plan", {
+        title: "Set task plan",
+        description: "Record the execution plan for a planning-stage task and move it to executing. One concrete step per entry, in order.",
+        inputSchema: {
+            taskId: z.string().min(1),
+            steps: z.array(z.string().min(1)).min(1).max(50).describe("Ordered plan steps."),
+        },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ taskId, steps }) => {
+        assertBudget(taskId);
+        const record = taskStore.transition(taskId, "executing", { plan: steps });
+        logToolCall(config, { tool: "task_plan", success: true, durationMs: 0 });
+        return {
+            content: [textBlock(taskText(record))],
+            structuredContent: structuredTask(record),
+        };
+    });
+    target.registerTool("task_status", {
+        title: "Task status",
+        description: "Fetch a task's state machine status, plan, and evidence trail.",
+        inputSchema: { taskId: z.string().min(1) },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: true },
+    }, async ({ taskId }) => {
+        const record = taskStore.get(taskId);
+        if (!record)
+            return taskNotFound(taskId);
+        return {
+            content: [textBlock(taskText(record))],
+            structuredContent: structuredTask(record),
+        };
+    });
+    target.registerTool("task_list", {
+        title: "List tasks",
+        description: "List tasks recorded for this workspace.",
+        inputSchema: { workspaceId: z.string().describe(workspaceIdDescription) },
+        outputSchema: resultOutputSchema(),
+        annotations: { readOnlyHint: true },
+    }, async ({ workspaceId }) => {
+        workspaceOf(workspaceId);
+        const records = taskStore.list({ workspaceId });
+        const lines = records.length > 0
+            ? records.map((record) => `${record.id}  ${record.status}${record.completionState ? ` (${record.completionState})` : ""}  ${record.goal.split("\n")[0]?.slice(0, 100)}`).join("\n")
+            : "No tasks for this workspace yet.";
+        return {
+            content: [textBlock(lines)],
+            structuredContent: {
+                result: lines,
+                tasks: records.map((record) => ({ taskId: record.id, status: record.status })),
+            },
+        };
+    });
+    target.registerTool("task_verify", {
+        title: "Verify task",
+        description: "Run the workspace's verification gates (tests, typecheck, build — auto-detected or explicit) and record the evidence. Passing gates move the task toward completion; failures move it to repairing with the failing output.",
+        inputSchema: {
+            taskId: z.string().min(1),
+            gates: z.array(z.object({
+                name: z.string().min(1),
+                command: z.string().min(1),
+            })).max(10).optional().describe("Explicit gates; defaults to auto-detected ones."),
+        },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ taskId, gates }) => {
+        assertBudget(taskId);
+        const current = taskStore.get(taskId);
+        if (!current)
+            return taskNotFound(taskId);
+        let record;
+        try {
+            record = taskStore.transition(taskId, "verifying");
+        }
+        catch (error) {
+            return transitionError(error, taskId);
+        }
+        void record;
+        const verification = await runVerification({
+            workspaceId: current.workspaceId ?? "",
+            workspaceRoot: current.workspaceRoot,
+            taskId,
+            explicitGates: mergeWithPreviouslyFailedGates(current, gates)?.map((gate) => ({ ...gate, kind: "custom" })),
+        });
+        taskStore.countToolCall(taskId);
+        if (!verification.passed) {
+            const failures = failuresOf(verification);
+            if (repairCyclesUsed(taskId) >= MAX_REPAIR_CYCLES) {
+                const failed = taskStore.transition(taskId, "failed", {
+                    error: `Repair budget exhausted after ${MAX_REPAIR_CYCLES} failed verification rounds: ${failures.map((failure) => failure.gate).join(", ")}. Inspect evidence and create a new task.`,
+                });
+                const extra = `Repair budget exhausted (${MAX_REPAIR_CYCLES} rounds). Task marked failed — no more automatic repair loops.\n${failures.map((failure) => `— ${failure.gate} (exit ${failure.exitCode ?? "?"})\n${failure.outputTail}`).join("\n\n")}`;
+                return {
+                    content: [textBlock(taskText(failed, extra))],
+                    structuredContent: { ...structuredTask(failed), result: taskText(failed, extra) },
+                };
+            }
+            const failed = taskStore.transition(taskId, "repairing", {
+                error: `Verification failed: ${failures.map((failure) => failure.gate).join(", ")}`,
+            });
+            const extra = `Verification FAILED. Fix the failures, then call task_verify again.\n${failures.map((failure) => `— ${failure.gate} (exit ${failure.exitCode ?? "?"})\n${failure.outputTail}`).join("\n\n")}`;
+            return {
+                content: [textBlock(taskText(failed, extra))],
+                structuredContent: { ...structuredTask(failed), result: taskText(failed, extra) },
+            };
+        }
+        const completed = taskStore.transition(taskId, "completed", { completionState: "verified_complete" });
+        return {
+            content: [textBlock(taskText(completed, "System verified: all gates passed."))],
+            structuredContent: structuredTask(completed),
+        };
+    });
+    target.registerTool("task_complete", {
+        title: "Complete task",
+        description: "Claim a task complete. The claim alone is never trusted: verification gates run first and only a passing run marks the task verified_complete. With no detected gates, pass acceptUnverified to explicitly record a model_complete verdict (audited as unverified).",
+        inputSchema: {
+            taskId: z.string().min(1),
+            acceptUnverified: z
+                .boolean()
+                .optional()
+                .describe("Explicitly mark the task model_complete when no verification gates exist."),
+        },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ taskId, acceptUnverified }) => {
+        assertBudget(taskId);
+        const current = taskStore.get(taskId);
+        if (!current)
+            return taskNotFound(taskId);
+        if (current.status === "planning") {
+            return {
+                content: [textBlock(`Task ${taskId} is still planning. Provide a plan (task_plan) and do the work before completing.`)],
+                isError: true,
+                structuredContent: { result: `Task ${taskId} is still planning.`, taskId, status: current.status },
+            };
+        }
+        if (current.status === "repairing") {
+            // Failed-gate evidence exists; a fresh claim must not swap in an
+            // easier gate set. The failing gates themselves must pass again.
+            return {
+                content: [textBlock(`Task ${taskId} is in repairing: earlier verification gates failed. ` +
+                        `Repair the failures and call task_verify (it re-runs the failing gates); completion claims are rejected until they pass.`)],
+                isError: true,
+                structuredContent: { result: `Task ${taskId} is in repairing; use task_verify.`, taskId, status: current.status },
+            };
+        }
+        const detected = detectVerificationGates(current.workspaceRoot);
+        if (detected.length === 0 && acceptUnverified !== true) {
+            return {
+                content: [textBlock(`No verification gates were detected for this workspace, so the claim cannot be verified. ` +
+                        `Run explicit gates via task_verify with a gates list, or pass acceptUnverified=true to record an explicitly unverified (model_complete) verdict.`)],
+                isError: true,
+                structuredContent: { result: "No verification gates available.", taskId, status: current.status },
+            };
+        }
+        try {
+            taskStore.transition(taskId, "verifying");
+        }
+        catch (error) {
+            return transitionError(error, taskId);
+        }
+        taskStore.appendEvidence(taskId, {
+            ts: new Date().toISOString(),
+            kind: "model_claim",
+            summary: "model claimed completion",
+        });
+        if (detected.length === 0) {
+            const completed = taskStore.transition(taskId, "completed", { completionState: "model_complete" });
+            return {
+                content: [textBlock(taskText(completed, "Marked model_complete (explicitly unverified — no gates were available)."))],
+                structuredContent: structuredTask(completed),
+            };
+        }
+        const verification = await runVerification({
+            workspaceId: current.workspaceId ?? "",
+            workspaceRoot: current.workspaceRoot,
+            taskId,
+        });
+        taskStore.countToolCall(taskId);
+        if (!verification.passed) {
+            const failures = failuresOf(verification);
+            const failed = taskStore.transition(taskId, "repairing", {
+                error: `Verification failed: ${failures.map((failure) => failure.gate).join(", ")}`,
+            });
+            const extra = `Completion rejected: gates failed. Repair, then task_verify.\n${failures.map((failure) => `— ${failure.gate} (exit ${failure.exitCode ?? "?"})\n${failure.outputTail}`).join("\n\n")}`;
+            return {
+                content: [textBlock(taskText(failed, extra))],
+                structuredContent: { ...structuredTask(failed), result: taskText(failed, extra) },
+            };
+        }
+        const completed = taskStore.transition(taskId, "completed", { completionState: "verified_complete" });
+        return {
+            content: [textBlock(taskText(completed, "System verified: all gates passed."))],
+            structuredContent: structuredTask(completed),
+        };
+    });
+    target.registerTool("task_cancel", {
+        title: "Cancel task",
+        description: "Cancel an unfinished task (terminal).",
+        inputSchema: { taskId: z.string().min(1) },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ taskId }) => {
+        const record = taskStore.get(taskId);
+        if (!record)
+            return taskNotFound(taskId);
+        try {
+            const cancelled = taskStore.transition(taskId, "cancelled", { error: "Cancelled by client." });
+            return { content: [textBlock(taskText(cancelled))], structuredContent: structuredTask(cancelled) };
+        }
+        catch (error) {
+            return transitionError(error, taskId);
+        }
+    });
+    target.registerTool("task_resume", {
+        title: "Resume task",
+        description: "Resume a failed task (crash recovery, repair-budget exhaustion) back to planning. Completed/cancelled tasks are terminal; in-flight tasks use the normal transitions.",
+        inputSchema: {
+            taskId: z.string().min(1),
+            reason: z.string().max(500).optional(),
+        },
+        outputSchema: taskOutputSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ taskId, reason }) => {
+        const record = taskStore.get(taskId);
+        if (!record)
+            return taskNotFound(taskId);
+        try {
+            const resumed = taskStore.replan(taskId, reason ?? "Resumed by client.");
+            logToolCall(config, { tool: "task_resume", success: true, durationMs: 0 });
+            return { content: [textBlock(taskText(resumed))], structuredContent: structuredTask(resumed) };
+        }
+        catch (error) {
+            return transitionError(error, taskId);
+        }
+    });
+    function taskNotFound(taskId) {
+        return {
+            content: [textBlock(`Unknown task: ${taskId}`)],
+            isError: true,
+            structuredContent: { result: `Unknown task: ${taskId}` },
+        };
+    }
+    function transitionError(error, taskId) {
+        if (error instanceof TaskTransitionError) {
+            return {
+                content: [textBlock(`${error.message}. Use task_status to see the current state.`)],
+                isError: true,
+                structuredContent: { result: error.message, taskId },
+            };
+        }
+        throw error;
+    }
+}

package/dist/tool-surfaces/claude.js

@@ -0,0 +1,220 @@
+import * as z from "zod/v4";
+import { editFileTool, writeFileTool, } from "../pi-tools.js";
+import { EDIT_TOOL_ANNOTATIONS, SHELL_TOOL_ANNOTATIONS, WRITE_TOOL_ANNOTATIONS, toolNames, workspaceIdDescription, } from "./types.js";
+import { contentText, countDiffStats, enforceShellPolicy, logFailedToolResponse, logToolCall, resultOutputSchema, sandboxDecision, snapshotBeforeRiskyExecution, textBlock, } from "./shared.js";
+const CLAUDE_INSTRUCTIONS = `Use ${toolNames.read} for direct file reads, ${toolNames.edit} for targeted modifications, ${toolNames.write} only for new files or complete rewrites, and ${toolNames.shell} for inspection, tests, builds, and other commands. Shell commands run with the local user's authority and are not sandboxed; workspace validation only selects their initial working directory. Command policy: inspection and ordinary workspace work (builds, tests, local edits) run freely; commands with effects outside the workspace (network fetches, package installs, recursive deletes, git push, permission changes) require explicit user approval in the conversation and the approvedByUser flag; privilege escalation, system management, and piping remote scripts into a shell are always blocked. Follow instructions returned by ${toolNames.openWorkspace}; read applicable instruction and skill files before working in their scope.`;
+export function claudeInstructions({ agents, skills, }) {
+    return `${agents}${skills}${CLAUDE_INSTRUCTIONS}`;
+}
+export function registerClaudeTools(context) {
+    registerClaudeMutationTools(context);
+    registerShellTool(context);
+}
+const CLAUDE_SHELL_DESCRIPTION = `Run a shell command with the local user's authority. Commands are not sandboxed; workspace validation only selects the initial working directory. Use this for file inspection, tests, builds, package scripts, and other commands.`;
+function registerClaudeMutationTools(context) {
+    const { server, config, workspaces } = context;
+    server.registerTool(toolNames.write, {
+        title: "Write file",
+        description: `Create or completely overwrite a file in a workspace. Prefer ${toolNames.edit} for targeted changes to existing files.`,
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            path: z
+                .string()
+                .describe("File path to write, relative to the workspace root."),
+            content: z.string().describe("Complete new file content."),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: WRITE_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, ...input }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        workspaces.resolvePath(workspace, input.path);
+        const response = await writeFileTool(input, {
+            cwd: workspace.root,
+            root: workspace.root,
+        });
+        if (response.isError) {
+            logFailedToolResponse(config, {
+                tool: toolNames.write,
+                workspaceId,
+                path: input.path,
+            }, response.content, startedAt);
+            return response;
+        }
+        logToolCall(config, {
+            tool: toolNames.write,
+            workspaceId,
+            path: input.path,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            ...response,
+            structuredContent: {
+                result: contentText(response.content),
+            },
+        };
+    });
+    server.registerTool(toolNames.edit, {
+        title: "Edit file",
+        description: `Edit one file in a workspace by replacing exact text blocks. Prefer this over ${toolNames.write} for targeted changes. Each oldText must match a unique, non-overlapping region of the original file; merge nearby changes into one edit and keep oldText as small as possible while still unique.`,
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            path: z
+                .string()
+                .describe("File path to edit, relative to the workspace root."),
+            edits: z
+                .array(z.object({
+                oldText: z
+                    .string()
+                    .describe("Exact text to replace. Must match uniquely in the original file."),
+                newText: z.string().describe("Replacement text."),
+            }))
+                .min(1),
+        },
+        outputSchema: resultOutputSchema({
+            status: z.literal("applied"),
+        }),
+        annotations: EDIT_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, ...input }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        workspaces.resolvePath(workspace, input.path);
+        const response = await editFileTool(input, {
+            cwd: workspace.root,
+            root: workspace.root,
+        });
+        if (response.isError) {
+            logFailedToolResponse(config, {
+                tool: toolNames.edit,
+                workspaceId,
+                path: input.path,
+            }, response.content, startedAt);
+            return response;
+        }
+        const stats = countDiffStats(response.details?.patch ?? response.details?.diff);
+        const editResultText = `Edited ${input.path} (+${stats.additions} -${stats.removals}).`;
+        const editContent = [textBlock(editResultText)];
+        logToolCall(config, {
+            tool: toolNames.edit,
+            workspaceId,
+            path: input.path,
+            success: true,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: editContent,
+            structuredContent: {
+                status: "applied",
+                result: contentText(editContent),
+            },
+        };
+    });
+}
+function registerShellTool(context) {
+    const { server, config, workspaces, processSessions } = context;
+    server.registerTool(toolNames.shell, {
+        title: "Bash",
+        description: CLAUDE_SHELL_DESCRIPTION,
+        inputSchema: {
+            workspaceId: z.string().describe(workspaceIdDescription),
+            command: z
+                .string()
+                .describe("Shell command to execute."),
+            workingDirectory: z
+                .string()
+                .optional()
+                .describe("Optional working directory relative to the workspace root. Defaults to the workspace root."),
+            timeout: z
+                .number()
+                .positive()
+                .max(300)
+                .optional()
+                .describe("Timeout in seconds. Defaults to 30, max 300."),
+            approvedByUser: z
+                .boolean()
+                .optional()
+                .describe("Set to true only after the user explicitly approved this exact command in the conversation. Required for tier-2 commands (network, installs, recursive deletes, pushes) unless the workspace runs in autonomous mode."),
+        },
+        outputSchema: resultOutputSchema(),
+        annotations: SHELL_TOOL_ANNOTATIONS,
+    }, async ({ workspaceId, workingDirectory, approvedByUser, ...input }) => {
+        const startedAt = performance.now();
+        const workspace = workspaces.getWorkspace(workspaceId);
+        const verdict = enforceShellPolicy(config, { tool: toolNames.shell, workspaceId, command: input.command, workspaceRoot: workspace.root }, approvedByUser);
+        if (verdict.denial) {
+            logFailedToolResponse(config, {
+                tool: toolNames.shell,
+                workspaceId,
+                workingDirectory: workingDirectory ?? ".",
+                command: input.command,
+                commandLength: input.command.length,
+            }, verdict.denial.content, startedAt);
+            return verdict.denial;
+        }
+        const sandbox = sandboxDecision(config, verdict.classification.tier, workspace.root);
+        if (sandbox.denialReason) {
+            logFailedToolResponse(config, {
+                tool: toolNames.shell,
+                workspaceId,
+                workingDirectory: workingDirectory ?? ".",
+                command: input.command,
+                commandLength: input.command.length,
+            }, [textBlock(sandbox.denialReason)], startedAt);
+            return {
+                content: [textBlock(sandbox.denialReason)],
+                isError: true,
+                structuredContent: { result: sandbox.denialReason },
+            };
+        }
+        const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+        await snapshotBeforeRiskyExecution(config, workspace, input.command);
+        // Security boundary: bash executes through the same process manager as
+        // every other shell tool — policy gate above, environment allowlist,
+        // OS-sandbox wrapper, and process journal all apply. The former Pi
+        // spawn path (which bypassed the sandbox wrapper) is gone.
+        const timeoutSeconds = Math.min(input.timeout ?? 30, 300);
+        let snapshot = await processSessions.start({
+            workspaceId,
+            command: input.command,
+            cwd,
+            workspaceRoot: workspace.root,
+            sandbox: sandbox.enabled,
+            yieldTimeMs: timeoutSeconds * 1000,
+            maxOutputTokens: 10_000,
+        });
+        let timedOut = false;
+        if (snapshot.running) {
+            timedOut = true;
+            processSessions.terminate(workspaceId, snapshot.sessionId);
+            snapshot = await processSessions.write({
+                workspaceId,
+                sessionId: snapshot.sessionId,
+                chars: "",
+                yieldTimeMs: 5_000,
+                maxOutputTokens: 10_000,
+            });
+        }
+        const statusLine = timedOut
+            ? `Command timed out after ${timeoutSeconds}s and was terminated.`
+            : snapshot.signal
+                ? `Process exited after signal ${snapshot.signal}.`
+                : `Process exited with code ${snapshot.exitCode ?? "unknown"}.`;
+        const result = snapshot.output
+            ? `${snapshot.output.replace(/\n$/, "")}\n${statusLine}`
+            : statusLine;
+        logToolCall(config, {
+            tool: toolNames.shell,
+            workspaceId,
+            workingDirectory: workingDirectory ?? ".",
+            command: input.command,
+            commandLength: input.command.length,
+            success: !timedOut && snapshot.exitCode === 0,
+            durationMs: Math.round(performance.now() - startedAt),
+        });
+        return {
+            content: [textBlock(result)],
+            structuredContent: { result },
+        };
+    });
+}