@canonmsg/claude-code-plugin 0.28.0 → 0.29.0

package/dist/session-state.js

@@ -1,11 +1,18 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { USAGE_LIMIT_ERROR_PREFIXES } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES, isCanonMessageIdConflict, isRetryableCanonDeliveryError, utf8ByteLength, VERB_LIMITS, } from '@canonmsg/core';
+import { boundTrailBlockMap, buildTrailBlockId, buildUndeliverableFinalNotice as buildHostUndeliverableFinalNotice, normalizePlanStepStatus, normalizeTrailKey, PLAN_BLOCK_TITLE, renderPlanSteps, truncateFailureDetail, } from '@canonmsg/coding-agent-host';
 export function createClaudeInputEnvelope(input) {
     const sourceMessageId = input.sourceMessageId ?? null;
     const fallbackId = randomUUID();
+    // Stamped so each turn result can be matched back to the envelope that caused
+    // it via SDKResultMessage.user_message_uuid, instead of inferring ownership
+    // from a mutable slot and arrival order.
+    const messageUuid = randomUUID();
     return {
         kind: input.kind,
-        msg: input.msg,
+        messageUuid,
+        msg: { ...input.msg, uuid: messageUuid },
         intent: input.intent ?? 'queue',
         sourceMessageId,
         markAccepted: Boolean(input.markAccepted),
@@ -49,8 +56,61 @@ export function shouldDeliverClaudeFinal(input) {
         return false;
     return true;
 }
+/** Bounds the correlation map if the SDK ever stops reporting a uuid we sent. */
+const MAX_TRACKED_DISPATCHED_INPUTS = 64;
+export function rememberDispatchedClaudeInput(dispatched, input) {
+    dispatched.set(input.messageUuid, input);
+    while (dispatched.size > MAX_TRACKED_DISPATCHED_INPUTS) {
+        const oldest = dispatched.keys().next();
+        if (oldest.done)
+            break;
+        dispatched.delete(oldest.value);
+    }
+}
+/**
+ * The envelope a turn result belongs to, matched by `user_message_uuid`.
+ *
+ * The SDK coalesces queued inputs — three rapid messages can produce two turns —
+ * and reports the LAST message of a coalesced batch, which is the correct owner
+ * of the reply. Entries up to and including the match are consumed, so messages
+ * folded into that batch do not linger. Returns null when the result carries no
+ * usable uuid, leaving the caller to fall back.
+ */
+export function takeClaudeResultOwner(dispatched, userMessageUuid) {
+    if (typeof userMessageUuid !== 'string' || !dispatched.has(userMessageUuid)) {
+        return null;
+    }
+    let owner = null;
+    for (const [key, envelope] of dispatched) {
+        dispatched.delete(key);
+        if (key === userMessageUuid) {
+            owner = envelope;
+            break;
+        }
+    }
+    return owner;
+}
+/**
+ * Whether an envelope owns the session's active-turn slot. Only Canon turns do;
+ * any future internal envelope must remain invisible to user-facing turn state.
+ */
+export function claudeInputOwnsTurnSlot(input) {
+    return input?.kind === 'canon';
+}
+/** Why a non-empty final was gated instead of sent. Diagnostics only. */
+export function describeUndeliveredClaudeFinal(input) {
+    if (!input.turn)
+        return 'no Canon turn owns this result';
+    if (input.turn.kind !== 'canon')
+        return `owning turn is '${input.turn.kind}'`;
+    if (input.interruptedTurnKeys.has(input.turn.turnKey))
+        return 'turn was interrupted';
+    if (input.finalizedTurnKeys.has(input.turn.turnKey))
+        return 'turn was already finalized';
+    return 'turn did not qualify for delivery';
+}
 export function resetClaudeCompletedTurnState(session) {
-    session.state.state = 'idle';
+    releaseClaudeTurnSlot(session);
     session.currentTurnId = null;
     session.currentTurnOpenedAt = null;
     session.currentTurnUpdatedAt = null;
@@ -58,8 +118,575 @@ export function resetClaudeCompletedTurnState(session) {
     session.pendingFinalText = null;
     session.pendingFinalDelivery = null;
     session.activeInput = null;
+    session.dispatchingInput = null;
     session.toolInProgress = false;
     session.turnState = 'idle';
+    // The trail bookkeeping only ever describes blocks of the turn that just
+    // ended; a tool_use id surviving into the next turn would resolve to a block
+    // that no longer exists.
+    if (session.turnActivity)
+        resetClaudeTurnActivityState(session.turnActivity);
+}
+/**
+ * Whether the session already owns the turn slot.
+ *
+ * 'running' covers both a turn the SDK is working on and one still being
+ * dispatched — the distinction matters only to an interrupt (below), never to
+ * whether the session is free to start something else. Deliberately NOT a new
+ * published state: `session.state.state` is the host's internal busy flag (the
+ * published session snapshot has no such field), and the user-facing signal is
+ * the turn state, which `openTurn` already publishes as 'thinking' at dequeue.
+ *
+ * 'requires_action' counts too: an approval or a question waiting on a human is
+ * a turn that is very much alive, holding the turn id and the live node. Reading
+ * it as free let a message arriving during the prompt open a SECOND turn over
+ * the waiting one — the same collision the reservation exists to stop, and
+ * inconsistent with every interrupt path, which already treats it as active.
+ */
+export function isClaudeTurnSlotReserved(state) {
+    return state === 'running' || state === 'requires_action';
+}
+/**
+ * Whether the SDK's `session_state_changed` echo may overwrite the host's own
+ * busy flag.
+ *
+ * The echo and the reservation share one field, and the echo lags: the 'idle'
+ * that closes turn A is emitted after A's result has flushed, and the host
+ * drains its queue INSIDE that result handler — so by the time the echo is
+ * processed, turn B may already hold the slot. Applying it there releases a
+ * slot that is taken, re-opening the dispatch-window race and killing the
+ * typing signal B just started. An 'idle' echo is therefore ignored while the
+ * host knows it is busy; every other echo is authoritative, so the SDK can
+ * still take the session busy on its own (a resumed session, an internal
+ * envelope) and nothing can wedge the flag at 'running'.
+ */
+export function shouldApplyClaudeEchoedSessionState(input) {
+    if (input.echoed !== 'idle')
+        return true;
+    return !input.dispatching && !input.hasPendingFinalDelivery;
+}
+/** Claim the slot for an input about to be dispatched. Must precede any await. */
+export function reserveClaudeTurnSlot(session) {
+    session.state.state = 'running';
+}
+/** Give the slot back — dispatch failed, or the turn is over. */
+export function releaseClaudeTurnSlot(session) {
+    session.state.state = 'idle';
+}
+/**
+ * What to do with a stop signal from the control channel.
+ *
+ * The dispatch window is the interesting case. The slot is reserved but the
+ * input has not reached Claude, so there is nothing for `query.interrupt()` to
+ * stop — yet consuming the signal as stale would make a Stop pressed in that
+ * window do NOTHING while the turn it was aimed at ran to completion, silently.
+ * Deferring hands it back to the poller, which revisits the same node a cycle
+ * later, by which time the input really is in flight.
+ *
+ * Outside that window a signal with nothing to act on is consumed, except that
+ * 'stop_and_drop' still has work to do while inputs are queued: dropping them.
+ */
+export function decideClaudeControlSignalAction(input) {
+    if (input.dispatching)
+        return 'defer';
+    if (isClaudeTurnSlotReserved(input.sessionState))
+        return 'act';
+    return input.type === 'stop_and_drop' && input.queueDepth > 0 ? 'act' : 'consume';
+}
+/**
+ * What to do with an inbound Canon message.
+ *
+ * `hasInterruptibleInput` is the one piece that is not just "is the session
+ * busy": an interrupt can only stop an input the SDK has actually pulled. In
+ * the dispatch window there is nothing in flight to interrupt — calling
+ * `query.interrupt()` there would fire at an idle SDK and then let the input it
+ * was meant to pre-empt reach the SDK a moment later, unaffected, while the
+ * interrupting message sat in the queue behind it. Such a message goes to the
+ * FRONT of the queue instead, and starts as soon as the dispatched turn ends.
+ *
+ * A session waiting on an approval ('requires_action') is busy like any other
+ * live turn: an ordinary message queues behind the prompt, and an interrupt
+ * stops the waiting turn rather than racing a second one alongside it.
+ */
+export function decideClaudeInboundDispatch(input) {
+    // A final still being handed to Canon owns the turn until it settles, even
+    // though the SDK itself is done.
+    if (input.hasPendingFinalDelivery)
+        return 'queue';
+    if (!isClaudeTurnSlotReserved(input.sessionState))
+        return 'start';
+    if (input.intent !== 'interrupt')
+        return 'queue';
+    return input.hasInterruptibleInput ? 'interrupt' : 'queue-front';
+}
+/**
+ * Whether a turn that has just finished may hand the slot back.
+ *
+ * Finishing spans awaits — the final send, the context-usage read — and the
+ * session reads free to inbound messages from the SDK's idle echo onward, so a
+ * message arriving in that window can reserve the slot for ITSELF. Releasing
+ * unconditionally afterwards would hand the same slot to a second message and
+ * put two turns into the SDK at once, which is exactly what the reservation
+ * exists to stop.
+ */
+export function shouldReleaseClaudeTurnSlot(input) {
+    if (input.dispatching)
+        return false;
+    return input.activeTurnKey === null || input.activeTurnKey === input.completedTurnKey;
+}
+/** Whether the next queued input may be dequeued now. */
+export function canDrainClaudeQueuedInput(input) {
+    return !input.closed
+        && !input.controlInterruptPending
+        && !isClaudeTurnSlotReserved(input.sessionState)
+        && input.queueDepth > 0;
+}
+/**
+ * Dispatch one input: reserve the slot, publish the turn, then do the slow
+ * work, then hand it to the SDK.
+ *
+ * The ORDER is the point, which is why this lives here rather than inline in
+ * the host: the reservation and `openTurn` must both happen before the first
+ * await. Marking the message accepted is a network round-trip and the artifact
+ * baseline walks the workspace; leaving the session readable as free across
+ * that window let a second message bypass the queue and open a competing turn
+ * over this one (`seedTurnStreaming` wiping the first turn's live node, two
+ * inputs in the SDK under mismatched attribution).
+ *
+ * Never rejects. An input that cannot be handed over — a throw in the window,
+ * or a session torn down mid-dispatch — is ABANDONED rather than dropped: the
+ * host settles the message and retires the turn, instead of leaving the sender
+ * on 'accepted' forever with a 'thinking' row nothing will complete.
+ */
+export async function dispatchClaudeInput(session, input, deps) {
+    reserveClaudeTurnSlot(session);
+    session.dispatchingInput = input;
+    deps.openTurn(input);
+    let failure = null;
+    try {
+        await deps.markAccepted(input);
+        await deps.prepareArtifacts(input);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    if (session.dispatchingInput === input)
+        session.dispatchingInput = null;
+    if (failure) {
+        deps.abandon(input, 'error', failure.error);
+        return;
+    }
+    if (session.closed) {
+        deps.abandon(input, 'closed');
+        return;
+    }
+    deps.send(input);
+}
+// ── Turn lifecycle: opening a turn before the SDK says anything ──────
+//
+// The host used to publish turn state only when the SDK echoed
+// `session_state_changed: running`, so everything between "message accepted"
+// and "first token" was silent — no thinking header, no dots. Opening is now
+// the host's own decision, taken synchronously at dequeue; these helpers hold
+// the part of that decision that is pure state.
+/** States in which a turn is live for the clients (mirrors the turn-state write). */
+export function isOpenClaudeTurnState(state) {
+    return state === 'thinking'
+        || state === 'streaming'
+        || state === 'tool'
+        || state === 'waiting_input';
+}
+/**
+ * Whether the SDK's `running` confirmation should open the turn itself.
+ *
+ * When the host already opened this turn the confirmation is a no-op: re-seeding
+ * `/streaming` would clobber the blocks and text the turn has produced since.
+ */
+export function shouldOpenClaudeTurnOnRunning(state) {
+    return !isOpenClaudeTurnState(state);
+}
+/**
+ * Move the session into a fresh open turn: 'thinking', with a turn id, before
+ * a single SDK message has arrived.
+ *
+ * The id is minted per OPEN, unconditionally. Keying the mint on "the turn
+ * state is not open" reads equivalent and is not: the state a finished turn
+ * actually sits in during the final-handoff window is 'streaming'
+ * (`markPendingFinalDelivery` puts it there and only the reset clears it), so a
+ * message arriving in that window — precisely the case this exists for — would
+ * inherit an id that already carries a `turn_complete` message, and the client
+ * drops a live turn whose id is already complete.
+ *
+ * Nothing needs the guard: a turn is only ever opened when none is running —
+ * at dequeue, or on the SDK's `running` echo for a turn the host did not open
+ * itself (`shouldOpenClaudeTurnOnRunning` has already proved the state is not
+ * an open one there).
+ */
+export function openClaudeTurn(session, now = Date.now()) {
+    session.currentTurnId = randomUUID();
+    session.currentTurnOpenedAt = now;
+    session.currentTurnUpdatedAt = now;
+    session.turnState = 'thinking';
+    session.toolInProgress = false;
+    session.pendingFinalText = null;
+    if (session.turnActivity)
+        resetClaudeTurnActivityState(session.turnActivity);
+}
+/**
+ * Whether an SDK message describes the agent's OWN work rather than a
+ * subagent's. Nested messages carry the id of the Task call that spawned them;
+ * that Task's row already stands for the whole subagent, and publishing its
+ * internals would flood the trail — and the 20-block budget the persisted turn
+ * trail is bounded to.
+ */
+export function isClaudeMainTurnMessage(parentToolUseId) {
+    return parentToolUseId == null;
+}
+export function createClaudeTurnActivityState() {
+    return {
+        blockIdByIndex: new Map(),
+        blockIdByToolUseId: new Map(),
+        planBlockId: null,
+    };
+}
+export function resetClaudeTurnActivityState(state) {
+    state.blockIdByIndex.clear();
+    state.blockIdByToolUseId.clear();
+    state.planBlockId = null;
+}
+export function claudeToolBlockId(toolUseId) {
+    return buildTrailBlockId('tool', toolUseId);
+}
+export function claudePlanBlockId(turnId) {
+    return buildTrailBlockId('plan', turnId ?? 'turn');
+}
+/**
+ * This turn's plan block, claimed once and then reused.
+ *
+ * Reading the claimed id back — rather than re-deriving it from the turn id on
+ * every TodoWrite — is what keeps a plan card whole: a turn id that changed
+ * mid-turn would otherwise split the plan into a second card instead of
+ * updating the first.
+ */
+export function claimClaudePlanBlockId(state, turnId) {
+    if (!state.planBlockId)
+        state.planBlockId = claudePlanBlockId(turnId);
+    return state.planBlockId;
+}
+function readTrimmedString(value) {
+    return normalizeTrailKey(value) ?? null;
+}
+/**
+ * Claim the trail block for a tool call the model has started emitting, and
+ * remember how to find it again from either the `tool_use` id (tool_result) or
+ * the content-block index (content_block_stop).
+ */
+export function registerClaudeToolCallBlock(state, input) {
+    const toolUseId = readTrimmedString(input.toolUseId);
+    const index = typeof input.index === 'number' && Number.isInteger(input.index)
+        ? input.index
+        : null;
+    // Without an id (older runtimes) the index still separates the parallel calls
+    // of one assistant message, which is where collisions actually happen.
+    const blockId = toolUseId
+        ? claudeToolBlockId(toolUseId)
+        : buildTrailBlockId('tool', input.turnId ?? 'turn', index ?? state.blockIdByIndex.size);
+    if (toolUseId) {
+        state.blockIdByToolUseId.set(toolUseId, blockId);
+        boundTrailBlockMap(state.blockIdByToolUseId);
+    }
+    if (index !== null) {
+        state.blockIdByIndex.set(index, blockId);
+        boundTrailBlockMap(state.blockIdByIndex);
+    }
+    return blockId;
+}
+/** The block a `tool_result` belongs to. Null when this turn never claimed one. */
+export function resolveClaudeToolBlockId(state, toolUseId) {
+    const id = readTrimmedString(toolUseId);
+    if (!id)
+        return null;
+    return state.blockIdByToolUseId.get(id) ?? null;
+}
+/**
+ * The block a `content_block_stop` closes, consumed on read — indexes restart
+ * at 0 with every assistant message, so a stale entry would mis-resolve.
+ */
+export function takeClaudeToolBlockIdByIndex(state, index) {
+    if (typeof index !== 'number' || !Number.isInteger(index))
+        return null;
+    const blockId = state.blockIdByIndex.get(index) ?? null;
+    if (blockId)
+        state.blockIdByIndex.delete(index);
+    return blockId;
+}
+// ── Tool call presentation ───────────────────────────────────────────
+const CLAUDE_TOOL_TITLE_MAX_CHARS = 120;
+const CLAUDE_TOOL_FAILURE_SUMMARY_MAX_CHARS = 120;
+/** TodoWrite is the plan card, not a tool receipt. */
+export const CLAUDE_PLAN_TOOL_NAME = 'TodoWrite';
+/** The margin row's title for the plan card, which is the card's own heading. */
+export const CLAUDE_PLAN_BLOCK_TITLE = PLAN_BLOCK_TITLE;
+function truncateClaudeToolText(value, maxChars) {
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxChars)
+        return collapsed;
+    let end = maxChars - 1;
+    // Cut on a code-point boundary. `slice` counts UTF-16 units, so a boundary
+    // that lands inside a surrogate pair (any emoji, and plenty of CJK) would
+    // leave a lone surrogate as the last character — an unpaired half that is not
+    // well-formed UTF-8 and renders as a replacement character wherever this
+    // title goes, from the live margin row to the persisted turn trail.
+    const lastUnit = collapsed.charCodeAt(end - 1);
+    if (lastUnit >= 0xd800 && lastUnit <= 0xdbff)
+        end -= 1;
+    return `${collapsed.slice(0, end)}…`;
+}
+function readToolInput(input, key) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return null;
+    return readTrimmedString(input[key]);
+}
+function claudeToolCallDetail(toolName, input) {
+    switch (toolName) {
+        case 'Bash': {
+            const command = readToolInput(input, 'command');
+            return command ? `Running: ${command}` : null;
+        }
+        case 'BashOutput': {
+            const id = readToolInput(input, 'bash_id');
+            return id ? `Reading output of ${id}` : null;
+        }
+        case 'Read':
+        case 'Write':
+        case 'Edit': {
+            const path = readToolInput(input, 'file_path');
+            return path ? `${toolName} ${path}` : null;
+        }
+        case 'NotebookEdit': {
+            const path = readToolInput(input, 'notebook_path');
+            return path ? `Edit ${path}` : null;
+        }
+        case 'Grep':
+        case 'Glob': {
+            const pattern = readToolInput(input, 'pattern');
+            return pattern ? `${toolName} ${pattern}` : null;
+        }
+        case 'Task': {
+            const description = readToolInput(input, 'description');
+            return description ? `Task: ${description}` : null;
+        }
+        case 'WebFetch': {
+            const url = readToolInput(input, 'url');
+            return url ? `Fetch ${url}` : null;
+        }
+        case 'WebSearch': {
+            const query = readToolInput(input, 'query');
+            return query ? `Search ${query}` : null;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * The margin row's title for a tool call: what the agent actually did, not just
+ * which tool it reached for. Falls back to the tool name whenever the typed
+ * input is missing or shaped differently than expected — an unknown tool is
+ * still worth a row.
+ */
+export function summarizeClaudeToolCall(name, input) {
+    const toolName = readTrimmedString(name) ?? 'Tool';
+    return truncateClaudeToolText(claudeToolCallDetail(toolName, input) ?? toolName, CLAUDE_TOOL_TITLE_MAX_CHARS);
+}
+function readToolResultText(content) {
+    const direct = readTrimmedString(content);
+    if (direct)
+        return direct;
+    if (!Array.isArray(content))
+        return null;
+    for (const entry of content) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const text = readTrimmedString(entry.text);
+        if (text)
+            return text;
+    }
+    return null;
+}
+/** One-line reason for a failed tool call, for the receipt's summary slot. */
+export function summarizeClaudeToolFailure(content) {
+    const text = readToolResultText(content);
+    return text
+        ? truncateClaudeToolText(text, CLAUDE_TOOL_FAILURE_SUMMARY_MAX_CHARS)
+        : 'Tool call failed';
+}
+const CLAUDE_ELAPSED_SUMMARY_MIN_SECONDS = 5;
+/**
+ * Progress text for a call that is taking a while. Short calls get nothing:
+ * every summary change is an RTDB write, and "Running for 1s" says nothing the
+ * running row does not already say.
+ */
+export function formatClaudeToolElapsed(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds))
+        return null;
+    const whole = Math.floor(seconds);
+    if (whole < CLAUDE_ELAPSED_SUMMARY_MIN_SECONDS)
+        return null;
+    if (whole < 60)
+        return `Running for ${whole}s`;
+    const minutes = Math.floor(whole / 60);
+    const remainder = whole % 60;
+    return remainder
+        ? `Running for ${minutes}m ${remainder}s`
+        : `Running for ${minutes}m`;
+}
+// ── Plan card ────────────────────────────────────────────────────────
+const CLAUDE_PLAN_MAX_ITEMS = 30;
+const CLAUDE_PLAN_ITEM_MAX_CHARS = 120;
+/**
+ * TodoWrite's typed input mapped onto the shared plan grammar (`renderPlanSteps`
+ * in @canonmsg/coding-agent-host), which both coding-agent hosts render through
+ * so a plan card reads the same whichever runtime produced it. What stays here
+ * is what is genuinely Claude's: the SDK's todo shape, its `activeForm` wording
+ * for the step being worked on ("Running the tests"), the per-step and
+ * per-plan bounds, and publishing NOTHING rather than a bare heading when a
+ * TodoWrite call carries no usable step.
+ *
+ * Unusable entries are dropped before rendering, so the numbering the reader
+ * sees stays contiguous.
+ */
+export function renderTodosAsPlan(todos) {
+    if (!Array.isArray(todos))
+        return null;
+    const steps = [];
+    for (const entry of todos.slice(0, CLAUDE_PLAN_MAX_ITEMS)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const content = readTrimmedString(record.content);
+        const activeForm = readTrimmedString(record.activeForm);
+        const status = normalizePlanStepStatus(record.status);
+        const label = status === 'in_progress'
+            ? activeForm ?? content
+            : content ?? activeForm;
+        if (!label)
+            continue;
+        steps.push({ text: truncateClaudeToolText(label, CLAUDE_PLAN_ITEM_MAX_CHARS), status });
+    }
+    if (steps.length === 0)
+        return null;
+    return renderPlanSteps(steps);
+}
+/**
+ * `content_block_start` for a `tool_use`: the call claims its row, titled with
+ * the tool's name until the typed input arrives on the assistant message.
+ */
+export function planClaudeToolCallStart(state, input) {
+    // Registered even for TodoWrite: `content_block_stop` resolves the turn out of
+    // its 'tool' state by index, and an unclaimed index would leave it stuck.
+    const blockId = registerClaudeToolCallBlock(state, input);
+    const toolName = readTrimmedString(input.name);
+    // TodoWrite is the plan card, published once its todos arrive; no receipt.
+    if (toolName === CLAUDE_PLAN_TOOL_NAME)
+        return [];
+    return [{
+            op: 'add',
+            id: blockId,
+            kind: 'tool',
+            status: 'running',
+            title: toolName ?? 'Claude tool use',
+        }];
+}
+/**
+ * The assistant message is the first place a call's typed INPUT is visible —
+ * `content_block_start` carries only the name. It is what turns "Bash" into
+ * "Running: npm test" and TodoWrite into the plan card.
+ */
+export function planClaudeAssistantTrail(state, content, turnId) {
+    if (!Array.isArray(content))
+        return [];
+    const commands = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const candidate = block;
+        if (candidate.type !== 'tool_use')
+            continue;
+        if (candidate.name === CLAUDE_PLAN_TOOL_NAME) {
+            const text = renderTodosAsPlan(candidate.input?.todos);
+            if (!text)
+                continue;
+            // One stable id per turn, so the card updates in place as steps tick over
+            // instead of stacking a new card per TodoWrite call.
+            commands.push({
+                op: 'add',
+                id: claimClaudePlanBlockId(state, turnId),
+                kind: 'plan',
+                status: 'running',
+                title: CLAUDE_PLAN_BLOCK_TITLE,
+                text,
+            });
+            continue;
+        }
+        // Without an id there is no way to tell whether this call already has a
+        // row; claiming another one would duplicate it. The name-only row that
+        // content_block_start published stands.
+        if (!readTrimmedString(candidate.id))
+            continue;
+        // Registering here as well as on content_block_start keeps the receipt
+        // (and its later completion) working when partial messages are off.
+        const blockId = registerClaudeToolCallBlock(state, { toolUseId: candidate.id, turnId });
+        commands.push({
+            op: 'add',
+            id: blockId,
+            // No status: an existing row keeps whatever it has, so a result that
+            // somehow landed first is not reopened.
+            kind: 'tool',
+            title: summarizeClaudeToolCall(candidate.name, candidate.input),
+        });
+    }
+    return commands;
+}
+/**
+ * `tool_result` on a `user` message: where a call's OUTCOME finally arrives.
+ * Rows settle here and nowhere else — `content_block_stop` only means the model
+ * finished writing the call.
+ */
+export function planClaudeToolResults(state, content) {
+    if (!Array.isArray(content))
+        return [];
+    const commands = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const candidate = block;
+        if (candidate.type !== 'tool_result')
+            continue;
+        // Keyed by tool_use id, so results that come back out of order still
+        // resolve the row that asked for them.
+        const blockId = resolveClaudeToolBlockId(state, candidate.tool_use_id);
+        if (!blockId)
+            continue;
+        if (candidate.is_error === true) {
+            commands.push({ op: 'fail', id: blockId, summary: summarizeClaudeToolFailure(candidate.content) });
+        }
+        else {
+            // The empty summary drops any progress note the row picked up while it
+            // ran: the last reading is not the call's duration (progress stops
+            // arriving before the tool returns), and "Running for 12s" on a row that
+            // has settled reads as a call still in flight.
+            commands.push({ op: 'complete', id: blockId, summary: '' });
+        }
+    }
+    return commands;
+}
+/** `tool_progress`: a long call says how long it has been going. */
+export function planClaudeToolProgress(state, input) {
+    const blockId = resolveClaudeToolBlockId(state, input.toolUseId);
+    const elapsed = formatClaudeToolElapsed(input.elapsedSeconds);
+    if (!blockId || !elapsed)
+        return [];
+    return [{ op: 'update', id: blockId, summary: elapsed }];
 }
 // Provenance for a Canon message entering the SDK. From 0.3.220 an absent
 // `origin` is "unattributed" and fails closed at strict isHuman() gates, so a
@@ -87,17 +714,15 @@ export function buildClaudeFinalTurnMetadata(input) {
         ...(input.turnTrail && input.turnTrail.length > 0 ? { turnTrail: input.turnTrail } : {}),
     };
 }
-const CLAUDE_FAILURE_DETAIL_MAX_CHARS = 280;
 function claudeFailureDetail(errors) {
     if (!Array.isArray(errors))
         return null;
     const first = errors.find((entry) => typeof entry === 'string' && entry.trim());
     if (typeof first !== 'string')
         return null;
-    const trimmed = first.trim();
-    return trimmed.length > CLAUDE_FAILURE_DETAIL_MAX_CHARS
-        ? `${trimmed.slice(0, CLAUDE_FAILURE_DETAIL_MAX_CHARS - 1)}…`
-        : trimmed;
+    // The shared bound on error text quoted back into a chat message, so no
+    // notice can let a multi-KB error body push itself over Canon's size limit.
+    return truncateFailureDetail(first);
 }
 function claudeUsageLimitDetail(errors) {
     if (!Array.isArray(errors))
@@ -144,6 +769,253 @@ export function composeClaudeFinalText(input) {
         return primary;
     return primary ? `${primary}\n\n${input.failureNotice}` : input.failureNotice;
 }
+/**
+ * How the host should react to a failed final-reply send.
+ *
+ * Core's `isRetryableCanonDeliveryError` is already right about what a retry
+ * can fix (429, 5xx, transport errors); what the host lacked was the other
+ * half — everything else is PERMANENT and must be surfaced instead of retried.
+ * A 409 from the server's idempotency guard means a message already exists
+ * under this id, so the reply is durable: that is a success, not a failure.
+ *
+ * A CHUNKED final is the exception (#616's rule, kept). A chunked send is N
+ * sequential messages that abort on the first failure, so a 409 says only that
+ * ONE part id is taken, with nothing to say which — and since the part ids are
+ * a pure hash of agent + conversation + turnKey, an id can be taken by an
+ * ENTIRELY DIFFERENT answer to the same inbound message, written by a previous
+ * process. Reading that as "the final is delivered" would finalize the turn
+ * with the tail never sent, so it stays 'permanent': a stops-short notice beats
+ * silently dropping the end of an answer.
+ *
+ * Resume support does not soften this. Core absorbs the one conflict that IS
+ * provably ours — the first part of a resumed attempt, whose write may have
+ * landed before its response was lost — and reports every other one, so a
+ * conflict reaching this function is precisely the case that must not be read
+ * as success.
+ */
+export function classifyFinalDeliveryFailure(error, options = {}) {
+    if (isCanonMessageIdConflict(error) && !options.chunked) {
+        return 'already-delivered';
+    }
+    return isRetryableCanonDeliveryError(error) ? 'retry' : 'permanent';
+}
+/**
+ * The pending-delivery record for a final that has to be retried, carrying the
+ * progress the next attempt needs.
+ *
+ * Progress is monotonic: a later attempt can only ever add parts, so the longer
+ * of the two lists wins and a retry can never rewind the cursor. The metadata
+ * and the self-context are pinned to the FIRST attempt's values, because those
+ * are what the durable parts were fingerprinted against.
+ */
+export function buildClaudePendingFinalDelivery(input) {
+    const previous = input.previous?.turnKey === input.turnKey ? input.previous : null;
+    const previousDelivered = previous?.deliveredMessageIds ?? [];
+    const nextDelivered = input.deliveredMessageIds ?? [];
+    const delivered = nextDelivered.length >= previousDelivered.length
+        ? [...nextDelivered]
+        : [...previousDelivered];
+    const metadata = previous?.metadata ?? input.metadata;
+    // `previous` may pin a null self-context (a conversation with none), which
+    // must still win over a later inbound message's value — hence the key check
+    // rather than `??`.
+    const selfContextId = previous && 'selfContextId' in previous
+        ? previous.selfContextId
+        : input.selfContextId;
+    const lastErrorMessage = input.lastErrorMessage ?? previous?.lastErrorMessage;
+    return {
+        turnKey: input.turnKey,
+        text: input.text,
+        messageId: input.messageId,
+        retryCount: previous?.retryCount ?? 0,
+        ...(input.suppressAutoReply ? { suppressAutoReply: true } : {}),
+        ...(delivered.length > 0 ? { deliveredMessageIds: delivered } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(selfContextId !== undefined ? { selfContextId } : {}),
+        ...(lastErrorMessage ? { lastErrorMessage: truncateFailureDetail(lastErrorMessage) } : {}),
+    };
+}
+/**
+ * What a retry of this turn's final should reuse: the parts already durable,
+ * and the metadata and self-context they were written with. Empty for a first
+ * attempt, or when the pending record belongs to a different turn.
+ */
+export function readClaudeFinalDeliveryResume(pending, turnKey) {
+    if (!pending || pending.turnKey !== turnKey)
+        return { deliveredMessageIds: [] };
+    return {
+        deliveredMessageIds: [...(pending.deliveredMessageIds ?? [])],
+        ...(pending.metadata ? { metadata: pending.metadata } : {}),
+        ...('selfContextId' in pending ? { selfContextId: pending.selfContextId } : {}),
+    };
+}
+/**
+ * The chunking options a final send opts into, built from the resume cursor.
+ *
+ * A helper rather than an inline literal so the opt-in is one testable seam:
+ * dropping `resumable` restores restart-from-part-1, which no assertion on a
+ * hand-built call could catch.
+ */
+export function buildClaudeFinalChunkingOptions(resume) {
+    return { resumable: true, deliveredMessageIds: resume.deliveredMessageIds };
+}
+/** True when a final of this size will be split across several messages. */
+export function claudeFinalWillChunk(finalText, maxTextBytes = DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES) {
+    // Mirrors core's splitTextByUtf8Bytes threshold so the host's pre-flight and
+    // the actual send always agree on whether chunking happens.
+    return utf8ByteLength(finalText) > maxTextBytes;
+}
+/**
+ * The turn trail to attach to a final that is about to be sent.
+ *
+ * A chunked final's LAST message carries the answer's tail, while the trail's
+ * text blocks carry the compacted head. chat-domain's `buildTurnRenderParts`
+ * appends `message.text` after structured speech that is not a prefix of it, so
+ * an unfiltered trail would render the head again above the tail. Text blocks
+ * are therefore dropped from a chunked final; tool/plan/approval/status blocks
+ * are the margin's activity record and stay. Unchunked finals are untouched,
+ * which keeps the common case byte-identical to before.
+ */
+export function prepareTurnTrailForDelivery(trail, willChunk) {
+    if (!willChunk)
+        return [...trail];
+    return trail.filter((block) => block.kind !== 'text');
+}
+export const CLAUDE_FINAL_TRUNCATION_MARKER = "\n\n_[truncated — the full answer exceeded Canon's message size limit]_";
+/** How far back from the cut a paragraph break is still worth cutting at. */
+const CLAUDE_TRUNCATION_BOUNDARY_WINDOW_CHARS = 400;
+function sliceByUtf8Bytes(text, maxBytes) {
+    let out = '';
+    let bytes = 0;
+    // Iterating code points (not UTF-16 units) keeps surrogate pairs intact,
+    // matching how core splits chunks.
+    for (const char of text) {
+        const charBytes = utf8ByteLength(char);
+        if (bytes + charBytes > maxBytes)
+            break;
+        out += char;
+        bytes += charBytes;
+    }
+    return out;
+}
+/**
+ * Last-resort degradation for a final Canon refuses to accept: keep as much of
+ * the answer as fits in ONE message and say that the rest was dropped. Prefers
+ * to cut at a paragraph break near the end so the survivor reads as prose. The
+ * result — marker included — always fits the byte budget.
+ *
+ * Deliberate trade-off: this keeps the HEAD, so a trailing paragraph is lost —
+ * including the turn-failure notice `composeClaudeFinalText` appends last. That
+ * is acceptable only because the host calls this on a final that already fits
+ * (an oversized final is chunked, never truncated), so nothing is actually cut;
+ * it is the bound that keeps the degraded send legal, not a text editor. A
+ * caller that truncates for real must re-attach its own trailing notice.
+ */
+export function buildTruncatedFinalText(finalText, maxTextBytes = DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES) {
+    if (utf8ByteLength(finalText) <= maxTextBytes)
+        return finalText;
+    const markerBytes = utf8ByteLength(CLAUDE_FINAL_TRUNCATION_MARKER);
+    const budget = maxTextBytes - markerBytes;
+    if (budget <= 0)
+        return CLAUDE_FINAL_TRUNCATION_MARKER.trim();
+    const head = sliceByUtf8Bytes(finalText, budget);
+    const windowStart = Math.max(0, head.length - CLAUDE_TRUNCATION_BOUNDARY_WINDOW_CHARS);
+    const boundary = head.lastIndexOf('\n\n');
+    const kept = boundary > 0 && boundary >= windowStart ? head.slice(0, boundary) : head;
+    return `${kept.trimEnd()}${CLAUDE_FINAL_TRUNCATION_MARKER}`;
+}
+/**
+ * Server-side `metadata` cap, taken from the shared contract rather than
+ * re-typed here. Note the UNIT: unlike message text, which the server measures
+ * in UTF-8 bytes, metadata is capped by `JSON.stringify(metadata).length` —
+ * UTF-16 code units — in both places it is checked (the request schema's
+ * misleadingly named `maxJsonBytes` and the handler's inline check). Mirroring
+ * it in bytes would be a different, stricter rule that drops the margin's
+ * activity record on payloads Canon would have accepted.
+ */
+export const CLAUDE_MESSAGE_METADATA_MAX_CHARS = VERB_LIMITS.messageMetadataJsonChars;
+/**
+ * Defensive pre-flight for message metadata. Hosts already bound the trail via
+ * core's `buildBoundedTurnTrail`, so this should never fire; if it ever does,
+ * losing the margin's activity record beats losing the answer.
+ */
+export function boundClaudeFinalMetadata(metadata, maxChars = CLAUDE_MESSAGE_METADATA_MAX_CHARS) {
+    if (JSON.stringify(metadata).length <= maxChars)
+        return metadata;
+    const { turnTrail: _turnTrail, ...rest } = metadata;
+    return rest;
+}
+/**
+ * How Claude says a final could not be delivered. The sentence's shape and the
+ * bound on the quoted error are shared with the other coding-agent hosts; only
+ * the voice is Claude's — it speaks as itself, in the first person, because
+ * that is who the reader has been talking to all turn.
+ */
+const CLAUDE_UNDELIVERABLE_FINAL_WORDING = {
+    lead: 'I finished this turn, but Canon rejected the reply',
+    partialLead: 'I finished this turn, but Canon rejected the rest of the reply, so it stops short',
+};
+/**
+ * The standalone notice for a final Canon will not accept — the last thing the
+ * host can say when the answer itself cannot be delivered.
+ *
+ * `partiallyDelivered` marks a chunked final whose earlier parts are already in
+ * the conversation: the reader can see text, and needs to be told it stops
+ * short rather than being left to assume the answer ended there.
+ */
+export function buildUndeliverableFinalNotice(input) {
+    return buildHostUndeliverableFinalNotice({
+        ...input,
+        wording: CLAUDE_UNDELIVERABLE_FINAL_WORDING,
+    });
+}
+/**
+ * What is left to say when the bounded retries for a final run out.
+ *
+ * With parts of a chunked answer already in the conversation, silence is the
+ * wrong ending: the reader takes the last delivered part for the end of the
+ * answer. That case gets the stops-short notice, which completes the turn.
+ *
+ * With NOTHING delivered there is deliberately no notice, so the host can clear
+ * `/streaming` and let functions' `onStreamingCleared` preserve the streamed
+ * text as a durable progress message — a notice would complete the turn and
+ * suppress exactly that fallback, leaving the reader with an apology and no
+ * answer at all.
+ */
+export function planExhaustedFinalDelivery(pending) {
+    const partiallyDelivered = (pending.deliveredMessageIds?.length ?? 0) > 0;
+    return {
+        partiallyDelivered,
+        notice: partiallyDelivered
+            ? buildUndeliverableFinalNotice({
+                error: pending.lastErrorMessage ?? 'delivery retries were exhausted',
+                partiallyDelivered: true,
+            })
+            : null,
+    };
+}
+/**
+ * End a final whose retries ran out: say it stops short, THEN retire the turn.
+ *
+ * The order is the point, which is why the sequence lives here. The pending
+ * record is what makes the session read busy to inbound messages, and the
+ * notice is a network send with its own retries — clearing the record first
+ * left the session 'running' with no timer and no pending delivery, so an
+ * interrupt arriving in that window fired `query.interrupt()` at an SDK whose
+ * turn had already produced its result, flipped the turn row to 'interrupted'
+ * and cleared `/streaming` out from under the retirement.
+ */
+export async function runClaudeExhaustedFinalDelivery(session, pending, deps) {
+    const { notice } = planExhaustedFinalDelivery(pending);
+    if (notice) {
+        // Best effort: the notice failing is no reason to leave the turn open.
+        await deps.sendNotice(notice).catch(() => { });
+    }
+    if (session.pendingFinalDelivery?.turnKey === pending.turnKey) {
+        session.pendingFinalDelivery = null;
+    }
+    deps.retireTurn();
+}
 // Model options are discovery-driven: the host publishes whatever the Claude
 // Code CLI it spawns reports. A CLI older than this predates whole model
 // families (2.1.220 is the first to know Opus 5), so an old binary silently