feat(tools): propagate timeout abort signals to tool execution

docs/api/TOOLS.md

@@ -57,8 +57,12 @@ export interface Tool {
   /** Secret scopes required to execute this tool (optional). */
   requiredSecretScopes?: string[];
 
-  /** Async function that executes the tool. */
-  execute: (args: unknown) => Promise<ToolResult>;
+  /** Optional execution context (abort signal, runtime metadata). */
+  execute: (args: unknown, context?: ToolExecutionContext) => Promise<ToolResult>;
+}
+
+export interface ToolExecutionContext {
+  signal?: AbortSignal;
 }
 ```
 

docs/architecture/CONTRIBUTOR_MAP.md

@@ -59,7 +59,7 @@ export const myTool: Tool = {
     },
     required: ['foo'],
   },
-  execute: async (rawArgs: unknown): Promise<ToolResult> => {
+  execute: async (rawArgs: unknown, _context?: { signal?: AbortSignal }): Promise<ToolResult> => {
     // ...
     return { success: true, output: 'ok' };
   },

docs/plans/analysis/2026-02-16-codebase-audit-report.md

@@ -16,6 +16,7 @@ Scope: Production-risk-first audit of bugs, code improvements, and feature oppor
 - ✅ F-008 addressed: WhatsApp Chromium launch is now sandboxed by default; no-sandbox mode is behind explicit `whatsapp.no_sandbox: true` opt-in.
 - ✅ F-014 addressed: `ModelRouter.setOnTierChange` now preserves existing listeners instead of replacing them, removing destructive listener-setter behavior.
 - ✅ F-002 addressed: `config.patch` now supports durable persistence via atomic write + backup when daemon has a concrete config path, and response includes `persisted`/`persistError` so UI can distinguish runtime-only vs disk-persisted updates.
+- ◑ F-003 partially addressed: tool execution now has an `AbortSignal` contract and executor triggers abort on timeout; host `shell.exec` and sandbox docker exec now respond to cancellation. Additional high-risk tools still need explicit cancellation coverage for full closure.
 
 ## Executive Summary
 

docs/plans/state.json

@@ -2547,6 +2547,24 @@
         "docs/plans/analysis/2026-02-16-codebase-audit-report.md"
       ],
       "test_status": "pnpm test:run src/gateway/handlers/handlers.test.ts src/config/persistence.test.ts + pnpm typecheck passing"
+    },
+    "audit-followup-tool-timeout-cancellation-contract": {
+      "status": "in_progress",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Started timeout-cancellation hardening: added ToolExecutionContext AbortSignal contract, executor abort-on-timeout propagation, and cancellation-aware shell execution for host and sandbox docker exec paths. Remaining work: migrate additional high-risk tools and add post-timeout side-effect regression coverage.",
+      "files_modified": [
+        "src/tools/types.ts",
+        "src/tools/executor.ts",
+        "src/tools/executor.test.ts",
+        "src/tools/builtin/shell.ts",
+        "src/sandbox/docker.ts",
+        "src/sandbox/tools.ts",
+        "docs/api/TOOLS.md",
+        "docs/architecture/CONTRIBUTOR_MAP.md",
+        "docs/plans/analysis/2026-02-16-codebase-audit-report.md"
+      ],
+      "test_status": "pnpm test:run src/tools/executor.test.ts src/tools/builtin/shell.test.ts + pnpm typecheck passing"
     }
   },
   "overall_progress": {