@navels/neal 0.1.0

package/dist/neal/providers/anthropic-claude.js

@@ -0,0 +1,1599 @@
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { query, } from '@anthropic-ai/claude-agent-sdk';
+import { buildStructuredJsonPrompt, runStructuredJsonProtocol, runStructuredJsonRepairLoop, validateStructuredJsonPayload, } from '../agents/structured-json.js';
+import { NealProviderError } from './types.js';
+const ANTHROPIC_CLAUDE_PROVIDER_ID = 'anthropic-claude';
+const requireFromProvider = createRequire(import.meta.url);
+const requireFromClaudeSdk = createRequire(requireFromProvider.resolve('@anthropic-ai/claude-agent-sdk'));
+function getGlibcVersionRuntime() {
+    const report = process.report;
+    const glibcVersionRuntime = report?.getReport?.().header?.glibcVersionRuntime;
+    return typeof glibcVersionRuntime === 'string' && glibcVersionRuntime.length > 0 ? glibcVersionRuntime : undefined;
+}
+function isGlibcRuntime(glibcVersionRuntime) {
+    return typeof glibcVersionRuntime === 'string' && glibcVersionRuntime.length > 0;
+}
+export function getClaudeCodeExecutablePath(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const resolve = options.resolve ?? requireFromClaudeSdk.resolve.bind(requireFromClaudeSdk);
+    const glibcVersionRuntime = 'glibcVersionRuntime' in options ? options.glibcVersionRuntime : getGlibcVersionRuntime();
+    if (platform !== 'linux' || !isGlibcRuntime(glibcVersionRuntime)) {
+        return undefined;
+    }
+    try {
+        return resolve(`@anthropic-ai/claude-agent-sdk-linux-${arch}/claude`);
+    }
+    catch {
+        return undefined;
+    }
+}
+// Extended thinking can run for many minutes before the first visible text or
+// tool call. Surfacing it keeps the turn-liveness watchdog from treating a
+// deep-thinking turn as a silent stall, but thinking deltas arrive far too
+// often to persist one event each, so emission is throttled per log state.
+const THINKING_PROGRESS_EMIT_INTERVAL_MS = 30_000;
+async function emitClaudeThinkingProgress(label, state, events, sessionHandle, role = roleForClaudeLabel(label), estimatedTokens) {
+    const now = Date.now();
+    if (now - state.lastThinkingEmitMs < THINKING_PROGRESS_EMIT_INTERVAL_MS) {
+        return;
+    }
+    state.lastThinkingEmitMs = now;
+    await emitProviderEvent(events, {
+        type: 'assistant_thinking',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role,
+        label,
+        sessionHandle,
+        ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
+    });
+}
+class ClaudeInactivityTimeoutError extends Error {
+    constructor(timeoutMs, label) {
+        super(`Claude ${label} timed out after ${Math.round(timeoutMs / 1000)}s without progress`);
+        this.name = 'ClaudeInactivityTimeoutError';
+    }
+}
+// In-round transient (`api_error`) retries back off exponentially: 500 ms
+// base, doubling per retry, capped at 5 s — the same schedule as the
+// generic-agentic adapter. `sleep` is injectable through the run functions so
+// tests observe the delays without wall-clock waiting.
+const API_RETRY_BASE_DELAY_MS = 500;
+const API_RETRY_MAX_DELAY_MS = 5_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function getApiRetryDelayMs(retryCount) {
+    return Math.min(API_RETRY_BASE_DELAY_MS * 2 ** (retryCount - 1), API_RETRY_MAX_DELAY_MS);
+}
+async function emitProviderEvent(events, event) {
+    await events?.(event);
+}
+function getMirroredAssistantText(event, role, label) {
+    if (event.type !== 'assistant_text' ||
+        event.provider !== ANTHROPIC_CLAUDE_PROVIDER_ID ||
+        event.role !== role ||
+        event.label !== label) {
+        return null;
+    }
+    const text = event.text.trim();
+    return text ? text : null;
+}
+function roleForClaudeLabel(label) {
+    return label === 'coder' ? 'coder' : 'structured-advisor';
+}
+async function flushClaudeText(label, state, events, sessionHandle, role = roleForClaudeLabel(label)) {
+    const trimmed = state.textBuffer.trim();
+    if (!trimmed) {
+        state.textBuffer = '';
+        return null;
+    }
+    await emitProviderEvent(events, {
+        type: 'assistant_text',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role,
+        label,
+        sessionHandle,
+        text: trimmed,
+    });
+    state.textBuffer = '';
+    return trimmed;
+}
+async function appendClaudeText(label, state, text, events, sessionHandle, role = roleForClaudeLabel(label)) {
+    state.sawTextDelta = true;
+    state.textBuffer += text;
+    const emittedTexts = [];
+    const lines = state.textBuffer.split('\n');
+    state.textBuffer = lines.pop() ?? '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        await emitProviderEvent(events, {
+            type: 'assistant_text',
+            provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+            role,
+            label,
+            sessionHandle,
+            text: trimmed,
+        });
+        emittedTexts.push(trimmed);
+    }
+    return emittedTexts;
+}
+async function logClaudeMessage(label, message, events, state, sessionHandle, role = roleForClaudeLabel(label)) {
+    switch (message.type) {
+        case 'assistant': {
+            if (state?.sawTextDelta) {
+                return [];
+            }
+            const textBlocks = message.message.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text.trim())
+                .filter(Boolean);
+            if (textBlocks.length > 0) {
+                for (const text of textBlocks) {
+                    await emitProviderEvent(events, {
+                        type: 'assistant_text',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        text,
+                    });
+                }
+                return textBlocks;
+            }
+            break;
+        }
+        case 'stream_event':
+            if (message.event.type === 'content_block_delta') {
+                if (message.event.delta.type === 'text_delta' && state) {
+                    return await appendClaudeText(label, state, message.event.delta.text, events, sessionHandle, role);
+                }
+                if (message.event.delta.type === 'thinking_delta' && state) {
+                    await emitClaudeThinkingProgress(label, state, events, sessionHandle, role);
+                }
+            }
+            else if (message.event.type === 'content_block_stop' && state) {
+                const flushedText = await flushClaudeText(label, state, events, sessionHandle, role);
+                return flushedText ? [flushedText] : [];
+            }
+            break;
+        case 'tool_progress':
+            await emitProviderEvent(events, {
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role,
+                label,
+                sessionHandle,
+                toolName: message.tool_name,
+                message: `tool ${message.tool_name} running (${message.elapsed_time_seconds}s)`,
+                providerData: {
+                    sdkMessageType: message.type,
+                    elapsedTimeSeconds: message.elapsed_time_seconds,
+                },
+            });
+            break;
+        case 'tool_use_summary':
+            await emitProviderEvent(events, {
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role,
+                label,
+                sessionHandle,
+                toolName: 'tool_use_summary',
+                message: message.summary,
+                providerData: { sdkMessageType: message.type },
+            });
+            break;
+        case 'system':
+            switch (message.subtype) {
+                case 'local_command_output':
+                    await emitProviderEvent(events, {
+                        type: 'tool_progress',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        toolName: 'local_command_output',
+                        message: message.content,
+                        providerData: { sdkMessageType: message.type, subtype: message.subtype },
+                    });
+                    break;
+                case 'task_started':
+                    await emitProviderEvent(events, {
+                        type: 'tool_started',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        toolName: 'task',
+                        providerData: { sdkMessageType: message.type, subtype: message.subtype, description: message.description },
+                    });
+                    await emitProviderEvent(events, {
+                        type: 'tool_progress',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        toolName: 'task',
+                        message: `task started: ${message.description}`,
+                        providerData: { sdkMessageType: message.type, subtype: message.subtype },
+                    });
+                    break;
+                case 'task_progress':
+                    await emitProviderEvent(events, {
+                        type: 'tool_progress',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        toolName: 'task',
+                        message: message.description,
+                        providerData: { sdkMessageType: message.type, subtype: message.subtype },
+                    });
+                    break;
+                case 'task_notification':
+                    await emitProviderEvent(events, {
+                        type: 'tool_progress',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        toolName: 'task',
+                        message: `task ${message.status}: ${message.summary}`,
+                        providerData: { sdkMessageType: message.type, subtype: message.subtype, status: message.status },
+                    });
+                    break;
+                case 'thinking_tokens':
+                    if (state) {
+                        await emitClaudeThinkingProgress(label, state, events, sessionHandle, role, message.estimated_tokens);
+                    }
+                    break;
+                case 'status':
+                    if (message.status) {
+                        await emitProviderEvent(events, {
+                            type: 'tool_progress',
+                            provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                            role,
+                            label,
+                            sessionHandle,
+                            toolName: 'status',
+                            message: `status: ${message.status}`,
+                            providerData: { sdkMessageType: message.type, subtype: message.subtype },
+                        });
+                    }
+                    break;
+                default:
+                    break;
+            }
+            break;
+        case 'result':
+            await emitProviderEvent(events, {
+                type: 'turn_completed',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role,
+                label,
+                sessionHandle,
+                usage: message.usage,
+                providerData: { sdkMessageType: message.type, subtype: message.subtype },
+            });
+            if (message.usage !== undefined) {
+                await emitProviderEvent(events, {
+                    type: 'usage_reported',
+                    provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                    role,
+                    label,
+                    sessionHandle,
+                    usage: message.usage,
+                    providerData: { sdkMessageType: message.type, subtype: message.subtype },
+                });
+            }
+            break;
+        default:
+            break;
+    }
+    return [];
+}
+// The timeout callback (which aborts the underlying query) runs before the
+// synchronous rejection, so the surfaced error is always the retryable
+// inactivity-timeout error — never the SDK's abort error, which would
+// misclassify the stall as a caller abort. Mirrors the Codex adapter.
+async function nextWithTimeout(promise, timeoutMs, label, onTimeout) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const timer = setTimeout(() => {
+            onTimeout?.();
+            rejectPromise(new ClaudeInactivityTimeoutError(timeoutMs, label));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolvePromise(value);
+        }, (error) => {
+            clearTimeout(timer);
+            rejectPromise(error);
+        });
+    });
+}
+function inferClaudeErrorKind(error, message, fallback, subtype) {
+    const text = `${subtype ?? ''}\n${message}`.toLowerCase();
+    if (error instanceof ClaudeInactivityTimeoutError || /\btimed out after\b/i.test(message)) {
+        return 'timeout';
+    }
+    if (text.includes('permission') || text.includes('denied') || text.includes('forbidden') || text.includes('not authorized')) {
+        return 'permission_denied';
+    }
+    if (text.includes('failed to provide valid structured output')) {
+        return 'structured_output_invalid';
+    }
+    if (text.includes('resume') || text.includes('session not found') || text.includes('session unavailable')) {
+        return 'session_unavailable';
+    }
+    if (isTransientClaudeFailure(subtype ?? null, message)) {
+        return 'api_error';
+    }
+    return fallback;
+}
+function isRetryableClaudeError(kind) {
+    return kind === 'timeout' || kind === 'session_unavailable' || kind === 'api_error';
+}
+function createClaudeProviderError(args) {
+    const kind = args.kind ?? inferClaudeErrorKind(args.cause, args.message, 'provider_failed', args.subtype);
+    return new NealProviderError({
+        message: args.message,
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: args.role,
+        sessionHandle: args.sessionHandle,
+        kind,
+        retryable: args.retryable ?? isRetryableClaudeError(kind),
+        cause: args.cause,
+    });
+}
+function normalizeClaudeProviderError(error, args) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof NealProviderError) {
+        if (error.sessionHandle || !args.sessionHandle) {
+            return error;
+        }
+        return createClaudeProviderError({
+            message: error.message,
+            role: error.role,
+            sessionHandle: args.sessionHandle,
+            kind: error.kind,
+            retryable: error.retryable,
+            cause: error,
+        });
+    }
+    return createClaudeProviderError({
+        message,
+        role: args.role,
+        sessionHandle: args.sessionHandle,
+        kind: args.kind,
+        cause: error,
+        subtype: args.subtype,
+    });
+}
+async function emitClaudeProviderError(events, error, label) {
+    await emitProviderEvent(events, {
+        type: 'provider_error',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: error.role,
+        label: label ?? (error.role === 'coder' ? 'coder' : undefined),
+        sessionHandle: error.sessionHandle,
+        message: error.message,
+        errorKind: error.kind,
+    });
+}
+function hasStructuredOutput(message) {
+    const raw = message;
+    return raw.structured_output !== undefined && raw.structured_output !== null;
+}
+function getPreferredStructuredOutput(result) {
+    const structuredResult = result.firstStructuredResult ?? result.lastResult;
+    const structuredOutput = structuredResult?.structured_output;
+    return structuredOutput === null ? undefined : structuredOutput;
+}
+async function collectClaudeResult(stream, cwd, label, inactivityTimeoutMs, events, role = roleForClaudeLabel(label), abortController) {
+    let sessionHandle = null;
+    let lastResult = null;
+    let firstStructuredResult = null;
+    const logState = { textBuffer: '', sawTextDelta: false, lastThinkingEmitMs: 0 };
+    const assistantTexts = [];
+    const iterator = stream[Symbol.asyncIterator]();
+    while (true) {
+        let next;
+        try {
+            // Aborting the per-turn controller cancels the SDK query on inactivity
+            // timeout, so a stalled turn stops burning its child process and tokens
+            // instead of racing a retry; the SDK owns stream teardown on abort, so
+            // no manual iterator.return() is needed (mirroring the Codex adapter).
+            next = await nextWithTimeout(iterator.next(), inactivityTimeoutMs, label, () => abortController?.abort());
+        }
+        catch (error) {
+            throw normalizeClaudeProviderError(error, {
+                role,
+                sessionHandle,
+            });
+        }
+        if (next.done) {
+            break;
+        }
+        const message = next.value;
+        const previousSessionHandle = sessionHandle;
+        sessionHandle = sessionHandle ?? message.session_id ?? null;
+        if (!previousSessionHandle && sessionHandle) {
+            await emitProviderEvent(events, {
+                type: 'session_started',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role,
+                label,
+                sessionHandle,
+                providerData: { sdkMessageType: message.type },
+            });
+        }
+        const emittedAssistantTexts = await logClaudeMessage(label, message, events, logState, sessionHandle, role);
+        if (emittedAssistantTexts.length > 0) {
+            assistantTexts.push(emittedAssistantTexts.join('\n\n'));
+        }
+        if (message.type === 'result') {
+            lastResult = message;
+            if (firstStructuredResult === null && hasStructuredOutput(message)) {
+                // Claude can emit late result messages for background tasks after the structured round result.
+                firstStructuredResult = message;
+            }
+        }
+    }
+    const flushedText = await flushClaudeText(label, logState, events, sessionHandle, role);
+    if (flushedText) {
+        assistantTexts.push(flushedText);
+    }
+    return {
+        sessionHandle,
+        lastResult,
+        firstStructuredResult,
+        assistantText: assistantTexts.join('\n\n').trim(),
+    };
+}
+// Creates the SDK-facing AbortController for one Claude turn so both
+// orchestration-level supervision (via the external caller-owned abort
+// signal, when present) and the per-turn inactivity timeout can cancel an
+// in-flight query through `Options.abortController`. Repair turns receive
+// their own unlinked controllers: repairs are short, prompt-only turns that
+// caller aborts intentionally do not cancel, but the inactivity timeout
+// still must be able to tear them down.
+function createClaudeTurnAbortController(signal) {
+    const abortController = new AbortController();
+    if (!signal) {
+        return abortController;
+    }
+    if (signal.aborted) {
+        abortController.abort(signal.reason);
+    }
+    else {
+        signal.addEventListener('abort', () => abortController.abort(signal.reason), { once: true });
+    }
+    return abortController;
+}
+// Builder-default derivation: when the run loop does not pass a per-turn
+// controller explicitly, query options carry an abortController only for an
+// external caller-owned abort signal.
+function deriveClaudeAbortController(signal) {
+    return signal ? createClaudeTurnAbortController(signal) : undefined;
+}
+function buildClaudeQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
+    return {
+        cwd: args.cwd,
+        ...(abortController ? { abortController } : {}),
+        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
+        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        tools: ['Read', 'Grep', 'Glob'],
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        ...(args.resumeHandle ? { resume: args.resumeHandle } : {}),
+        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        stderr: (data) => {
+            void args.events?.({
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle: args.resumeHandle ?? null,
+                toolName: 'stderr',
+                message: data,
+                isError: true,
+                providerData: { stream: 'stderr' },
+            });
+        },
+        outputFormat: {
+            type: 'json_schema',
+            schema: args.schema,
+        },
+    };
+}
+function buildClaudeQueryStream(args, defaultModel, defaultEffort, abortController) {
+    return query({
+        prompt: args.prompt,
+        options: buildClaudeQueryOptions(args, defaultModel, undefined, defaultEffort, abortController),
+    });
+}
+function buildClaudeJsonBlockReviewPrompt(args) {
+    if (args.structuredJsonProtocol?.protocol === 'neal-json-block-v1') {
+        return buildStructuredJsonPrompt(args.prompt, args.structuredJsonProtocol);
+    }
+    return args.prompt;
+}
+function buildClaudeJsonBlockQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
+    return {
+        cwd: args.cwd,
+        ...(abortController ? { abortController } : {}),
+        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
+        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        tools: ['Read', 'Grep', 'Glob'],
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        ...(args.resumeHandle ? { resume: args.resumeHandle } : {}),
+        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        stderr: (data) => {
+            void args.events?.({
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle: args.resumeHandle ?? null,
+                toolName: 'stderr',
+                message: data,
+                isError: true,
+                providerData: { stream: 'stderr' },
+            });
+        },
+    };
+}
+function buildClaudeJsonBlockQueryStream(args, defaultModel, defaultEffort, abortController) {
+    return query({
+        prompt: buildClaudeJsonBlockReviewPrompt(args),
+        options: buildClaudeJsonBlockQueryOptions(args, defaultModel, undefined, defaultEffort, abortController),
+    });
+}
+function buildClaudeJsonBlockRepairQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController) {
+    return {
+        cwd: args.cwd,
+        ...(abortController ? { abortController } : {}),
+        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
+        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        tools: [],
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        stderr: (data) => {
+            void args.events?.({
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: `${args.label}:structured-json-repair`,
+                sessionHandle: null,
+                toolName: 'stderr',
+                message: data,
+                isError: true,
+                providerData: { stream: 'stderr' },
+            });
+        },
+    };
+}
+function buildClaudeJsonBlockRepairQueryStream(args, repairPrompt, defaultModel, defaultEffort, abortController) {
+    return query({
+        prompt: repairPrompt,
+        options: buildClaudeJsonBlockRepairQueryOptions(args, defaultModel, undefined, defaultEffort, abortController),
+    });
+}
+function getClaudeResultErrorMessage(result) {
+    const raw = result;
+    if (!raw) {
+        return null;
+    }
+    if (typeof raw.result === 'string' && raw.result.trim()) {
+        return raw.result.trim();
+    }
+    if (raw.error && typeof raw.error === 'object') {
+        const message = raw.error.message;
+        if (typeof message === 'string' && message.trim()) {
+            return message.trim();
+        }
+    }
+    const errors = raw.errors;
+    if (Array.isArray(errors)) {
+        const messages = errors
+            .map((error) => (typeof error === 'string' ? error.trim() : ''))
+            .filter(Boolean);
+        if (messages.length > 0) {
+            return messages.join('; ');
+        }
+    }
+    return null;
+}
+// Callers classifying SDK result messages must gate on `is_error` before
+// calling this: a successful result's `result` field is the assistant's final
+// text, which can legitimately contain failure vocabulary (plans, reviews, and
+// docs that discuss error handling all mention strings like "api_error" or
+// "rate limit"), and matching on it turns a document about retries into an
+// endless retry loop.
+function isTransientClaudeFailure(subtype, message) {
+    const text = `${subtype ?? ''}\n${message ?? ''}`.toLowerCase();
+    return (text.includes('api_error') ||
+        text.includes('api error') ||
+        text.includes('internal server error') ||
+        text.includes('overloaded') ||
+        text.includes('rate limit') ||
+        text.includes('temporar') ||
+        (subtype === 'error_during_execution' &&
+            text.includes('[ede_diagnostic]') &&
+            text.includes('result_type=assistant') &&
+            text.includes('last_content_type=none') &&
+            text.includes('stop_reason=end_turn')) ||
+        text.includes('try again'));
+}
+function isStructuredOutputRetryExhaustion(subtype, message) {
+    const text = `${subtype ?? ''}\n${message ?? ''}`.toLowerCase();
+    return (subtype === 'error_max_structured_output_retries' ||
+        text.includes('failed to provide valid structured output'));
+}
+function getClaudeStructuredFailureKind(subtype, message) {
+    if (isTransientClaudeFailure(subtype, message)) {
+        return 'api_error';
+    }
+    if (isStructuredOutputRetryExhaustion(subtype, message)) {
+        return 'structured_output_invalid';
+    }
+    return subtype === 'success' || subtype === null ? 'structured_output_missing' : 'provider_failed';
+}
+function isClaudeJsonBlockStructuredAdvisorRound(args) {
+    return args.structuredJsonProtocol?.protocol === 'neal-json-block-v1';
+}
+function getClaudeAssistantTextForLocalJson(result, mirroredAssistantText = '') {
+    return [
+        result.assistantText,
+        mirroredAssistantText,
+        getClaudeResultErrorMessage(result.lastResult) ?? '',
+    ].find((value) => value.trim().length > 0)?.trim() ?? '';
+}
+function getStructuredJsonFailureSummaries(failure) {
+    return {
+        parseErrorSummary: failure.phase === 'extraction' ? failure.errorSummary : undefined,
+        validationErrorSummary: failure.phase === 'validation' ? failure.errorSummary : undefined,
+    };
+}
+function buildStructuredJsonProviderData(args) {
+    const summaries = args.failure
+        ? getStructuredJsonFailureSummaries(args.failure)
+        : {};
+    return {
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        protocol: args.roundArgs.structuredJsonProtocol.protocol,
+        schemaLabel: args.roundArgs.structuredJsonProtocol.schemaLabel,
+        attemptNumber: args.attemptNumber,
+        repairAttemptLimit: args.roundArgs.structuredJsonProtocol.repairAttemptLimit,
+        assistantTextLength: args.assistantTextLength,
+        extractedJsonLength: args.rawJson?.length ?? 0,
+        ...(args.source ? { source: args.source } : {}),
+        ...(summaries.parseErrorSummary ? { parseErrorSummary: summaries.parseErrorSummary } : {}),
+        ...(summaries.validationErrorSummary ? { validationErrorSummary: summaries.validationErrorSummary } : {}),
+        ...(args.originalSessionHandle !== undefined ? { originalSessionHandle: args.originalSessionHandle } : {}),
+        ...(args.repairSessionHandle !== undefined ? { repairSessionHandle: args.repairSessionHandle } : {}),
+    };
+}
+async function emitStructuredJsonExtractionStarted(args) {
+    await emitProviderEvent(args.roundArgs.events, {
+        type: 'tool_progress',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        sessionHandle: args.sessionHandle,
+        toolName: 'structured_json_extraction_started',
+        message: 'Extracting Claude review JSON control payload.',
+        providerData: buildStructuredJsonProviderData({
+            roundArgs: args.roundArgs,
+            attemptNumber: args.attemptNumber,
+            assistantTextLength: args.assistantText.length,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: args.repairSessionHandle,
+        }),
+    });
+}
+async function emitStructuredJsonFailure(args) {
+    const toolName = args.failure.phase === 'validation'
+        ? 'structured_json_validation_failed'
+        : 'structured_json_extraction_failed';
+    await emitProviderEvent(args.roundArgs.events, {
+        type: 'tool_progress',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        sessionHandle: args.sessionHandle,
+        toolName,
+        message: args.failure.phase === 'validation'
+            ? 'Claude review JSON control payload failed Neal validation.'
+            : 'Claude review JSON control payload could not be extracted or parsed.',
+        isError: true,
+        providerData: buildStructuredJsonProviderData({
+            roundArgs: args.roundArgs,
+            attemptNumber: args.attemptNumber,
+            assistantTextLength: args.assistantTextLength,
+            rawJson: args.failure.extraction.rawJson,
+            failure: args.failure,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: args.repairSessionHandle,
+        }),
+    });
+}
+async function emitStructuredJsonRepairStarted(args) {
+    await emitProviderEvent(args.roundArgs.events, {
+        type: 'tool_progress',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        sessionHandle: args.originalSessionHandle,
+        toolName: 'structured_json_repair_started',
+        message: `Repairing Claude review JSON control payload (${args.attemptNumber}/${args.attemptLimit}).`,
+        providerData: buildStructuredJsonProviderData({
+            roundArgs: args.roundArgs,
+            attemptNumber: args.attemptNumber,
+            assistantTextLength: args.assistantTextLength,
+            originalSessionHandle: args.originalSessionHandle,
+        }),
+    });
+}
+async function emitStructuredJsonOutputReceived(args) {
+    await emitProviderEvent(args.roundArgs.events, {
+        type: 'structured_output_received',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        sessionHandle: args.sessionHandle,
+        providerData: buildStructuredJsonProviderData({
+            roundArgs: args.roundArgs,
+            attemptNumber: args.attemptNumber,
+            assistantTextLength: args.assistantTextLength,
+            source: args.validation.source,
+            rawJson: args.validation.rawJson,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: args.repairSessionHandle,
+        }),
+    });
+}
+async function validateClaudeJsonBlockResponse(args) {
+    await emitStructuredJsonExtractionStarted(args);
+    const validation = validateStructuredJsonPayload(args.assistantText, args.roundArgs.structuredJsonProtocol.validator);
+    if (!validation.ok) {
+        await emitStructuredJsonFailure({
+            roundArgs: args.roundArgs,
+            failure: validation,
+            assistantTextLength: args.assistantText.length,
+            sessionHandle: args.sessionHandle,
+            attemptNumber: args.attemptNumber,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: args.repairSessionHandle,
+        });
+    }
+    return validation;
+}
+async function repairClaudeJsonBlockResponse(args) {
+    let repairResult;
+    try {
+        repairResult = await runStructuredJsonRepairLoop({
+            originalAssistantText: args.assistantText,
+            initialFailure: args.initialFailure,
+            schemaLabel: args.roundArgs.structuredJsonProtocol.schemaLabel,
+            schema: args.roundArgs.schema,
+            attemptLimit: args.roundArgs.structuredJsonProtocol.repairAttemptLimit,
+            validator: args.roundArgs.structuredJsonProtocol.validator,
+            callRepair: async ({ prompt, attemptNumber, attemptLimit }) => {
+                await emitStructuredJsonRepairStarted({
+                    roundArgs: args.roundArgs,
+                    attemptNumber,
+                    attemptLimit,
+                    assistantTextLength: args.assistantText.length,
+                    originalSessionHandle: args.originalSessionHandle,
+                });
+                const repairAbortController = new AbortController();
+                const stream = args.createRepairStream(args.roundArgs, prompt, args.defaultModel, args.defaultEffort, repairAbortController);
+                const result = await collectClaudeResult(stream, args.roundArgs.cwd, `${args.roundArgs.label}:structured-json-repair`, args.roundArgs.inactivityTimeoutMs, args.roundArgs.events, 'structured-advisor', repairAbortController);
+                return {
+                    assistantText: getClaudeAssistantTextForLocalJson(result),
+                    sessionHandle: result.sessionHandle,
+                };
+            },
+        });
+    }
+    catch (error) {
+        const providerError = normalizeClaudeProviderError(error, {
+            role: 'structured-advisor',
+            sessionHandle: args.originalSessionHandle,
+            kind: 'structured_output_invalid',
+        });
+        await emitProviderEvent(args.roundArgs.events, {
+            type: 'tool_progress',
+            provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+            role: 'structured-advisor',
+            label: args.roundArgs.label,
+            sessionHandle: providerError.sessionHandle,
+            toolName: 'structured_json_repair_failed',
+            message: 'Claude review JSON control payload repair failed before producing a valid Neal payload.',
+            isError: true,
+            providerData: {
+                ...buildStructuredJsonProviderData({
+                    roundArgs: args.roundArgs,
+                    attemptNumber: 0,
+                    assistantTextLength: args.assistantText.length,
+                    failure: args.initialFailure,
+                    originalSessionHandle: args.originalSessionHandle,
+                }),
+                errorKind: providerError.kind,
+                errorMessage: providerError.message,
+            },
+        });
+        await emitClaudeProviderError(args.roundArgs.events, providerError, args.roundArgs.label);
+        throw providerError;
+    }
+    for (const attempt of repairResult.attempts) {
+        if (!attempt.result.ok) {
+            await emitStructuredJsonFailure({
+                roundArgs: args.roundArgs,
+                failure: attempt.result,
+                assistantTextLength: args.assistantText.length,
+                sessionHandle: args.originalSessionHandle ?? attempt.sessionHandle,
+                attemptNumber: attempt.attemptNumber,
+                originalSessionHandle: args.originalSessionHandle,
+                repairSessionHandle: attempt.sessionHandle,
+            });
+        }
+    }
+    if (repairResult.ok) {
+        const returnedSessionHandle = args.originalSessionHandle ?? repairResult.sessionHandle;
+        await emitProviderEvent(args.roundArgs.events, {
+            type: 'tool_progress',
+            provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+            role: 'structured-advisor',
+            label: args.roundArgs.label,
+            sessionHandle: returnedSessionHandle,
+            toolName: 'structured_json_repair_succeeded',
+            message: 'Claude review JSON control payload repair produced a valid Neal payload.',
+            providerData: buildStructuredJsonProviderData({
+                roundArgs: args.roundArgs,
+                attemptNumber: repairResult.attemptNumber,
+                assistantTextLength: args.assistantText.length,
+                source: repairResult.result.source,
+                rawJson: repairResult.result.rawJson,
+                originalSessionHandle: args.originalSessionHandle,
+                repairSessionHandle: repairResult.sessionHandle,
+            }),
+        });
+        await emitStructuredJsonOutputReceived({
+            roundArgs: args.roundArgs,
+            validation: repairResult.result,
+            assistantTextLength: args.assistantText.length,
+            sessionHandle: returnedSessionHandle,
+            attemptNumber: repairResult.attemptNumber,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: repairResult.sessionHandle,
+        });
+        return {
+            sessionHandle: returnedSessionHandle,
+            structured: repairResult.result.structured,
+        };
+    }
+    await emitProviderEvent(args.roundArgs.events, {
+        type: 'tool_progress',
+        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+        role: 'structured-advisor',
+        label: args.roundArgs.label,
+        sessionHandle: args.originalSessionHandle,
+        toolName: 'structured_json_repair_failed',
+        message: 'Claude review JSON control payload repair attempts were exhausted.',
+        isError: true,
+        providerData: buildStructuredJsonProviderData({
+            roundArgs: args.roundArgs,
+            attemptNumber: repairResult.attempts.at(-1)?.attemptNumber ?? args.roundArgs.structuredJsonProtocol.repairAttemptLimit,
+            assistantTextLength: args.assistantText.length,
+            rawJson: repairResult.lastFailure.extraction.rawJson,
+            failure: repairResult.lastFailure,
+            originalSessionHandle: args.originalSessionHandle,
+            repairSessionHandle: repairResult.attempts.at(-1)?.sessionHandle ?? null,
+        }),
+    });
+    const providerError = createClaudeProviderError({
+        message: `Claude review JSON control payload remained invalid after ${args.roundArgs.structuredJsonProtocol.repairAttemptLimit} repair attempt(s): ${repairResult.lastFailure.errorSummary}`,
+        role: 'structured-advisor',
+        sessionHandle: args.originalSessionHandle,
+        kind: 'structured_output_invalid',
+        retryable: false,
+        cause: repairResult.lastFailure,
+    });
+    await emitClaudeProviderError(args.roundArgs.events, providerError, args.roundArgs.label);
+    throw providerError;
+}
+async function validateOrRepairClaudeJsonBlockResponse(args) {
+    try {
+        return await runStructuredJsonProtocol({
+            provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+            role: 'structured-advisor',
+            label: args.roundArgs.label,
+            protocol: args.roundArgs.structuredJsonProtocol,
+            prompt: args.roundArgs.prompt,
+            events: args.roundArgs.events,
+            initialSessionHandle: args.sessionHandle,
+            runInitial: async () => ({
+                assistantText: args.assistantText,
+                sessionHandle: args.sessionHandle,
+            }),
+            runRepair: async (prompt) => {
+                const repairAbortController = new AbortController();
+                const stream = args.createRepairStream(args.roundArgs, prompt, args.defaultModel, args.defaultEffort, repairAbortController);
+                const result = await collectClaudeResult(stream, args.roundArgs.cwd, `${args.roundArgs.label}:structured-json-repair`, args.roundArgs.inactivityTimeoutMs, args.roundArgs.events, 'structured-advisor', repairAbortController);
+                return {
+                    assistantText: getClaudeAssistantTextForLocalJson(result),
+                    sessionHandle: result.sessionHandle,
+                };
+            },
+            createProviderError: (errorArgs) => createClaudeProviderError({
+                message: errorArgs.message,
+                role: 'structured-advisor',
+                sessionHandle: errorArgs.sessionHandle,
+                kind: errorArgs.kind,
+                retryable: false,
+                cause: errorArgs.cause,
+            }),
+        });
+    }
+    catch (error) {
+        const providerError = normalizeClaudeProviderError(error, {
+            role: 'structured-advisor',
+            sessionHandle: args.sessionHandle,
+            kind: 'structured_output_invalid',
+        });
+        await emitClaudeProviderError(args.roundArgs.events, providerError, args.roundArgs.label);
+        throw providerError;
+    }
+}
+async function runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, createStream = buildClaudeJsonBlockQueryStream, createRepairStream = buildClaudeJsonBlockRepairQueryStream, defaultEffort, sleep = defaultSleep) {
+    let sessionHandle = args.resumeHandle ?? null;
+    let apiRetryCount = 0;
+    const apiRetryLimit = args.apiRetryLimit;
+    while (true) {
+        const mirroredAssistantTexts = [];
+        const primaryEvents = args.events
+            ? async (event) => {
+                const text = getMirroredAssistantText(event, 'structured-advisor', args.label);
+                if (text) {
+                    mirroredAssistantTexts.push(text);
+                }
+                await args.events?.(event);
+            }
+            : undefined;
+        let result;
+        try {
+            const turnAbortController = createClaudeTurnAbortController(args.signal);
+            result = await collectClaudeResult(createStream(args, defaultModel, defaultEffort, turnAbortController), args.cwd, args.label, args.inactivityTimeoutMs, primaryEvents, 'structured-advisor', turnAbortController);
+        }
+        catch (error) {
+            const providerError = normalizeClaudeProviderError(error, {
+                role: 'structured-advisor',
+                sessionHandle,
+            });
+            if (providerError.kind === 'api_error' && apiRetryCount < apiRetryLimit) {
+                apiRetryCount += 1;
+                await emitProviderEvent(args.events, {
+                    type: 'tool_progress',
+                    provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label: args.label,
+                    sessionHandle,
+                    toolName: 'api_retry',
+                    message: `transient API failure; retrying review (${apiRetryCount}/${apiRetryLimit})`,
+                    isError: true,
+                    providerData: {
+                        retryCount: apiRetryCount,
+                        retryLimit: apiRetryLimit,
+                        message: providerError.message,
+                    },
+                });
+                await sleep(getApiRetryDelayMs(apiRetryCount));
+                continue;
+            }
+            const mirroredAssistantText = mirroredAssistantTexts.join('\n\n').trim();
+            if (mirroredAssistantText &&
+                (providerError.kind === 'structured_output_invalid' || providerError.kind === 'structured_output_missing')) {
+                return await validateOrRepairClaudeJsonBlockResponse({
+                    roundArgs: args,
+                    assistantText: mirroredAssistantText,
+                    defaultModel,
+                    defaultEffort,
+                    sessionHandle: providerError.sessionHandle ?? sessionHandle,
+                    createRepairStream,
+                });
+            }
+            await emitClaudeProviderError(args.events, providerError, args.label);
+            throw providerError;
+        }
+        sessionHandle = result.sessionHandle ?? sessionHandle;
+        const subtype = result.lastResult?.subtype ?? null;
+        const resultErrorMessage = getClaudeResultErrorMessage(result.lastResult);
+        const isErrorResult = result.lastResult?.is_error === true;
+        if (isErrorResult && isTransientClaudeFailure(subtype, resultErrorMessage) && apiRetryCount < apiRetryLimit) {
+            apiRetryCount += 1;
+            await emitProviderEvent(args.events, {
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle,
+                toolName: 'api_retry',
+                message: `transient Claude error result; retrying review (${apiRetryCount}/${apiRetryLimit})`,
+                isError: true,
+                providerData: {
+                    retryCount: apiRetryCount,
+                    retryLimit: apiRetryLimit,
+                    subtype,
+                    message: resultErrorMessage,
+                },
+            });
+            await sleep(getApiRetryDelayMs(apiRetryCount));
+            continue;
+        }
+        const structuredRetryExhausted = isStructuredOutputRetryExhaustion(subtype, resultErrorMessage);
+        if (subtype && subtype !== 'success' && !structuredRetryExhausted) {
+            const providerError = createClaudeProviderError({
+                message: resultErrorMessage
+                    ? `Claude ${args.label} did not return a successful result${subtype ? ` (${subtype})` : ''}: ${resultErrorMessage}`
+                    : `Claude ${args.label} did not return a successful result${subtype ? ` (${subtype})` : ''}`,
+                role: 'structured-advisor',
+                sessionHandle,
+                kind: getClaudeStructuredFailureKind(subtype, resultErrorMessage),
+                subtype,
+            });
+            await emitClaudeProviderError(args.events, providerError, args.label);
+            throw providerError;
+        }
+        const assistantText = getClaudeAssistantTextForLocalJson(result, mirroredAssistantTexts.join('\n\n').trim());
+        return await validateOrRepairClaudeJsonBlockResponse({
+            roundArgs: args,
+            assistantText,
+            defaultModel,
+            defaultEffort,
+            sessionHandle,
+            createRepairStream,
+        });
+    }
+}
+async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream = buildClaudeQueryStream, defaultEffort, sleep = defaultSleep) {
+    if (isClaudeJsonBlockStructuredAdvisorRound(args)) {
+        return await runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, undefined, undefined, defaultEffort, sleep);
+    }
+    let sessionHandle = args.resumeHandle ?? null;
+    let apiRetryCount = 0;
+    const apiRetryLimit = args.apiRetryLimit;
+    while (true) {
+        let result;
+        const mirroredAssistantTexts = [];
+        const primaryEvents = args.events
+            ? async (event) => {
+                const text = getMirroredAssistantText(event, 'structured-advisor', args.label);
+                if (text) {
+                    mirroredAssistantTexts.push(text);
+                }
+                await args.events?.(event);
+            }
+            : undefined;
+        try {
+            const turnAbortController = createClaudeTurnAbortController(args.signal);
+            const stream = createStream(args, defaultModel, defaultEffort, turnAbortController);
+            result = await collectClaudeResult(stream, args.cwd, args.label, args.inactivityTimeoutMs, primaryEvents, 'structured-advisor', turnAbortController);
+        }
+        catch (error) {
+            const providerError = normalizeClaudeProviderError(error, {
+                role: 'structured-advisor',
+                sessionHandle,
+            });
+            const mirroredAssistantText = mirroredAssistantTexts.join('\n\n').trim();
+            if (providerError.kind === 'structured_output_invalid') {
+                await emitProviderEvent(args.events, {
+                    type: 'tool_progress',
+                    provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label: args.label,
+                    sessionHandle: providerError.sessionHandle ?? sessionHandle,
+                    toolName: 'structured_output_stream_error',
+                    message: 'Claude SDK structured output stream failed before Neal could process a final structured result.',
+                    isError: true,
+                    providerData: {
+                        errorKind: providerError.kind,
+                        errorMessage: providerError.message,
+                        collectedAssistantTextLength: mirroredAssistantText.length,
+                        mirroredAssistantTextCount: mirroredAssistantTexts.length,
+                    },
+                });
+            }
+            if (providerError.kind === 'api_error' && apiRetryCount < apiRetryLimit) {
+                apiRetryCount += 1;
+                await emitProviderEvent(args.events, {
+                    type: 'tool_progress',
+                    provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label: args.label,
+                    sessionHandle,
+                    toolName: 'api_retry',
+                    message: `transient API failure; retrying review (${apiRetryCount}/${apiRetryLimit})`,
+                    isError: true,
+                    providerData: {
+                        retryCount: apiRetryCount,
+                        retryLimit: apiRetryLimit,
+                        message: providerError.message,
+                    },
+                });
+                await sleep(getApiRetryDelayMs(apiRetryCount));
+                continue;
+            }
+            await emitClaudeProviderError(args.events, providerError, args.label);
+            throw providerError;
+        }
+        sessionHandle = result.sessionHandle ?? sessionHandle;
+        const lastResult = result.lastResult;
+        const structured = getPreferredStructuredOutput(result);
+        if (structured !== undefined) {
+            await emitProviderEvent(args.events, {
+                type: 'structured_output_received',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle,
+            });
+            return {
+                sessionHandle,
+                structured,
+            };
+        }
+        const subtype = lastResult?.subtype ?? null;
+        const resultErrorMessage = getClaudeResultErrorMessage(lastResult);
+        const structuredRetryExhausted = isStructuredOutputRetryExhaustion(subtype, resultErrorMessage);
+        if (structuredRetryExhausted) {
+            await emitProviderEvent(args.events, {
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle,
+                toolName: 'structured_output_retry_exhausted',
+                message: 'Claude SDK structured output failed after retries.',
+                isError: true,
+                providerData: {
+                    subtype,
+                    resultMessage: resultErrorMessage,
+                    collectedAssistantTextLength: result.assistantText.length,
+                    mirroredAssistantTextCount: mirroredAssistantTexts.length,
+                },
+            });
+        }
+        if (lastResult?.is_error === true && isTransientClaudeFailure(subtype, resultErrorMessage) && apiRetryCount < apiRetryLimit) {
+            apiRetryCount += 1;
+            await emitProviderEvent(args.events, {
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'structured-advisor',
+                label: args.label,
+                sessionHandle,
+                toolName: 'api_retry',
+                message: `transient Claude error result; retrying review (${apiRetryCount}/${apiRetryLimit})`,
+                isError: true,
+                providerData: {
+                    retryCount: apiRetryCount,
+                    retryLimit: apiRetryLimit,
+                    subtype,
+                    message: resultErrorMessage,
+                },
+            });
+            await sleep(getApiRetryDelayMs(apiRetryCount));
+            continue;
+        }
+        const providerError = createClaudeProviderError({
+            message: resultErrorMessage
+                ? `Claude ${args.label} did not return a successful result${subtype ? ` (${subtype})` : ''}: ${resultErrorMessage}`
+                : `Claude ${args.label} did not return a successful result${subtype ? ` (${subtype})` : ''}`,
+            role: 'structured-advisor',
+            sessionHandle,
+            kind: getClaudeStructuredFailureKind(subtype, resultErrorMessage),
+            subtype,
+        });
+        await emitClaudeProviderError(args.events, providerError, args.label);
+        throw providerError;
+    }
+}
+class AnthropicClaudeStructuredAdvisorAdapter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runStructuredRound(args) {
+        return runClaudeStructuredAdvisorRound(args, this.options.model, undefined, this.options.effort ?? undefined);
+    }
+}
+// Tool names that write to the local filesystem. Edit and Write are the only
+// write-class tools Neal exposes to the coder; the extra names keep the write
+// jail closed if the exposed toolset ever widens.
+const CLAUDE_WRITE_TOOL_NAMES = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+function getClaudeWriteToolPath(toolInput) {
+    if (toolInput === null || typeof toolInput !== 'object') {
+        return null;
+    }
+    const record = toolInput;
+    const filePath = record.file_path ?? record.notebook_path;
+    return typeof filePath === 'string' && filePath.trim() ? filePath : null;
+}
+// Mechanical enforcement of `toolPolicy.allowedWritePaths` for coder turns.
+// The coder runs with `permissionMode: 'bypassPermissions'`, which skips the
+// SDK's permission checks entirely — the `canUseTool` permission callback is
+// never consulted — but PreToolUse hooks still run before every tool call and
+// their denies are honored, so the hook is the SDK's mechanism for a per-path
+// write jail. Paths are compared after resolving against the turn cwd (the
+// allowlisted paths arrive absolute from the plan rounds); a write-class call
+// without a recognizable file path is denied, failing closed. Shell is closed
+// off separately: `allowRun: false` removes Bash from the tools list, so a
+// jailed turn cannot route writes around this hook through a shell command.
+function buildClaudeWritePathGuardHooks(cwd, allowedWritePaths) {
+    const allowedPaths = new Set(allowedWritePaths.map((path) => resolve(cwd, path)));
+    const guard = async (input) => {
+        if (input.hook_event_name !== 'PreToolUse' || !CLAUDE_WRITE_TOOL_NAMES.has(input.tool_name)) {
+            return { continue: true };
+        }
+        const filePath = getClaudeWriteToolPath(input.tool_input);
+        if (filePath !== null && allowedPaths.has(resolve(cwd, filePath))) {
+            return { continue: true };
+        }
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: `This turn may only write to: ${[...allowedPaths].join(', ')}. ` +
+                    `${input.tool_name} targeting ${filePath ?? 'an unrecognized path'} is not allowed.`,
+            },
+        };
+    };
+    return { PreToolUse: [{ hooks: [guard] }] };
+}
+function buildClaudeCoderQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
+    return {
+        cwd: args.cwd,
+        ...(abortController ? { abortController } : {}),
+        ...(defaultModel ? { model: defaultModel } : {}),
+        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        // `toolPolicy.allowRun: false` (plan-authoring turns) removes Bash so the
+        // "no shell" jail is enforced by tool absence, not prompt text.
+        tools: args.toolPolicy?.allowRun === false
+            ? ['Read', 'Grep', 'Glob', 'Edit', 'Write']
+            : ['Read', 'Grep', 'Glob', 'Bash', 'Edit', 'Write'],
+        ...(args.toolPolicy?.allowedWritePaths
+            ? { hooks: buildClaudeWritePathGuardHooks(args.cwd, args.toolPolicy.allowedWritePaths) }
+            : {}),
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        ...(args.resumeHandle ? { resume: args.resumeHandle } : {}),
+        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        ...(args.outputSchema
+            ? {
+                outputFormat: {
+                    type: 'json_schema',
+                    schema: args.outputSchema,
+                },
+            }
+            : {}),
+        stderr: (data) => {
+            void args.events?.({
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'coder',
+                label: 'coder',
+                sessionHandle: args.resumeHandle ?? null,
+                toolName: 'stderr',
+                message: data,
+                isError: true,
+                providerData: { stream: 'stderr' },
+            });
+        },
+    };
+}
+function buildClaudeCoderQueryStream(args, defaultModel, defaultEffort, abortController) {
+    return query({
+        prompt: args.prompt,
+        options: buildClaudeCoderQueryOptions(args, defaultModel, undefined, defaultEffort, abortController),
+    });
+}
+function buildClaudeCoderRepairQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController) {
+    return {
+        cwd: args.cwd,
+        ...(abortController ? { abortController } : {}),
+        ...(defaultModel ? { model: defaultModel } : {}),
+        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        tools: [],
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        stderr: (data) => {
+            void args.events?.({
+                type: 'tool_progress',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'coder',
+                label: `${args.label}:structured-json-repair`,
+                sessionHandle: null,
+                toolName: 'stderr',
+                message: data,
+                isError: true,
+                providerData: { stream: 'stderr' },
+            });
+        },
+    };
+}
+function buildClaudeCoderRepairQueryStream(args, repairPrompt, defaultModel, defaultEffort, abortController) {
+    return query({
+        prompt: repairPrompt,
+        options: buildClaudeCoderRepairQueryOptions(args, defaultModel, undefined, defaultEffort, abortController),
+    });
+}
+async function runClaudeStructuredCoderPrompt(args, defaultModel, createStream = buildClaudeCoderQueryStream, createRepairStream = buildClaudeCoderRepairQueryStream, defaultEffort, sleep = defaultSleep) {
+    let sessionHandle = args.resumeHandle ?? null;
+    let apiRetryCount = 0;
+    const apiRetryLimit = args.apiRetryLimit ?? 0;
+    // Mirrors the structured-advisor rounds: a transient error result (e.g. a
+    // stream idle timeout surfaced in the result message) must restart the round
+    // instead of feeding the error text into JSON extraction. Budget-gated so an
+    // exhausted budget falls through to today's behavior.
+    const throwIfRetryableTransientResult = (result, label) => {
+        if (apiRetryCount >= apiRetryLimit) {
+            return;
+        }
+        if (result.lastResult?.is_error !== true) {
+            return;
+        }
+        const subtype = result.lastResult?.subtype ?? null;
+        const resultErrorMessage = getClaudeResultErrorMessage(result.lastResult);
+        if (isTransientClaudeFailure(subtype, resultErrorMessage)) {
+            throw createClaudeProviderError({
+                message: resultErrorMessage
+                    ? `Claude ${label} returned a transient error result${subtype ? ` (${subtype})` : ''}: ${resultErrorMessage}`
+                    : `Claude ${label} returned a transient error result${subtype ? ` (${subtype})` : ''}`,
+                role: 'coder',
+                sessionHandle,
+                kind: 'api_error',
+                retryable: true,
+                subtype,
+            });
+        }
+    };
+    while (true) {
+        try {
+            return await runStructuredJsonProtocol({
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'coder',
+                label: args.label,
+                protocol: args.structuredJsonProtocol,
+                prompt: args.prompt,
+                events: args.events,
+                initialSessionHandle: args.resumeHandle ?? null,
+                runInitial: async (prompt) => {
+                    const turnAbortController = createClaudeTurnAbortController(args.signal);
+                    const result = await collectClaudeResult(createStream({
+                        ...args,
+                        prompt,
+                    }, defaultModel, defaultEffort, turnAbortController), args.cwd, args.label, args.inactivityTimeoutMs, args.events, 'coder', turnAbortController);
+                    throwIfRetryableTransientResult(result, args.label);
+                    sessionHandle = result.sessionHandle ?? sessionHandle;
+                    if (sessionHandle && sessionHandle !== args.resumeHandle) {
+                        await args.onSessionStarted?.(sessionHandle);
+                    }
+                    return {
+                        assistantText: getClaudeAssistantTextForLocalJson(result),
+                        sessionHandle,
+                    };
+                },
+                runRepair: async (prompt) => {
+                    const repairAbortController = new AbortController();
+                    const result = await collectClaudeResult(createRepairStream(args, prompt, defaultModel, defaultEffort, repairAbortController), args.cwd, `${args.label}:structured-json-repair`, args.inactivityTimeoutMs, args.events, 'coder', repairAbortController);
+                    throwIfRetryableTransientResult(result, `${args.label}:structured-json-repair`);
+                    return {
+                        assistantText: getClaudeAssistantTextForLocalJson(result),
+                        sessionHandle: result.sessionHandle,
+                    };
+                },
+                createProviderError: (errorArgs) => createClaudeProviderError({
+                    message: errorArgs.message,
+                    role: 'coder',
+                    sessionHandle: errorArgs.sessionHandle,
+                    kind: errorArgs.kind,
+                    retryable: false,
+                    cause: errorArgs.cause,
+                }),
+            });
+        }
+        catch (error) {
+            const providerError = normalizeClaudeProviderError(error, {
+                role: 'coder',
+                sessionHandle,
+                kind: 'structured_output_invalid',
+            });
+            if (providerError.kind === 'api_error' && providerError.retryable && apiRetryCount < apiRetryLimit) {
+                apiRetryCount += 1;
+                await emitProviderEvent(args.events, {
+                    type: 'tool_progress',
+                    provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                    role: 'coder',
+                    label: args.label,
+                    sessionHandle,
+                    toolName: 'api_retry',
+                    message: `transient Claude failure; retrying ${args.label} (${apiRetryCount}/${apiRetryLimit})`,
+                    isError: true,
+                    providerData: {
+                        retryCount: apiRetryCount,
+                        retryLimit: apiRetryLimit,
+                        message: providerError.message,
+                    },
+                });
+                await sleep(getApiRetryDelayMs(apiRetryCount));
+                // Fresh attempt: never resume the failed attempt's session.
+                sessionHandle = args.resumeHandle ?? null;
+                continue;
+            }
+            await emitClaudeProviderError(args.events, providerError, args.label);
+            throw providerError;
+        }
+    }
+}
+class AnthropicClaudeCoderAdapter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runPrompt(args) {
+        let sessionHandle = args.resumeHandle ?? null;
+        let result;
+        try {
+            const turnAbortController = createClaudeTurnAbortController(args.signal);
+            const stream = buildClaudeCoderQueryStream(args, this.options.model, this.options.effort ?? undefined, turnAbortController);
+            result = await collectClaudeResult(stream, args.cwd, 'coder', args.inactivityTimeoutMs, args.events, 'coder', turnAbortController);
+            sessionHandle = result.sessionHandle ?? sessionHandle;
+        }
+        catch (error) {
+            const providerError = normalizeClaudeProviderError(error, {
+                role: 'coder',
+                sessionHandle,
+            });
+            await emitClaudeProviderError(args.events, providerError, 'coder');
+            throw providerError;
+        }
+        if (sessionHandle && sessionHandle !== args.resumeHandle) {
+            await args.onSessionStarted?.(sessionHandle);
+        }
+        const statusResult = args.outputSchema && result.firstStructuredResult ? result.firstStructuredResult : result.lastResult;
+        const subtype = statusResult?.subtype ?? null;
+        const resultErrorMessage = getClaudeResultErrorMessage(statusResult);
+        if (subtype && subtype !== 'success') {
+            const providerError = createClaudeProviderError({
+                message: resultErrorMessage
+                    ? `Claude coder did not return a successful result (${subtype}): ${resultErrorMessage}`
+                    : `Claude coder did not return a successful result (${subtype})`,
+                sessionHandle,
+                subtype,
+                role: 'coder',
+            });
+            await emitClaudeProviderError(args.events, providerError, 'coder');
+            throw providerError;
+        }
+        if (args.outputSchema) {
+            const structuredOutput = getPreferredStructuredOutput(result);
+            if (structuredOutput === undefined) {
+                const providerError = createClaudeProviderError({
+                    message: 'Claude coder did not return structured output',
+                    role: 'coder',
+                    sessionHandle,
+                    kind: 'structured_output_missing',
+                    subtype,
+                });
+                await emitClaudeProviderError(args.events, providerError, 'coder');
+                throw providerError;
+            }
+            await emitProviderEvent(args.events, {
+                type: 'structured_output_received',
+                provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                role: 'coder',
+                label: 'coder',
+                sessionHandle,
+            });
+            return {
+                sessionHandle: sessionHandle,
+                finalResponse: JSON.stringify(structuredOutput),
+            };
+        }
+        const finalResponse = result.assistantText || getClaudeResultErrorMessage(result.lastResult) || '';
+        if (!finalResponse.trim()) {
+            const providerError = createClaudeProviderError({
+                message: 'Claude coder returned no final response',
+                role: 'coder',
+                sessionHandle,
+                kind: 'structured_output_missing',
+                subtype,
+            });
+            await emitClaudeProviderError(args.events, providerError, 'coder');
+            throw providerError;
+        }
+        return {
+            sessionHandle: sessionHandle,
+            finalResponse,
+        };
+    }
+    async runStructuredPrompt(args) {
+        return runClaudeStructuredCoderPrompt(args, this.options.model, undefined, undefined, this.options.effort ?? undefined);
+    }
+}
+export function createAnthropicClaudeStructuredAdvisorAdapter(options = {}) {
+    return new AnthropicClaudeStructuredAdvisorAdapter(options);
+}
+export function createAnthropicClaudeCoderAdapter(options = {}) {
+    return new AnthropicClaudeCoderAdapter(options);
+}
+export const anthropicClaudeProviderDefinition = {
+    id: 'anthropic-claude',
+    displayName: 'Anthropic Claude',
+    capabilities: {
+        coder: {
+            supported: true,
+            toolAccess: {
+                read: true,
+                write: true,
+                shell: true,
+            },
+            supportsSessionResume: true,
+            supportsModelOverride: true,
+            supportsStructuredOutput: true,
+            usageReporting: 'opportunistic',
+            supportedEfforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+        },
+        'structured-advisor': {
+            supported: true,
+            // Reviewers run read-only: read tools only, no write, no shell. The
+            // reviewer option builders expose only ['Read','Grep','Glob'] (repair
+            // exposes none), so a reviewer can inspect the checkout but never edit it
+            // or run commands.
+            toolAccess: {
+                read: true,
+                write: false,
+                shell: false,
+            },
+            supportsSessionResume: true,
+            supportsModelOverride: true,
+            supportsStructuredOutput: true,
+            usageReporting: 'opportunistic',
+            supportedEfforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+        },
+    },
+    createCoderAdapter: createAnthropicClaudeCoderAdapter,
+    createStructuredAdvisorAdapter: createAnthropicClaudeStructuredAdvisorAdapter,
+};
+export const anthropicClaudeProviderTestHooks = {
+    buildClaudeCoderQueryOptions,
+    buildClaudeCoderRepairQueryOptions,
+    buildClaudeJsonBlockQueryOptions,
+    buildClaudeJsonBlockRepairQueryOptions,
+    buildClaudeJsonBlockReviewPrompt,
+    buildClaudeQueryOptions,
+    collectClaudeResult,
+    getClaudeCodeExecutablePath,
+    getMirroredAssistantText,
+    getPreferredStructuredOutput,
+    isGlibcRuntime,
+    logClaudeMessage,
+    THINKING_PROGRESS_EMIT_INTERVAL_MS,
+    runClaudeJsonBlockStructuredAdvisorRound,
+    runClaudeStructuredCoderPrompt,
+    runClaudeStructuredAdvisorRound,
+};