@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/claude-status-detectors.ts

@@ -0,0 +1,426 @@
+import { extractClaudeModelUnavailableMessage } from "@humwick/sdk";
+import type { PaneObservation, ProviderStatusUpdate } from "../adapter";
+import type { ClaudeClearSessionVerdict, ClaudeProbeActivity } from "./claude-session-probe";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+
+// LEGACY PANE-SCRAPE FALLBACK (#766/#768) — busy/idle is now driven primarily by
+// Claude Code's intrinsic session probe (readClaudeSessionStatusAsync, ./claude-session-probe):
+// `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` carries a machine-readable `status` field
+// on CC ≥2.1.119. These two pane heuristics are the SOLE fallback for pre-2.1.119 /
+// probe-missing sessions, and claudePaneLooksReady still backs the input-readiness gate
+// (waitForClaudeInputReady) + the prompt-gate busy guard — so they stay. They string-match
+// CC's TUI chrome against captured tmux scrollback (~80 lines), so they break whenever CC
+// restyles its footer/banner. Deliberately substring/regex based (no machine-readable
+// signal existed when these were written). Known break conditions, so the next CC restyle
+// is a fast fix rather than a hunt:
+//   readiness (claudePaneLooksReady) breaks if CC renames/removes ALL of: the
+//     "bypass permissions" / "shift+tab to cycle" / "? for shortcuts" footer hints,
+//     the "/effort" hint, or the "Welcome back" / "Claude Code" banner.
+//   busy (claudePaneIsBusy) breaks if CC drops BOTH the live "… (<elapsed>" spinner
+//     counter and the 2.1.218 "Thought for <elapsed> (ctrl+o to expand)" activity line
+//     (the "esc to interrupt" hint was already dropped in 2.1.x).
+//   FALSE POSITIVES: agent output that literally QUOTES any of these strings (e.g. a
+//     transcript discussing "esc to interrupt", or this very comment shown in a pane)
+//     reads as ready. Busy checks gate themselves on the LAST N lines (the live
+//     footer), including direct callers such as the prompt-gate guard.
+// History: 18067b5 (busy counter), and the readiness footer-vs-banner fix below.
+export function claudePaneLooksReady(text: string): boolean {
+  // A quoted dialog can remain above a LIVE composer. Its persistent footer is
+  // stronger evidence than modal text elsewhere in the visible pane.
+  if (text.includes("bypass permissions on") || text.includes("shift+tab to cycle")
+    || text.includes("? for shortcuts") || text.includes("/effort")) return true;
+  // The 2.1.282 bypass modal contains both "Claude Code" and "bypass permissions".
+  // Those generic readiness witnesses otherwise submit the initial prompt into the
+  // acceptance dialog instead of waiting for an input composer.
+  if (claudeBypassPermissionDialog(text)) return false;
+  // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
+  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
+  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
+  // renders at the prompt. Requiring the banner made every delivery after the first screen
+  // of output time out as "input not ready". Any one of these strong, Claude-specific
+  // markers means the TUI is up and the input box exists.
+  return text.includes("Welcome back")
+    || text.includes("Claude Code");
+}
+
+/** The visible 2.1.282 acceptance modal, before Claude has an input composer. */
+export function claudeBypassPermissionDialog(text: string): boolean {
+  return /running in Bypass Permissions mode/i.test(text)
+    && /^\s*[❯>]?\s*No, exit\s*$/im.test(text)
+    && /^\s*[❯>]?\s*Yes, I accept\s*$/im.test(text);
+}
+
+/** Adapter-owned copy for the startup modal's display-only blocked state. */
+export function claudeBypassDialogDisplayGate(sessionName: string, observedAt: number): NonNullable<PaneObservation["displayGate"]> {
+  return { phase: "show", timelineTitle: "Claude waiting at bypass permissions dialog", providerState: {
+    state: "blocked", reason: "permissionRequest", label: "Claude bypass acceptance dialog",
+    message: "Claude is waiting for Bypass Permissions acceptance in its terminal.",
+    source: `claude-pane:${sessionName}`,
+    recommendedAction: "Open the terminal and select Yes, I accept.", enteredAt: observedAt,
+  } };
+}
+
+// The live spinner: "✶ Perambulating… (2m 17s · ↓ 8.7k tokens)", "… (", optional hook or
+// tool status ("running PostToolUse hook · ", #3026), then "[Nh ][Nm ]Ns". Anchored on the
+// gerund ellipsis so it can't match the "… +N lines (ctrl+o to expand)" truncation marker,
+// the idle input box, or the "/btw … without interrupting Claude's current work" hint.
+const CLAUDE_BUSY_SPINNER_RE = /…\s*\((?:[^()\n]*·\s*)?(?:\d+h\s+)?(?:\d+m\s+)?\d+s\b/;
+// Claude Code 2.1.218 replaced the gerund spinner during its thinking phase with
+// "Thought for 13s (ctrl+o to expand)" (and, after a tool call starts,
+// "Thought for 12s, called callmux (ctrl+o to expand)"). The intrinsic session
+// probe remains the primary, version-robust activity source, but 2.1.218 can leave
+// that probe idle during this phase. Treat this live footer as a busy veto so a
+// monitorless worker cannot false-idle before its first assistant output.
+const CLAUDE_BUSY_THOUGHT_RE = /^\s*Thought for (?:\d+h\s+)?(?:\d+m\s+)?\d+s(?:,\s*called [^(\n]+)?\s*\(ctrl\+o to expand\)\s*$/im;
+const CLAUDE_ACTIVITY_FOOTER_LINES = 10;
+/** A full-row rule; the composer's input rows sit between two of them. */
+export const CLAUDE_COMPOSER_RULE_RE = /^\s*─{10,}\s*$/;
+// Input rows plus the two or three status rows under the composer; a taller composer falls back.
+const CLAUDE_COMPOSER_SEARCH_LINES = 30;
+const CLAUDE_ACTIVITY_BLOCK_MAX_LINES = 40;
+// A notification Claude right-aligns on the row above the composer ("You've used 80% of …").
+const CLAUDE_RIGHT_ALIGNED_NOTICE_RE = /^\s{20,}\S/;
+
+interface ClaudePaneRegions {
+  /** The composer and its status rows; without a recognizable composer, the last rows. */
+  footer: string;
+  /** The block right above the composer, where the live spinner or thinking row renders. */
+  activity?: string[];
+}
+
+// #2202 — find the composer instead of counting rows from the bottom. Inline rendering
+// (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN) pads the capture with blank rows below it, and a
+// completed "Thought for …" row can sit within any fixed window above it.
+function claudePaneRegions(text: string): ClaudePaneRegions {
+  const lines = text.trimEnd().split("\n");
+  const composer = claudeComposerRuleRow(lines);
+  if (composer === undefined) return { footer: lines.slice(-CLAUDE_ACTIVITY_FOOTER_LINES).join("\n") };
+  let row = composer - 1;
+  while (row >= 0 && (!lines[row]!.trim() || CLAUDE_RIGHT_ALIGNED_NOTICE_RE.test(lines[row]!))) row--;
+  const activity: string[] = [];
+  for (const floor = row - CLAUDE_ACTIVITY_BLOCK_MAX_LINES; row > floor && row >= 0 && lines[row]!.trim(); row--) activity.unshift(lines[row]!);
+  return { footer: lines.slice(composer).join("\n"), activity };
+}
+
+/** The rule row right above the composer's `❯` input row, searched near the bottom of the pane. */
+function claudeComposerRuleRow(lines: string[]): number | undefined {
+  for (let i = lines.length - 1; i >= Math.max(1, lines.length - CLAUDE_COMPOSER_SEARCH_LINES); i--) {
+    if (lines[i]!.trimStart().startsWith("❯") && CLAUDE_COMPOSER_RULE_RE.test(lines[i - 1]!)) return i - 1;
+  }
+  return undefined;
+}
+
+export function claudePaneIsBusy(text: string): boolean {
+  return claudeRegionsAreBusy(claudePaneRegions(text));
+}
+
+function claudeRegionsAreBusy({ footer, activity }: ClaudePaneRegions): boolean {
+  // Claude Code <2.1.x rendered "(esc to interrupt)" in the spinner footer; 2.1.x
+  // dropped that hint. Keep both older signals and the 2.1.218 thinking line so
+  // the pane veto works across those formats.
+  if (footer.includes("esc to interrupt")) return true;
+  if (!activity) return CLAUDE_BUSY_SPINNER_RE.test(footer) || CLAUDE_BUSY_THOUGHT_RE.test(footer);
+  // Rows rejoin so a counter Claude wrapped at a narrow width still reads (#3026). A thinking
+  // row is live only as the block's head: a completed one stays above "⎿ Interrupted" or output.
+  return CLAUDE_BUSY_SPINNER_RE.test(activity.join(" ")) || CLAUDE_BUSY_THOUGHT_RE.test(claudeActivityHead(activity));
+}
+
+/** The block's last row above any tip Claude prints under its spinner. */
+function claudeActivityHead(activity: string[]): string {
+  const tip = activity.findIndex((row) => /^\s*⎿\s+Tip:/.test(row));
+  return (tip >= 0 ? activity.slice(0, tip) : activity).at(-1) ?? "";
+}
+
+// #1588 — persistent TUI chrome that is present at the prompt regardless of whether a
+// conversation is loaded, so it must NEVER be picked as a pre-clear conversation anchor.
+// (Includes the claudePaneLooksReady footer markers plus the box/hint chrome around them.)
+const CLAUDE_CHROME_MARKERS = [
+  "bypass permissions",
+  "shift+tab to cycle",
+  "? for shortcuts",
+  "/effort",
+  "Welcome back",
+  "Claude Code",
+  "esc to interrupt",
+  "ctrl+o to expand",
+  "/btw",
+  "Tip:",
+  "Tips for getting started",
+];
+
+// #1588 — pick a distinctive line from the PRE-clear pane that belongs to the loaded
+// conversation body (not the persistent chrome/footer), so its DISAPPEARANCE after `/clear`
+// is positive evidence the conversation was actually wiped. claudePaneLooksReady alone can't
+// tell "before clear" from "after clear" — its footer markers are present in both — so the
+// self-resume barrier (waitForClaudeClearCommitted) keys off this anchor instead. Returns the
+// longest content-rich, chrome-free line, or undefined when the pane has no such line (e.g. an
+// already-empty conversation) — in which case the clear can't be positively confirmed and the
+// caller falls to continuationDelivered:false so the #1023 backstop covers it.
+export function claudeConversationAnchor(pane: string): string | undefined {
+  let best: string | undefined;
+  for (const raw of claudeConversationRows(pane)) {
+    const line = raw.trim();
+    if (line.length < 20) continue;
+    if (CLAUDE_CHROME_MARKERS.some((marker) => line.includes(marker))) continue;
+    // Require substantial alphanumeric content so a box-border / ASCII-art / punctuation
+    // line can never serve as the anchor (those can reappear on the fresh cleared screen).
+    const alnum = (line.match(/[A-Za-z0-9]/g) ?? []).length;
+    if (alnum < 12) continue;
+    if (!best || line.length > best.length) best = line;
+  }
+  return best;
+}
+
+const CLAUDE_BANNER_RE = /Claude Code v\d/;
+// A turn opens with the user's prompt or an assistant, tool or event bullet.
+const CLAUDE_TURN_ROW_RE = /^\s*[❯>⏺●]/;
+
+// #3151 — the rows `/clear` wipes: none of the startup header (banner, model, cwd, tip), which it
+// repaints, and nothing from the composer down, whose status rows change on their own.
+function claudeConversationRows(pane: string): string[] {
+  const lines = pane.trimEnd().split("\n");
+  const end = claudeComposerRuleRow(lines) ?? lines.length;
+  const banner = lines.findIndex((line) => CLAUDE_BANNER_RE.test(line));
+  if (banner < 0 || banner >= end) return lines.slice(0, end);
+  const start = lines.findIndex((line, row) => row > banner && row < end && CLAUDE_TURN_ROW_RE.test(line));
+  return start < 0 ? [] : lines.slice(start, end);
+}
+
+// #1588 — CLEAR-AWARE completion check for the self-resume barrier. The `/clear` keystroke is
+// async in the Claude TUI: submitTextToTmux returns as soon as the keys are typed, and the
+// persistent footer (claudePaneLooksReady) matches the STILL-UNCLEARED pane, so accepting the
+// first ready match let the continuation race the async clear and get wiped (the #1588 window).
+// A clear is treated as COMMITTED only with positive evidence: the pane is (a) not busy (the
+// clear/redraw finished processing), (b) back at the input-ready footer, and (c) no longer shows
+// the pre-clear conversation anchor (the loaded conversation is gone). Any of these missing →
+// NOT committed → keep waiting (and, on timeout, the caller reports continuationDelivered:false
+// so the backstop re-injects — uncertainty resolves toward the backstop, never toward a wipe).
+//
+// #2261 — the anchor test above is the FALLBACK signal, not the primary one, and `currentPane`
+// MUST be a VISIBLE-SCREEN capture (captureTmuxVisiblePaneAsync). Claude's `/clear` repaints only
+// the visible screen, so an anchor that had already scrolled into tmux history stays in a
+// scrollback capture forever and the barrier can never confirm a clear that plainly committed.
+export interface ClaudeClearEvidence {
+  /**
+   * #2261 — the intrinsic probe's verdict on Claude's session id (./claude-session-probe), ALREADY
+   * SETTLED by the caller across a poll interval. Default `unknown` (no probe / pre-2.1.119 /
+   * unreadable / liveness-failed / pid changed) keeps the pure anchor behavior.
+   */
+  session?: ClaudeClearSessionVerdict;
+  /** #2849 — pre-clear pane captured AND anchorless: vacuous clear, so idle+ready
+   * suffices. Never set from a failed capture — that stays fail-closed. */
+  preClearEmpty?: boolean;
+  /** #2849r1/#2850 — the poller saw a CLAUDE_VACUOUS_CLEAR_READY_POLLS idle+ready streak.
+   * A ready pane can predate the /clear commit (#1588), and with no probe verdict this
+   * streak is the only commit evidence. Set by the poller. */
+  settledReady?: boolean;
+}
+
+export function claudeClearCommitted(
+  preClearAnchor: string | undefined,
+  currentPane: string,
+  evidence: ClaudeClearEvidence = {},
+): boolean {
+  if (claudePaneIsBusy(currentPane)) return false;
+  if (!claudePaneLooksReady(currentPane)) return false;
+  // #2261 PRIMARY signal — machine-readable and version-robust: committing `/clear` mints a NEW
+  // Claude session (fresh sessionId + fresh transcript file), so a same-pid session rotation is
+  // direct proof the loaded conversation is gone, independent of any TUI chrome.
+  //
+  // It is authoritative in BOTH directions, and that is what keeps it a STRENGTHENING rather than
+  // a relaxation. `unchanged` means the probe positively says the clear has not committed, so it
+  // must VETO — never let the (visible-screen-only) anchor heuristic confirm over it, e.g. when
+  // unrelated output has merely scrolled the anchor off the screen. The busy/ready gates above
+  // still gate both verdicts, so the #1588 ordering property (never inject while the clear is
+  // still processing) is untouched. `unknown` is no evidence: it falls through to the anchor test,
+  // whose failure still resolves to false → the #1023 backstop re-injects.
+  if (evidence.session === "rotated") return true;
+  if (evidence.session === "unchanged") return false;
+  // #2849r1 — vacuous clear, BELOW the session veto: an unchanged session still
+  // refuses, and a lone ready poll may be the pre-clear footer (#1588), so both
+  // settledReady (a long consecutive-ready streak, #2850) and preClearEmpty are required.
+  if (evidence.preClearEmpty === true && evidence.settledReady === true) return true;
+  if (!preClearAnchor) return false;
+  return !currentPane.includes(preClearAnchor);
+}
+
+export interface ClaudeActivityReadOptions {
+  /** #1621: the probe's busy assertion predates an interrupt relay sent (claudeProbeVerdict),
+   *  so it may describe a turn that was cancelled. */
+  probeBusyStale?: boolean;
+  /**
+   * #1980 U2 — when the intrinsic session probe is UNAVAILABLE (pre-2.1.119 / unresolvable
+   * config-home), may a bare input-ready-looking pane be read as `idle`?
+   *   true  (default) — legacy pane-scrape turn-boundary detection (the monitorless turn-watch):
+   *                     an input-ready footer ends the turn.
+   *   false — the busy BACKSTOP path: an input-ready-looking footer is NOT positive evidence a
+   *           turn ended — a long foreground tool renders the exact same prompt box while fully
+   *           alive (#766/#1980) — so with no probe to corroborate it is SILENCE, reported as
+   *           `unknown` (the backstop holds the turn) rather than `idle` (which force-cancels it).
+   *           This is what stops the `no-busy-observed` false-cancel from ever being reached.
+   */
+  paneFallbackIsIdle?: boolean;
+}
+
+export function claudeActivityFromProbeAndPane(
+  probe: ClaudeProbeActivity | undefined,
+  pane: string,
+  opts: ClaudeActivityReadOptions = {},
+): ClaudeProbeActivity {
+  const regions = claudePaneRegions(pane);
+  // The pane's live activity is the strongest busy evidence there is and always wins.
+  if (claudeRegionsAreBusy(regions)) return "busy";
+  const ready = claudePaneLooksReady(regions.footer);
+  if (probe === "busy") {
+    // Probe-busy is authoritative (#766, #3026). Only after relay's own interrupt (#1621) may a
+    // positively input-ready footer overrule it; a shelled-out or unreadable pane keeps it busy.
+    return opts.probeBusyStale && ready ? "idle" : "busy";
+  }
+  // A probe-`idle` is the provider's OWN end-of-turn assertion (positive evidence); a positively
+  // input-ready pane corroborates it, an ambiguous pane holds as unknown.
+  if (probe === "idle") return ready ? "idle" : "unknown";
+  // probe is undefined/unknown here (unavailable, or Claude `waiting`): the pane-scrape fallback.
+  // #1980 U2 — an input-ready footer is only trustworthy as turn-end when the caller opts in
+  // (paneFallbackIsIdle, the turn-boundary path). For the busy backstop (opt-out) it is silence,
+  // held as `unknown`, so a live foreground tool the probe cannot see is never force-cancelled.
+  if (ready && (opts.paneFallbackIsIdle ?? true)) return "idle";
+  return "unknown";
+}
+
+// #286: detect the subscription usage-limit modal in the pane and turn it into the
+// provider-neutral rate-limit hold (idle + blocked) that the relay's resume sweep lifts
+// at reset. Unlike the pane model-rejection observation below, it remains a legacy status path.
+export function claudeRateLimitStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const parsed = parseClaudeRateLimitPane(text);
+  if (!parsed) return null;
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({
+      errorType: parsed.errorType ?? "session_limit", kind: parsed.kind ?? "usage_limit",
+      ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
+      message: parsed.message,
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+    }),
+  };
+}
+
+// #769 — detect the API connection-retry banner in the live terminal footer. Three stable
+// anchors from the banner text: "Unable to connect to API", "Retrying in <N>s",
+// "attempt <N>/<M>". Gated on the LAST N lines so agent output that merely QUOTES these
+// strings (e.g. quoting this comment, or a discussion of retry logic) doesn't false-positive —
+// the live banner always lives in the footer; quoted strings appear in the scrollback body.
+// Break condition: if CC renames/removes any anchor substring the detector stops firing — a
+// fast fix once the new footer wording is known, and one with no correctness consequence now
+// that this is advisory.
+//
+// #1651 — this returns a DIAGNOSTIC, not a status. It used to return
+// `status: "idle"` + `clear: ["subagent"]` + a blocked `conn_retry` providerState. The runner
+// treats an idle provider-turn as the turn ENDING (runner-core setProviderStatus), which
+// clears the work record and calls completeObservedTaskClaims(): retry chrome rendered in a
+// pane could therefore COMPLETE THE TASK CLAIMS OF A TURN THAT WAS STILL RUNNING. The footer
+// gate did not prevent this — the banner is genuinely in the footer during a live turn, which
+// is exactly when the detector fired.
+//
+// The turn stays live/unknown throughout the retries. Claude's own retry ladder is long
+// (measured at 179s for a refused connection), but lateness is not permission to infer failure
+// from pane text: only a correlated StopFailure may end the turn, after the native ladder
+// exhausts. Disappearance likewise proves nothing — it only clears the diagnostic flag.
+const CLAUDE_CONN_RETRY_FOOTER_LINES = 10;
+const CLAUDE_CONN_RETRY_ANCHOR_RE = /Unable to connect to API/;
+const CLAUDE_CONN_RETRY_RATE_RE = /Retrying in \d+s/;
+const CLAUDE_CONN_RETRY_ATTEMPT_RE = /attempt \d+\/\d+/;
+
+export function claudeConnectionRetryObservation(text: string, sessionName?: string, nowMs?: number): PaneObservation | null {
+  const footer = text.split("\n").slice(-CLAUDE_CONN_RETRY_FOOTER_LINES).join("\n");
+  if (
+    !CLAUDE_CONN_RETRY_ANCHOR_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_RATE_RE.test(footer) ||
+    !CLAUDE_CONN_RETRY_ATTEMPT_RE.test(footer)
+  ) return null;
+  return {
+    eventType: "claude.pane_connection_retry_candidate",
+    source: "pane",
+    detectorId: "connection-retry",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message: "Pane shows Claude's API connection-retry banner. Advisory only: the turn is unchanged.",
+  };
+}
+
+/** The falling edge. It used to publish a bare `idle` — an unconditional turn-end with no
+ *  evidence behind it at all. A banner leaving the footer proves nothing about the turn, so
+ *  this is a diagnostic too: it clears the caller's flag and says so. */
+export function claudeConnectionRetryClearedObservation(sessionName?: string, nowMs?: number): PaneObservation {
+  return {
+    eventType: "claude.pane_connection_retry_cleared",
+    source: "pane",
+    detectorId: "connection-retry",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message: "Pane no longer shows the connection-retry banner. Advisory only: proves nothing about the turn.",
+  };
+}
+
+// #1651 — this returns a DIAGNOSTIC, not a status. It used to return `status: "error"` +
+// `clear: ["provider-turn", "subagent"]` + a TERMINAL failed provider state + suppressed
+// restart from a single pane match — reproduced live: the harmless sentence "The test fixture
+// says: not an available model" triggered every one of those, from a pane, where the matched
+// text may simply be an agent quoting a fixture, a code comment, or this very file.
+//
+// A pane match is never terminal. Only a correlated StopFailure whose native error type
+// explicitly denotes model-not-found/unavailable (not yet wired — see #1651's Direction
+// section) may end a turn this way. This detector only notices.
+//
+// Scoped to the trailing modal/composer structural block: the same positional technique
+// rate-limit.ts's livePaneBlock uses (Claude Code pins its composer to the bottom of the
+// screen, separated from the conversation by a blank row, and draws blocking dialogs in that
+// same spot), reimplemented locally rather than importing that module's private helper. An
+// agent's own scrollback quoting/discussing the rejection text sits above the blank row and
+// so can never reach this scan.
+//
+// Repetition is the caller's job, not this function's: claude.ts requires the SAME message on
+// two consecutive polls before it will even publish the diagnostic — this stays pure so it can
+// be unit tested without threading adapter state through it.
+export function claudeModelUnavailableObservation(text: string, sessionName?: string, nowMs?: number): PaneObservation | null {
+  const block = trailingStructuralBlock(text);
+  const message = extractClaudeModelUnavailableMessage(block);
+  if (!message) return null;
+  return {
+    eventType: "claude.pane_model_unavailable_candidate",
+    source: "pane",
+    detectorId: "model-unavailable",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message,
+  };
+}
+
+export interface ClaudeModelUnavailableObservationState {
+  message?: string;
+  reported: boolean;
+}
+
+export function initialClaudeModelUnavailableObservationState(): ClaudeModelUnavailableObservationState {
+  return { reported: false };
+}
+
+/** Require two identical reads before a pane candidate reaches diagnostic telemetry. */
+export function debounceClaudeModelUnavailableObservation(
+  observation: PaneObservation | null,
+  state: ClaudeModelUnavailableObservationState,
+): { state: ClaudeModelUnavailableObservationState; observation?: PaneObservation } {
+  if (!observation?.message) return { state: initialClaudeModelUnavailableObservationState() };
+  if (state.message !== observation.message) return { state: { message: observation.message, reported: false } };
+  if (state.reported) return { state };
+  return { state: { ...state, reported: true }, observation };
+}
+
+function trailingStructuralBlock(text: string): string {
+  const lines = text.split(/\r?\n/);
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim() === "") end--;
+  let start = end;
+  while (start > 0 && lines[start - 1]!.trim() !== "") start--;
+  return lines.slice(start, end).join("\n");
+}

package/src/adapters/claude-subagents.ts

@@ -0,0 +1,93 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { harnessSubagentsEnabled } from "@humwick/sdk";
+import { claudeModelFamily, extractCallerSettings } from "../claude-settings";
+import { shellQuote } from "@humwick/sdk/shell-utils";
+import { resolve } from "node:path";
+import type { ProvisioningHookSet } from "@humwick/sdk";
+import type { RunnerSpawnConfig, SpawnArgs } from "../adapter";
+import { claudeVersionAtLeast } from "./claude-session-probe";
+
+export function claudeSubagentPolicy(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">) {
+  const options = config.agentProfile?.providerOptions?.claude;
+  if (!config.agentProfile || options?.subagentModel === null) return undefined;
+  return { model: options?.subagentModel ?? "sonnet", effort: options?.subagentMaxEffort ?? "high", contextTokens: options?.subagentContextTokens ?? 200_000 };
+}
+
+export function claudeSubagentEnv(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">): Record<string, string> {
+  const policy = claudeSubagentPolicy(config);
+  const enabled = writeChildEnv({}, { AGENT_RELAY_HARNESS_SUBAGENTS: harnessSubagentsEnabled(config) ? "1" : "0" });
+  return policy ? writeChildEnv({}, { ...enabled,
+    CLAUDE_CODE_SUBAGENT_MODEL: policy.model,
+    CLAUDE_CODE_SUBAGENT_MODEL_FORCE: "1",
+    CLAUDE_CODE_FORK_SUBAGENT: "0",
+    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "0",
+    CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
+    AGENT_RELAY_CLAUDE_SUBAGENT_CAP: "1",
+  }) : writeChildEnv({}, { ...enabled, AGENT_RELAY_CLAUDE_SUBAGENT_CAP: "0" });
+}
+
+export function claudeSubagentSettings(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile" | "model">): Record<string, unknown> {
+  const policy = claudeSubagentPolicy(config);
+  if (!policy) return harnessSubagentsEnabled(config) ? {} : { disableAllHooks: false };
+  const mainFamily = claudeModelFamily(config.model);
+  // Model settings apply to both parent and children, including canonicalized aliases (#3424).
+  const modelSettings = mainFamily && mainFamily !== policy.model
+    ? { [policy.model]: { maxEffortLevel: policy.effort, autoCompactWindow: policy.contextTokens } } : undefined;
+  return { disableAllHooks: false, ...(modelSettings ? { modelSettings } : {}), autoCompactEnabled: true };
+}
+
+// Always supplied through settings, including profiles with the Relay plugin switched off.
+export function claudeSubagentHooks(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">): ProvisioningHookSet {
+  const stop = { SubagentStop: [{ hooks: [{ type: "command" as const, command: `bash "${resolve(import.meta.dir, "../../plugins/claude/hooks/subagent-stop.sh")}"`, timeout: 5 }] }] };
+  if (harnessSubagentsEnabled(config) && !claudeSubagentPolicy(config)) return stop;
+  const guard = { type: "command" as const, command: `bun ${shellQuote(resolve(import.meta.dir, "../../plugins/claude/hooks/subagent-guard.cjs"))}`, timeout: 5, onFailure: "block" as const };
+  return { ...stop,
+    PreToolUse: [{ matcher: "Agent|Task|Skill|TeamCreate|TeamDelete|SendMessage|Workflow", hooks: [guard] }],
+    UserPromptExpansion: [{ hooks: [guard] }],
+    UserPromptSubmit: [{ hooks: [guard] }],
+  };
+}
+
+export function assertClaudeSubagentVersion(version: string): void {
+  if (!claudeVersionAtLeast(version, "2.1.296")) throw new Error(`Claude sub-agent caps require Claude Code >=2.1.296; installed: ${version || "unknown"}`);
+}
+
+export async function verifyClaudeSubagentVersion(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile" | "env" | "cwd">): Promise<void> {
+  if (!claudeSubagentPolicy(config)) return;
+  const child = Bun.spawn(["claude", "--version"], { cwd: config.cwd, env: config.env, stdout: "pipe", stderr: "pipe", timeout: 10_000 });
+  const [stdout, stderr, exit] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (exit !== 0) throw new Error(`Cannot verify Claude sub-agent cap support: ${stderr.trim() || exit}`);
+  assertClaudeSubagentVersion(stdout.trim());
+}
+
+// Pass source locations to the runtime resolver; never inspect skill definitions at launch.
+export function configureClaudeSubagentLaunch(config: Pick<RunnerSpawnConfig, "harnessSubagents" | "agentProfile">, launch: Pick<SpawnArgs, "args" | "env" | "cwd">): void {
+  if (harnessSubagentsEnabled(config) && !claudeSubagentPolicy(config)) return;
+  const values = (flag: string, variadic = false) => {
+    const out: string[] = [];
+    for (let i = 0; i < launch.args.length; i++) {
+      const arg = launch.args[i]!;
+      if (arg.startsWith(`${flag}=`)) out.push(arg.slice(flag.length + 1));
+      else if (arg === flag) do {
+        if (!launch.args[i + 1] || launch.args[i + 1]!.startsWith("-")) break;
+        out.push(launch.args[++i]!);
+      } while (variadic);
+    }
+    return out;
+  };
+  if (launch.args.some((arg) => /^--(?:bare|safe-mode|autocompact)(?:=|$)/.test(arg))) {
+    throw new Error("Capped Claude profiles cannot use --bare, --safe-mode or --autocompact; they suppress mandatory hooks or override compaction policy");
+  }
+  if (["CLAUDE_CODE_SIMPLE", "CLAUDE_CODE_SAFE_MODE"].some((key) => ["1", "true"].includes(relayEnv(launch.env, key) ?? ""))) throw new Error("Capped Claude profiles cannot suppress mandatory hooks through ambient bare or safe mode");
+  const sources = (values("--setting-sources").at(-1) ?? "user,project,local").split(",");
+  if (!sources.includes("user")) throw new Error("Capped Claude profiles require user settings to load mandatory hooks");
+  const settings = extractCallerSettings([launch.args], launch.cwd)?.settings ?? {};
+  const callerEnv = settings.env as Record<string, unknown> | undefined;
+  const protectedEnv = [...Object.keys(claudeSubagentEnv(config)), "CLAUDE_CODE_SIMPLE", "CLAUDE_CODE_SAFE_MODE", "CLAUDE_CODE_AUTO_COMPACT_WINDOW", "DISABLE_AUTO_COMPACT", "AGENT_RELAY_CLAUDE_SKILL_SOURCES"];
+  if (callerEnv && protectedEnv.some((key) => key in callerEnv)) throw new Error("Capped Claude profiles cannot override child policy through --settings env");
+  writeChildEnv(launch.env, { AGENT_RELAY_CLAUDE_SKILL_SOURCES: JSON.stringify({ cwd: launch.cwd,
+    sources,
+    directories: values("--add-dir", true), plugins: values("--plugin-dir", true),
+    settings: { enabledPlugins: settings.enabledPlugins, skillOverrides: settings.skillOverrides },
+  }) });
+}