Problem

Sub-agents can stall indefinitely while remaining in "running" status. Today the only automated protection is runTimeoutSeconds (wall-clock cap), which can't distinguish active work from a stalled agent. Manual detection requires checking sessions_history timestamps — unreliable since LLMs have no internal timers and can't self-trigger checks.

Proposed solution

A two-stage stall recovery system that monitors time since last tool call per sub-agent:

Stage 1 — Nudge (stallNudgeSeconds): After N seconds of no tool calls, inject a system message ("You appear stalled — resume your task or report what's blocking you"). Cheap, might recover agents that are confused or lost.

Stage 2 — Kill (stallTimeoutSeconds): If no tool call within M seconds after the nudge, auto-kill the agent and notify the parent session. Backstop for cases where nudging can't help (dead-on-arrival, context exhaustion, hung tool calls).

Config:

{
  "agents": {
    "defaults": {
      "subagents": {
        "stallNudgeSeconds": 90,
        "stallTimeoutSeconds": 180
      }
    }
  }
}

Also available as per-spawn overrides on sessions_spawn.

Why both stages?

• Nudge alone is optimistic — many stalls aren't recoverable (agent never started, context full, platform-level issue)
• Kill alone is wasteful — some agents just need a tap on the shoulder
• Escalating intervention: cheapest recovery first, then hard cutoff

Related issues

• [RFC]: Agent stall detection watchdog (reply-chain monitor) #23867 — Stall detection watchdog (nudge via reply-chain monitoring)
• [Feature]: Add 3-tier model timeouts (total / first-token / stall) for streaming runs #19380 — stallTimeoutSeconds for streaming chunk gaps (model-level, not sub-agent tool calls)
• [Feature]: Per-session activity state (busy/idle + awaiting_user, awaiting_subagent) via gateway API + WS statechange #39127 — Per-session activity state tracking (lastRunActivityAt) — potential infrastructure for this
• [Feature]: Optional session activity watchdog and alerts (blocked by #39127) #39141 — Session activity watchdog and alerts