agent-relay-runner 0.127.6 → 0.127.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.127.6",
+  "version": "0.127.8",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.127.6",
+  "version": "0.127.8",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -92,6 +92,11 @@ export interface ProviderSessionTurnContext {
 
 export interface ProviderSessionTurnResult {
   reasoningSettled?: boolean;
+  // The transcript-embedded event time of the exact tool_use anchor that triggered this
+  // pre-flush harvest (when resolvable) — a more accurate stamp for a resolved permission
+  // prompt's display ordering than the hook's own wall-clock receipt time, which a provider
+  // can flush/timestamp its transcript entry after.
+  toolUseOccurredAt?: number;
 }
 
 export interface ProviderUserPromptInput {
@@ -124,6 +129,11 @@ export interface ProviderPermissionPromptHandler {
   buildView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt;
   buildHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown>;
   buildResolvedPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt;
+  // #1173: for prompt kinds whose PreToolUse hook is answered immediately (deny-then-hold —
+  // see control-server.ts's AskUserQuestion branch) rather than held open for the decision,
+  // this renders the eventual "answer" decision as the normal user-prompt text to inject back
+  // into the session. Absent for prompt kinds that still ride the hook response directly.
+  buildAnswerInjectionPrompt?(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string;
 }
 
 export interface ProviderConfig {

package/src/adapters/claude-permission.ts

@@ -12,6 +12,7 @@ export const claudePermissionPromptHandler: ProviderPermissionPromptHandler = {
   buildView: claudePermissionApprovalView,
   buildHookResponse: claudePermissionHookResponse,
   buildResolvedPrompt: claudeResolvedPermissionPrompt,
+  buildAnswerInjectionPrompt: claudeAnswerInjectionPrompt,
 };
 
 function claudePermissionApprovalView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt {
@@ -155,6 +156,23 @@ function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: Provi
   };
 }
 
+// #1173: AskUserQuestion's PreToolUse hook is answered with `deny` immediately (see
+// control-server.ts) so Claude flushes its buffered reasoning instead of blocking on the human.
+// The user's actual answer arrives afterward as a normal injected prompt, not as a hook
+// response — this renders that prompt's text from the same view/decision shape the old
+// blocking flow used, so the model sees a clear, structured hand-off instead of silence.
+function claudeAnswerInjectionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string {
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const questions = Array.isArray(view.questions) ? view.questions : Array.isArray(toolInput.questions) ? toolInput.questions : undefined;
+  const rows = resolvedQuestionRows(questions, decision.answers, "(no answer given)");
+  const qa = rows.map((row) => `Q: ${row.question}\nA: ${row.answer}`).join("\n\n");
+  return [
+    "This was answered by the user via the Agent Relay dashboard — the AskUserQuestion tool call itself was intercepted and will not resolve; it will not return a result. Here is their answer:",
+    qa,
+    "Continue the task using their answer(s) above — do not call AskUserQuestion again for the same question(s), and do not wait for the original tool call to return.",
+  ].join("\n\n");
+}
+
 function claudeResolvedPermissionBody(input: { kind: string; title: string; toolName: string; promptBody: string; decisionLabel: string; questions?: unknown[]; answers?: Record<string, string> }): string {
   if (input.kind === "questions") {
     return [

package/src/adapters/claude-session-capture.ts

@@ -13,6 +13,7 @@ import {
   stepDedupKeys,
   transcriptHasToolUseAnchor,
   transcriptLooksComplete,
+  transcriptToolUseOccurredAt,
 } from "./claude-transcript";
 import { IncrementalClaudeTranscriptTail } from "./claude-transcript-tail";
 
@@ -23,10 +24,22 @@ interface ReasoningTailState {
 }
 
 const REASONING_POLL_MS = 1_200;
+// Bounded the same way as control-server.ts's resolvedApprovals so a long session's dedup
+// guard (see emittedStepKeys) can't grow without limit.
+const EMITTED_STEP_KEY_LIMIT = 2048;
 
 export class ClaudeSessionCapture {
   private narrativeFlushEntryCount = 0;
   private reasoningTail?: ReasoningTailState;
+  // Step signatures already published to chat — by the deny-then-hold pre-flush harvest or a
+  // prior reasoning-tail instance — kept for the life of this capture (not reset when a new
+  // tail starts). A fresh tail is created on every new prompt (see startReasoningTail),
+  // including the runner's own injected AskUserQuestion answer; it re-reads the transcript
+  // from byte 0 and recomputes "latest turn" steps from scratch, so if that first poll lands
+  // before the injected prompt's own transcript entry has advanced the "latest turn" window,
+  // it can re-derive the exact same step signatures the earlier tail already emitted. Seeding
+  // each new tail's `seen` set from this closes that gap regardless of the exact timing.
+  private emittedStepKeys = new Set<string>();
   private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
   private sessionEventsCb: (events: ProviderSessionEventBatch) => void = (events) => { for (const event of events) this.sessionEventCb(event); };
 
@@ -55,7 +68,8 @@ export class ClaudeSessionCapture {
         (ok) => { if (!ok) ctx.log(`pre-flush session outbox incomplete before blocking control (${ctx.pendingSessionEventCount()} pending)`); },
         (error) => ctx.log(`pre-flush session outbox failed before blocking control: ${errMessage(error)}`),
       );
-      return { reasoningSettled: settled.settled };
+      const toolUseOccurredAt = input.toolName ? transcriptToolUseOccurredAt(jsonl, input.toolName, input.toolInput) : undefined;
+      return { reasoningSettled: settled.settled, ...(toolUseOccurredAt ? { toolUseOccurredAt } : {}) };
     }
 
     const turnId = input.promptId ?? ctx.turnId;
@@ -129,7 +143,7 @@ export class ClaudeSessionCapture {
   private startReasoningTail(transcriptPath: string, ctx: ProviderSessionTurnContext): void {
     if (ctx.reasoningCapture === false) return;
     this.stopSessionTrace();
-    const seen = new Set<string>();
+    const seen = new Set<string>(this.emittedStepKeys);
     const emittedNarrationKeys = new Set<string>();
     const transcriptTail = new IncrementalClaudeTranscriptTail();
     const turnIdAtStart = ctx.turnId;
@@ -153,6 +167,7 @@ export class ClaudeSessionCapture {
       for (const { sig, step } of keyed) {
         if (seen.has(sig)) continue;
         seen.add(sig);
+        this.rememberEmittedStepKey(sig);
         emitted += 1;
         events.push({
           type: step.type,
@@ -177,6 +192,16 @@ export class ClaudeSessionCapture {
     void poll();
   }
 
+  private rememberEmittedStepKey(sig: string): void {
+    this.emittedStepKeys.delete(sig);
+    this.emittedStepKeys.add(sig);
+    while (this.emittedStepKeys.size > EMITTED_STEP_KEY_LIMIT) {
+      const oldest = this.emittedStepKeys.values().next().value;
+      if (oldest === undefined) break;
+      this.emittedStepKeys.delete(oldest);
+    }
+  }
+
   private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
     const tail = this.reasoningTail;
     if (!tail || !tail.emittedNarrationKeys.size) return false;

package/src/adapters/claude-tmux.ts

@@ -0,0 +1,133 @@
+// Claude tmux transport plumbing (extracted from ./claude for the file-size
+// ratchet, #300/#291): session/socket naming, pane capture, input-ready gating,
+// paste/submit injection, launcher-script materialization, and env-key selection.
+// The adapter (./claude) keeps the lifecycle decisions; this module owns the
+// mechanical tmux interactions they ride on. Public symbols are re-exported from
+// ./claude so existing import paths (including claude.test.ts) keep resolving.
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
+import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { claudePaneLooksReady } from "./claude-status-detectors";
+import { launcherScriptPathForSession } from "../session-scratch";
+
+export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
+export const CLAUDE_TMUX_SUBMIT_KEY = "C-m";
+export const CLAUDE_TMUX_READY_TIMEOUT_MS = 10_000;
+
+export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
+  if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
+  return `${prefix}-${instanceId.slice(0, 8)}`;
+}
+
+export function tmuxSocketName(sessionName: string): string {
+  const socketName = sanitizeFsName(`agent-relay-${sessionName}`, { replacement: "-", collapse: false, lowercase: true });
+  assertTmuxSocketPathFits(socketName);
+  return socketName;
+}
+
+export function tmuxSocketPath(socketName: string, socketDir = defaultTmuxSocketDir()): string {
+  return join(socketDir, socketName);
+}
+
+export function assertTmuxSocketPathFits(socketName: string, socketDir = defaultTmuxSocketDir()): void {
+  const path = tmuxSocketPath(socketName, socketDir);
+  const bytes = Buffer.byteLength(path);
+  if (bytes < 108) return;
+  throw new Error(`derived name too long for tmux socket; pass a short \`label\` (socket path is ${bytes} bytes; must be < 108)`);
+}
+
+function defaultTmuxSocketDir(): string {
+  const base = process.env.TMUX_TMPDIR || "/tmp";
+  const uid = typeof process.getuid === "function" ? process.getuid() : "user";
+  return join(base, `tmux-${uid}`);
+}
+
+export function captureTmuxPane(sessionName: string, socketName?: string): string {
+  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-t", sessionName, "-S", "-80"), {
+    stdin: "ignore", stdout: "pipe", stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(`tmux capture-pane failed: ${stderr || `exit code ${result.exitCode}`}`);
+  }
+  return result.stdout.toString();
+}
+
+export async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!tmuxHasSession(sessionName, socketName)) throw new Error("tmux session exited before Claude became ready");
+    if (claudePaneLooksReady(captureTmuxPane(sessionName, socketName))) return;
+    await Bun.sleep(200);
+  }
+  throw new Error(`Claude input was not ready within ${timeoutMs}ms`);
+}
+
+function pasteTextIntoTmux(sessionName: string, text: string, socketName?: string): void {
+  const bufferName = `agent-relay-${crypto.randomUUID()}`;
+  const setResult = Bun.spawnSync(tmuxCommand(socketName, "set-buffer", "-b", bufferName, text), {
+    stdin: "ignore", stdout: "ignore", stderr: "pipe",
+  });
+  if (setResult.exitCode !== 0) {
+    const stderr = setResult.stderr.toString().trim();
+    throw new Error(`tmux set-buffer failed: ${stderr || `exit code ${setResult.exitCode}`}`);
+  }
+  try {
+    const pasteResult = Bun.spawnSync(tmuxCommand(socketName, "paste-buffer", "-b", bufferName, "-t", sessionName), {
+      stdin: "ignore", stdout: "ignore", stderr: "pipe",
+    });
+    if (pasteResult.exitCode !== 0) {
+      const stderr = pasteResult.stderr.toString().trim();
+      throw new Error(`tmux paste-buffer failed: ${stderr || `exit code ${pasteResult.exitCode}`}`);
+    }
+  } finally {
+    Bun.spawnSync(tmuxCommand(socketName, "delete-buffer", "-b", bufferName), {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+  }
+}
+
+export async function submitTextToTmux(sessionName: string, text: string, socketName?: string): Promise<void> {
+  pasteTextIntoTmux(sessionName, text, socketName);
+  await Bun.sleep(CLAUDE_TMUX_SUBMIT_DELAY_MS);
+  const result = Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, CLAUDE_TMUX_SUBMIT_KEY), {
+    stdin: "ignore", stdout: "ignore", stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(`tmux submit failed: ${stderr || `exit code ${result.exitCode}`}`);
+  }
+}
+
+// tmux new-session has a hard command-length limit that includes every argv item,
+// including `-e KEY=value`. The launcher script keeps tmux argv bounded by carrying
+// both env payloads (profile JSON, tokens, etc.) and the provider command/prompt.
+export function writeLauncherScript(sessionName: string, env: Record<string, string>, shellCmd: string): string {
+  const scriptPath = launcherScriptPathForSession(sessionName);
+  const launcherDir = dirname(scriptPath); mkdirSync(launcherDir, { recursive: true, mode: 0o700 }); chmodSync(launcherDir, 0o700);
+  const exports = Object.entries(env)
+    .map(([key, value]) => `export ${shellEnvKey(key)}=${shellQuote(value)}`)
+    .join("\n");
+  writeFileSync(scriptPath, `#!/usr/bin/env bash\n${exports ? `${exports}\n` : ""}exec ${shellCmd}\n`, { mode: 0o700 });
+  return scriptPath;
+}
+
+function shellEnvKey(key: string): string {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return key;
+  throw new Error(`invalid environment variable name for Claude launcher: ${key}`);
+}
+
+export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>): string[] {
+  const keys = new Set<string>();
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("AGENT_RELAY_") || key.startsWith("CLAUDE_")) {
+      keys.add(key);
+    }
+  }
+  for (const key of Object.keys(providerEnv)) {
+    keys.add(key);
+  }
+  return [...keys].sort();
+}

package/src/adapters/claude-transcript.ts

@@ -267,6 +267,35 @@ export function transcriptHasToolUseAnchor(jsonl: string, toolName: string, tool
   return false;
 }
 
+/**
+ * The transcript-embedded `timestamp` of the specific assistant entry carrying the exact
+ * tool_use block that triggered a PreToolUse hook (same anchor match as
+ * transcriptHasToolUseAnchor above). Used to stamp a resolved permission prompt with the
+ * tool call's real event time — a hook's own wall-clock receipt time can end up earlier than
+ * the entry the provider eventually flushes for that same call, which otherwise sorts the
+ * resolved prompt ahead of the narration that led up to it (#1185).
+ */
+export function transcriptToolUseOccurredAt(jsonl: string, toolName: string, toolInput: unknown): number | undefined {
+  const wantInput = canonicalJson(toolInput ?? {});
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (entry.type !== "assistant" || isSidechainEntry(entry)) continue;
+    for (const block of blocks(entry.message)) {
+      if (block.type === "tool_use" && block.name === toolName && canonicalJson(block.input ?? {}) === wantInput) {
+        return transcriptEntryOccurredAt(entry);
+      }
+    }
+  }
+  return undefined;
+}
+
 /**
  * Extract the ordered narration, reasoning, and tool steps for the most recent
  * turn (since the last real user prompt). Used by the reasoning tailer to stream

package/src/adapters/claude.ts

@@ -1,8 +1,7 @@
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { type Message } from "agent-relay-sdk";
-import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
@@ -14,8 +13,8 @@ import { claudeProviderMessageText } from "./claude-delivery";
 import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "./claude-prompt-gates";
 import { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
-import { launcherScriptPathForSession } from "../session-scratch";
 import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
+import { CLAUDE_TMUX_READY_TIMEOUT_MS, captureTmuxPane, submitTextToTmux, tmuxEnvKeys, tmuxSessionName, tmuxSocketName, waitForClaudeInputReady, writeLauncherScript } from "./claude-tmux";
 import { claudePermissionPromptHandler } from "./claude-permission";
 
 export class ClaudeAdapter implements ProviderAdapter {
@@ -468,9 +467,9 @@ export class ClaudeAdapter implements ProviderAdapter {
 }
 
 export const CLAUDE_EXIT_COMMAND = "/exit";
-export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
-export const CLAUDE_TMUX_SUBMIT_KEY = "C-m";
-export const CLAUDE_TMUX_READY_TIMEOUT_MS = 10_000;
+// tmux transport plumbing moved to ./claude-tmux (#300 ratchet); re-exported so
+// existing `./claude` consumers + tests keep their import paths.
+export { CLAUDE_TMUX_SUBMIT_DELAY_MS, CLAUDE_TMUX_SUBMIT_KEY, CLAUDE_TMUX_READY_TIMEOUT_MS, tmuxSessionName, tmuxSocketName, tmuxSocketPath, assertTmuxSocketPathFits, tmuxEnvKeys, waitForClaudeInputReady, submitTextToTmux } from "./claude-tmux";
 // Monitorless turn detection (Fix: isolated agents reach task "done" like Codex).
 const CLAUDE_TURN_WATCH_ID = "tmux-turn";
 const CLAUDE_TURN_POLL_MS = 1500;
@@ -528,107 +527,13 @@ function stripClaudePermissionArgs(args: string[], stripToolArgs = false): strin
 }
 
 
-export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
-  if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
-  return `${prefix}-${instanceId.slice(0, 8)}`;
-}
-
-export function tmuxSocketName(sessionName: string): string {
-  return sanitizeFsName(`agent-relay-${sessionName}`, { replacement: "-", collapse: false, lowercase: true });
-}
-
 // Shared tmux helpers; tmuxHasSession re-exported for ./claude consumers + tests.
 export { tmuxHasSession };
 
-function captureTmuxPane(sessionName: string, socketName?: string): string {
-  const result = Bun.spawnSync(tmuxCommand(socketName, "capture-pane", "-p", "-t", sessionName, "-S", "-80"), {
-    stdin: "ignore", stdout: "pipe", stderr: "pipe",
-  });
-  if (result.exitCode !== 0) {
-    const stderr = result.stderr.toString().trim();
-    throw new Error(`tmux capture-pane failed: ${stderr || `exit code ${result.exitCode}`}`);
-  }
-  return result.stdout.toString();
-}
-
 // Re-export pane-status detectors (moved to ./claude-status-detectors) so existing
 // import paths (including claude.test.ts) continue to resolve via this module.
 export { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
 
-async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (!tmuxHasSession(sessionName, socketName)) throw new Error("tmux session exited before Claude became ready");
-    if (claudePaneLooksReady(captureTmuxPane(sessionName, socketName))) return;
-    await Bun.sleep(200);
-  }
-  throw new Error(`Claude input was not ready within ${timeoutMs}ms`);
-}
-
-function pasteTextIntoTmux(sessionName: string, text: string, socketName?: string): void {
-  const bufferName = `agent-relay-${crypto.randomUUID()}`;
-  const setResult = Bun.spawnSync(tmuxCommand(socketName, "set-buffer", "-b", bufferName, text), {
-    stdin: "ignore", stdout: "ignore", stderr: "pipe",
-  });
-  if (setResult.exitCode !== 0) {
-    const stderr = setResult.stderr.toString().trim();
-    throw new Error(`tmux set-buffer failed: ${stderr || `exit code ${setResult.exitCode}`}`);
-  }
-  try {
-    const pasteResult = Bun.spawnSync(tmuxCommand(socketName, "paste-buffer", "-b", bufferName, "-t", sessionName), {
-      stdin: "ignore", stdout: "ignore", stderr: "pipe",
-    });
-    if (pasteResult.exitCode !== 0) {
-      const stderr = pasteResult.stderr.toString().trim();
-      throw new Error(`tmux paste-buffer failed: ${stderr || `exit code ${pasteResult.exitCode}`}`);
-    }
-  } finally {
-    Bun.spawnSync(tmuxCommand(socketName, "delete-buffer", "-b", bufferName), {
-      stdin: "ignore", stdout: "ignore", stderr: "ignore",
-    });
-  }
-}
-
-async function submitTextToTmux(sessionName: string, text: string, socketName?: string): Promise<void> {
-  pasteTextIntoTmux(sessionName, text, socketName);
-  await Bun.sleep(CLAUDE_TMUX_SUBMIT_DELAY_MS);
-  const result = Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, CLAUDE_TMUX_SUBMIT_KEY), {
-    stdin: "ignore", stdout: "ignore", stderr: "pipe",
-  });
-  if (result.exitCode !== 0) {
-    const stderr = result.stderr.toString().trim();
-    throw new Error(`tmux submit failed: ${stderr || `exit code ${result.exitCode}`}`);
-  }
-}
-
-function writeLauncherScript(sessionName: string, env: Record<string, string>, shellCmd: string): string {
-  const scriptPath = launcherScriptPathForSession(sessionName);
-  const launcherDir = dirname(scriptPath); mkdirSync(launcherDir, { recursive: true, mode: 0o700 }); chmodSync(launcherDir, 0o700);
-  const exports = Object.entries(env)
-    .map(([key, value]) => `export ${shellEnvKey(key)}=${shellQuote(value)}`)
-    .join("\n");
-  writeFileSync(scriptPath, `#!/usr/bin/env bash\n${exports ? `${exports}\n` : ""}exec ${shellCmd}\n`, { mode: 0o700 });
-  return scriptPath;
-}
-
-function shellEnvKey(key: string): string {
-  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return key;
-  throw new Error(`invalid environment variable name for Claude launcher: ${key}`);
-}
-
-export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>): string[] {
-  const keys = new Set<string>();
-  for (const key of Object.keys(env)) {
-    if (key.startsWith("AGENT_RELAY_") || key.startsWith("CLAUDE_")) {
-      keys.add(key);
-    }
-  }
-  for (const key of Object.keys(providerEnv)) {
-    keys.add(key);
-  }
-  return [...keys].sort();
-}
-
 // Shared shell-quoting; re-exported so `./claude` consumers + tests resolve it.
 export { shellQuote };
 

package/src/control-server.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import type { Message, ReplyObligation } from "agent-relay-sdk";
+import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderPermissionDecisionReason, ProviderPermissionPromptHandler, ProviderPermissionResolvedPrompt, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
@@ -18,6 +18,11 @@ const PERMISSION_TIMEOUT_REASON =
   "No response received within ~15 minutes (timeout, not a dismissal). Re-ask if you still need a decision.";
 const PERMISSION_STOP_REASON = "The runner restarted while this permission request was pending; the original hook is no longer connected.";
 const RESOLVED_APPROVAL_LIMIT = 1024;
+// #1173: the immediate PreToolUse response for a "questions" prompt (see the deny-then-hold
+// branch in handlePermissionRequest below). Bridges the hand-off so the model doesn't read a
+// bare denial and re-ask — the real answer follows shortly as an injected user prompt.
+const PENDING_QUESTION_DENY_REASON =
+  "The user is answering this question directly via Agent Relay, not through this tool call — do not re-ask it. Their answer will follow as your next message; wait for it and continue from there.";
 
 // A hook that failed in a way it could not handle itself reports here so the
 // failure is never silent (#198 item 5). Phase 1 logs it FATAL to the per-agent
@@ -34,6 +39,12 @@ interface MonitorSocketData {
 
 type MonitorSocket = ServerWebSocket<MonitorSocketData>;
 
+interface PendingPermissionWaiter {
+  resolve(input: ProviderPermissionDecisionInput): void;
+  timer: Timer;
+  suppressResolvedStatus?: boolean;
+}
+
 export interface ControlServer {
   port: number;
   url: string;
@@ -49,9 +60,14 @@ interface ControlServerOptions {
   // Provider session-final and pre-flush hooks hand over their capture source so
   // the runner can surface the provider turn in dashboard chat without the agent
   // re-emitting it via /reply.
-  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean } | void>;
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean; toolUseOccurredAt?: number } | void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
   onPermissionAbandoned?(input: PendingPermissionRequestRecord & { reason: string; decisionReason: ProviderPermissionDecisionReason }): Promise<void> | void;
+  // #1173: a "questions" (AskUserQuestion) prompt's own PreToolUse hook is answered with `deny`
+  // immediately (see the branch in handlePermissionRequest) instead of held open for the human,
+  // so there is no live HTTP request left to answer once the decision resolves. This delivers
+  // that resolution instead: `text` is the prompt to inject as a normal user turn.
+  onAnswerInject?(input: { approvalId: string; text?: string }): Promise<void> | void;
   // A provider user-prompt hook hands over text typed directly into the session
   // so the runner can mirror it into dashboard chat.
   onUserPrompt?(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void>;
@@ -78,7 +94,7 @@ export type ResolvedPermissionPrompt = ProviderPermissionResolvedPrompt;
 export function startControlServer(options: ControlServerOptions): ControlServer {
   const monitors = new Set<MonitorSocket>();
   const pendingDeliveries = new Map<string, { resolve(ids: number[]): void; timer: Timer }>();
-  const pendingPermissionRequests = new Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>();
+  const pendingPermissionRequests = new Map<string, PendingPermissionWaiter>();
   // approvalIds already resolved, so a duplicate decision (e.g. bus replay after a
   // reconnect, or both the PreToolUse and PermissionRequest hooks racing one answer)
   // is an idempotent no-op instead of a silent command failure (#693).
@@ -213,17 +229,19 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, input.approvalId);
       recordResolvedApproval(resolvedApprovals, input.approvalId);
       pending.resolve(withDecisionReason(input, input.decision === "deny" || input.decision === "abort" ? "dismissed" : "answered"));
-      options.onStatus({
-        status: "busy",
-        reason: "provider-turn",
-        providerState: {
-          state: "active",
-          reason: "permissionResolved",
-          label: options.permissionPromptHandler?.resolvedLabel ?? "Provider approval resolved",
-          source: options.permissionPromptHandler?.source ?? options.providerSourceId ?? "provider",
-          updatedAt: Date.now(),
-        },
-      });
+      if (!pending.suppressResolvedStatus) {
+        options.onStatus({
+          status: "busy",
+          reason: "provider-turn",
+          providerState: {
+            state: "active",
+            reason: "permissionResolved",
+            label: options.permissionPromptHandler?.resolvedLabel ?? "Provider approval resolved",
+            source: options.permissionPromptHandler?.source ?? options.providerSourceId ?? "provider",
+            updatedAt: Date.now(),
+          },
+        });
+      }
       return true;
     },
   };
@@ -292,26 +310,91 @@ function withDecisionReason(input: ProviderPermissionDecisionInput, kind: Provid
 
 async function handlePermissionRequest(
   req: Request,
-	  options: ControlServerOptions,
-	  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
+  options: ControlServerOptions,
+  pendingPermissionRequests: Map<string, PendingPermissionWaiter>,
 ): Promise<Response> {
   const handler = options.permissionPromptHandler;
   if (!handler) return Response.json({ ok: false, reason: "permission prompt handler unavailable" }, { status: 501 });
   const occurredAt = Date.now();
   const body = await req.json().catch(() => null);
   if (!isRecord(body)) return Response.json({});
-  // #435/#1116: flush any un-mirrored narrative before the blocking form appears in
-  // chat. The adapter owns how to settle its capture source; the transport only
-  // forwards the hook payload as an anchor and stamps the returned truth value.
   const transcriptPath = typeof body.transcript_path === "string" ? body.transcript_path : "";
   const toolName = typeof body.tool_name === "string" ? body.tool_name : undefined;
   const toolInput = isRecord(body.tool_input) ? body.tool_input : undefined;
+  const approvalId = crypto.randomUUID();
+
+  // #1173: a PreToolUse "questions" prompt (the provider's AskUserQuestion) used to block this hook
+  // response for up to ~15 minutes waiting on the human — which meant the turn's reasoning that
+  // led to the question stayed buffered in the provider's process (never flushed to the transcript
+  // JSONL) for exactly as long as the human took to answer, so the dashboard could only ever
+  // show the question AFTER the reasoning that motivated it. Denying the tool call immediately
+  // is the ordinary, already-supported "rejected tool call" hook contract: the provider persists the
+  // buffered turn + a rejected tool_result right away, on its own, same as any other denied tool
+  // — so the settle-poll harvest below (previously doomed to time out for this one case) now
+  // finds the freshly-flushed anchor within moments. The human's eventual answer is delivered
+  // afterward as a normal injected prompt (see the `.then` below), not as this hook's response.
+  const probeView = handler.buildView(approvalId, body, true);
+  if (body.hook_event_name === "PreToolUse" && probeView.kind === "questions" && handler.buildAnswerInjectionPrompt) {
+    const response = Response.json(handler.buildHookResponse(
+      { approvalId, decision: "deny", reason: PENDING_QUESTION_DENY_REASON },
+      body,
+    ));
+    void awaitPermissionDecision({
+      options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput,
+      blockedReason: "pendingQuestion",
+      recommendedAction: "Answer the question in Agent Relay.",
+      suppressResolvedStatus: true,
+    }).then(({ decision, view }) => {
+      const text = decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length
+        ? handler.buildAnswerInjectionPrompt!(view, decision, body)
+        : pendingQuestionDismissalPrompt(decision);
+      return options.onAnswerInject?.({ approvalId, text });
+    }).catch(() => {});
+    return response;
+  }
+
+  const { decision } = await awaitPermissionDecision({
+    options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput,
+    blockedReason: "permissionRequest",
+    recommendedAction: "Review the permission request in Agent Relay.",
+  });
+  return Response.json(handler.buildHookResponse(decision, body));
+}
+
+// Shared by both the traditional block-until-decided flow and the #1173 deny-then-hold flow:
+// pre-flushes narrative (#435/#1116), builds+persists the interactive view, publishes the
+// blocked providerState, and resolves once a decision arrives (or the wait times out). Callers
+// differ only in what happens with the resolved decision (build a hook response vs. inject an
+// answer prompt), so that part is left to them.
+async function awaitPermissionDecision(params: {
+  options: ControlServerOptions;
+  pendingPermissionRequests: Map<string, PendingPermissionWaiter>;
+  handler: ProviderPermissionPromptHandler;
+  approvalId: string;
+  body: Record<string, unknown>;
+  occurredAt: number;
+  transcriptPath: string;
+  toolName?: string;
+  toolInput?: unknown;
+  blockedReason: string;
+  recommendedAction: string;
+  suppressResolvedStatus?: boolean;
+}): Promise<{ decision: ProviderPermissionDecisionInput; view: InteractivePrompt }> {
+  const { options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput, blockedReason, recommendedAction, suppressResolvedStatus } = params;
+  // #435/#1116: flush any un-mirrored narrative before the blocking form appears in
+  // chat. The adapter owns how to settle its capture source; the transport only
+  // forwards the hook payload as an anchor and stamps the returned truth value.
   let reasoningSettled = true;
+  // Defaults to the hook's own wall-clock receipt time; refined below to the transcript's own
+  // tool_use event time when the pre-flush harvest can resolve it (#1185) — the hook can receive
+  // before the provider flushes/timestamps that entry, which otherwise sorts the resolved prompt
+  // ahead of the narration that led up to it.
+  let resolvedOccurredAt = occurredAt;
   if (transcriptPath && options.onSessionTurn) {
     const result = await options.onSessionTurn({ transcriptPath, isPreFlush: true, toolName, toolInput }).catch(() => undefined);
     if (result && typeof result.reasoningSettled === "boolean") reasoningSettled = result.reasoningSettled;
+    if (result && typeof result.toolUseOccurredAt === "number") resolvedOccurredAt = result.toolUseOccurredAt;
   }
-  const approvalId = crypto.randomUUID();
   const view = handler.buildView(approvalId, body, reasoningSettled);
   const waitMs = options.permissionWaitMs ?? PERMISSION_WAIT_MS;
   const hookDeadlineAt = occurredAt + waitMs;
@@ -327,9 +410,9 @@ async function handlePermissionRequest(
     reason: "provider-turn",
     providerState: {
       state: "blocked",
-      reason: "permissionRequest",
+      reason: blockedReason,
       label: view.title,
-      recommendedAction: "Review the permission request in Agent Relay.",
+      recommendedAction,
       source: handler.source,
       pendingApproval: view,
       updatedAt: Date.now(),
@@ -342,14 +425,20 @@ async function handlePermissionRequest(
       bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, approvalId);
       resolve(withDecisionReason({ approvalId, decision: "deny", reason: PERMISSION_TIMEOUT_REASON }, "timeout"));
     }, waitMs);
-    pendingPermissionRequests.set(approvalId, { resolve, timer });
+    pendingPermissionRequests.set(approvalId, { resolve, timer, suppressResolvedStatus });
   });
 
   if (decision.decisionReason?.kind !== "timeout" && options.onPermissionResolved) {
-    await Promise.resolve(options.onPermissionResolved(handler.buildResolvedPrompt(view, decision, body, occurredAt))).catch(() => {});
+    await Promise.resolve(options.onPermissionResolved(handler.buildResolvedPrompt(view, decision, body, resolvedOccurredAt))).catch(() => {});
   }
 
-  return Response.json(handler.buildHookResponse(decision, body));
+  return { decision, view };
+}
+
+function pendingQuestionDismissalPrompt(decision: ProviderPermissionDecisionInput): string {
+  const timedOut = decision.decisionReason?.kind === "timeout";
+  const event = timedOut ? "timed out before the user answered" : "was dismissed before the user answered";
+  return `Your previous AskUserQuestion ${event}. Proceed on your best judgment, or re-ask if you still need a decision.`;
 }
 
 async function handleSessionTurn(req: Request, options: ControlServerOptions): Promise<Response> {

package/src/runner-core.ts

@@ -277,6 +277,12 @@ export class AgentRunner {
   // wakes one) so the blocked badge lifts on its own.
   private rateLimitHold?: ProviderState;
   private pendingRateLimitHold?: ProviderState;
+  // #1173: like rateLimitHold — a deny-then-hold "questions" (AskUserQuestion) prompt's own
+  // turn genuinely ends (the provider reacts to the denial and stops normally) before the human
+  // answers, so the pendingApproval can't ride the provider-turn active-work claim (it would
+  // vanish the instant that claim clears on the real idle). Persists across that idle; cleared
+  // once the answer is injected (or the prompt is dismissed/times out).
+  private pendingQuestionHold?: ProviderState;
   // Settle-poll cadence for the pre-flush anchor (#1116) — instance fields (not just the
   // module constants) so tests can shrink them without waiting out the real bound.
   private settlePollIntervalMs = SETTLE_POLL_INTERVAL_MS;
@@ -429,6 +435,7 @@ export class AgentRunner {
       onReplyObligations: () => Promise.resolve(this.obligationCache.get()),
       onSessionTurn: (input) => this.publishSessionTurn(input), onPermissionResolved: (input) => this.publishSessionEvent({ from: this.agentId, to: "user", body: input.body, occurredAt: input.occurredAt, session: { type: "prompt-resolution", origin: "provider", label: input.decisionLabel, ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}), stepId: `prompt-resolution:${input.approvalId}`, promptResolution: input } }),
       onPermissionAbandoned: (input) => this.publishPermissionAbandonedNotice(input),
+      onAnswerInject: (input) => this.injectAnswerPrompt(input),
       onUserPrompt: (input) => this.handleUserPrompt(input),
       onSessionBoundary: (input) => this.handleSessionBoundary(input),
       onHookFatal: (report) => this.reportHookFatal(report),
@@ -926,6 +933,29 @@ export class AgentRunner {
     return { injected: true, messageId, attachmentCount: attachments.length };
   }
 
+  // #1173: the resolution side of the deny-then-hold AskUserQuestion flow (see control-server.ts's
+  // handlePermissionRequest). By the time this fires, the original PreToolUse hook has long since
+  // been answered with `deny` — there's no live HTTP request to respond to — so the human's answer
+  // (or dismissal) is delivered by clearing the pending-question hold and injecting a normal
+  // user prompt via the same path the dashboard chat box uses.
+  private async injectAnswerPrompt(input: { approvalId: string; text?: string }): Promise<void> {
+    const heldApprovalId = typeof this.pendingQuestionHold?.pendingApproval?.id === "string" ? this.pendingQuestionHold.pendingApproval.id : undefined;
+    if (heldApprovalId && heldApprovalId !== input.approvalId) return;
+    if (heldApprovalId === input.approvalId) {
+      this.pendingQuestionHold = undefined;
+      this.publishStatus();
+    }
+    const text = input.text ?? "The question was dismissed or timed out before the user answered. Proceed on your best judgment, or re-ask if you still need a decision.";
+    if (!this.process || !this.options.adapter.deliverInitialPrompt) {
+      this.sessionLog(`could not inject AskUserQuestion answer for ${input.approvalId}: provider process/prompt-injection unavailable`);
+      return;
+    }
+    this.recordInjectedPrompt(text.trim());
+    await this.options.adapter.deliverInitialPrompt(this.process, text).catch((error) => {
+      this.sessionLog(`failed to inject AskUserQuestion answer for ${input.approvalId}: ${errMessage(error)}`);
+    });
+  }
+
   private async promptInjectionText(body: string, messageId: number | undefined, attachments: Record<string, unknown>[]): Promise<string> {
     if (!attachments.length) return body;
     const messages = await messagesWithCachedAttachments([{
@@ -1251,10 +1281,18 @@ export class AgentRunner {
           this.rateLimitHold = update.providerState;
           if (fresh) this.publishRateLimitNotice(update.providerState);
         }
+      } else if (ps.state === "blocked" && ps.reason === "pendingQuestion") {
+        // #1173: set directly (never deferred) — unlike the rate-limit hold, this always
+        // arrives while the turn that asked is still busy, well before the real idle it must
+        // survive. Any other providerState (a fresh question, a plain approval, etc.) still
+        // supersedes it via the `else` branch below.
+        this.providerBlocked = true;
+        this.pendingQuestionHold = update.providerState;
       } else {
         this.providerBlocked = ps.state === "blocked";
         this.pendingRateLimitHold = undefined;
         this.rateLimitHold = undefined;
+        this.pendingQuestionHold = undefined;
       }
     } else if (status === "idle") {
       this.providerBlocked = false;
@@ -1313,6 +1351,12 @@ export class AgentRunner {
         this.currentTurnStartedAt = Date.now();
         this.compactionMidTurn = false;
         this.sessionLog(`turn started (turn ${this.currentTurnId})`);
+        // #1173: a genuinely new turn starting (not the mid-turn busy update that sets the
+        // hold itself — that arrives while currentTurnId is already set) means the human moved
+        // on without using the form (a fresh message, a self-resume, etc.). The normal
+        // answer/dismiss path already cleared this; this is the fallback for every other way
+        // forward progress can happen, so a stale question never lingers past its own turn.
+        this.pendingQuestionHold = undefined;
       }
       id = this.currentTurnId;
       this.busyReconciler.arm();
@@ -1904,7 +1948,7 @@ export class AgentRunner {
     const staleProviderTurnBusy = this.isStaleProviderTurnOnlyBusy(status, activeWork, busyReasons, liveness);
     const effectiveStatus = staleProviderTurnBusy ? "idle" : status;
     const agentStatus = runnerAgentStatus(effectiveStatus);
-    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork));
+    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? this.pendingQuestionHold ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork));
     this.bus.setSemanticStatus(effectiveStatus === "offline" || effectiveStatus === "error" ? "idle" : effectiveStatus);
     this.bus.status({
       agentStatus,