@skaile/workspaces 0.29.1 → 0.31.0

package/dist/bridge/drivers/claude-sdk.js

@@ -1,9 +1,9 @@
 import { dispatchCapability } from '../../chunk-RRVQAE5D.js';
 import { fetchProviderModels } from '../../chunk-BMQKMOQY.js';
-import { AuthError, classifyClaudeSdkError } from '../../chunk-PAYAFNXG.js';
-import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger } from '../../chunk-ZEKWHJBB.js';
+import { AuthError, classifyClaudeSdkError } from '../../chunk-NGJ6E344.js';
+import { BUILTIN_DRIVER_CATALOG, AgentDriver, getBridgeLogger } from '../../chunk-OEXA7BBK.js';
 import '../../chunk-6E6PKKAD.js';
-import '../../chunk-24UIWON4.js';
+import '../../chunk-JB35MVBN.js';
 import '../../chunk-NSBPE2FW.js';
 import { spawnSync } from 'child_process';
 import { existsSync, readFileSync, readdirSync, writeFileSync, renameSync } from 'fs';
@@ -235,6 +235,8 @@ var ClaudeSdkDriver = class extends AgentDriver {
   sdk = null;
   toolIdToName = /* @__PURE__ */ new Map();
   prevText = "";
+  /** Set once the streaming text of the current message classifies as a self-healable auth render. */
+  suppressingAuthStream = false;
   /** Active query — may stay alive between turns if streamInput works. */
   query = null;
   /** Resolves when the current turn completes. */
@@ -336,6 +338,7 @@ var ClaudeSdkDriver = class extends AgentDriver {
     if (isFirstAttempt) this._lastTokens = null;
     this.running = true;
     this.prevText = "";
+    this.suppressingAuthStream = false;
     this.turnCompleted = false;
     const turnPromise = new Promise((resolve, reject) => {
       this.turnResolve = resolve;
@@ -360,115 +363,24 @@ var ClaudeSdkDriver = class extends AgentDriver {
       const errMsg = err instanceof Error ? err.message : String(err);
       const isStaleResume = !_budget.staleResume && /No conversation found with session ID/i.test(errMsg);
       if (isStaleResume) {
-        const staleId = this.config.resumeSessionId || this.sessionId || "unknown";
-        this.log.warn("stale Claude Code session, retrying with a fresh session", { staleId });
-        this.emit("agent-event", {
-          type: "resume_failed",
-          resumeSessionId: staleId,
-          reason: "jsonl_lost"
-        });
-        this.emit("agent-event", {
-          type: "error",
-          error: "Claude Code session state was lost (likely a prior crash). Restarting with a fresh session \u2014 previous conversation context is not available.",
-          fatal: false
-        });
-        this.sessionId = "";
-        this.hasSession = false;
-        this.query = null;
-        this.config.resumeSessionId = void 0;
-        this.turnResolve = null;
-        this.turnReject = null;
-        this.running = false;
+        this.prepareStaleResumeRetry();
         retrying = true;
         return this.prompt(message, { ..._budget, staleResume: true });
       }
       const isPoisonedHistory = !_budget.poison && /invalid_request_error/i.test(errMsg) && /media[_ ]?type|could not process image|image exceeds|cache_control/i.test(errMsg);
       const poisonSessionId = this.config.resumeSessionId || this.sessionId;
       if (isPoisonedHistory && poisonSessionId) {
-        const scrub = scrubPoisonedTranscript({
-          configDir: this.resolveClaudeConfigDir(),
-          sessionId: poisonSessionId,
-          log: this.log
-        });
-        if (scrub.changed) {
-          this.log.warn("scrubbed poisoned Claude Code transcript, retrying resume", {
-            sessionId: poisonSessionId,
-            corrected: scrub.corrected,
-            stubbed: scrub.stubbed,
-            cacheStripped: scrub.cacheStripped
-          });
-          this.emit("agent-event", {
-            type: "resume_failed",
-            resumeSessionId: poisonSessionId,
-            reason: "jsonl_poisoned"
-          });
-          const plural = (n) => n === 1 ? "" : "s";
-          const repairs = [];
-          if (scrub.corrected > 0)
-            repairs.push(`${scrub.corrected} media type${plural(scrub.corrected)} corrected`);
-          if (scrub.stubbed > 0)
-            repairs.push(`${scrub.stubbed} image${plural(scrub.stubbed)} removed`);
-          if (scrub.cacheStripped > 0)
-            repairs.push(
-              `${scrub.cacheStripped} malformed block${plural(scrub.cacheStripped)} cleaned`
-            );
-          this.emit("agent-event", {
-            type: "error",
-            error: `Recovered corrupt data in the conversation history (${repairs.join(", ")}). Retrying \u2014 earlier context is preserved.`,
-            fatal: false
-          });
-          this.query = null;
-          this.turnResolve = null;
-          this.turnReject = null;
-          this.running = false;
+        if (this.attemptPoisonScrubRetry(poisonSessionId)) {
           retrying = true;
           return this.prompt(message, { ..._budget, poison: true });
         }
-        this.log.warn("poisoned-transcript error but scrub found nothing to repair", {
-          sessionId: poisonSessionId,
-          filePath: scrub.filePath
-        });
       }
       const isAuthError = err instanceof AuthError && !_budget.auth;
       if (isAuthError && this.config.onAuthError) {
-        this.log.info("auth error caught; invoking onAuthError refresh callback");
-        let refreshed = false;
-        try {
-          const mint = await this.config.onAuthError({
-            configId: this.config.aiProviderConfigId ?? ""
-          });
-          refreshed = mint.ok;
-          if (!mint.ok) {
-            this.log.info("onAuthError reported refresh failure; surfacing AuthError", {
-              code: mint.code
-            });
-          }
-        } catch (refreshErr) {
-          this.log.warn("onAuthError callback threw; surfacing original AuthError", {
-            error: refreshErr instanceof Error ? refreshErr.message : String(refreshErr)
-          });
-        }
-        if (refreshed) {
-          this.log.info("credentials refreshed; retrying prompt");
-          this.query = null;
-          this.turnResolve = null;
-          this.turnReject = null;
-          this.running = false;
+        if (await this.attemptAuthSelfHeal(err)) {
           retrying = true;
           return this.prompt(message, { ..._budget, auth: true });
         }
-        try {
-          this.emit("agent-event", {
-            type: "error",
-            error: err.message,
-            detail: err.detail
-          });
-        } catch (emitErr) {
-          this.log.warn(
-            "agent-event listener threw during deferred auth-error surfacing; suppressing",
-            { error: emitErr instanceof Error ? emitErr.message : String(emitErr) }
-          );
-        }
       }
       throw err;
     } finally {
@@ -479,6 +391,133 @@ var ClaudeSdkDriver = class extends AgentDriver {
       }
     }
   }
+  /**
+   * Side-effects of the stale-resume recovery path: emit the resume-outcome and
+   * non-fatal error events, then reset session state so the recursive prompt()
+   * starts a fresh session. The caller owns the decision to recurse — this only
+   * performs the state mutation, never control flow.
+   */
+  prepareStaleResumeRetry() {
+    const staleId = this.config.resumeSessionId || this.sessionId || "unknown";
+    this.log.warn("stale Claude Code session, retrying with a fresh session", { staleId });
+    this.emit("agent-event", {
+      type: "resume_failed",
+      resumeSessionId: staleId,
+      reason: "jsonl_lost"
+    });
+    this.emit("agent-event", {
+      type: "error",
+      error: "Claude Code session state was lost (likely a prior crash). Restarting with a fresh session \u2014 previous conversation context is not available.",
+      fatal: false
+    });
+    this.sessionId = "";
+    this.hasSession = false;
+    this.query = null;
+    this.config.resumeSessionId = void 0;
+    this.turnResolve = null;
+    this.turnReject = null;
+    this.running = false;
+  }
+  /**
+   * Side-effects of the poisoned-transcript recovery path: scrub the on-disk
+   * transcript and, when something was repaired, emit recovery events and reset
+   * query state. Returns `true` when the scrub changed the transcript (the
+   * caller should recurse) and `false` otherwise. The caller owns the decision
+   * to recurse — this only performs the scrub + state mutation, never control
+   * flow.
+   */
+  attemptPoisonScrubRetry(poisonSessionId) {
+    const scrub = scrubPoisonedTranscript({
+      configDir: this.resolveClaudeConfigDir(),
+      sessionId: poisonSessionId,
+      log: this.log
+    });
+    if (scrub.changed) {
+      this.log.warn("scrubbed poisoned Claude Code transcript, retrying resume", {
+        sessionId: poisonSessionId,
+        corrected: scrub.corrected,
+        stubbed: scrub.stubbed,
+        cacheStripped: scrub.cacheStripped
+      });
+      this.emit("agent-event", {
+        type: "resume_failed",
+        resumeSessionId: poisonSessionId,
+        reason: "jsonl_poisoned"
+      });
+      const plural = (n) => n === 1 ? "" : "s";
+      const repairs = [];
+      if (scrub.corrected > 0)
+        repairs.push(`${scrub.corrected} media type${plural(scrub.corrected)} corrected`);
+      if (scrub.stubbed > 0) repairs.push(`${scrub.stubbed} image${plural(scrub.stubbed)} removed`);
+      if (scrub.cacheStripped > 0)
+        repairs.push(
+          `${scrub.cacheStripped} malformed block${plural(scrub.cacheStripped)} cleaned`
+        );
+      this.emit("agent-event", {
+        type: "error",
+        error: `Recovered corrupt data in the conversation history (${repairs.join(", ")}). Retrying \u2014 earlier context is preserved.`,
+        fatal: false
+      });
+      this.query = null;
+      this.turnResolve = null;
+      this.turnReject = null;
+      this.running = false;
+      return true;
+    }
+    this.log.warn("poisoned-transcript error but scrub found nothing to repair", {
+      sessionId: poisonSessionId,
+      filePath: scrub.filePath
+    });
+    return false;
+  }
+  /**
+   * Side-effects of the auth-error recovery path: invoke the `onAuthError`
+   * refresh callback. On success, reset query state and return `true` (the
+   * caller should recurse). On failure, emit the deferred `agent-event: error`
+   * (paired with the deferral in {@link failTurn}) and return `false`. The
+   * caller owns the decision to recurse and the subsequent rethrow — this only
+   * performs the refresh + state mutation, never control flow.
+   */
+  async attemptAuthSelfHeal(err) {
+    this.log.info("auth error caught; invoking onAuthError refresh callback");
+    let refreshed = false;
+    try {
+      const mint = await this.config.onAuthError({
+        configId: this.config.aiProviderConfigId ?? ""
+      });
+      refreshed = mint.ok;
+      if (!mint.ok) {
+        this.log.info("onAuthError reported refresh failure; surfacing AuthError", {
+          code: mint.code
+        });
+      }
+    } catch (refreshErr) {
+      this.log.warn("onAuthError callback threw; surfacing original AuthError", {
+        error: refreshErr instanceof Error ? refreshErr.message : String(refreshErr)
+      });
+    }
+    if (refreshed) {
+      this.log.info("credentials refreshed; retrying prompt");
+      this.query = null;
+      this.turnResolve = null;
+      this.turnReject = null;
+      this.running = false;
+      return true;
+    }
+    try {
+      this.emit("agent-event", {
+        type: "error",
+        error: err.message,
+        detail: err.detail
+      });
+    } catch (emitErr) {
+      this.log.warn(
+        "agent-event listener threw during deferred auth-error surfacing; suppressing",
+        { error: emitErr instanceof Error ? emitErr.message : String(emitErr) }
+      );
+    }
+    return false;
+  }
   /**
    * Resolve the Claude Code config directory — the parent of `projects/` — from
    * the driver config, the process environment, or the `~/.claude` default.
@@ -714,42 +753,54 @@ var ClaudeSdkDriver = class extends AgentDriver {
     try {
       for await (const msg of this.query) {
         if (this.abortController?.signal.aborted) break;
-        const sessionId = "session_id" in msg ? msg.session_id : void 0;
-        if (sessionId) {
-          if (!this.hasSession) {
-            this.hasSession = true;
-            this.log.debug("session id assigned", { sessionId });
-          }
-          this.sessionId = sessionId;
-        }
+        this.captureSessionId(msg);
         this.handleSdkMessage(msg);
         if (msg.type === "result" && !msg.is_error) {
           this.completeTurn();
         }
       }
     } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      if (error.name === "AbortError" || this.abortController?.signal.aborted) {
-        this.log.info("aborted");
-      } else {
-        const detail = classifyClaudeSdkError({
-          errors: [error.message],
-          oauthCredential: this.usingOauthCredential
-        });
-        this.log.error("consumer error", {
-          message: error.message,
-          category: detail.category,
-          retryable: detail.retryable
-        });
-        const surfaced = detail.category === "auth" ? new AuthError(detail) : error;
-        this.failTurn(surfaced, detail);
-      }
+      this.handleConsumerError(err);
     } finally {
       this.log.debug("query generator ended");
       this.completeTurn();
       this.query = null;
     }
   }
+  /** Capture the SDK session id from a message (first one assigns hasSession). */
+  captureSessionId(msg) {
+    const sessionId = "session_id" in msg ? msg.session_id : void 0;
+    if (sessionId) {
+      if (!this.hasSession) {
+        this.hasSession = true;
+        this.log.debug("session id assigned", { sessionId });
+      }
+      this.sessionId = sessionId;
+    }
+  }
+  /**
+   * Handle an error thrown by the query's async generator. Aborts are logged
+   * silently; everything else is classified and routed through {@link failTurn}
+   * (auth-shaped failures promoted to {@link AuthError}).
+   */
+  handleConsumerError(err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    if (error.name === "AbortError" || this.abortController?.signal.aborted) {
+      this.log.info("aborted");
+      return;
+    }
+    const detail = classifyClaudeSdkError({
+      errors: [error.message],
+      oauthCredential: this.usingOauthCredential
+    });
+    this.log.error("consumer error", {
+      message: error.message,
+      category: detail.category,
+      retryable: detail.retryable
+    });
+    const surfaced = detail.category === "auth" ? new AuthError(detail) : error;
+    this.failTurn(surfaced, detail);
+  }
   /**
    * Signal the current turn as done — idempotent per turn.
    *
@@ -834,6 +885,23 @@ var ClaudeSdkDriver = class extends AgentDriver {
   // Message handling
   // ---------------------------------------------------------------------------
   handleSdkMessage(msg) {
+    if (this.handleRateLimitEvent(msg)) return;
+    if (msg.type === "assistant") {
+      this.handleAssistantMessage(msg);
+    } else if (msg.type === "stream_event") {
+      this.handleStreamEvent(msg);
+    } else if (msg.type === "user") {
+      this.handleUserMessage(msg);
+    } else if (msg.type === "result") {
+      this.handleResultMessage(msg);
+    }
+  }
+  /**
+   * Surface subscription rate-limit telemetry as a structured warning log.
+   * Returns `true` when the message was a rate-limit event (and fully handled),
+   * so the caller can stop dispatching.
+   */
+  handleRateLimitEvent(msg) {
     const maybeRateLimit = msg;
     if (maybeRateLimit.type === "rate_limit_event" && maybeRateLimit.rate_limit_info) {
       const info = maybeRateLimit.rate_limit_info;
@@ -843,115 +911,177 @@ var ClaudeSdkDriver = class extends AgentDriver {
         utilization: info.utilization,
         resetsAt: info.resetsAt
       });
-      return;
+      return true;
     }
-    if (msg.type === "assistant") {
-      const agentMsg = this.mapAssistantMessage(msg);
-      this.emit("agent-event", { type: "message_start", message: agentMsg });
-      if (agentMsg.toolCalls) {
-        for (const tc of agentMsg.toolCalls) {
-          this.emit("agent-event", {
-            type: "tool_call",
-            name: tc.name,
-            tool: { name: tc.name },
-            input: tc.input
-          });
-        }
-      }
+    return false;
+  }
+  handleAssistantMessage(msg) {
+    const agentMsg = this.mapAssistantMessage(msg);
+    if (this.isSuppressibleAuthRender(agentMsg)) {
+      this.log.info("suppressing SDK auth-error assistant text; self-heal will retry");
       this.prevText = "";
-      this.emit("agent-event", { type: "message_end", message: agentMsg });
-    } else if (msg.type === "stream_event") {
-      const event = msg.event;
-      if (event?.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta.text) {
-        const delta = event.delta.text;
-        this.prevText += delta;
-        const agentMsg = {
-          role: "assistant",
-          content: [{ type: "text", text: this.prevText }]
-        };
-        this.emit("agent-event", {
-          type: "message_update",
-          message: agentMsg,
-          _textDelta: delta
-        });
-      }
-    } else if (msg.type === "user") {
-      const toolResults = this.mapToolResults(msg);
-      for (const result of toolResults) {
+      this.suppressingAuthStream = false;
+      return;
+    }
+    this.emit("agent-event", { type: "message_start", message: agentMsg });
+    if (agentMsg.toolCalls) {
+      for (const tc of agentMsg.toolCalls) {
         this.emit("agent-event", {
-          type: "tool_execution_end",
-          toolName: result.toolName
+          type: "tool_call",
+          name: tc.name,
+          tool: { name: tc.name },
+          input: tc.input
         });
       }
-      if (toolResults.length > 0) {
-        this.emit("agent-event", { type: "turn_end", toolResults });
-      }
-    } else if (msg.type === "result") {
-      const usage = msg.usage;
-      if (usage) {
-        const tokens = {};
-        if (typeof usage.input_tokens === "number") tokens.inputTokens = usage.input_tokens;
-        if (typeof usage.output_tokens === "number") tokens.outputTokens = usage.output_tokens;
-        if (typeof usage.cache_read_input_tokens === "number")
-          tokens.cacheReadTokens = usage.cache_read_input_tokens;
-        if (typeof usage.cache_creation_input_tokens === "number")
-          tokens.cacheCreationTokens = usage.cache_creation_input_tokens;
-        this._lastTokens = tokens;
-      }
-      const modelUsage = msg.modelUsage;
-      if (modelUsage) {
-        const first = Object.values(modelUsage)[0];
-        if (first?.contextWindow) this._contextWindow = first.contextWindow;
-      }
-      if (msg.subtype === "success" && !msg.is_error) {
-        if (msg.result) {
-          const agentMsg = {
-            role: "assistant",
-            content: msg.result
-          };
-          this.emit("agent-event", { type: "message_end", message: agentMsg });
-        }
-        this.emit("agent-event", {
-          type: "result",
-          subtype: msg.subtype,
-          summary: msg.result ?? "Task completed",
-          costUsd: msg.total_cost_usd ?? 0,
-          ...this._lastTokens ? { tokens: this._lastTokens } : {}
-        });
-      } else {
-        const looseMsg = msg;
-        const errors = looseMsg.errors?.length ? looseMsg.errors : [];
-        if (looseMsg.is_error) {
-          const detail = classifyClaudeSdkError({
-            errors,
-            terminalReason: msg.terminal_reason,
-            subtype: msg.subtype,
-            oauthCredential: this.usingOauthCredential
-          });
-          this.log.error("turn ended with error", {
-            subtype: msg.subtype,
-            terminalReason: msg.terminal_reason,
-            errorsCount: errors.length,
-            category: detail.category,
-            retryable: detail.retryable
-          });
-          const errorText = errors.join("; ") || `Agent stopped: ${msg.subtype}`;
-          if (detail.category === "auth") {
-            this.failTurn(new AuthError({ ...detail, message: errorText }), detail);
-          } else if (errors.length > 0) {
-            this.emit("agent-event", {
-              type: "error",
-              error: errorText,
-              detail
-            });
-          }
-        }
-        this.emit("agent-event", {
-          type: "result",
-          subtype: msg.subtype,
-          errors
-        });
+    }
+    this.prevText = "";
+    this.suppressingAuthStream = false;
+    this.emit("agent-event", { type: "message_end", message: agentMsg });
+  }
+  // True when this assistant text is the SDK's render of a 401 about to be self-healed.
+  isSuppressibleAuthRender(msg) {
+    if (this.authSelfHealUsed || this.config.onAuthError == null) return false;
+    if (msg.toolCalls && msg.toolCalls.length > 0) return false;
+    const text = typeof msg.content === "string" ? msg.content : msg.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("");
+    return this.textIsAuthRender(text);
+  }
+  // Cheap substring pre-filter keeps the full classifier off the hot path of
+  // every assistant message / stream delta; only auth-shaped text pays for it.
+  textIsAuthRender(text) {
+    const lower = text.trim().toLowerCase();
+    if (!lower) return false;
+    if (!lower.includes("auth") && !lower.includes("401") && !lower.includes("login")) {
+      return false;
+    }
+    return classifyClaudeSdkError({ errors: [text], oauthCredential: this.usingOauthCredential }).category === "auth";
+  }
+  handleStreamEvent(msg) {
+    const event = msg.event;
+    if (event?.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta.text) {
+      const delta = event.delta.text;
+      this.prevText += delta;
+      if (!this.suppressingAuthStream && this.textIsAuthRender(this.prevText)) {
+        this.suppressingAuthStream = true;
+        this.log.info("suppressing SDK auth-error stream; self-heal will retry");
       }
+      if (this.suppressingAuthStream) return;
+      const agentMsg = {
+        role: "assistant",
+        content: [{ type: "text", text: this.prevText }]
+      };
+      this.emit("agent-event", {
+        type: "message_update",
+        message: agentMsg,
+        _textDelta: delta
+      });
+    }
+  }
+  handleUserMessage(msg) {
+    const toolResults = this.mapToolResults(msg);
+    for (const result of toolResults) {
+      this.emit("agent-event", {
+        type: "tool_execution_end",
+        toolName: result.toolName
+      });
+    }
+    if (toolResults.length > 0) {
+      this.emit("agent-event", { type: "turn_end", toolResults });
+    }
+  }
+  handleResultMessage(msg) {
+    this.captureResultUsage(msg);
+    if (msg.subtype === "success" && !msg.is_error) {
+      this.handleSuccessResult(msg);
+    } else {
+      this.handleErrorResult(msg);
+    }
+  }
+  /**
+   * Capture token usage + context-window size from a result message.
+   * Anthropic separates fresh prompt input from cached/cache-creation
+   * tokens — surface all four to consumers that want a complete picture.
+   */
+  captureResultUsage(msg) {
+    const usage = msg.usage;
+    if (usage) {
+      const tokens = {};
+      if (typeof usage.input_tokens === "number") tokens.inputTokens = usage.input_tokens;
+      if (typeof usage.output_tokens === "number") tokens.outputTokens = usage.output_tokens;
+      if (typeof usage.cache_read_input_tokens === "number")
+        tokens.cacheReadTokens = usage.cache_read_input_tokens;
+      if (typeof usage.cache_creation_input_tokens === "number")
+        tokens.cacheCreationTokens = usage.cache_creation_input_tokens;
+      this._lastTokens = tokens;
+    }
+    const modelUsage = msg.modelUsage;
+    if (modelUsage) {
+      const first = Object.values(modelUsage)[0];
+      if (first?.contextWindow) this._contextWindow = first.contextWindow;
+    }
+  }
+  /** Emit the message_end (if any) + success result event for a clean turn. */
+  handleSuccessResult(msg) {
+    if (msg.result) {
+      const agentMsg = {
+        role: "assistant",
+        content: msg.result
+      };
+      this.emit("agent-event", { type: "message_end", message: agentMsg });
+    }
+    this.emit("agent-event", {
+      type: "result",
+      subtype: msg.subtype,
+      summary: msg.result ?? "Task completed",
+      costUsd: msg.total_cost_usd ?? 0,
+      ...this._lastTokens ? { tokens: this._lastTokens } : {}
+    });
+  }
+  /**
+   * Handle the non-clean branch (legacy `SDKResultError`, or a `success`
+   * subtype carrying `is_error: true`). Read via the loose shape since the
+   * second case omits `errors` on the typed variant. See devlog note
+   * 2026-06-08-claude-sdk-error-result-handling.
+   */
+  handleErrorResult(msg) {
+    const looseMsg = msg;
+    const errors = looseMsg.errors?.length ? looseMsg.errors : [];
+    if (looseMsg.is_error) {
+      this.handleResultErrorPayload(msg, errors);
+    }
+    this.emit("agent-event", {
+      type: "result",
+      subtype: msg.subtype,
+      errors
+    });
+  }
+  /**
+   * Classify + route an `is_error` result payload: auth-shaped errors throw
+   * via `failTurn`; populated non-auth errors surface a normal `error` event;
+   * empty errors defer to the consumer-error catch.
+   */
+  handleResultErrorPayload(msg, errors) {
+    const detail = classifyClaudeSdkError({
+      errors,
+      terminalReason: msg.terminal_reason,
+      subtype: msg.subtype,
+      oauthCredential: this.usingOauthCredential
+    });
+    this.log.error("turn ended with error", {
+      subtype: msg.subtype,
+      terminalReason: msg.terminal_reason,
+      errorsCount: errors.length,
+      category: detail.category,
+      retryable: detail.retryable
+    });
+    const errorText = errors.join("; ") || `Agent stopped: ${msg.subtype}`;
+    if (detail.category === "auth") {
+      this.failTurn(new AuthError({ ...detail, message: errorText }), detail);
+    } else if (errors.length > 0) {
+      this.emit("agent-event", {
+        type: "error",
+        error: errorText,
+        detail
+      });
     }
   }
   // ---------------------------------------------------------------------------