@navels/neal 0.1.0 → 0.3.0

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

@@ -2,6 +2,8 @@ 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 { agentSettingsIsolated } from './agent-settings-isolation.js';
+import { agentSubprocessEnv } from './git-config-isolation.js';
 import { NealProviderError } from './types.js';
 const ANTHROPIC_CLAUDE_PROVIDER_ID = 'anthropic-claude';
 const requireFromProvider = createRequire(import.meta.url);
@@ -57,7 +59,7 @@ class ClaudeInactivityTimeoutError extends Error {
 }
 // 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
+// openai-compatible 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;
@@ -125,9 +127,44 @@ async function appendClaudeText(label, state, text, events, sessionHandle, role
     }
     return emittedTexts;
 }
-async function logClaudeMessage(label, message, events, state, sessionHandle, role = roleForClaudeLabel(label)) {
+function getClaudeBashCommand(toolInput) {
+    if (toolInput === null || typeof toolInput !== 'object') {
+        return null;
+    }
+    const command = toolInput.command;
+    return typeof command === 'string' && command.trim() ? command : null;
+}
+// Extracts the human-readable text of a tool_result block: string content is
+// used as-is; block-array content contributes its text blocks. Non-text
+// content (images, documents) yields null.
+function getClaudeToolResultText(content) {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return null;
+    }
+    const texts = [];
+    for (const block of content) {
+        if (block !== null &&
+            typeof block === 'object' &&
+            block.type === 'text' &&
+            typeof block.text === 'string') {
+            texts.push(block.text);
+        }
+    }
+    return texts.length > 0 ? texts.join('\n') : null;
+}
+async function logClaudeMessage(label, message, events, state, sessionHandle, role = roleForClaudeLabel(label), cwd) {
     switch (message.type) {
         case 'assistant': {
+            if (state) {
+                for (const block of message.message.content) {
+                    if (block.type === 'tool_use') {
+                        state.pendingToolUses.set(block.id, { name: block.name, input: block.input });
+                    }
+                }
+            }
             if (state?.sawTextDelta) {
                 return [];
             }
@@ -150,6 +187,72 @@ async function logClaudeMessage(label, message, events, state, sessionHandle, ro
             }
             break;
         }
+        case 'user': {
+            // SDK tool executions surface as user messages carrying tool_result
+            // blocks. Matching them against the turn's pending tool_use blocks maps
+            // Bash runs to `command_completed` and successful write-tool calls to
+            // `file_changed`. Read-class tools (Read/Grep/Glob) intentionally emit
+            // nothing here — they are not verification evidence. The mapping is
+            // role-agnostic: advisor rounds run a read-only toolset, so they never
+            // produce Bash or write tool_uses.
+            if (!state) {
+                break;
+            }
+            const content = message.message.content;
+            if (!Array.isArray(content)) {
+                break;
+            }
+            for (const block of content) {
+                if (block.type !== 'tool_result') {
+                    continue;
+                }
+                const pending = state.pendingToolUses.get(block.tool_use_id);
+                if (!pending) {
+                    continue;
+                }
+                state.pendingToolUses.delete(block.tool_use_id);
+                if (pending.name === 'Bash') {
+                    const command = getClaudeBashCommand(pending.input);
+                    if (!command) {
+                        continue;
+                    }
+                    // The SDK's tool_result exposes no exit code, so `exitCode` is
+                    // omitted; `status` carries the is_error signal instead.
+                    const output = getClaudeToolResultText(block.content);
+                    await emitProviderEvent(events, {
+                        type: 'command_completed',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        itemId: block.tool_use_id,
+                        command,
+                        status: block.is_error === true ? 'failed' : 'completed',
+                        ...(output !== null ? { output } : {}),
+                        ...(cwd ? { cwd } : {}),
+                        providerData: { sdkMessageType: message.type, toolName: pending.name, toolUseId: block.tool_use_id },
+                    });
+                }
+                else if (CLAUDE_WRITE_TOOL_NAMES.has(pending.name) && block.is_error !== true) {
+                    // An is_error result means the write did not happen (e.g. a
+                    // write-path guard deny), so it must not claim a file change.
+                    const filePath = getClaudeWriteToolPath(pending.input);
+                    if (!filePath) {
+                        continue;
+                    }
+                    await emitProviderEvent(events, {
+                        type: 'file_changed',
+                        provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
+                        role,
+                        label,
+                        sessionHandle,
+                        files: [filePath],
+                        providerData: { sdkMessageType: message.type, toolName: pending.name, toolUseId: block.tool_use_id },
+                    });
+                }
+            }
+            break;
+        }
         case 'stream_event':
             if (message.event.type === 'content_block_delta') {
                 if (message.event.delta.type === 'text_delta' && state) {
@@ -274,6 +377,9 @@ async function logClaudeMessage(label, message, events, state, sessionHandle, ro
             }
             break;
         case 'result':
+            // Turn boundary: a tool_use whose result never arrived must not match a
+            // tool_result from a later turn in the same stream.
+            state?.pendingToolUses.clear();
             await emitProviderEvent(events, {
                 type: 'turn_completed',
                 provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
@@ -281,6 +387,10 @@ async function logClaudeMessage(label, message, events, state, sessionHandle, ro
                 label,
                 sessionHandle,
                 usage: message.usage,
+                // One `result` message is one query invocation = one turn, so
+                // `total_cost_usd` is a per-turn figure that sums cleanly across turns.
+                costUsd: message.total_cost_usd,
+                costSource: 'provider',
                 providerData: { sdkMessageType: message.type, subtype: message.subtype },
             });
             if (message.usage !== undefined) {
@@ -291,6 +401,8 @@ async function logClaudeMessage(label, message, events, state, sessionHandle, ro
                     label,
                     sessionHandle,
                     usage: message.usage,
+                    costUsd: message.total_cost_usd,
+                    costSource: 'provider',
                     providerData: { sdkMessageType: message.type, subtype: message.subtype },
                 });
             }
@@ -401,7 +513,12 @@ async function collectClaudeResult(stream, cwd, label, inactivityTimeoutMs, even
     let sessionHandle = null;
     let lastResult = null;
     let firstStructuredResult = null;
-    const logState = { textBuffer: '', sawTextDelta: false, lastThinkingEmitMs: 0 };
+    const logState = {
+        textBuffer: '',
+        sawTextDelta: false,
+        lastThinkingEmitMs: 0,
+        pendingToolUses: new Map(),
+    };
     const assistantTexts = [];
     const iterator = stream[Symbol.asyncIterator]();
     while (true) {
@@ -435,7 +552,7 @@ async function collectClaudeResult(stream, cwd, label, inactivityTimeoutMs, even
                 providerData: { sdkMessageType: message.type },
             });
         }
-        const emittedAssistantTexts = await logClaudeMessage(label, message, events, logState, sessionHandle, role);
+        const emittedAssistantTexts = await logClaudeMessage(label, message, events, logState, sessionHandle, role, cwd);
         if (emittedAssistantTexts.length > 0) {
             assistantTexts.push(emittedAssistantTexts.join('\n\n'));
         }
@@ -484,36 +601,72 @@ function createClaudeTurnAbortController(signal) {
 function deriveClaudeAbortController(signal) {
     return signal ? createClaudeTurnAbortController(signal) : undefined;
 }
-function buildClaudeQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
+function buildClaudeCoreQueryOptions(spec) {
     return {
-        cwd: args.cwd,
-        ...(abortController ? { abortController } : {}),
-        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
-        ...(defaultEffort ? { effort: defaultEffort } : {}),
-        tools: ['Read', 'Grep', 'Glob'],
+        cwd: spec.cwd,
+        // Full environment plus the git-config isolation overrides: Claude's Bash
+        // tool must not be able to write the operator's real global gitconfig.
+        // See git-config-isolation.ts.
+        env: agentSubprocessEnv(),
+        ...(spec.abortController ? { abortController: spec.abortController } : {}),
+        ...(spec.model ? { model: spec.model } : {}),
+        ...(spec.effort ? { effort: spec.effort } : {}),
+        tools: spec.tools,
+        ...(spec.hooks ? { hooks: spec.hooks } : {}),
+        // Under compat qualification only, run Claude in the SDK's isolation mode
+        // (load no filesystem settings). Left unset, the SDK loads ~/.claude and any
+        // repo .claude by default, pulling in the operator's interactive config —
+        // permissions, statusline, CLAUDE.md, and the Stop / Notification hooks that
+        // fire a desktop notifier on every turn. compat runs the whole role matrix,
+        // so those hooks would spam one notification per turn; isolating keeps the
+        // capability probe quiet and hermetic. Normal neal runs (pipeline, local
+        // `neal go`) honor the operator's config — it's their machine. neal's own
+        // hooks (the coder write-path guard passed programmatically above) are
+        // unaffected either way. See agent-settings-isolation.ts.
+        ...(agentSettingsIsolated() ? { settingSources: [] } : {}),
         permissionMode: 'bypassPermissions',
         allowDangerouslySkipPermissions: true,
-        ...(args.resumeHandle ? { resume: args.resumeHandle } : {}),
-        ...(claudeExecutablePath ? { pathToClaudeCodeExecutable: claudeExecutablePath } : {}),
+        ...(spec.resumeHandle ? { resume: spec.resumeHandle } : {}),
+        ...(spec.claudeExecutablePath ? { pathToClaudeCodeExecutable: spec.claudeExecutablePath } : {}),
+        ...(spec.outputSchema
+            ? {
+                outputFormat: {
+                    type: 'json_schema',
+                    schema: spec.outputSchema,
+                },
+            }
+            : {}),
         stderr: (data) => {
-            void args.events?.({
+            void spec.events?.({
                 type: 'tool_progress',
                 provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
-                role: 'structured-advisor',
-                label: args.label,
-                sessionHandle: args.resumeHandle ?? null,
+                role: spec.stderrRole,
+                label: spec.stderrLabel,
+                sessionHandle: spec.stderrSessionHandle,
                 toolName: 'stderr',
                 message: data,
                 isError: true,
                 providerData: { stream: 'stderr' },
             });
         },
-        outputFormat: {
-            type: 'json_schema',
-            schema: args.schema,
-        },
     };
 }
+function buildClaudeQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
+    return buildClaudeCoreQueryOptions({
+        cwd: args.cwd,
+        abortController,
+        model: args.model ?? defaultModel,
+        effort: defaultEffort,
+        tools: ['Read', 'Grep', 'Glob'],
+        resumeHandle: args.resumeHandle,
+        claudeExecutablePath,
+        outputSchema: args.schema,
+        events: args.events,
+        stderrRole: 'structured-advisor',
+        stderrLabel: args.label,
+        stderrSessionHandle: args.resumeHandle ?? null,
+    });
+}
 function buildClaudeQueryStream(args, defaultModel, defaultEffort, abortController) {
     return query({
         prompt: args.prompt,
@@ -527,30 +680,19 @@ function buildClaudeJsonBlockReviewPrompt(args) {
     return args.prompt;
 }
 function buildClaudeJsonBlockQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
-    return {
+    return buildClaudeCoreQueryOptions({
         cwd: args.cwd,
-        ...(abortController ? { abortController } : {}),
-        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
-        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        abortController,
+        model: args.model ?? defaultModel,
+        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' },
-            });
-        },
-    };
+        resumeHandle: args.resumeHandle,
+        claudeExecutablePath,
+        events: args.events,
+        stderrRole: 'structured-advisor',
+        stderrLabel: args.label,
+        stderrSessionHandle: args.resumeHandle ?? null,
+    });
 }
 function buildClaudeJsonBlockQueryStream(args, defaultModel, defaultEffort, abortController) {
     return query({
@@ -559,29 +701,18 @@ function buildClaudeJsonBlockQueryStream(args, defaultModel, defaultEffort, abor
     });
 }
 function buildClaudeJsonBlockRepairQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController) {
-    return {
+    return buildClaudeCoreQueryOptions({
         cwd: args.cwd,
-        ...(abortController ? { abortController } : {}),
-        ...((args.model ?? defaultModel) ? { model: args.model ?? defaultModel ?? undefined } : {}),
-        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        abortController,
+        model: args.model ?? defaultModel,
+        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' },
-            });
-        },
-    };
+        claudeExecutablePath,
+        events: args.events,
+        stderrRole: 'structured-advisor',
+        stderrLabel: `${args.label}:structured-json-repair`,
+        stderrSessionHandle: null,
+    });
 }
 function buildClaudeJsonBlockRepairQueryStream(args, repairPrompt, defaultModel, defaultEffort, abortController) {
     return query({
@@ -959,7 +1090,33 @@ async function validateOrRepairClaudeJsonBlockResponse(args) {
         throw providerError;
     }
 }
-async function runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, createStream = buildClaudeJsonBlockQueryStream, createRepairStream = buildClaudeJsonBlockRepairQueryStream, defaultEffort, sleep = defaultSleep) {
+// Both advisor protocols give up on an unsuccessful Claude result with the
+// same normalized provider error; only the loop position at which each
+// protocol reaches this differs (see runClaudeStructuredAdvisorRoundLoop).
+async function createClaudeAdvisorUnsuccessfulResultError(details) {
+    const providerError = createClaudeProviderError({
+        message: details.resultErrorMessage
+            ? `Claude ${details.label} did not return a successful result${details.subtype ? ` (${details.subtype})` : ''}: ${details.resultErrorMessage}`
+            : `Claude ${details.label} did not return a successful result${details.subtype ? ` (${details.subtype})` : ''}`,
+        role: 'structured-advisor',
+        sessionHandle: details.sessionHandle,
+        kind: getClaudeStructuredFailureKind(details.subtype, details.resultErrorMessage),
+        subtype: details.subtype,
+    });
+    await emitClaudeProviderError(details.events, providerError, details.label);
+    return providerError;
+}
+// One advisor round loop serves both structured-output protocols. The shared
+// skeleton — per-turn abort controller, assistant-text mirroring, transient
+// api_error retries with exponential backoff, transient error-result
+// retries, and the final unsuccessful-result error — is identical for both;
+// the `run.protocol` discriminator selects the json-block behavior (local
+// extraction/validation with the repair sub-loop, plus the mirrored-prose
+// recovery when the stream fails after emitting assistant text) or the
+// native behavior (SDK `json_schema` structured output with stream-error and
+// retry-exhaustion telemetry).
+async function runClaudeStructuredAdvisorRoundLoop(run, defaultModel, defaultEffort, sleep = defaultSleep) {
+    const args = run.args;
     let sessionHandle = args.resumeHandle ?? null;
     let apiRetryCount = 0;
     const apiRetryLimit = args.apiRetryLimit;
@@ -974,56 +1131,9 @@ async function runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, crea
                 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) {
+        // Reads `sessionHandle` at call time, so post-collect callers observe the
+        // handle updated from the just-collected result.
+        const retryAfterTransientErrorResult = async (subtype, message) => {
             apiRetryCount += 1;
             await emitProviderEvent(args.events, {
                 type: 'tool_progress',
@@ -1038,60 +1148,15 @@ async function runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, crea
                     retryCount: apiRetryCount,
                     retryLimit: apiRetryLimit,
                     subtype,
-                    message: resultErrorMessage,
+                    message,
                 },
             });
             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);
+            result = await collectClaudeResult(run.createStream(run.args, defaultModel, defaultEffort, turnAbortController), args.cwd, args.label, args.inactivityTimeoutMs, primaryEvents, 'structured-advisor', turnAbortController);
         }
         catch (error) {
             const providerError = normalizeClaudeProviderError(error, {
@@ -1099,7 +1164,7 @@ async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream
                 sessionHandle,
             });
             const mirroredAssistantText = mirroredAssistantTexts.join('\n\n').trim();
-            if (providerError.kind === 'structured_output_invalid') {
+            if (run.protocol === 'native' && providerError.kind === 'structured_output_invalid') {
                 await emitProviderEvent(args.events, {
                     type: 'tool_progress',
                     provider: ANTHROPIC_CLAUDE_PROVIDER_ID,
@@ -1137,11 +1202,51 @@ async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream
                 await sleep(getApiRetryDelayMs(apiRetryCount));
                 continue;
             }
+            if (run.protocol === 'json-block' &&
+                mirroredAssistantText &&
+                (providerError.kind === 'structured_output_invalid' || providerError.kind === 'structured_output_missing')) {
+                return await validateOrRepairClaudeJsonBlockResponse({
+                    roundArgs: run.args,
+                    assistantText: mirroredAssistantText,
+                    defaultModel,
+                    defaultEffort,
+                    sessionHandle: providerError.sessionHandle ?? sessionHandle,
+                    createRepairStream: run.createRepairStream,
+                });
+            }
             await emitClaudeProviderError(args.events, providerError, args.label);
             throw providerError;
         }
         sessionHandle = result.sessionHandle ?? sessionHandle;
         const lastResult = result.lastResult;
+        const subtype = lastResult?.subtype ?? null;
+        const resultErrorMessage = getClaudeResultErrorMessage(lastResult);
+        const structuredRetryExhausted = isStructuredOutputRetryExhaustion(subtype, resultErrorMessage);
+        const isTransientErrorResult = lastResult?.is_error === true && isTransientClaudeFailure(subtype, resultErrorMessage);
+        if (run.protocol === 'json-block') {
+            if (isTransientErrorResult && apiRetryCount < apiRetryLimit) {
+                await retryAfterTransientErrorResult(subtype, resultErrorMessage);
+                continue;
+            }
+            if (subtype && subtype !== 'success' && !structuredRetryExhausted) {
+                throw await createClaudeAdvisorUnsuccessfulResultError({
+                    events: args.events,
+                    label: args.label,
+                    subtype,
+                    resultErrorMessage,
+                    sessionHandle,
+                });
+            }
+            const assistantText = getClaudeAssistantTextForLocalJson(result, mirroredAssistantTexts.join('\n\n').trim());
+            return await validateOrRepairClaudeJsonBlockResponse({
+                roundArgs: run.args,
+                assistantText,
+                defaultModel,
+                defaultEffort,
+                sessionHandle,
+                createRepairStream: run.createRepairStream,
+            });
+        }
         const structured = getPreferredStructuredOutput(result);
         if (structured !== undefined) {
             await emitProviderEvent(args.events, {
@@ -1156,9 +1261,6 @@ async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream
                 structured,
             };
         }
-        const subtype = lastResult?.subtype ?? null;
-        const resultErrorMessage = getClaudeResultErrorMessage(lastResult);
-        const structuredRetryExhausted = isStructuredOutputRetryExhaustion(subtype, resultErrorMessage);
         if (structuredRetryExhausted) {
             await emitProviderEvent(args.events, {
                 type: 'tool_progress',
@@ -1177,40 +1279,28 @@ async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream
                 },
             });
         }
-        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));
+        if (isTransientErrorResult && apiRetryCount < apiRetryLimit) {
+            await retryAfterTransientErrorResult(subtype, resultErrorMessage);
             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),
+        throw await createClaudeAdvisorUnsuccessfulResultError({
+            events: args.events,
+            label: args.label,
             subtype,
+            resultErrorMessage,
+            sessionHandle,
         });
-        await emitClaudeProviderError(args.events, providerError, args.label);
-        throw providerError;
     }
 }
+async function runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, createStream = buildClaudeJsonBlockQueryStream, createRepairStream = buildClaudeJsonBlockRepairQueryStream, defaultEffort, sleep = defaultSleep) {
+    return runClaudeStructuredAdvisorRoundLoop({ protocol: 'json-block', args, createStream, createRepairStream }, defaultModel, defaultEffort, sleep);
+}
+async function runClaudeStructuredAdvisorRound(args, defaultModel, createStream = buildClaudeQueryStream, defaultEffort, sleep = defaultSleep) {
+    if (isClaudeJsonBlockStructuredAdvisorRound(args)) {
+        return await runClaudeJsonBlockStructuredAdvisorRound(args, defaultModel, undefined, undefined, defaultEffort, sleep);
+    }
+    return runClaudeStructuredAdvisorRoundLoop({ protocol: 'native', args, createStream }, defaultModel, defaultEffort, sleep);
+}
 class AnthropicClaudeStructuredAdvisorAdapter {
     options;
     constructor(options = {}) {
@@ -1264,45 +1354,27 @@ function buildClaudeWritePathGuardHooks(cwd, allowedWritePaths) {
     return { PreToolUse: [{ hooks: [guard] }] };
 }
 function buildClaudeCoderQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController = deriveClaudeAbortController(args.signal)) {
-    return {
+    return buildClaudeCoreQueryOptions({
         cwd: args.cwd,
-        ...(abortController ? { abortController } : {}),
-        ...(defaultModel ? { model: defaultModel } : {}),
-        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        abortController,
+        model: defaultModel,
+        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' },
-            });
-        },
-    };
+        hooks: args.toolPolicy?.allowedWritePaths
+            ? buildClaudeWritePathGuardHooks(args.cwd, args.toolPolicy.allowedWritePaths)
+            : undefined,
+        resumeHandle: args.resumeHandle,
+        claudeExecutablePath,
+        outputSchema: args.outputSchema,
+        events: args.events,
+        stderrRole: 'coder',
+        stderrLabel: 'coder',
+        stderrSessionHandle: args.resumeHandle ?? null,
+    });
 }
 function buildClaudeCoderQueryStream(args, defaultModel, defaultEffort, abortController) {
     return query({
@@ -1311,29 +1383,18 @@ function buildClaudeCoderQueryStream(args, defaultModel, defaultEffort, abortCon
     });
 }
 function buildClaudeCoderRepairQueryOptions(args, defaultModel, claudeExecutablePath = getClaudeCodeExecutablePath(), defaultEffort, abortController) {
-    return {
+    return buildClaudeCoreQueryOptions({
         cwd: args.cwd,
-        ...(abortController ? { abortController } : {}),
-        ...(defaultModel ? { model: defaultModel } : {}),
-        ...(defaultEffort ? { effort: defaultEffort } : {}),
+        abortController,
+        model: defaultModel,
+        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' },
-            });
-        },
-    };
+        claudeExecutablePath,
+        events: args.events,
+        stderrRole: 'coder',
+        stderrLabel: `${args.label}:structured-json-repair`,
+        stderrSessionHandle: null,
+    });
 }
 function buildClaudeCoderRepairQueryStream(args, repairPrompt, defaultModel, defaultEffort, abortController) {
     return query({