@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/claude-prompt-gates.ts

@@ -0,0 +1,269 @@
+import { isRecord } from "@humwick/sdk";
+import type { PaneObservation, RunnerSpawnConfig } from "../adapter";
+import { claudeTrustProjectKeys } from "../claude-workspace-trust";
+import { claudeBypassPermissionDialog } from "./claude-status-detectors";
+
+export interface ClaudeConfigPromptGatePrevention {
+  id: string;
+  description: string;
+  apply(seed: Record<string, unknown>, context: { host?: Record<string, unknown>; config: RunnerSpawnConfig }): void;
+}
+
+export interface ClaudeLaunchPromptGatePrevention {
+  id: string;
+  description: string;
+  apply(config: RunnerSpawnConfig): { strictMcpConfig?: boolean };
+}
+
+type PaneGateMatch = { message?: string };
+
+/**
+ * #1651 — how much authority a pane match is allowed to carry.
+ *
+ * `advisory` is the only correct value for a gate detected purely from TUI geometry. It
+ * produces a {@link PaneObservation} and NOTHING else: no keystroke (the concept no longer
+ * exists in this file), no ProviderStatusUpdate, hence no status, no `clear`, no
+ * providerState. #1611/#1615/#1621/#1637/#1642 each tried to make one of these gates safe by
+ * tightening its string matcher; the matcher was never the problem — granting a string match
+ * the authority to mutate state was.
+ *
+ * The retired usage-limit pane gate (#1664) is deliberately not represented here: provider
+ * state comes from structured provider failures, never a pane scrape.
+ */
+
+interface ClaudePanePromptGate {
+  id: string;
+  label: string;
+  policy: string;
+  minDetections: number;
+  match(text: string): PaneGateMatch | null;
+}
+
+export interface ClaudePromptGatePaneState {
+  currentGateId?: string;
+  consecutiveDetections: number;
+  handledGateId?: string;
+}
+
+export interface ClaudePromptGatePaneContext {
+  sessionName?: string;
+  busy?: boolean;
+  nowMs?: number;
+  sourceId?: string;
+}
+
+export interface ClaudePromptGatePaneResult {
+  /** #1651 — always present when a gate reached minDetections. Diagnostic only. */
+  observation?: PaneObservation;
+  /** Kept for callers which assert absence; `never` makes a status impossible to emit. */
+  status?: never;
+  state: ClaudePromptGatePaneState;
+}
+
+export const claudeConfigPromptGatePreventions: ClaudeConfigPromptGatePrevention[] = [
+  {
+    id: "first-run-onboarding",
+    description: "Pre-accept Claude Code's first-run onboarding gate.",
+    apply(seed, { host }) {
+      seed.hasCompletedOnboarding = true;
+      if (typeof host?.lastOnboardingVersion === "string") seed.lastOnboardingVersion = host.lastOnboardingVersion;
+    },
+  },
+  {
+    id: "theme-selection",
+    description: "Pre-seed a theme so the first-run theme picker does not render.",
+    apply(seed, { host }) {
+      seed.theme = typeof host?.theme === "string" ? host.theme : "dark";
+    },
+  },
+  {
+    id: "bypass-permissions-mode",
+    description: "Pre-accept Claude's open-approval bypass-permissions modal.",
+    apply(seed, { config }) {
+      if (config.approvalMode === "open") seed.bypassPermissionsModeAccepted = true;
+    },
+  },
+  {
+    id: "workspace-trust",
+    description: "Trust the managed spawn cwd and clear project onboarding.",
+    apply(seed, { config }) {
+      // #2254 — seed EVERY key CC may resolve this cwd under (lexical, realpath, git
+      // canonical root), not just the lexical worktree path. Host-base launches, which
+      // never reach this seed, get the same keys written into the shared config by
+      // ensureClaudeWorkspaceTrust on the launch path.
+      const keys = claudeTrustProjectKeys(config.cwd);
+      if (!keys.length) return;
+      const projects: Record<string, unknown> = { ...(isRecord(seed.projects) ? seed.projects : {}) };
+      for (const key of keys) {
+        projects[key] = { ...(isRecord(projects[key]) ? projects[key] : {}), hasTrustDialogAccepted: true, hasCompletedProjectOnboarding: true };
+      }
+      seed.projects = projects;
+    },
+  },
+];
+
+export const claudeLaunchPromptGatePreventions: ClaudeLaunchPromptGatePrevention[] = [
+  {
+    id: "project-mcp-discovery",
+    description: "Use strict controlled MCP config so Claude never prompts for ambient project .mcp.json servers.",
+    apply() {
+      return { strictMcpConfig: true };
+    },
+  },
+];
+
+// Every wording CC has shipped for the folder-trust modal: the pre-2.1 phrasing plus the
+// 2.1.233 rewrite (header, question, and affirmative option). Stateless — no /g flag.
+const WORKSPACE_TRUST_PROMPT = /do you trust (?:the files in )?(?:this folder|this project|this directory)|accessing workspace|quick safety check|yes,? ?I trust this folder/i;
+
+const panePromptGates: ClaudePanePromptGate[] = [
+  // #1651 — the five gates below are ADVISORY. Each used to type a key into a live pane the
+  // instant `claudePaneIsBusy` happened to read false, then publish a fabricated
+  // idle + clear:["subagent"]. Two independent hazards, both realized:
+  //   - the four Enter gates SUBMIT whatever text is already sitting in the composer;
+  //   - project-mcp-discovery's Escape CANCELS a live turn.
+  // Neither needed the matcher to be wrong. `claudePaneIsBusy` is a last-ten-lines scrape
+  // whose only busy witness sits on the very last budgeted line, so one extra row of bottom
+  // chrome (a wrapped advisory, a two-line composer, one more trailing blank) flips it to
+  // false ON A LIVE TURN — measured on CC 2.1.220. A persistent ready-looking footer is not
+  // an authorization boundary, so none of these may hold one.
+  // Real startup modals are already prevented structurally, before launch, by
+  // claudeConfigPromptGatePreventions / claudeLaunchPromptGatePreventions above; these
+  // entries are the backstop that NOTICES a prevention missed, not a second actuator.
+  {
+    id: "workspace-trust",
+    label: "Workspace trust",
+    policy: "accept-trusted-workspace",
+    minDetections: 2,
+    // #2254 — CC 2.1.233 reworded this modal ("Accessing workspace" / "Quick safety check:
+    // Is this a project you created or one you trust?" / "Yes, I trust this folder"), so the
+    // old "do you trust this folder" matcher never fired and the wedge was silent. Both
+    // wordings are matched now. Still ADVISORY (see the block comment above): the actual
+    // prevention is the pre-launch trust seed, this only makes a missed seed observable.
+    match: (text) => WORKSPACE_TRUST_PROMPT.test(text) && /\b(?:yes|proceed|trust|continue)\b/i.test(text)
+      ? { message: lineMatching(text, WORKSPACE_TRUST_PROMPT) }
+      : null,
+  },
+  {
+    id: "bypass-permissions-mode",
+    label: "Bypass permissions mode",
+    policy: "accept-configured-open-approval",
+    minDetections: 2,
+    match: (text) => claudeBypassPermissionDialog(text)
+      ? { message: lineMatching(text, /bypass permissions mode/i) }
+      : null,
+  },
+  {
+    id: "project-mcp-discovery",
+    label: "Project MCP discovery",
+    policy: "reject-ambient-project-mcp",
+    minDetections: 2,
+    match: (text) => /\bnew MCP servers? found\b/i.test(text) && /\b(?:select|enable|servers?)\b/i.test(text)
+      ? { message: lineMatching(text, /new MCP servers? found/i) }
+      : null,
+  },
+  {
+    id: "theme-selection",
+    label: "Theme selection",
+    policy: "accept-default-theme",
+    minDetections: 2,
+    match: (text) => /choose (?:the )?(?:text style|theme).*Claude Code/i.test(text) && /\b(?:dark|light) mode\b/i.test(text)
+      ? { message: lineMatching(text, /choose/i) }
+      : null,
+  },
+  {
+    id: "first-run-onboarding",
+    label: "First-run onboarding",
+    policy: "accept-onboarding",
+    minDetections: 2,
+    match: (text) => /welcome to Claude Code/i.test(text) && /\b(?:let'?s get started|continue|get started)\b/i.test(text)
+      ? { message: lineMatching(text, /welcome to Claude Code/i) }
+      : null,
+  },
+  // #1514 (review finding 3) — the "Exit anyway / Move to background / Stay"
+  // confirmation is deliberately NOT a live pane-watcher gate. Auto-pressing Enter
+  // on a session that did NOT initiate shutdown is unsafe: it could submit stray
+  // input or dismiss an unrelated modal on an attached/live session. This dialog is
+  // only ever the right thing to answer under an explicit Relay shutdown, so it is
+  // handled solely by the runner's shutdown grace loop (confirmClaudeExitDialogUnderGrant
+  // in claude-exit.ts) — which runs only after this runner sent `/exit` under a one-shot
+  // grant. #1647 made that structural rather than advisory: this file cannot even import
+  // the exit writers (claude-exit.guard.test.ts fails the build if it ever does). The
+  // orphan safety net for a session already wedged mid-shutdown is the orchestrator's
+  // wedged-session reaper, not a keypress into a live pane.
+];
+
+export function applyClaudeConfigPromptGatePreventions(
+  seed: Record<string, unknown>,
+  host: Record<string, unknown> | undefined,
+  config: RunnerSpawnConfig,
+): Record<string, unknown> {
+  const next = { ...seed };
+  for (const prevention of claudeConfigPromptGatePreventions) prevention.apply(next, { host, config });
+  return next;
+}
+
+export function claudeLaunchPromptGateSettings(config: RunnerSpawnConfig): { strictMcpConfig: boolean } {
+  return {
+    strictMcpConfig: claudeLaunchPromptGatePreventions.some((prevention) => prevention.apply(config).strictMcpConfig === true),
+  };
+}
+
+export function initialClaudePromptGatePaneState(): ClaudePromptGatePaneState {
+  return { consecutiveDetections: 0 };
+}
+
+export function evaluateClaudePromptGatePane(
+  text: string,
+  state: ClaudePromptGatePaneState,
+  context: ClaudePromptGatePaneContext = {},
+): ClaudePromptGatePaneResult {
+  const detected = firstDetectedPaneGate(text);
+  if (!detected) return { state: initialClaudePromptGatePaneState() };
+  if (context.busy) {
+    return { state: { ...state, currentGateId: undefined, consecutiveDetections: 0 } };
+  }
+  if (state.handledGateId === detected.entry.id) {
+    return { state };
+  }
+
+  const consecutiveDetections = state.currentGateId === detected.entry.id ? state.consecutiveDetections + 1 : 1;
+  const nextState: ClaudePromptGatePaneState = {
+    currentGateId: detected.entry.id,
+    consecutiveDetections,
+    ...(state.handledGateId ? { handledGateId: state.handledGateId } : {}),
+  };
+  if (consecutiveDetections < detected.entry.minDetections) return { state: nextState };
+
+  const observedAt = context.nowMs ?? Date.now();
+  const observation: PaneObservation = {
+    eventType: "claude.pane_gate_candidate",
+    source: "pane",
+    detectorId: detected.entry.id,
+    observedAt,
+    ...(context.sessionName ? { sessionName: context.sessionName } : {}),
+    ...(detected.match.message ? { message: detected.match.message } : {}),
+    detail: { label: detected.entry.label, policy: detected.entry.policy, paneSource: paneSource(context) },
+  };
+  return {
+    observation,
+    state: { ...nextState, handledGateId: detected.entry.id },
+  };
+}
+
+function paneSource(context: ClaudePromptGatePaneContext): string {
+  const source = context.sourceId ?? "claude-pane";
+  return context.sessionName ? `${source}:${context.sessionName}` : source;
+}
+
+function firstDetectedPaneGate(text: string): { entry: ClaudePanePromptGate; match: PaneGateMatch } | null {
+  for (const entry of panePromptGates) {
+    const match = entry.match(text);
+    if (match) return { entry, match };
+  }
+  return null;
+}
+
+function lineMatching(text: string, pattern: RegExp): string | undefined {
+  return text.split(/\r?\n/).map((line) => line.trim()).find((line) => pattern.test(line));
+}

package/src/adapters/claude-prompt-hook.ts

@@ -0,0 +1,145 @@
+// #2664 — Claude's UserPromptSubmit hook fires only when Claude accepts an Enter: at queue time
+// for a busy agent and never again on dequeue, and not at all for a swallowed Enter. A matching
+// hook fired after our Enter is therefore the acceptance proof; the composer read is only a fallback.
+
+// Transport changes observed on Claude Code 2.1.284-2.1.285, and nothing else: image paths it attached
+// become leading [Image #N] chips, and a long paste arrives inside a <pasted_content> wrapper, even
+// a single-line one (#3081). The whitespace around the wrapper and its body varies by release, so
+// both are compared trimmed.
+// Image pastes also collapse blank-line runs (including the runner's attachment separator).
+const LEADING_IMAGE_CHIPS = /^(?:\[Image #\d+\])+/;
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|webp)$/i;
+const PASTED_CONTENT = /^\s*<pasted_content id="([^"]*)">([\s\S]*)<\/pasted_content id="\1">\s*$/;
+
+function sameText(hook: string, sent: string): boolean {
+  return hook === sent || (hook.trim() !== "" && hook.trim() === sent.trim());
+}
+
+interface Span { start: number; end: number }
+
+/** Every whole-token occurrence of one of OUR image attachment paths, with the one space Claude removes before it. */
+function attachmentSpans(sent: string, imagePaths: readonly string[]): Span[] {
+  const spans: Span[] = [];
+  for (const path of new Set(imagePaths.filter((path) => IMAGE_FILE.test(path)))) {
+    for (let at = sent.indexOf(path); at >= 0; at = sent.indexOf(path, at + 1)) {
+      const end = at + path.length;
+      if ((at > 0 && !/\s/.test(sent[at - 1]!)) || (end < sent.length && !/\s/.test(sent[end]!))) continue;
+      spans.push({ start: at > 0 && sent[at - 1] === " " ? at - 1 : at, end });
+    }
+  }
+  return spans.sort((a, b) => a.start - b.start).filter((span, i, all) => i === 0 || span.start >= all[i - 1]!.end);
+}
+
+/**
+ * Whether dropping exactly `k` of `spans` from `sent` leaves `body`, with blank-line runs
+ * collapsed on both sides and the same edge trimming as sameText. A DP over
+ * (span, dropped, matched) instead of enumerating subsets, so the work stays polynomial.
+ */
+function matchesWithoutSpans(body: string, sent: string, spans: Span[], k: number): boolean {
+  const trimmed = body.trim() !== "";
+  const target = (trimmed ? body.trim() : body).replace(/\n{2,}/g, "\n");
+  const feed = (from: number, to: number, matched: number): number => {
+    for (let i = from; i < to; i++) {
+      const ch = sent[i]!;
+      if (trimmed && /\s/.test(ch) && (matched === 0 || matched === target.length)) continue;
+      // Collapse as we feed so removing an image-only line also joins newline runs correctly.
+      if (ch === "\n" && matched > 0 && target[matched - 1] === "\n") continue;
+      if (matched >= target.length || target[matched] !== ch) return -1;
+      matched++;
+    }
+    return matched;
+  };
+  const seen = new Set<string>();
+  const walk = (index: number, from: number, dropped: number, matched: number): boolean => {
+    const key = `${index},${dropped},${matched}`;
+    if (dropped > k || seen.has(key)) return false;
+    seen.add(key);
+    const span = spans[index];
+    const upto = feed(from, span ? span.start : sent.length, matched);
+    if (upto < 0) return false;
+    if (!span) return dropped === k && upto === target.length;
+    if (walk(index + 1, span.end, dropped + 1, upto)) return true;
+    const kept = feed(span.start, span.end, upto);
+    return kept >= 0 && walk(index + 1, span.end, dropped, kept);
+  };
+  return walk(0, 0, 0, 0);
+}
+
+/**
+ * Raw whole-prompt equality first, then only the evidenced transport changes; never a substring.
+ * Only `imagePaths` (the attachments this submit carried) can become chips; literal paths in the
+ * text are never candidates.
+ */
+export function claudeHookPromptMatches(hookPrompt: string, submitted: string, imagePaths: readonly string[] = []): boolean {
+  const hook = hookPrompt.replace(/\r\n?/g, "\n");
+  const sent = submitted.replace(/\r\n?/g, "\n");
+  if (hook.trim() === "") return false;
+  if (sameText(hook, sent)) return true;
+  const chips = LEADING_IMAGE_CHIPS.exec(hook)?.[0] ?? "";
+  const images = chips.split("[").length - 1;
+  let body = hook.slice(chips.length);
+  const wrapped = PASTED_CONTENT.exec(body);
+  if (wrapped) body = wrapped[2]!;
+  if (images === 0) return wrapped !== null && sameText(body, sent);
+  const spans = attachmentSpans(sent, imagePaths);
+  return images <= spans.length && matchesWithoutSpans(body, sent, spans, images);
+}
+
+export interface ClaudePromptHookExpectation {
+  /** Hooks count only from now on; call right before the first Enter. Idempotent. */
+  arm(): void;
+  accepted(): boolean;
+  /** Resolves true as soon as a matching hook arrives, or with the current state after `ms`. */
+  wait(ms: number): Promise<boolean>;
+  release(): void;
+}
+
+interface PendingPrompt { text: string; imagePaths: readonly string[]; hit: boolean; armedAt?: number; wake?: () => void }
+
+/**
+ * One expectation per session at a time (submits are serialized behind the submit fence). A hook
+ * counts only if stamped as fired at or after arm(): a delayed earlier hook cannot vouch for our
+ * Enter, and an unstamped one's arrival time says nothing about when Claude accepted.
+ */
+export class ClaudePromptHookLedger {
+  private pending?: PendingPrompt;
+  private stampedHookSeen = false;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** A stamped hook has reached the runner, so the hook path works in this Claude's environment. */
+  get hookPathVerified(): boolean { return this.stampedHookSeen; }
+
+  /** SessionStart's stamped check-in: evidence of a working hook path before the first prompt. */
+  hookCheckedIn(firedAt: number | undefined): void {
+    if (firedAt !== undefined) this.stampedHookSeen = true;
+  }
+
+  /** An Enter went unconfirmed by any hook: the path may have broken, so re-verify before trusting it. */
+  hookPathLost(): void { this.stampedHookSeen = false; }
+
+  expect(text: string, imagePaths: readonly string[] = []): ClaudePromptHookExpectation {
+    const entry: PendingPrompt = { text, imagePaths, hit: false };
+    this.pending = entry;
+    return {
+      arm: () => { entry.armedAt ??= this.now(); },
+      accepted: () => entry.hit,
+      wait: (ms) => entry.hit ? Promise.resolve(true) : new Promise<boolean>((resolve) => {
+        const timer = setTimeout(() => { entry.wake = undefined; resolve(entry.hit); }, ms);
+        entry.wake = () => { clearTimeout(timer); entry.wake = undefined; resolve(true); };
+      }),
+      release: () => { if (this.pending === entry) this.pending = undefined; },
+    };
+  }
+
+  /** `firedAt` is when the hook ran (epoch ms). Returns "unstamped" when the hook carried none. */
+  observe(prompt: string, firedAt: number | undefined): "unstamped" | void {
+    if (firedAt === undefined) return "unstamped";
+    this.stampedHookSeen = true;
+    const entry = this.pending;
+    if (!entry || entry.hit || entry.armedAt === undefined) return;
+    if (firedAt < entry.armedAt || !claudeHookPromptMatches(prompt, entry.text, entry.imagePaths)) return;
+    entry.hit = true;
+    entry.wake?.();
+  }
+}