@ferris1225/pi-subagents 0.14.0 → 0.16.0

package/README.md

@@ -23,10 +23,13 @@ agent, and keep the workflow moving without manual polling.
   elapsed time; completion also produces a concise notification.
 - **Per-agent configuration** — enable agents, pick model and thinking strength per agent,
   tune concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Idle watchdog** — a sub-agent whose stdout goes silent for a configurable
+  duration is terminated and retried with the fallback model, so a stalled SSE
+  stream never hangs the workflow.
 - **Automatic model fallback** — if an agent's model fails at the provider level before
-  producing any output, the run is retried once with the main window's current model.
-  Per-run only, never persisted: a transient provider hiccup does not silently downgrade
-  the configured model.
+  producing any output (or the idle watchdog fires), the run is retried once with the
+  main window's current model. Per-run only, never persisted: a transient provider
+  hiccup does not silently downgrade the configured model.
 - **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
   recurse.
 
@@ -331,7 +334,8 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
   "proactiveInjection": true,
   "agentScope": "user",
   "maxConcurrency": 4,
-  "maxFixRounds": 2
+  "maxFixRounds": 2,
+  "idleTimeoutSec": 90
 }
 ```
 
@@ -347,6 +351,7 @@ agent's default — its frontmatter `thinking`, else the global default). The gl
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
 | `maxConcurrency` | Max sub-agent processes running at once (1–16, default 4), and the max tasks one parallel `subagent` call accepts. Extra work waits in the queue. |
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL`: the extension dispatches a `worker` (briefed with the review's concrete findings) then a `reviewer` re-review, repeating up to this many times before waking the main agent with the full chain. `0` disables it (the main agent handles fixes itself). Default 2. The reviewer stays read-only and in its own context; the loop is orchestrated by the extension, not by the reviewer. |
+| `idleTimeoutSec` | Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes silent for this long is terminated and retried with the fallback model (if one is available). `0` disables the idle watchdog. Default 90. Unlike the total timeout, this only fires when the child produces no output at all — a long but active run is never interrupted. |
 
 ### Configuration migration
 
@@ -361,6 +366,8 @@ The config file migrates itself on load — no manual steps after an upgrade:
 - **Removed keys** — `maxSubagentDepth` (0.14) is dropped on load: sub-agent children are
   always leaf processes (the `subagent` tool is excluded from their toolset, with a depth
   marker as defense in depth). To disable delegation entirely, use `"enabledAgents": []`.
+- **New fields** — `idleTimeoutSec` (0.16) is filled in on load with its default (90)
+  when missing from an older config.
 
 Model selection uses this precedence:
 
@@ -375,8 +382,10 @@ At runtime, if an agent's model fails at the provider level before producing any
 model id, auth, thinking level, quota, ...), the run is retried **once** with the main window's
 current model. This per-run degradation is never persisted — a transient provider hiccup must
 not silently downgrade the configured model — and it does not apply to task-level failures
-(the model worked, the task failed), aborts, or timeouts. Results carry a `model fell back
-from …` note when it happened.
+(the model worked, the task failed), aborts, or total timeouts. Idle timeouts (the child's
+stdout goes silent for `idleTimeoutSec` seconds) are treated as model-level failures and do
+trigger the fallback, since a stalled SSE stream is usually a provider-side issue. Results
+carry a `model fell back from …` note when it happened.
 
 Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -58,6 +58,15 @@ export const DEFAULT_MAX_FIX_ROUNDS = 2;
 /** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
 export const MAX_FIX_ROUNDS_LIMIT = 5;
 
+/**
+ * Default idle timeout in seconds: a sub-agent whose stdout (JSON event stream)
+ * goes silent for this long is terminated and may be retried with the fallback
+ * model. 0 disables the idle watchdog. Default: 90.
+ */
+export const DEFAULT_IDLE_TIMEOUT_SEC = 90;
+/** Upper bound accepted for idleTimeoutSec (defensive clamp). 0 disables. */
+export const IDLE_TIMEOUT_SEC_LIMIT = 600;
+
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
@@ -93,6 +102,12 @@ export interface SubagentsConfig {
 	 * Default: 2.
 	 */
 	maxFixRounds: number;
+	/**
+	 * Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes
+	 * silent for this long is terminated and may be retried with the fallback
+	 * model. 0 disables the idle watchdog. Default: 90.
+	 */
+	idleTimeoutSec: number;
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -106,6 +121,7 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	agentScope: "user",
 	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
 	maxFixRounds: DEFAULT_MAX_FIX_ROUNDS,
+	idleTimeoutSec: DEFAULT_IDLE_TIMEOUT_SEC,
 };
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
@@ -151,6 +167,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		agentScope: DEFAULT_CONFIG.agentScope,
 		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
 		maxFixRounds: DEFAULT_CONFIG.maxFixRounds,
+		idleTimeoutSec: DEFAULT_CONFIG.idleTimeoutSec,
 	};
 
 	if (Array.isArray(raw.enabledAgents)) {
@@ -218,6 +235,11 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
 	}
 
+	// 0 disables the idle watchdog; otherwise clamp to [0, upper].
+	if (typeof raw.idleTimeoutSec === "number" && Number.isFinite(raw.idleTimeoutSec)) {
+		config.idleTimeoutSec = Math.max(0, Math.min(IDLE_TIMEOUT_SEC_LIMIT, Math.round(raw.idleTimeoutSec)));
+	}
+
 	return config;
 }
 

package/src/index.ts

@@ -134,7 +134,7 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number): st
 	const fallbackNote = result.modelFallbackFrom
 		? ` (model fell back from ${result.modelFallbackFrom} to ${result.model ?? "main-window model"})`
 		: "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, "", text];
 	if (truncated) {
 		// The full text lives on disk so the main agent can read it on demand.
 		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent)})`);
@@ -375,6 +375,7 @@ export default function (pi: ExtensionAPI): void {
 							signal,
 							onLive,
 							makeDetails: makeDetails("single", true),
+							idleTimeoutMs: config.idleTimeoutSec * 1000,
 						},
 						sessionRef,
 					);
@@ -477,6 +478,7 @@ export default function (pi: ExtensionAPI): void {
 									signal: backgroundSignal,
 									onLive,
 									makeDetails: makeDetails("single", true),
+									idleTimeoutMs: config.idleTimeoutSec * 1000,
 								},
 								sessionRef,
 							);
@@ -587,14 +589,14 @@ export default function (pi: ExtensionAPI): void {
 			if (args.tasks && args.tasks.length > 0) {
 				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
 				for (const t of args.tasks.slice(0, 4)) {
-					const preview = t.task.length > 48 ? `${t.task.slice(0, 48)}…` : t.task;
+					const preview = formatTaskSummary(t.task, 48);
 					text += `\n  ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`;
 				}
 				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
 				return new Text(text, 0, 0);
 			}
 			const task: string = args.task ?? "";
-			const preview = task.length > 60 ? `${task.slice(0, 60)}…` : task;
+			const preview = formatTaskSummary(task, 60);
 			return new Text(
 				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")} ${theme.fg("dim", preview)}`,
 				0,
@@ -663,9 +665,9 @@ export default function (pi: ExtensionAPI): void {
 							// parent reviewer; summarize() already carries the relationLabel.
 							const head = r.groupId ? theme.fg("dim", "  ↳ ") : " ";
 							const note = r.annotation ? theme.fg("dim", ` · ${r.annotation}`) : "";
-							lines.push(truncateToWidth(`${head}${icon} ${monitor.summarize(r)} · ${label}${note}`, width, ""));
+							lines.push(truncateToWidth(`${head}${icon} #${r.id} ${monitor.summarize(r)} · ${label}${note}`, width, ""));
 							if (r.status === "queued" || r.status === "running") {
-								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task)}`), width, ""));
+								lines.push(truncateToWidth(theme.fg("dim", `     task: ${formatTaskSummary(r.task, Math.max(20, width - 11))}`), width, ""));
 							}
 							// Activity sits one indent level below the agent name.
 							if (r.activity) lines.push(truncateToWidth(theme.fg("dim", `     ${r.activity}`), width, ""));

package/src/monitor.ts

@@ -56,23 +56,145 @@ export interface RunChainMeta {
 
 const TASK_SUMMARY_MAX = 80;
 const TASK_SUMMARY_ELLIPSIS = "…";
+/** Columns reserved at the END of a truncated summary so the distinguishing
+ * keywords (paths, symbols, ...) survive; the head gets the rest. */
+const TASK_SUMMARY_TAIL_MAX = 28;
+/** Tail share of a non-default maxWidth (narrow widgets keep a usable tail). */
+const TASK_SUMMARY_TAIL_SHARE = 0.35;
+const TASK_SUMMARY_TAIL_MIN = 8;
+const TASK_SUMMARY_KEY_SEP = " · ";
+/** kebab/snake words that are task boilerplate, never distinguishing signal. */
+const KEY_FRAGMENT_STOPWORDS = new Set([
+	"self-contained",
+	"read-only",
+	"write-only",
+	"auto-fix",
+	"re-review",
+	"one-line",
+	"pre-commit",
+]);
 const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 
-/** One-line task preview, capped by terminal display columns (including the ellipsis). */
-export function formatTaskSummary(task: string): string {
-	const oneLine = stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
-	if (visibleWidth(oneLine) <= TASK_SUMMARY_MAX) return oneLine;
+interface KeyFragment {
+	text: string;
+	index: number;
+}
 
-	const prefixMax = TASK_SUMMARY_MAX - visibleWidth(TASK_SUMMARY_ELLIPSIS);
-	let prefix = "";
-	let prefixWidth = 0;
-	for (const { segment } of graphemeSegmenter.segment(oneLine)) {
+/**
+ * Pull the most distinguishing fragments out of a task: file paths, quoted
+ * phrases, camelCase/PascalCase symbols and kebab/snake compounds. Sorted by
+ * first occurrence and deduped (a path covers its own sub-fragments). These
+ * are what make parallel tasks of the same agent look different.
+ */
+export function extractKeyFragments(text: string): string[] {
+	const fragments: KeyFragment[] = [];
+	const add = (re: RegExp, group = 0): void => {
+		for (const m of text.matchAll(re)) {
+			const g = m[group];
+			if (g === undefined) continue;
+			fragments.push({ text: g, index: m.index ?? 0 });
+		}
+	};
+	// Quoted phrases first (highest signal).
+	add(/["'`]([^"'`]{4,60})["'`]/g, 1);
+	// Paths with a known extension (src/index.ts, build/out.js.map).
+	add(/(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,5}(?![A-Za-z0-9_.-])/g);
+	// Paths with a slash but no extension (src/components, .github/workflows).
+	add(/(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]+(?:[\\/][A-Za-z0-9_.-]+)+(?![\\/])/g);
+	// camelCase / PascalCase identifiers (function or type names).
+	add(/\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/g);
+	// snake_case / kebab-case compound words.
+	add(/\b[a-z][a-z0-9]+[-_][a-z0-9][a-z0-9_-]*\b/g);
+
+	fragments.sort((a, b) => a.index - b.index);
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const f of fragments) {
+		const t = f.text.trim();
+		if (t.length < 4 || KEY_FRAGMENT_STOPWORDS.has(t)) continue;
+		if (seen.has(t)) continue;
+		// A longer fragment (the full path) covers its own sub-fragments.
+		if (out.some((o) => o.includes(t) || t.includes(o))) continue;
+		seen.add(t);
+		out.push(t);
+	}
+	return out;
+}
+
+function takeGraphemes(segments: string[], maxWidth: number): string {
+	let width = 0;
+	const out: string[] = [];
+	for (const segment of segments) {
 		const segmentWidth = visibleWidth(segment);
-		if (prefixWidth + segmentWidth > prefixMax) break;
-		prefix += segment;
-		prefixWidth += segmentWidth;
+		if (width + segmentWidth > maxWidth) break;
+		out.push(segment);
+		width += segmentWidth;
+	}
+	return out.join("");
+}
+
+function tailGraphemes(segments: string[], maxWidth: number): string {
+	let width = 0;
+	const tail: string[] = [];
+	for (let i = segments.length - 1; i >= 0; i--) {
+		const segmentWidth = visibleWidth(segments[i]);
+		if (width + segmentWidth > maxWidth) break;
+		tail.unshift(segments[i]);
+		width += segmentWidth;
+	}
+	return tail.join("");
+}
+
+/**
+ * One-line task preview, capped by `maxWidth` display columns (default 80).
+ * `keysOnly` (default): extracted key fragments (paths, quoted phrases,
+ * symbols) are shown bare — the agent name is already displayed next to the
+ * task line, so templated prose ("explore: trace how ...") adds nothing.
+ * `keysOnly: false` keeps the prose as `head…tail` (used for completion
+ * messages, where the Task line is the reader's only context).
+ * Grapheme-safe — CJK, ZWJ emoji and combining sequences are never split.
+ */
+export function formatTaskSummary(task: string, maxWidth: number = TASK_SUMMARY_MAX, keysOnly = true): string {
+	const oneLine = stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
+	if (maxWidth <= 0 || visibleWidth(oneLine) <= maxWidth) return oneLine;
+
+	const segments = [...graphemeSegmenter.segment(oneLine)].map((s) => s.segment);
+	const ellipsisWidth = visibleWidth(TASK_SUMMARY_ELLIPSIS);
+
+	if (keysOnly) {
+		const fragments = extractKeyFragments(oneLine);
+		if (fragments.length > 0) {
+			const keyMax = maxWidth - 1;
+			let keys = "";
+			for (const fragment of fragments) {
+				const piece = keys ? `${TASK_SUMMARY_KEY_SEP}${fragment}` : fragment;
+				const total = keys + piece;
+				if (visibleWidth(total) > keyMax) {
+					// Budget exhausted: keep what fits, unless nothing fits yet.
+					if (!keys) {
+						// A single over-long fragment keeps its tail
+						// (extension/symbol) and is prefixed with the ellipsis.
+						const fragmentSegments = [...graphemeSegmenter.segment(piece)].map((s) => s.segment);
+						keys = `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(fragmentSegments, keyMax - ellipsisWidth)}`;
+					}
+					break;
+				}
+				keys = total;
+			}
+			return keys;
+		}
+	}
+
+	// No distinctive fragments (or prose mode): fall back to head…tail.
+	const tailMax = Math.max(
+		TASK_SUMMARY_TAIL_MIN,
+		Math.min(TASK_SUMMARY_TAIL_MAX, Math.round(maxWidth * TASK_SUMMARY_TAIL_SHARE)),
+	);
+	const headMax = maxWidth - ellipsisWidth - tailMax;
+	if (headMax <= 0) {
+		return `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, maxWidth - ellipsisWidth)}`;
 	}
-	return `${prefix}${TASK_SUMMARY_ELLIPSIS}`;
+	return `${takeGraphemes(segments, headMax)}${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, tailMax)}`;
 }
 
 function formatTokens(count: number): string {

package/src/setup.ts

@@ -14,6 +14,7 @@ import {
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
+	DEFAULT_IDLE_TIMEOUT_SEC,
 	DEFAULT_MAX_CONCURRENCY,
 	DEFAULT_MAX_FIX_ROUNDS,
 	THINKING_LEVEL_VALUES,
@@ -197,6 +198,8 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
 /** Preset rounds offered for the auto-fix loop (0 disables it). */
 const FIX_ROUNDS_STEPS = [0, 1, 2, 3, 5];
+/** Preset seconds offered for the idle timeout (0 disables it). */
+const IDLE_TIMEOUT_STEPS = [0, 30, 60, 90, 120, 180, 300, 600];
 
 async function pickCount(
 	ctx: ExtensionCommandContext,
@@ -298,6 +301,15 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		);
 		if (maxFixRounds === undefined) return notifyCancelled(ctx);
 
+		const idleTimeoutSec = await pickCount(
+			ctx,
+			"Idle timeout in seconds? (0 = disabled, kills a sub-agent whose output goes silent)",
+			IDLE_TIMEOUT_STEPS,
+			base.idleTimeoutSec,
+			DEFAULT_IDLE_TIMEOUT_SEC,
+		);
+		if (idleTimeoutSec === undefined) return notifyCancelled(ctx);
+
 		const next: SubagentsConfig = {
 		enabledAgents: enabled,
 		agentModels: repairStaleModels(ctx, picked.models),
@@ -309,6 +321,7 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		agentScope: scope,
 		maxConcurrency,
 		maxFixRounds,
+		idleTimeoutSec,
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
@@ -323,6 +336,7 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		"Change agent scope",
 		"Change max concurrent sub-agents",
 		"Change max fix rounds",
+		"Change idle timeout",
 		"Full re-setup",
 	]);
 	if (choice === undefined) return notifyCancelled(ctx);
@@ -384,6 +398,16 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		);
 		if (maxFixRounds === undefined) return notifyCancelled(ctx);
 		next.maxFixRounds = maxFixRounds;
+	} else if (choice.startsWith("Change idle")) {
+		const idleTimeoutSec = await pickCount(
+			ctx,
+			"Idle timeout in seconds? (0 = disabled, kills a sub-agent whose output goes silent)",
+			IDLE_TIMEOUT_STEPS,
+			config.idleTimeoutSec,
+			DEFAULT_IDLE_TIMEOUT_SEC,
+		);
+		if (idleTimeoutSec === undefined) return notifyCancelled(ctx);
+		next.idleTimeoutSec = idleTimeoutSec;
 	}
 
 	await saveConfig(next, configPath);

package/src/spawn.ts

@@ -31,6 +31,10 @@ export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 /** No default deadline: sub-agents may run until completion or explicit cancellation. */
 export const SUBAGENT_TIMEOUT_MS = 0;
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
+/** Default idle watchdog: terminate a child whose stdout goes silent for this
+ * many milliseconds. 0 disables it. The actual value comes from config
+ * (idleTimeoutSec); this constant is only a fallback for tests. */
+export const SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS = 0;
 
 export interface UsageStats {
 	input: number;
@@ -155,6 +159,10 @@ export function isFailedResult(result: SingleResult): boolean {
 export function isModelLevelFailure(result: SingleResult): boolean {
 	if (!isFailedResult(result)) return false;
 	if (result.stopReason === "aborted") return false;
+	// An idle timeout (stdout went silent) signals a stalled provider connection,
+	// not a task-level failure: allow model fallback even if the model produced
+	// partial output before going quiet.
+	if (result.errorMessage?.includes("idle timeout")) return true;
 	// The model produced text: the failure belongs to the task, not the model.
 	if (getFinalOutput(result.messages)) return false;
 	if (result.errorMessage?.includes("timed out")) return false;
@@ -253,8 +261,11 @@ export interface RunSingleOptions {
 	cwd?: string;
 	/** Thinking level passed to the child pi process. */
 	thinkingLevel?: ThinkingLevel;
-	/** Optional timeout; zero (the default) disables it. Intended for tests and controlled callers. */
+	/** Optional total timeout; zero (the default) disables it. Intended for tests and controlled callers. */
 	timeoutMs?: number;
+	/** Idle timeout in ms: terminate the child if its stdout produces no activity
+	 * for this duration. 0 (the default) disables the idle watchdog. */
+	idleTimeoutMs?: number;
 	signal?: AbortSignal;
 	onUpdate?: OnUpdateCallback;
 	onLive?: (e: SubagentLiveEvent) => void;
@@ -271,6 +282,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		cwd,
 		thinkingLevel = SUBAGENT_THINKING_LEVEL,
 		timeoutMs = SUBAGENT_TIMEOUT_MS,
+		idleTimeoutMs = SUBAGENT_DEFAULT_IDLE_TIMEOUT_MS,
 		signal,
 		onUpdate,
 		onLive,
@@ -351,12 +363,15 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
 			let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
 			let abortHandler: (() => void) | undefined;
+			let lastActivityAt = Date.now();
+			let idleTimer: ReturnType<typeof setInterval> | undefined;
 
 			const finish = (code: number | null): void => {
 				if (closed) return;
 				closed = true;
 				if (forceKillTimer) clearTimeout(forceKillTimer);
 				if (timeoutTimer) clearTimeout(timeoutTimer);
+				if (idleTimer) clearInterval(idleTimer);
 				if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
 				resolve(code ?? 1);
 			};
@@ -466,6 +481,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			// message (including a reviewer's verdict line) from parsing.
 			const stdoutDecoder = new StringDecoder("utf8");
 			proc.stdout.on("data", (data) => {
+				lastActivityAt = Date.now();
 				buffer += stdoutDecoder.write(data);
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
@@ -519,6 +535,20 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 				}, timeoutMs);
 			}
 
+			if (idleTimeoutMs > 0) {
+				const checkInterval = Math.min(10_000, Math.floor(idleTimeoutMs / 3));
+				idleTimer = setInterval(() => {
+					if (closed) return;
+					if (Date.now() - lastActivityAt >= idleTimeoutMs) {
+						if (idleTimer) clearInterval(idleTimer);
+						timedOut = true;
+						currentResult.stopReason = "error";
+						currentResult.errorMessage = `Subagent idle timeout: no activity for ${Math.ceil(idleTimeoutMs / 1000)} seconds.`;
+						terminate();
+					}
+				}, checkInterval);
+			}
+
 			if (signal) {
 				abortHandler = (): void => {
 					wasAborted = true;