@kushalkhemka/opensec-pi-subagents 0.19.8 → 0.19.10

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.10] - 2026-10-07
+
+### Fixed
+
+- **A hung tool call held a subagent forever.** Turn limits only count finished turns, and a turn whose tool never returns (a `find /`, a server that never exits) never finishes, so `max_turns` and the grace turns could not stop it. Subagent `bash` calls now get a timeout (the new `toolTimeoutSeconds` setting, default 1200 s, `0` = off): Pi kills the command's whole process tree and the agent sees the timeout and carries on. Any other tool still running a minute past the limit is stopped by a watchdog and the agent is resumed with a note to split the work into bounded steps, up to 3 times per run (nested `Agent` / workflow calls are exempt). Resumed agents get the same protection.
+
+## [0.19.9] - 2026-10-03
+
+### Fixed
+
+- **No load warning on Pi 1.0.** `@sinclair/typebox` and `typebox` were listed in `dependencies`, which Pi 1.0 reports as host-provided packages that can bypass its extension loader. They are now optional `"*"` peer dependencies (Pi supplies both on 0.87.1 and 1.0) and stay devDependencies for tests and typecheck.
+
+### Changed
+
+- The development pins of `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` move from 0.84.2 to 1.0.0, so `npm test` and `prepublishOnly` run the e2e tests that need Pi 1.0 APIs.
+
 ## [0.19.8] - 2026-10-03
 
 The Node build now carries the same fixes as the Bun build (0.19.5-bun.x).

package/README.md

@@ -82,6 +82,7 @@ model and thinking level unless their definition or call overrides them.
 | Setting | Default | Meaning |
 |---|---|---|
 | Background concurrency (`/agents → Settings`) | `10` | How many background agents run at once. |
+| Tool timeout (`/agents → Settings`, `toolTimeoutSeconds`) | `1200` | Seconds one subagent tool call may run (`0` = no limit). A `bash` call is killed at the limit and the agent sees the timeout; any other tool still running a minute later is stopped and the agent is told to continue another way (up to 3 times per run). |
 
 ## Notes
 

package/dist/agent-runner.d.ts

@@ -157,6 +157,31 @@ export declare function setRememberAgents(b: boolean): void;
 export declare function getGraceTurns(): number;
 /** Set the grace turns value (minimum 1). */
 export declare function setGraceTurns(n: number): void;
+export declare const TOOL_TIMEOUT_CEILING = 86400;
+/** Get the per-tool-call time limit in seconds (0 = no limit). */
+export declare function getToolTimeoutSeconds(): number;
+/** Set the per-tool-call time limit in seconds (0 = no limit). */
+export declare function setToolTimeoutSeconds(n: number): void;
+/** Times one run is resumed after a stuck tool before it is left stopped. */
+export declare const MAX_TOOL_RECOVERIES = 3;
+export interface HungTool {
+    toolName: string;
+    seconds: number;
+}
+/** The prompt that resumes an agent whose tool call the watchdog stopped. */
+export declare function hungToolPrompt(hung: HungTool): string;
+/**
+ * Bound a subagent session's tool calls (see `toolTimeoutSeconds`).
+ *
+ * `bash` calls without a timeout, or with a longer one, get the limit. The
+ * watchdog covers every tool: past the limit (plus slack) it aborts the run,
+ * which kills a running command's process tree, and `takeHung()` then reports
+ * the call so the caller can resume the agent with `hungToolPrompt()`.
+ */
+export declare function installToolTimeouts(session: AgentSession, limitSeconds?: number): {
+    takeHung(): HungTool | undefined;
+    dispose(): void;
+};
 /**
  * Try to find the right model for an agent type.
  * Priority: explicit option > config.model > parent model.

package/dist/agent-runner.js

@@ -348,6 +348,101 @@ let graceTurns = 5;
 export function getGraceTurns() { return graceTurns; }
 /** Set the grace turns value (minimum 1). */
 export function setGraceTurns(n) { graceTurns = Math.max(1, n); }
+/**
+ * Longest a single tool call may run, in seconds. 0 = no limit.
+ *
+ * Turn limits only count finished turns, and a turn whose tool never returns
+ * never finishes: a `find /` or a server that never closes would hold the agent
+ * forever. So a subagent's `bash` calls get this as their timeout (pi kills the
+ * whole process tree and reports the timeout to the model, which carries on),
+ * and a watchdog stops any other tool that overruns it and tells the agent to
+ * continue another way.
+ */
+let toolTimeoutSeconds = 1200;
+export const TOOL_TIMEOUT_CEILING = 86_400;
+/** Get the per-tool-call time limit in seconds (0 = no limit). */
+export function getToolTimeoutSeconds() { return toolTimeoutSeconds; }
+/** Set the per-tool-call time limit in seconds (0 = no limit). */
+export function setToolTimeoutSeconds(n) {
+    toolTimeoutSeconds = Math.min(TOOL_TIMEOUT_CEILING, Math.max(0, Math.floor(n)));
+}
+/** How long past the limit the watchdog waits, so a timing-out `bash` reports its own timeout first. */
+const WATCHDOG_SLACK_MS = 60_000;
+const WATCHDOG_INTERVAL_MS = 5_000;
+/** Times one run is resumed after a stuck tool before it is left stopped. */
+export const MAX_TOOL_RECOVERIES = 3;
+const WATCHDOG_EXEMPT_TOOLS = new Set(EXCLUDED_TOOL_NAMES);
+function formatDuration(seconds) {
+    if (seconds < 120)
+        return `${seconds} seconds`;
+    return `${Math.round(seconds / 60)} minutes`;
+}
+/** The prompt that resumes an agent whose tool call the watchdog stopped. */
+export function hungToolPrompt(hung) {
+    return `Your ${hung.toolName} call ran for ${formatDuration(hung.seconds)} without finishing, so it was stopped and its `
+        + "output is lost. Continue the task without repeating that call: split the work into smaller, bounded steps "
+        + "(search specific folders rather than the whole filesystem, limit depth and output, add timeouts).";
+}
+/**
+ * Bound a subagent session's tool calls (see `toolTimeoutSeconds`).
+ *
+ * `bash` calls without a timeout, or with a longer one, get the limit. The
+ * watchdog covers every tool: past the limit (plus slack) it aborts the run,
+ * which kills a running command's process tree, and `takeHung()` then reports
+ * the call so the caller can resume the agent with `hungToolPrompt()`.
+ */
+export function installToolTimeouts(session, limitSeconds = toolTimeoutSeconds) {
+    if (limitSeconds <= 0)
+        return { takeHung: () => undefined, dispose: () => { } };
+    const priorBeforeToolCall = session.agent.beforeToolCall;
+    session.agent.beforeToolCall = async (context, signal) => {
+        if (context.toolCall.name === "bash" && context.args && typeof context.args === "object") {
+            const args = context.args;
+            if (typeof args.timeout !== "number" || !(args.timeout > 0) || args.timeout > limitSeconds) {
+                args.timeout = limitSeconds;
+            }
+        }
+        return priorBeforeToolCall?.(context, signal);
+    };
+    const running = new Map();
+    let hung;
+    const unsubscribe = session.subscribe((event) => {
+        // Nested agents and workflows wait on child runs with their own limits.
+        if (event.type === "tool_execution_start" && !WATCHDOG_EXEMPT_TOOLS.has(event.toolName)) {
+            running.set(event.toolCallId, { toolName: event.toolName, started: Date.now() });
+        }
+        if (event.type === "tool_execution_end")
+            running.delete(event.toolCallId);
+        if (event.type === "agent_end")
+            running.clear();
+    });
+    const timer = setInterval(() => {
+        if (hung)
+            return;
+        const now = Date.now();
+        for (const call of running.values()) {
+            if (now - call.started < limitSeconds * 1000 + WATCHDOG_SLACK_MS)
+                continue;
+            hung = { toolName: call.toolName, seconds: Math.round((now - call.started) / 1000) };
+            running.clear();
+            void session.abort();
+            return;
+        }
+    }, WATCHDOG_INTERVAL_MS);
+    timer.unref?.();
+    return {
+        takeHung() {
+            const out = hung;
+            hung = undefined;
+            return out;
+        },
+        dispose() {
+            clearInterval(timer);
+            unsubscribe();
+            session.agent.beforeToolCall = priorBeforeToolCall;
+        },
+    };
+}
 /**
  * Try to find the right model for an agent type.
  * Priority: explicit option > config.model > parent model.
@@ -867,6 +962,7 @@ export async function runAgent(ctx, type, prompt, options) {
         });
     }
     options.onSessionCreated?.(session);
+    const toolTimeouts = installToolTimeouts(session);
     // Track turns for graceful max_turns enforcement
     let turnCount = 0;
     const maxTurns = resolveEffectiveMaxTurns(type, options.maxTurns);
@@ -937,6 +1033,16 @@ export async function runAgent(ctx, type, prompt, options) {
             return { responseText: "", session, aborted: true, steered: false };
         }
         await session.prompt(effectivePrompt);
+        for (let recoveries = 0;; recoveries++) {
+            const hung = toolTimeouts.takeHung();
+            if (!hung)
+                break;
+            if (aborted || options.signal?.aborted || recoveries >= MAX_TOOL_RECOVERIES) {
+                aborted = true;
+                break;
+            }
+            await session.prompt(hungToolPrompt(hung));
+        }
         // One more prompt when a schema was asked for and nothing usable came back
         // — the model answered in prose, or only ever called the tool invalidly.
         // Inside this `try`, so the turn tracking, the text collector and above all
@@ -949,6 +1055,7 @@ export async function runAgent(ctx, type, prompt, options) {
         }
     }
     finally {
+        toolTimeouts.dispose();
         unsubTurns();
         collector.unsubscribe();
         cleanupAbort();
@@ -1004,12 +1111,20 @@ export async function resumeAgent(session, prompt, options = {}) {
             }
         })
         : () => { };
+    const toolTimeouts = installToolTimeouts(session);
     try {
         if (options.signal?.aborted)
             return { text: "" };
         await session.prompt(prompt);
+        for (let recoveries = 0; recoveries < MAX_TOOL_RECOVERIES && !options.signal?.aborted; recoveries++) {
+            const hung = toolTimeouts.takeHung();
+            if (!hung)
+                break;
+            await session.prompt(hungToolPrompt(hung));
+        }
     }
     finally {
+        toolTimeouts.dispose();
         collector.unsubscribe();
         unsubEvents();
         cleanupAbort();

package/dist/index.js

@@ -18,7 +18,7 @@ import { abortable } from "./abortable.js";
 import { hasAgentBadge, renderAgentName } from "./agent-color.js";
 import { buildNewAgentFile, disableInContent, enableInContent, isEmptyStub, locateAgentFile, personalAgentsDir, projectAgentsDir, serializeAgentFile } from "./agent-file-toggle.js";
 import { AgentManager, isTopLevelAgent } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, getRememberAgents, normalizeMaxTurns, resolveEffectiveMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, setRememberAgents, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, getRememberAgents, getToolTimeoutSeconds, normalizeMaxTurns, resolveEffectiveMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, setRememberAgents, setToolTimeoutSeconds, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getConfig, getFallbackSubagent, isDefaultsDisabled, NO_FALLBACK, registerAgents, resolveSpawnType, resolveType, setDefaultsDisabled, setFallbackSubagent } from "./agent-types.js";
 import { inChildSessionContext } from "./child-context.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
@@ -1351,6 +1351,7 @@ export default function (pi) {
         setMaxConcurrentForeground: (n) => manager.setMaxConcurrentForeground(n),
         setDefaultMaxTurns,
         setGraceTurns,
+        setToolTimeoutSeconds,
         setDefaultJoinMode,
         setBackgroundByDefault,
         setSchedulingEnabled,
@@ -3241,6 +3242,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
             // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
             defaultMaxTurns: getDefaultMaxTurns() ?? 0,
             graceTurns: getGraceTurns(),
+            toolTimeoutSeconds: getToolTimeoutSeconds(),
             defaultJoinMode: getDefaultJoinMode(),
             backgroundByDefault: getBackgroundByDefault(),
             schedulingEnabled: isSchedulingEnabled(),
@@ -3277,7 +3279,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
     const _settingsSnapshotIsComplete = true;
     void _settingsSnapshotIsComplete;
     const NUMERIC_IDS = new Set([
-        "maxConcurrent", "maxConcurrentForeground", "defaultMaxTurns", "graceTurns", "maxSubagentDepth",
+        "maxConcurrent", "maxConcurrentForeground", "defaultMaxTurns", "graceTurns", "toolTimeoutSeconds", "maxSubagentDepth",
     ]);
     async function showSettings(ctx) {
         function buildItems() {
@@ -3285,6 +3287,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
             const mcf = manager.getMaxConcurrentForeground();
             const dmt = getDefaultMaxTurns() ?? 0;
             const gt = getGraceTurns();
+            const tts = getToolTimeoutSeconds();
             const msd = getMaxSubagentDepth();
             // Label what unset actually does — it targets general-purpose even when
             // that is unregistered (the permissive hardcoded tier), so showing "none"
@@ -3322,6 +3325,13 @@ Write the file using the write tool. Only write the file, nothing else.`;
                     currentValue: String(gt),
                     values: [String(gt)],
                 },
+                {
+                    id: "toolTimeoutSeconds",
+                    label: "Tool timeout",
+                    description: "Seconds one subagent tool call may run before it is stopped and the agent continues (0 = no limit, Enter to type)",
+                    currentValue: String(tts),
+                    values: [String(tts)],
+                },
                 {
                     id: "maxSubagentDepth",
                     label: "Nested depth",
@@ -3501,6 +3511,13 @@ Write the file using the write tool. Only write the file, nothing else.`;
                     notifyApplied(ctx, `Grace turns set to ${n}`);
                 }
             }
+            else if (id === "toolTimeoutSeconds") {
+                const n = parseInt(value, 10);
+                if (n >= 0) {
+                    setToolTimeoutSeconds(n);
+                    notifyApplied(ctx, n === 0 ? "Tool timeout off" : `Tool timeout set to ${getToolTimeoutSeconds()} s`);
+                }
+            }
             else if (id === "maxSubagentDepth") {
                 const n = parseInt(value, 10);
                 if (n >= 0) {
@@ -3671,7 +3688,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
                         ? String(getDefaultMaxTurns() ?? 0)
                         : result === "maxSubagentDepth"
                             ? String(getMaxSubagentDepth())
-                            : String(getGraceTurns());
+                            : result === "toolTimeoutSeconds"
+                                ? String(getToolTimeoutSeconds())
+                                : String(getGraceTurns());
             const label = result === "maxConcurrent"
                 ? "Max concurrency (1+)"
                 : result === "maxConcurrentForeground"
@@ -3680,7 +3699,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
                         ? "Default max turns (0 = unlimited)"
                         : result === "maxSubagentDepth"
                             ? "Nested depth (0/1 = nesting off)"
-                            : "Grace turns (1+)";
+                            : result === "toolTimeoutSeconds"
+                                ? "Tool timeout in seconds (0 = no limit)"
+                                : "Grace turns (1+)";
             // Loop until user enters a valid integer or cancels (Esc / null).
             // Silently trims whitespace; rejects non-numeric input by re-prompting.
             let input = await ctx.ui.input(label, current);

package/dist/settings.d.ts

@@ -30,6 +30,11 @@ export interface SubagentsSettings {
      */
     defaultMaxTurns?: number;
     graceTurns?: number;
+    /**
+     * Longest one tool call of a subagent may run, in seconds (0 = no limit,
+     * default 1200). See `toolTimeoutSeconds` in agent-runner.ts.
+     */
+    toolTimeoutSeconds?: number;
     defaultJoinMode?: JoinMode;
     /**
      * Whether a top-level `Agent` spawn that doesn't say runs detached.
@@ -300,6 +305,7 @@ export interface SettingsAppliers {
     setMaxConcurrentForeground: (n: number) => void;
     setDefaultMaxTurns: (n: number) => void;
     setGraceTurns: (n: number) => void;
+    setToolTimeoutSeconds: (n: number) => void;
     setDefaultJoinMode: (mode: JoinMode) => void;
     setBackgroundByDefault: (b: boolean) => void;
     setSchedulingEnabled: (b: boolean) => void;

package/dist/settings.js

@@ -17,6 +17,7 @@ const VALID_AGENT_MENTION_MODES = new Set(["model", "direct", "off"]);
 const MAX_CONCURRENT_CEILING = 1024;
 const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
+const TOOL_TIMEOUT_CEILING = 86_400;
 const SUBAGENT_DEPTH_CEILING = 16;
 /** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
 function sanitize(raw) {
@@ -46,6 +47,11 @@ function sanitize(raw) {
         r.graceTurns <= GRACE_TURNS_CEILING) {
         out.graceTurns = r.graceTurns;
     }
+    if (Number.isInteger(r.toolTimeoutSeconds) &&
+        r.toolTimeoutSeconds >= 0 &&
+        r.toolTimeoutSeconds <= TOOL_TIMEOUT_CEILING) {
+        out.toolTimeoutSeconds = r.toolTimeoutSeconds;
+    }
     if (Number.isInteger(r.maxSubagentDepth) &&
         r.maxSubagentDepth >= 0 &&
         r.maxSubagentDepth <= SUBAGENT_DEPTH_CEILING) {
@@ -178,6 +184,8 @@ export function applySettings(s, appliers) {
         appliers.setDefaultMaxTurns(s.defaultMaxTurns);
     if (typeof s.graceTurns === "number")
         appliers.setGraceTurns(s.graceTurns);
+    if (typeof s.toolTimeoutSeconds === "number")
+        appliers.setToolTimeoutSeconds(s.toolTimeoutSeconds);
     if (typeof s.maxSubagentDepth === "number")
         appliers.setMaxSubagentDepth(s.maxSubagentDepth);
     if (typeof s.fallbackSubagent === "string")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kushalkhemka/opensec-pi-subagents",
-  "version": "0.19.8",
+  "version": "0.19.10",
   "description": "Fork of @tintinweb/pi-subagents with parent model/thinking inheritance and cached agent discovery.",
   "author": "tintinweb",
   "contributors": [
@@ -30,13 +30,21 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.84.0",
     "@earendil-works/pi-coding-agent": ">=0.84.0",
-    "@earendil-works/pi-tui": ">=0.84.0"
+    "@earendil-works/pi-tui": ">=0.84.0",
+    "@sinclair/typebox": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@sinclair/typebox": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
-    "nanoid": "^5.1.16",
-    "typebox": "^1.3.7"
+    "nanoid": "^5.1.16"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
@@ -54,11 +62,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@sinclair/typebox": "^0.34.49",
     "@types/node": "^25.5.0",
     "@vitest/coverage-istanbul": "^4.1.10",
+    "typebox": "^1.3.7",
     "typescript": "^6.0.0",
     "vitest": "^4.0.18"
   },

package/src/agent-runner.ts

@@ -405,6 +405,112 @@ export function getGraceTurns(): number { return graceTurns; }
 /** Set the grace turns value (minimum 1). */
 export function setGraceTurns(n: number): void { graceTurns = Math.max(1, n); }
 
+/**
+ * Longest a single tool call may run, in seconds. 0 = no limit.
+ *
+ * Turn limits only count finished turns, and a turn whose tool never returns
+ * never finishes: a `find /` or a server that never closes would hold the agent
+ * forever. So a subagent's `bash` calls get this as their timeout (pi kills the
+ * whole process tree and reports the timeout to the model, which carries on),
+ * and a watchdog stops any other tool that overruns it and tells the agent to
+ * continue another way.
+ */
+let toolTimeoutSeconds = 1200;
+export const TOOL_TIMEOUT_CEILING = 86_400;
+
+/** Get the per-tool-call time limit in seconds (0 = no limit). */
+export function getToolTimeoutSeconds(): number { return toolTimeoutSeconds; }
+/** Set the per-tool-call time limit in seconds (0 = no limit). */
+export function setToolTimeoutSeconds(n: number): void {
+  toolTimeoutSeconds = Math.min(TOOL_TIMEOUT_CEILING, Math.max(0, Math.floor(n)));
+}
+
+/** How long past the limit the watchdog waits, so a timing-out `bash` reports its own timeout first. */
+const WATCHDOG_SLACK_MS = 60_000;
+const WATCHDOG_INTERVAL_MS = 5_000;
+/** Times one run is resumed after a stuck tool before it is left stopped. */
+export const MAX_TOOL_RECOVERIES = 3;
+const WATCHDOG_EXEMPT_TOOLS: ReadonlySet<string> = new Set(EXCLUDED_TOOL_NAMES);
+
+export interface HungTool {
+  toolName: string;
+  seconds: number;
+}
+
+function formatDuration(seconds: number): string {
+  if (seconds < 120) return `${seconds} seconds`;
+  return `${Math.round(seconds / 60)} minutes`;
+}
+
+/** The prompt that resumes an agent whose tool call the watchdog stopped. */
+export function hungToolPrompt(hung: HungTool): string {
+  return `Your ${hung.toolName} call ran for ${formatDuration(hung.seconds)} without finishing, so it was stopped and its `
+    + "output is lost. Continue the task without repeating that call: split the work into smaller, bounded steps "
+    + "(search specific folders rather than the whole filesystem, limit depth and output, add timeouts).";
+}
+
+/**
+ * Bound a subagent session's tool calls (see `toolTimeoutSeconds`).
+ *
+ * `bash` calls without a timeout, or with a longer one, get the limit. The
+ * watchdog covers every tool: past the limit (plus slack) it aborts the run,
+ * which kills a running command's process tree, and `takeHung()` then reports
+ * the call so the caller can resume the agent with `hungToolPrompt()`.
+ */
+export function installToolTimeouts(session: AgentSession, limitSeconds = toolTimeoutSeconds): {
+  takeHung(): HungTool | undefined;
+  dispose(): void;
+} {
+  if (limitSeconds <= 0) return { takeHung: () => undefined, dispose: () => {} };
+
+  const priorBeforeToolCall = session.agent.beforeToolCall;
+  session.agent.beforeToolCall = async (context, signal) => {
+    if (context.toolCall.name === "bash" && context.args && typeof context.args === "object") {
+      const args = context.args as { timeout?: unknown };
+      if (typeof args.timeout !== "number" || !(args.timeout > 0) || args.timeout > limitSeconds) {
+        args.timeout = limitSeconds;
+      }
+    }
+    return priorBeforeToolCall?.(context, signal);
+  };
+
+  const running = new Map<string, { toolName: string; started: number }>();
+  let hung: HungTool | undefined;
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    // Nested agents and workflows wait on child runs with their own limits.
+    if (event.type === "tool_execution_start" && !WATCHDOG_EXEMPT_TOOLS.has(event.toolName)) {
+      running.set(event.toolCallId, { toolName: event.toolName, started: Date.now() });
+    }
+    if (event.type === "tool_execution_end") running.delete(event.toolCallId);
+    if (event.type === "agent_end") running.clear();
+  });
+  const timer = setInterval(() => {
+    if (hung) return;
+    const now = Date.now();
+    for (const call of running.values()) {
+      if (now - call.started < limitSeconds * 1000 + WATCHDOG_SLACK_MS) continue;
+      hung = { toolName: call.toolName, seconds: Math.round((now - call.started) / 1000) };
+      running.clear();
+      void session.abort();
+      return;
+    }
+  }, WATCHDOG_INTERVAL_MS);
+  (timer as { unref?: () => void }).unref?.();
+
+  return {
+    takeHung() {
+      const out = hung;
+      hung = undefined;
+      return out;
+    },
+    dispose() {
+      clearInterval(timer);
+      unsubscribe();
+      session.agent.beforeToolCall = priorBeforeToolCall;
+    },
+  };
+}
+
 /**
  * Try to find the right model for an agent type.
  * Priority: explicit option > config.model > parent model.
@@ -1108,6 +1214,8 @@ export async function runAgent(
 
   options.onSessionCreated?.(session);
 
+  const toolTimeouts = installToolTimeouts(session);
+
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
   const maxTurns = resolveEffectiveMaxTurns(type, options.maxTurns);
@@ -1180,6 +1288,15 @@ export async function runAgent(
       return { responseText: "", session, aborted: true, steered: false };
     }
     await session.prompt(effectivePrompt);
+    for (let recoveries = 0; ; recoveries++) {
+      const hung = toolTimeouts.takeHung();
+      if (!hung) break;
+      if (aborted || options.signal?.aborted || recoveries >= MAX_TOOL_RECOVERIES) {
+        aborted = true;
+        break;
+      }
+      await session.prompt(hungToolPrompt(hung));
+    }
 
     // One more prompt when a schema was asked for and nothing usable came back
     // — the model answered in prose, or only ever called the tool invalidly.
@@ -1192,6 +1309,7 @@ export async function runAgent(
       await session.prompt(structuredRetryPrompt(structuredCapture));
     }
   } finally {
+    toolTimeouts.dispose();
     unsubTurns();
     collector.unsubscribe();
     cleanupAbort();
@@ -1257,10 +1375,17 @@ export async function resumeAgent(
       })
     : () => {};
 
+  const toolTimeouts = installToolTimeouts(session);
   try {
     if (options.signal?.aborted) return { text: "" };
     await session.prompt(prompt);
+    for (let recoveries = 0; recoveries < MAX_TOOL_RECOVERIES && !options.signal?.aborted; recoveries++) {
+      const hung = toolTimeouts.takeHung();
+      if (!hung) break;
+      await session.prompt(hungToolPrompt(hung));
+    }
   } finally {
+    toolTimeouts.dispose();
     collector.unsubscribe();
     unsubEvents();
     cleanupAbort();

package/src/index.ts

@@ -19,7 +19,7 @@ import { abortable } from "./abortable.js";
 import { hasAgentBadge, renderAgentName } from "./agent-color.js";
 import { buildNewAgentFile, disableInContent, enableInContent, isEmptyStub, locateAgentFile, personalAgentsDir, projectAgentsDir, serializeAgentFile } from "./agent-file-toggle.js";
 import { AgentManager, isTopLevelAgent } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, getRememberAgents, normalizeMaxTurns, resolveEffectiveMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, setRememberAgents, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, getRememberAgents, getToolTimeoutSeconds, normalizeMaxTurns, resolveEffectiveMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, setRememberAgents, setToolTimeoutSeconds, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getConfig, getFallbackSubagent, isDefaultsDisabled, NO_FALLBACK, registerAgents, resolveSpawnType, resolveType, setDefaultsDisabled, setFallbackSubagent } from "./agent-types.js";
 import { inChildSessionContext } from "./child-context.js";
 import { type RpcHandle, registerRpcHandlers } from "./cross-extension-rpc.js";
@@ -1462,6 +1462,7 @@ export default function (pi: ExtensionAPI) {
       setMaxConcurrentForeground: (n) => manager.setMaxConcurrentForeground(n),
       setDefaultMaxTurns,
       setGraceTurns,
+      setToolTimeoutSeconds,
       setDefaultJoinMode,
       setBackgroundByDefault,
       setSchedulingEnabled,
@@ -3506,6 +3507,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
       // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
+      toolTimeoutSeconds: getToolTimeoutSeconds(),
       defaultJoinMode: getDefaultJoinMode(),
       backgroundByDefault: getBackgroundByDefault(),
       schedulingEnabled: isSchedulingEnabled(),
@@ -3552,7 +3554,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
   void _settingsSnapshotIsComplete;
 
   const NUMERIC_IDS = new Set([
-    "maxConcurrent", "maxConcurrentForeground", "defaultMaxTurns", "graceTurns", "maxSubagentDepth",
+    "maxConcurrent", "maxConcurrentForeground", "defaultMaxTurns", "graceTurns", "toolTimeoutSeconds", "maxSubagentDepth",
   ]);
 
   async function showSettings(ctx: ExtensionCommandContext) {
@@ -3561,6 +3563,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
       const mcf = manager.getMaxConcurrentForeground();
       const dmt = getDefaultMaxTurns() ?? 0;
       const gt = getGraceTurns();
+      const tts = getToolTimeoutSeconds();
       const msd = getMaxSubagentDepth();
       // Label what unset actually does — it targets general-purpose even when
       // that is unregistered (the permissive hardcoded tier), so showing "none"
@@ -3599,6 +3602,13 @@ Write the file using the write tool. Only write the file, nothing else.`;
           currentValue: String(gt),
           values: [String(gt)],
         },
+        {
+          id: "toolTimeoutSeconds",
+          label: "Tool timeout",
+          description: "Seconds one subagent tool call may run before it is stopped and the agent continues (0 = no limit, Enter to type)",
+          currentValue: String(tts),
+          values: [String(tts)],
+        },
         {
           id: "maxSubagentDepth",
           label: "Nested depth",
@@ -3780,6 +3790,12 @@ Write the file using the write tool. Only write the file, nothing else.`;
           setGraceTurns(n);
           notifyApplied(ctx, `Grace turns set to ${n}`);
         }
+      } else if (id === "toolTimeoutSeconds") {
+        const n = parseInt(value, 10);
+        if (n >= 0) {
+          setToolTimeoutSeconds(n);
+          notifyApplied(ctx, n === 0 ? "Tool timeout off" : `Tool timeout set to ${getToolTimeoutSeconds()} s`);
+        }
       } else if (id === "maxSubagentDepth") {
         const n = parseInt(value, 10);
         if (n >= 0) {
@@ -3964,7 +3980,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
             ? String(getDefaultMaxTurns() ?? 0)
             : result === "maxSubagentDepth"
               ? String(getMaxSubagentDepth())
-              : String(getGraceTurns());
+              : result === "toolTimeoutSeconds"
+                ? String(getToolTimeoutSeconds())
+                : String(getGraceTurns());
 
       const label = result === "maxConcurrent"
         ? "Max concurrency (1+)"
@@ -3974,7 +3992,9 @@ Write the file using the write tool. Only write the file, nothing else.`;
             ? "Default max turns (0 = unlimited)"
             : result === "maxSubagentDepth"
               ? "Nested depth (0/1 = nesting off)"
-              : "Grace turns (1+)";
+              : result === "toolTimeoutSeconds"
+                ? "Tool timeout in seconds (0 = no limit)"
+                : "Grace turns (1+)";
 
       // Loop until user enters a valid integer or cancels (Esc / null).
       // Silently trims whitespace; rejects non-numeric input by re-prompting.

package/src/settings.ts

@@ -40,6 +40,11 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
+  /**
+   * Longest one tool call of a subagent may run, in seconds (0 = no limit,
+   * default 1200). See `toolTimeoutSeconds` in agent-runner.ts.
+   */
+  toolTimeoutSeconds?: number;
   defaultJoinMode?: JoinMode;
   /**
    * Whether a top-level `Agent` spawn that doesn't say runs detached.
@@ -313,6 +318,7 @@ export interface SettingsAppliers {
   setMaxConcurrentForeground: (n: number) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
+  setToolTimeoutSeconds: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
   setBackgroundByDefault: (b: boolean) => void;
   setSchedulingEnabled: (b: boolean) => void;
@@ -350,6 +356,7 @@ const VALID_AGENT_MENTION_MODES: ReadonlySet<string> = new Set<AgentMentionMode>
 const MAX_CONCURRENT_CEILING = 1024;
 const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
+const TOOL_TIMEOUT_CEILING = 86_400;
 const SUBAGENT_DEPTH_CEILING = 16;
 
 /** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
@@ -387,6 +394,13 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
+  if (
+    Number.isInteger(r.toolTimeoutSeconds) &&
+    (r.toolTimeoutSeconds as number) >= 0 &&
+    (r.toolTimeoutSeconds as number) <= TOOL_TIMEOUT_CEILING
+  ) {
+    out.toolTimeoutSeconds = r.toolTimeoutSeconds as number;
+  }
   if (
     Number.isInteger(r.maxSubagentDepth) &&
     (r.maxSubagentDepth as number) >= 0 &&
@@ -523,6 +537,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   }
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+  if (typeof s.toolTimeoutSeconds === "number") appliers.setToolTimeoutSeconds(s.toolTimeoutSeconds);
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);