@parall/claude-agent 1.51.0 → 1.52.0

package/dist/dispatch.js

@@ -3,12 +3,13 @@ import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { execSync, spawn } from 'node:child_process';
 import { appendPreparedLocalAttachmentRefs, pinLocalAttachmentPaths, } from '@parall/agent-core/internal/attachment-input';
-import { parseClaudeStreamJson } from './output-parser.js';
+import { ClaudeInputRegistry } from './input-lifecycle.js';
+import { parseClaudeStreamJson, } from './output-parser.js';
+import { classifyClaudeTurn } from './turn-outcome.js';
 const IS_WIN32 = process.platform === 'win32';
-// 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;
+const CAPABILITY_PROBE_TIMEOUT_MS = 15_000;
+class MissingClaudeLifecycleCapabilityError extends Error {
+}
 function quoteWin32Arg(arg) {
     if (!/[\s"&|^<>()]/.test(arg))
         return arg;
@@ -77,8 +78,10 @@ export function buildSpawnEnv(parentEnv, claudeHome, context, opts) {
 }
 export class ClaudeCodeAdapter {
     opts;
+    inputLifecycleMode = 'explicit';
     processes = new Map();
-    pendingInjections = new Map();
+    capabilityProbe;
+    capabilityProbeHandle;
     shuttingDown = false;
     _model;
     _effortLevel;
@@ -114,27 +117,46 @@ export class ClaudeCodeAdapter {
             state.needsRestart = true;
         }
     }
-    enqueueDuringDispatch(sessionKey, body) {
+    enqueueDuringDispatch(sessionKey, body, inputLifecycle) {
+        // 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) {
-        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();
@@ -144,17 +166,35 @@ export class ClaudeCodeAdapter {
         }
     }
     hasPendingInjections(sessionKey) {
-        return (this.pendingInjections.get(sessionKey) ?? 0) > 0;
-    }
-    async *dispatch({ event, bodyForAgent, sessionKey, context, }) {
-        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 state = this.processes.get(sessionKey);
+        if (!state)
+            return false;
+        return state.inputs.hasPendingInjections();
+    }
+    async *dispatch({ event, bodyForAgent, sessionKey, context, inputLifecycle, }) {
+        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;
         let releasePreparedAttachments = () => { };
@@ -170,7 +210,7 @@ export class ClaudeCodeAdapter {
             context.log?.warn?.(`failed to prepare local attachments: ${String(err)}`);
         }
         try {
-            yield* this.runTurn(sessionKey, promptBody, context.log);
+            yield* this.runTurn(sessionKey, promptBody, deliveryKey, inputLifecycle, context.log);
         }
         finally {
             releasePreparedAttachments();
@@ -202,163 +242,130 @@ export class ClaudeCodeAdapter {
             this.killProcess(sessionKey, state);
         }
         this.processes.clear();
-        this.pendingInjections.clear();
     }
     async shutdown() {
         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.
-    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.
-     */
-    async *consumeSteerTurn(sessionKey, log) {
-        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', result: r })),
-            new Promise((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();
-        }
-    }
-    async *runTurn(sessionKey, promptBody, log) {
+    async *runTurn(sessionKey, promptBody, deliveryKey, lifecycle, log) {
         let state;
         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;
-                }
-                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 };
+        try {
+            yield* this.consumeDelivery(sessionKey, state, delivery, log);
+        }
+        finally {
+            state.inputs.remove(delivery);
+        }
+    }
+    ensureRuntimeCapability(log) {
+        if (!this.capabilityProbe) {
+            const probe = this.probeRuntimeCapability(log);
+            this.capabilityProbe = probe.catch((err) => {
+                if (!(err instanceof MissingClaudeLifecycleCapabilityError)) {
+                    this.capabilityProbe = undefined;
                 }
-                else if (parsed.type === 'runtime_session') {
-                    yield parsed;
+                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.
+     */
+    async probeRuntimeCapability(log) {
+        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');
                 }
-                else {
-                    yield { ...parsed, groupKey };
+                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;
             }
         }
-        while (true) {
+        finally {
+            clearTimeout(timer);
+            if (this.capabilityProbeHandle === handle) {
+                this.capabilityProbeHandle = undefined;
+            }
+            this.terminateHandle(handle);
+        }
+    }
+    /**
+     * 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.
+     */
+    async *consumeDelivery(sessionKey, state, target, log) {
+        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;
+        const noticeTexts = [];
+        // 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) {
                 state.done = true;
@@ -368,6 +375,9 @@ export class ClaudeCodeAdapter {
                 if (detail) {
                     log?.warn?.(`subprocess stderr: ${detail}`);
                 }
+                if (settledAsLimit())
+                    target.suppressFailReport = true;
+                await state.inputs.failBestEffort(target, log);
                 if (!sawError) {
                     yield {
                         type: 'error',
@@ -375,35 +385,97 @@ export class ClaudeCodeAdapter {
                             `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 === 'session_id') {
-                this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-                yield {
-                    type: 'runtime_session',
-                    runtimeSessionId: parsed.sessionId,
-                    runtimeLaneKey: sessionKey,
-                };
+            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 === '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');
+            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;
                 }
-                if (state.needsRestart) {
+                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;
                 }
-                return;
+                continue;
+            }
+            if (parsed.type === 'turn_end') {
+                // 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 (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;
+                }
+                // 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') {
                 sawError = true;
@@ -418,8 +490,22 @@ export class ClaudeCodeAdapter {
                 yield parsed;
                 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);
+        }
     }
     ensureProcess(sessionKey, log) {
         if (this.shuttingDown) {
@@ -440,13 +526,23 @@ export class ClaudeCodeAdapter {
         }
         const handle = this.spawnProcess(sessionKey, log);
         const parser = parseClaudeStreamJson(handle.proc.stdout);
-        const state = { handle, parser, done: false, needsRestart: false };
+        const state = {
+            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;
     }
-    spawnProcess(sessionKey, log) {
-        const args = this.buildArgs(sessionKey);
+    spawnProcess(sessionKey, log, resume = true) {
+        const args = this.buildArgs(sessionKey, resume);
         const env = buildSpawnEnv(process.env, this.opts.claudeHome, this.buildPlaceholderContext(sessionKey), {
             allowApiKey: this.opts.allowApiKey,
             effortLevel: this._effortLevel,
@@ -482,21 +578,28 @@ export class ClaudeCodeAdapter {
         return { proc, exitPromise, stderrChunks };
     }
     killProcess(sessionKey, state) {
+        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);
+    }
+    terminateHandle(handle) {
         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 {
@@ -504,9 +607,20 @@ export class ClaudeCodeAdapter {
             }
         }
     }
-    writeUserMessage(handle, text) {
+    writeCapabilityProbe(handle) {
+        const payload = JSON.stringify({
+            type: 'user',
+            uuid: randomUUID(),
+            parent_tool_use_id: null,
+            message: { role: 'user', content: [] },
+        });
+        handle.proc.stdin.write(`${payload}\n`);
+    }
+    writeUserMessage(handle, text, commandUuid) {
         const payload = JSON.stringify({
             type: 'user',
+            uuid: commandUuid,
+            parent_tool_use_id: null,
             message: {
                 role: 'user',
                 content: [{ type: 'text', text }],
@@ -514,7 +628,7 @@ export class ClaudeCodeAdapter {
         });
         handle.proc.stdin.write(`${payload}\n`);
     }
-    buildArgs(sessionKey) {
+    buildArgs(sessionKey, resume = true) {
         const args = [
             '--verbose',
             '--input-format',
@@ -540,7 +654,8 @@ export class ClaudeCodeAdapter {
         if (this.opts.additionalDirs.length > 0) {
             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;
     }
     buildPlaceholderContext(sessionKey) {