@parall/claude-agent 1.51.0 → 1.52.0

package/src/dispatch.ts

@@ -9,14 +9,21 @@ import {
 import type {
   CleanupForkOpts,
   DispatchAdapter,
+  DispatchInputLifecycle,
   DispatchOpts,
   ForkOpts,
   GatewayLogger,
   RuntimeEvent,
 } from '@parall/agent-core';
 import type { ClaudeAgentConfig } from './config.js';
-import { parseClaudeStreamJson, type ClaudeParsedEvent } from './output-parser.js';
-import { ClaudeSessionManager, type ClaudeProcessHandle } from './session-manager.js';
+import { ClaudeInputRegistry, type ClaudeInputDelivery } from './input-lifecycle.js';
+import {
+  parseClaudeStreamJson,
+  type ClaudeParsedEvent,
+  type ClaudeResultMeta,
+} from './output-parser.js';
+import type { ClaudeProcessHandle, ClaudeSessionManager } from './session-manager.js';
+import { classifyClaudeTurn } from './turn-outcome.js';
 
 type ClaudeCodeAdapterOptions = Pick<
   ClaudeAgentConfig,
@@ -58,11 +65,9 @@ type ClaudeCodeAdapterOptions = Pick<
 };
 
 const IS_WIN32 = process.platform === 'win32';
+const CAPABILITY_PROBE_TIMEOUT_MS = 15_000;
 
-// Upper bound on spurious empty turn_end frames skipped per turn (see the
-// guard in runTurn) — keeps a pathological stream of empty `result` frames
-// from spinning the drain loop forever.
-const MAX_SPURIOUS_TURN_END_SKIPS = 3;
+class MissingClaudeLifecycleCapabilityError extends Error {}
 
 function quoteWin32Arg(arg: string): string {
   if (!/[\s"&|^<>()]/.test(arg)) return arg;
@@ -154,12 +159,15 @@ type ProcessState = {
   parser: AsyncGenerator<ClaudeParsedEvent>;
   done: boolean;
   needsRestart: boolean;
-  steerReadPending?: Promise<IteratorResult<ClaudeParsedEvent>>;
+  capabilities?: Set<string>;
+  inputs: ClaudeInputRegistry;
 };
 
 export class ClaudeCodeAdapter implements DispatchAdapter {
+  readonly inputLifecycleMode = 'explicit' as const;
   private readonly processes = new Map<string, ProcessState>();
-  private readonly pendingInjections = new Map<string, number>();
+  private capabilityProbe?: Promise<void>;
+  private capabilityProbeHandle?: ClaudeProcessHandle;
   private shuttingDown = false;
   private _model: string | undefined;
   private _effortLevel: string | undefined;
@@ -197,24 +205,43 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
   }
 
-  enqueueDuringDispatch(sessionKey: string, body: string): boolean {
+  enqueueDuringDispatch(
+    sessionKey: string,
+    body: string,
+    inputLifecycle?: DispatchInputLifecycle,
+  ): boolean {
+    // Exact identity is mandatory for soft steer. Without it the later
+    // buffered dispatch could only guess which stdout boundary belonged to
+    // this input — the bug this adapter is designed to remove.
+    if (!inputLifecycle) return false;
     const state = this.processes.get(sessionKey);
     if (!state || state.done) return false;
+    // A throwaway process already proved the CLI capability before any
+    // business process started. The real process revalidates its own init.
+    if (!state.capabilities?.has('msg_lifecycle_v1')) return false;
     const { proc } = state.handle;
     if (proc.exitCode !== null || proc.signalCode !== null || proc.stdin.destroyed) return false;
     try {
-      this.writeUserMessage(state.handle, body);
-      this.pendingInjections.set(sessionKey, (this.pendingInjections.get(sessionKey) ?? 0) + 1);
+      if (state.inputs.getByKey(inputLifecycle.deliveryKey)) return true;
+      const delivery = state.inputs.register(inputLifecycle.deliveryKey, inputLifecycle, true);
+      this.writeUserMessage(state.handle, body, delivery.commandUuid);
       return true;
     } catch {
+      const delivery = state.inputs.getByKey(inputLifecycle.deliveryKey);
+      if (delivery) {
+        void state.inputs.failBestEffort(delivery);
+        state.inputs.remove(delivery);
+      }
       return false;
     }
   }
 
   abortDispatch(sessionKey: string): void {
-    this.pendingInjections.delete(sessionKey);
     const state = this.processes.get(sessionKey);
     if (!state || state.done) return;
+    for (const delivery of state.inputs.values()) {
+      if (!delivery.terminal) void state.inputs.failBestEffort(delivery);
+    }
     state.done = true;
     try {
       state.handle.proc.stdin.end();
@@ -224,7 +251,9 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
   }
 
   hasPendingInjections(sessionKey: string): boolean {
-    return (this.pendingInjections.get(sessionKey) ?? 0) > 0;
+    const state = this.processes.get(sessionKey);
+    if (!state) return false;
+    return state.inputs.hasPendingInjections();
   }
 
   async *dispatch({
@@ -232,15 +261,29 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     bodyForAgent,
     sessionKey,
     context,
+    inputLifecycle,
   }: DispatchOpts): AsyncIterable<RuntimeEvent> {
-    const pending = this.pendingInjections.get(sessionKey) ?? 0;
-    if (pending > 0) {
-      this.pendingInjections.delete(sessionKey);
-      context.log?.info?.(`consuming ${pending} steer turn(s)`);
-      for (let i = 0; i < pending; i++) {
-        yield* this.consumeSteerTurn(sessionKey, context.log);
+    const deliveryKey = inputLifecycle?.deliveryKey ?? event.dispatchEventId ?? event.messageId;
+    const existingState = this.processes.get(sessionKey);
+    const injected = existingState?.inputs.getByKey(deliveryKey);
+    if (existingState && injected) {
+      if (injected.terminal === 'failed') {
+        // The server released this exact WorkItem for retry. Its buffered
+        // bookkeeping dispatch is now real work again, not a no-op.
+        existingState.inputs.remove(injected);
+      } else {
+        injected.drained = true;
+        context.log?.info?.(`consuming steer input ${injected.commandUuid}`);
+        try {
+          yield* this.consumeDelivery(sessionKey, existingState, injected, context.log);
+        } finally {
+          existingState.inputs.remove(injected);
+        }
+        if (existingState.needsRestart && !existingState.inputs.hasPendingInjections()) {
+          this.killProcess(sessionKey, existingState);
+        }
+        return;
       }
-      return;
     }
 
     let promptBody = bodyForAgent;
@@ -257,7 +300,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
 
     try {
-      yield* this.runTurn(sessionKey, promptBody, context.log);
+      yield* this.runTurn(sessionKey, promptBody, deliveryKey, inputLifecycle, context.log);
     } finally {
       releasePreparedAttachments();
     }
@@ -298,172 +341,146 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       this.killProcess(sessionKey, state);
     }
     this.processes.clear();
-    this.pendingInjections.clear();
   }
 
   async shutdown(): Promise<void> {
     this.shuttingDown = true;
+    if (this.capabilityProbeHandle) {
+      this.terminateHandle(this.capabilityProbeHandle);
+      this.capabilityProbeHandle = undefined;
+    }
     this.resetProcesses();
     await this.opts.sessionManager.shutdownAll();
   }
 
-  // Steer-turn read timeout. Overridable via PRLL_STEER_TURN_TIMEOUT_MS (ms),
-  // chiefly so tests can exercise the timeout path without a 10s wait.
-  private readonly steerTurnTimeoutMs = Number(process.env.PRLL_STEER_TURN_TIMEOUT_MS) || 10_000;
-
-  /**
-   * Consume a steer turn whose message was already written to stdin via
-   * enqueueDuringDispatch. Skip the stdin write — only read parser output.
-   * If no output arrives within STEER_TURN_TIMEOUT_MS, the steer was
-   * incorporated into the previous turn and there is nothing to consume.
-   *
-   * On timeout, the losing parser.next() promise is saved to
-   * state.steerReadPending so the next runTurn can drain it instead of
-   * silently losing the first event of the subsequent turn.
-   */
-  private async *consumeSteerTurn(
-    sessionKey: string,
-    log: GatewayLogger | undefined,
-  ): AsyncGenerator<RuntimeEvent> {
-    const state = this.processes.get(sessionKey);
-    if (!state || state.done) {
-      throw new Error('process dead during steer consumption');
-    }
-
-    const groupKey = randomUUID();
-
-    // Reuse a pull already issued by a prior steer timeout instead of issuing a
-    // fresh one. A burst of N steers all takes the pending-skip path, which calls
-    // this method N times in a loop. Issuing a new state.parser.next() on each
-    // call while a previous pull is still in flight queues multiple reads on the
-    // same async generator, but only one can be stashed in the single-slot
-    // state.steerReadPending — every earlier pull is then consumed-and-dropped,
-    // silently losing parser events. When a dropped event is a tool_call, its
-    // tool_result later orphans into "call_id does not match any tool_call".
-    // Threading the single in-flight pull through every call keeps at most one
-    // outstanding read and loses nothing.
-    const parserNext = state.steerReadPending ?? state.parser.next();
-    state.steerReadPending = undefined;
-    const firstRead = await Promise.race([
-      parserNext.then((r) => ({ kind: 'value' as const, result: r })),
-      new Promise<{ kind: 'timeout' }>((resolve) =>
-        setTimeout(() => resolve({ kind: 'timeout' }), this.steerTurnTimeoutMs),
-      ),
-    ]);
-
-    if (firstRead.kind === 'timeout') {
-      state.steerReadPending = parserNext;
-      log?.info?.(`steer turn timeout — steer was incorporated into previous turn`);
-      return;
-    }
-
-    let next = firstRead.result;
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-      if (next.done) {
-        state.done = true;
-        this.processes.delete(sessionKey);
-        throw new Error('process exited while consuming steer turn');
-      }
-      const parsed = next.value;
-
-      if (parsed.type === 'session_id') {
-        this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-        yield {
-          type: 'runtime_session',
-          runtimeSessionId: parsed.sessionId,
-          runtimeLaneKey: sessionKey,
-        };
-      } else if (parsed.type === 'turn_end') {
-        if (state.needsRestart) this.killProcess(sessionKey, state);
-        return;
-      } else if (parsed.type === 'error') {
-        yield parsed;
-      } else if (parsed.type === 'text') {
-        yield { ...parsed, project: false, groupKey };
-      } else if (parsed.type === 'runtime_session') {
-        yield parsed;
-      } else {
-        yield { ...parsed, groupKey };
-      }
-      next = await state.parser.next();
-    }
-  }
-
   private async *runTurn(
     sessionKey: string,
     promptBody: string,
+    deliveryKey: string,
+    lifecycle: DispatchInputLifecycle | undefined,
     log: GatewayLogger | undefined,
   ): AsyncGenerator<RuntimeEvent> {
     let state: ProcessState;
     try {
+      await this.ensureRuntimeCapability(log);
       state = this.ensureProcess(sessionKey, log);
     } catch (err) {
+      try {
+        await lifecycle?.update('failed');
+      } catch (reportErr) {
+        log?.warn?.(`failed to report rejected Claude input as failed: ${String(reportErr)}`);
+      }
       yield { type: 'error', message: `Claude spawn failed: ${String(err)}` };
       return;
     }
-    const groupKey = randomUUID();
-    let sawError = false;
-    // Poison-frame guard. When `--resume` (with or without `--fork-session`)
-    // targets a transcript whose tail is dangling (previous process was
-    // killed mid-turn — exactly the fork-on-busy case), Claude CLI emits a
-    // spurious EMPTY result frame (num_turns: 0) at startup, BEFORE the
-    // queued stdin user frame is processed. Treating its turn_end as the
-    // dispatch boundary returns with zero output, the work item sweeps as
-    // no_action, and the real reply is orphaned in a soon-to-be-killed
-    // subprocess. A legitimate turn always reports num_turns >= 1 (even with
-    // no visible text); undefined (CLIs that omit the field) must NOT skip.
-    let sawSubstantiveEvent = false;
-    let spuriousTurnEndSkips = 0;
-
+    const delivery = state.inputs.register(deliveryKey, lifecycle, false);
     try {
-      this.writeUserMessage(state.handle, promptBody);
+      this.writeUserMessage(state.handle, promptBody, delivery.commandUuid);
     } catch (err) {
+      await state.inputs.failBestEffort(delivery, log);
+      state.inputs.remove(delivery);
       yield { type: 'error', message: `Claude stdin write failed: ${String(err)}` };
       this.killProcess(sessionKey, state);
       return;
     }
 
-    if (state.steerReadPending) {
-      const orphaned = await state.steerReadPending;
-      state.steerReadPending = undefined;
-      if (!orphaned.done) {
-        const parsed = orphaned.value;
-        // An orphaned read can deliver this turn's FIRST event — if it is
-        // substantive it must count toward the poison-frame guard below, or
-        // a later num_turns=0 turn_end would be wrongly skipped despite real
-        // output having been produced this turn.
-        if (
-          parsed.type !== 'session_id' &&
-          parsed.type !== 'runtime_session' &&
-          parsed.type !== 'turn_end'
-        ) {
-          sawSubstantiveEvent = true;
+    try {
+      yield* this.consumeDelivery(sessionKey, state, delivery, log);
+    } finally {
+      state.inputs.remove(delivery);
+    }
+  }
+
+  private ensureRuntimeCapability(log: GatewayLogger | undefined): Promise<void> {
+    if (!this.capabilityProbe) {
+      const probe = this.probeRuntimeCapability(log);
+      this.capabilityProbe = probe.catch((err) => {
+        if (!(err instanceof MissingClaudeLifecycleCapabilityError)) {
+          this.capabilityProbe = undefined;
         }
-        if (parsed.type === 'session_id') {
-          this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-          yield {
-            type: 'runtime_session',
-            runtimeSessionId: parsed.sessionId,
-            runtimeLaneKey: sessionKey,
-          };
-        } else if (parsed.type === 'turn_end') {
-          if (state.needsRestart) this.killProcess(sessionKey, state);
-          return;
-        } else if (parsed.type === 'error') {
-          sawError = true;
-          yield parsed;
-        } else if (parsed.type === 'text') {
-          yield { ...parsed, project: false, groupKey };
-        } else if (parsed.type === 'runtime_session') {
-          yield parsed;
-        } else {
-          yield { ...parsed, groupKey };
+        throw err;
+      });
+    }
+    return this.capabilityProbe;
+  }
+
+  /**
+   * Claude does not emit system.init until it receives its first stdin
+   * command (2.1.220 emits queued/started before init). Probe a throwaway
+   * process with an empty, non-WorkItem command; only after its init
+   * advertises msg_lifecycle_v1 may any business input enter a real process.
+   */
+  private async probeRuntimeCapability(log: GatewayLogger | undefined): Promise<void> {
+    const handle = this.spawnProcess('__capability_probe__', log, false);
+    this.capabilityProbeHandle = handle;
+    const parser = parseClaudeStreamJson(handle.proc.stdout!);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      this.terminateHandle(handle);
+    }, CAPABILITY_PROBE_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+      this.writeCapabilityProbe(handle);
+      while (true) {
+        const next = await parser.next();
+        if (next.done) {
+          const detail = handle.stderrChunks.join('').trim();
+          if (timedOut) {
+            throw new Error(
+              `Claude runtime capability probe timed out after ${CAPABILITY_PROBE_TIMEOUT_MS}ms`,
+            );
+          }
+          throw new Error(detail || 'Claude exited before its runtime capability probe completed');
         }
+        if (next.value.type !== 'runtime_init') continue;
+        if (!next.value.capabilities.includes('msg_lifecycle_v1')) {
+          throw new MissingClaudeLifecycleCapabilityError(
+            'Claude runtime lacks required msg_lifecycle_v1 capability; refusing heuristic input coverage',
+          );
+        }
+        return;
       }
+    } finally {
+      clearTimeout(timer);
+      if (this.capabilityProbeHandle === handle) {
+        this.capabilityProbeHandle = undefined;
+      }
+      this.terminateHandle(handle);
     }
+  }
 
-    while (true) {
+  /**
+   * Drain the shared stdout stream until the exact UUID written for target
+   * reaches a terminal lifecycle state. Other injected inputs may start and
+   * finish while this drain is active; their callbacks advance independently
+   * and their later bookkeeping dispatch becomes a no-op.
+   */
+  private async *consumeDelivery(
+    sessionKey: string,
+    state: ProcessState,
+    target: ClaudeInputDelivery,
+    log: GatewayLogger | undefined,
+  ): AsyncGenerator<RuntimeEvent> {
+    if (target.terminal) return;
+    const groupKey = randomUUID();
+    let sawError = false;
+    // Turn-outcome evidence for this dispatch (agent-turn-outcome-design
+    // §4.1). Lifecycle terminals — not turn_end — bound consumption, so the
+    // result frame for the turn that carried this delivery is the LAST
+    // non-poison turn_end observed before the terminal. Poison frames
+    // (num_turns: 0 startup artifacts) never overwrite evidence. At most one
+    // turn_outcome is emitted per dispatch, right before the generator
+    // returns; with no evidence and no crash, nothing is emitted and the
+    // legacy boolean error path stands (refine-only, never guess).
+    let lastResultMeta: ClaudeResultMeta | undefined;
+    const noticeTexts: string[] = [];
+    // usage_limit settles via the lane-level deferred complete; a failed-input
+    // report would race it with an immediate redrive into the choked LLM.
+    const settledAsLimit = () =>
+      classifyClaudeTurn(lastResultMeta, noticeTexts).outcome === 'usage_limit';
+
+    while (!target.terminal) {
       const next = await state.parser.next();
 
       if (next.done) {
@@ -476,6 +493,8 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
         if (detail) {
           log?.warn?.(`subprocess stderr: ${detail}`);
         }
+        if (settledAsLimit()) target.suppressFailReport = true;
+        await state.inputs.failBestEffort(target, log);
         if (!sawError) {
           yield {
             type: 'error',
@@ -484,43 +503,101 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
               `Claude exited with code ${exit.code ?? 'unknown'}${exit.signal ? ` (${exit.signal})` : ''}`,
           };
         }
+        // No evidence at all classifies as runtime_crash (the process died
+        // before any result frame); with evidence, classify what we saw.
+        yield classifyClaudeTurn(lastResultMeta, noticeTexts);
         return;
       }
 
       const parsed = next.value;
 
-      if (
-        parsed.type !== 'session_id' &&
-        parsed.type !== 'runtime_session' &&
-        parsed.type !== 'turn_end'
-      ) {
-        sawSubstantiveEvent = true;
+      if (parsed.type === 'runtime_init') {
+        state.capabilities = new Set(parsed.capabilities);
+        if (parsed.sessionId) {
+          this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
+          yield {
+            type: 'runtime_session',
+            runtimeSessionId: parsed.sessionId,
+            runtimeLaneKey: sessionKey,
+          };
+        }
+        if (!state.capabilities.has('msg_lifecycle_v1')) {
+          await state.inputs.failBestEffort(target, log);
+          yield {
+            type: 'error',
+            message:
+              'Claude runtime lacks required msg_lifecycle_v1 capability; refusing heuristic input coverage',
+          };
+          this.killProcess(sessionKey, state);
+          return;
+        }
+        continue;
       }
 
-      if (parsed.type === 'session_id') {
-        this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-        yield {
-          type: 'runtime_session',
-          runtimeSessionId: parsed.sessionId,
-          runtimeLaneKey: sessionKey,
-        };
+      if (parsed.type === 'command_lifecycle') {
+        if (!state.capabilities?.has('msg_lifecycle_v1')) {
+          await state.inputs.failBestEffort(target, log);
+          yield {
+            type: 'error',
+            message: 'Claude emitted command lifecycle before advertising msg_lifecycle_v1',
+          };
+          this.killProcess(sessionKey, state);
+          return;
+        }
+        const delivery = state.inputs.getByCommand(parsed.commandUuid);
+        if (!delivery) {
+          log?.warn?.(`ignoring lifecycle for unknown Claude command ${parsed.commandUuid}`);
+          continue;
+        }
+        try {
+          await state.inputs.apply(delivery, parsed.state);
+        } catch (err) {
+          await state.inputs.failBestEffort(delivery, log);
+          yield {
+            type: 'error',
+            message: `Claude input lifecycle update failed: ${String(err)}`,
+          };
+          this.killProcess(sessionKey, state);
+          return;
+        }
         continue;
       }
 
       if (parsed.type === 'turn_end') {
-        if (
-          parsed.numTurns === 0 &&
-          !sawSubstantiveEvent &&
-          spuriousTurnEndSkips < MAX_SPURIOUS_TURN_END_SKIPS
-        ) {
-          spuriousTurnEndSkips++;
-          log?.warn?.('ignoring spurious empty turn_end (num_turns=0) — resume/fork poison frame');
-          continue;
+        // Evidence capture: the poison startup frame (numTurns === 0) is a
+        // resume artifact, not a turn boundary — never let it overwrite real
+        // evidence.
+        if (parsed.numTurns !== 0) {
+          lastResultMeta = parsed.resultMeta;
         }
-        if (state.needsRestart) {
-          this.killProcess(sessionKey, state);
+        if (parsed.isError) {
+          const limitSettled = settledAsLimit();
+          const failedDelivery = parsed.userMessageUuid
+            ? state.inputs.getByCommand(parsed.userMessageUuid)
+            : undefined;
+          if (!failedDelivery) {
+            if (limitSettled) {
+              for (const delivery of state.inputs.values()) {
+                delivery.suppressFailReport = true;
+              }
+            }
+            await state.inputs.failAllBestEffort(log);
+            yield classifyClaudeTurn(lastResultMeta, noticeTexts);
+            this.killProcess(sessionKey, state);
+            return;
+          }
+          failedDelivery.resultFailed = true;
+          if (limitSettled) failedDelivery.suppressFailReport = true;
         }
-        return;
+        // result adjacency is not a consumption boundary: the matching
+        // command_lifecycle(completed) may follow it or interleave with a
+        // different queued/injected command.
+        continue;
+      }
+
+      if (parsed.type === 'assistant_error') {
+        noticeTexts.push(parsed.message);
+        continue;
       }
 
       if (parsed.type === 'error') {
@@ -539,8 +616,25 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
         continue;
       }
 
+      if (parsed.type === 'turn_outcome') {
+        // (never produced by the parser — type guard only)
+        continue;
+      }
+
       yield { ...parsed, groupKey };
     }
+
+    // Delivery reached a lifecycle terminal. Classify only when a result
+    // frame was observed during this drain: a delivery whose frames were
+    // drained by a sibling consumption window has no evidence here, and
+    // guessing would mislabel the turn (refine-only rule, §4.3).
+    if (lastResultMeta) {
+      yield classifyClaudeTurn(lastResultMeta, noticeTexts);
+    }
+
+    if (state.needsRestart && !state.inputs.hasPendingInjections()) {
+      this.killProcess(sessionKey, state);
+    }
   }
 
   private ensureProcess(sessionKey: string, log: GatewayLogger | undefined): ProcessState {
@@ -562,14 +656,28 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
 
     const handle = this.spawnProcess(sessionKey, log);
     const parser = parseClaudeStreamJson(handle.proc.stdout!);
-    const state: ProcessState = { handle, parser, done: false, needsRestart: false };
+    const state: ProcessState = {
+      handle,
+      parser,
+      done: false,
+      needsRestart: false,
+      // A throwaway process already proved the current CLI advertises this
+      // capability. Real 2.1.220 sends queued/started before its own init,
+      // so pre-seed the gate and still verify the real init when it arrives.
+      capabilities: new Set(['msg_lifecycle_v1']),
+      inputs: new ClaudeInputRegistry(),
+    };
     this.processes.set(sessionKey, state);
     this.opts.sessionManager.registerProcess(sessionKey, handle);
     return state;
   }
 
-  private spawnProcess(sessionKey: string, log: GatewayLogger | undefined): ClaudeProcessHandle {
-    const args = this.buildArgs(sessionKey);
+  private spawnProcess(
+    sessionKey: string,
+    log: GatewayLogger | undefined,
+    resume = true,
+  ): ClaudeProcessHandle {
+    const args = this.buildArgs(sessionKey, resume);
     const env = buildSpawnEnv(
       process.env,
       this.opts.claudeHome,
@@ -625,20 +733,27 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
   }
 
   private killProcess(sessionKey: string, state: ProcessState) {
+    for (const delivery of state.inputs.values()) {
+      if (!delivery.terminal) void state.inputs.failBestEffort(delivery);
+    }
     state.done = true;
     const current = this.processes.get(sessionKey);
     if (current === state) {
       this.processes.delete(sessionKey);
     }
+    this.terminateHandle(state.handle);
+  }
+
+  private terminateHandle(handle: ClaudeProcessHandle): void {
     try {
-      state.handle.proc.stdin.end();
+      handle.proc.stdin.end();
     } catch {
       /* best-effort */
     }
-    if (state.handle.proc.exitCode === null && state.handle.proc.signalCode === null) {
+    if (handle.proc.exitCode === null && handle.proc.signalCode === null) {
       try {
-        if (!IS_WIN32 || !state.handle.proc.pid || !killWin32Tree(state.handle.proc.pid)) {
-          state.handle.proc.kill('SIGTERM');
+        if (!IS_WIN32 || !handle.proc.pid || !killWin32Tree(handle.proc.pid)) {
+          handle.proc.kill('SIGTERM');
         }
       } catch {
         /* best-effort */
@@ -646,9 +761,21 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
   }
 
-  private writeUserMessage(handle: ClaudeProcessHandle, text: string) {
+  private writeCapabilityProbe(handle: ClaudeProcessHandle): void {
+    const payload = JSON.stringify({
+      type: 'user',
+      uuid: randomUUID(),
+      parent_tool_use_id: null,
+      message: { role: 'user', content: [] },
+    });
+    handle.proc.stdin.write(`${payload}\n`);
+  }
+
+  private writeUserMessage(handle: ClaudeProcessHandle, text: string, commandUuid: string) {
     const payload = JSON.stringify({
       type: 'user',
+      uuid: commandUuid,
+      parent_tool_use_id: null,
       message: {
         role: 'user',
         content: [{ type: 'text', text }],
@@ -657,7 +784,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     handle.proc.stdin.write(`${payload}\n`);
   }
 
-  private buildArgs(sessionKey: string): string[] {
+  private buildArgs(sessionKey: string, resume = true): string[] {
     const args = [
       '--verbose',
       '--input-format',
@@ -693,7 +820,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       args.push('--add-dir', ...this.opts.additionalDirs);
     }
 
-    args.push(...this.opts.sessionManager.getResumeArgs(sessionKey));
+    if (resume) args.push(...this.opts.sessionManager.getResumeArgs(sessionKey));
     return args;
   }