Building Self-Healing AI Agents with Claude API — Error Detection, Auto-Recovery, and Graceful Degradation Patterns for Production

// self-healing-agent.ts — Core self-healing agent structure
import Anthropic from "@anthropic-ai/sdk";
 
// Error category definitions
type ErrorCategory =
  | "transient_api"
  | "context_overflow"
  | "tool_failure"
  | "malformed_output"
  | "reasoning_error"
  | "infinite_loop"
  | "cascade_failure";
 
interface DiagnosisResult {
  category: ErrorCategory;
  severity: "low" | "medium" | "high" | "critical";
  rootCause: string;
  suggestedStrategy: string;
  retryable: boolean;
}
 
interface HealingResult {
  success: boolean;
  strategy: string;
  attemptsUsed: number;
  degraded: boolean; // Whether graceful degradation was applied
}
 
class SelfHealingAgent {
  private client: Anthropic;
  private maxRetries = 3;
  private loopDetector: LoopDetector;
  private circuitBreaker: CircuitBreaker;
  private metrics: MetricsCollector;
 
  constructor() {
    this.client = new Anthropic();
    this.loopDetector = new LoopDetector();
    this.circuitBreaker = new CircuitBreaker();
    this.metrics = new MetricsCollector();
  }
 
  // Main agent loop with self-healing capabilities
  async run(task: string): Promise<string> {
    let context: Anthropic.MessageParam[] = [];
    let result = "";
 
    for (let step = 0; step < 20; step++) {
      try {
        // Loop detection check
        if (this.loopDetector.isLooping(context)) {
          await this.healFromLoop(context);
        }
 
        // Circuit breaker check
        if (this.circuitBreaker.isOpen()) {
          return this.gracefulDegrade(task, context);
        }
 
        const response = await this.callWithHealing(context, task);
 
        // Branch based on stop_reason
        if (response.stop_reason === "end_turn") {
          result = this.extractText(response);
          break;
        }
 
        // Execute tool calls with self-healing
        if (response.stop_reason === "tool_use") {
          const toolResults = await this.executeToolsWithHealing(
            response.content
          );
          context.push(
            { role: "assistant", content: response.content },
            { role: "user", content: toolResults }
          );
        }
      } catch (error) {
        // Self-healing flow: Detect → Diagnose → Heal → Verify
        const diagnosis = await this.diagnose(error);
        this.metrics.recordError(diagnosis);
        const healing = await this.heal(diagnosis, context, task);
 
        if (!healing.success) {
          // Fall back to graceful degradation
          return this.gracefulDegrade(task, context);
        }
      }
    }
 
    return result;
  }
 
  // Individual method implementations follow below
  // ...
}

// retry-with-backoff.ts — Exponential backoff with jitter
interface RetryConfig {
  maxRetries: number;
  baseDelay: number;      // milliseconds
  maxDelay: number;       // milliseconds
  jitterFactor: number;   // 0 to 1
}
 
const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxRetries: 3,
  baseDelay: 1000,
  maxDelay: 30000,
  jitterFactor: 0.5,
};
 
async function callWithRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig = DEFAULT_RETRY_CONFIG
): Promise<T> {
  let lastError: Error | null = null;
 
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      lastError = error;
 
      // Non-retryable errors are thrown immediately
      if (!isRetryable(error)) throw error;
 
      if (attempt < config.maxRetries) {
        const delay = calculateDelay(attempt, config);
        console.log(
          `[Retry ${attempt + 1}/${config.maxRetries}] ` +
          `Waiting ${delay}ms before retry...`
        );
        await sleep(delay);
      }
    }
  }
 
  throw lastError;
}
 
function calculateDelay(attempt: number, config: RetryConfig): number {
  // Exponential backoff: baseDelay * 2^attempt
  const exponentialDelay = config.baseDelay * Math.pow(2, attempt);
  const cappedDelay = Math.min(exponentialDelay, config.maxDelay);
 
  // Add jitter to distribute server load
  const jitter = cappedDelay * config.jitterFactor * Math.random();
  return cappedDelay + jitter;
}
 
function isRetryable(error: any): boolean {
  // 429 Rate Limit and 5xx are transient — safe to retry
  if (error.status === 429) return true;
  if (error.status >= 500 && error.status < 600) return true;
  // Network errors are retryable
  if (error.code === "ECONNRESET" || error.code === "ETIMEDOUT") return true;
  // Anthropic's overloaded_error is retryable
  if (error.error?.type === "overloaded_error") return true;
  return false;
}
 
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// context-compression.ts — Automatic context compression
class ContextCompressor {
  private client: Anthropic;
  private maxContextTokens: number;
 
  constructor(client: Anthropic, maxTokens = 150000) {
    this.client = client;
    this.maxContextTokens = maxTokens;
  }
 
  async compressIfNeeded(
    messages: Anthropic.MessageParam[]
  ): Promise<Anthropic.MessageParam[]> {
    const estimatedTokens = this.estimateTokens(messages);
 
    if (estimatedTokens < this.maxContextTokens * 0.8) {
      return messages; // Below 80% — no compression needed
    }
 
    console.log(
      `[ContextCompressor] Token estimate: ${estimatedTokens} ` +
      `(limit: ${this.maxContextTokens}). Compressing...`
    );
 
    // Strategy 1: Summarize older conversation turns
    const summarized = await this.summarizeOldMessages(messages);
 
    // Strategy 2: Trim verbose tool results
    const trimmed = this.trimToolResults(summarized);
 
    const newEstimate = this.estimateTokens(trimmed);
    console.log(
      `[ContextCompressor] Compressed: ${estimatedTokens} → ${newEstimate} tokens`
    );
 
    return trimmed;
  }
 
  private async summarizeOldMessages(
    messages: Anthropic.MessageParam[]
  ): Promise<Anthropic.MessageParam[]> {
    if (messages.length <= 6) return messages;
 
    // Keep the 6 most recent messages, summarize the rest
    const oldMessages = messages.slice(0, -6);
    const recentMessages = messages.slice(-6);
 
    const summaryResponse = await this.client.messages.create({
      model: "claude-sonnet-4-6",  // Cost-efficient model for compression
      max_tokens: 1024,
      system: "Summarize the conversation history concisely. Focus on " +
              "key decisions, completed actions, and unresolved issues.",
      messages: [
        {
          role: "user",
          content: `Summarize the following conversation:\n\n` +
                   JSON.stringify(oldMessages, null, 2),
        },
      ],
    });
 
    const summaryText =
      summaryResponse.content[0].type === "text"
        ? summaryResponse.content[0].text
        : "";
 
    return [
      {
        role: "user",
        content: `[Previous conversation summary]\n${summaryText}`,
      },
      { role: "assistant", content: "Understood. I'll continue based on this summary." },
      ...recentMessages,
    ];
  }
 
  private trimToolResults(
    messages: Anthropic.MessageParam[]
  ): Anthropic.MessageParam[] {
    return messages.map((msg) => {
      if (msg.role !== "user" || !Array.isArray(msg.content)) return msg;
 
      const trimmedContent = msg.content.map((block: any) => {
        if (block.type !== "tool_result") return block;
 
        // Truncate tool results longer than 1000 characters
        if (
          typeof block.content === "string" &&
          block.content.length > 1000
        ) {
          return {
            ...block,
            content:
              block.content.slice(0, 1000) +
              "\n... [truncated for context management]",
          };
        }
        return block;
      });
 
      return { ...msg, content: trimmedContent };
    });
  }
 
  private estimateTokens(messages: Anthropic.MessageParam[]): number {
    // Rough estimate: ~0.4 tokens per character for mixed content
    const text = JSON.stringify(messages);
    return Math.ceil(text.length * 0.4);
  }
}

// supervisor-pattern.ts — External monitoring and automatic intervention
interface AgentState {
  taskId: string;
  startTime: number;
  stepCount: number;
  tokenUsage: number;
  lastToolCalls: string[];    // Recent tool call history
  progressIndicators: string[]; // Signs of progress
}
 
class SupervisorAgent {
  private client: Anthropic;
  private thresholds = {
    maxSteps: 30,
    maxDuration: 300000,       // 5 minutes
    maxTokens: 500000,
    loopDetectionWindow: 5,    // Monitor last 5 tool calls
  };
 
  constructor(client: Anthropic) {
    this.client = client;
  }
 
  // Evaluate worker agent state
  async evaluate(state: AgentState): Promise<SupervisorDecision> {
    // 1. Quantitative checks (fast)
    const quantCheck = this.quantitativeCheck(state);
    if (quantCheck.action !== "continue") return quantCheck;
 
    // 2. Loop detection (pattern matching)
    const loopCheck = this.detectLoop(state.lastToolCalls);
    if (loopCheck.action !== "continue") return loopCheck;
 
    // 3. Qualitative check (Claude-powered progress evaluation)
    if (state.stepCount > 10 && state.stepCount % 5 === 0) {
      return await this.qualitativeCheck(state);
    }
 
    return { action: "continue" };
  }
 
  private quantitativeCheck(state: AgentState): SupervisorDecision {
    const elapsed = Date.now() - state.startTime;
 
    if (state.stepCount > this.thresholds.maxSteps) {
      return {
        action: "intervene",
        reason: `Step count exceeded: ${state.stepCount}/${this.thresholds.maxSteps}`,
        strategy: "reset_with_summary",
      };
    }
 
    if (elapsed > this.thresholds.maxDuration) {
      return {
        action: "intervene",
        reason: `Duration exceeded: ${elapsed}ms/${this.thresholds.maxDuration}ms`,
        strategy: "force_completion",
      };
    }
 
    if (state.tokenUsage > this.thresholds.maxTokens) {
      return {
        action: "intervene",
        reason: `Token usage exceeded: ${state.tokenUsage}`,
        strategy: "compress_and_continue",
      };
    }
 
    return { action: "continue" };
  }
 
  private detectLoop(toolCalls: string[]): SupervisorDecision {
    const window = toolCalls.slice(-this.thresholds.loopDetectionWindow);
 
    // Check for consecutive identical tool calls
    if (window.length >= 3) {
      const unique = new Set(window);
      if (unique.size === 1) {
        return {
          action: "intervene",
          reason: `Loop detected: "${window[0]}" called ${window.length} times consecutively`,
          strategy: "break_loop",
        };
      }
    }
 
    // Detect oscillation patterns like A → B → A → B
    if (window.length >= 4) {
      const pattern = window.slice(0, 2).join(",");
      const repeated = window.slice(2, 4).join(",");
      if (pattern === repeated) {
        return {
          action: "intervene",
          reason: `Oscillation detected: ${pattern}`,
          strategy: "alternative_approach",
        };
      }
    }
 
    return { action: "continue" };
  }
 
  private async qualitativeCheck(
    state: AgentState
  ): Promise<SupervisorDecision> {
    // Use Claude to evaluate progress qualitatively
    const response = await this.client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 512,
      system:
        "You are a Supervisor monitoring an AI agent's progress. " +
        "Based on the information below, determine if the agent is making " +
        "healthy progress. Respond in JSON: {\"healthy\": boolean, \"reason\": string}",
      messages: [
        {
          role: "user",
          content:
            `Steps: ${state.stepCount}\n` +
            `Recent tools: ${state.lastToolCalls.slice(-10).join(", ")}\n` +
            `Progress indicators: ${state.progressIndicators.join("; ")}`,
        },
      ],
    });
 
    const text =
      response.content[0].type === "text" ? response.content[0].text : "{}";
 
    try {
      const evaluation = JSON.parse(text);
      if (!evaluation.healthy) {
        return {
          action: "intervene",
          reason: evaluation.reason,
          strategy: "guided_correction",
        };
      }
    } catch {
      // Ignore JSON parse failures and continue
    }
 
    return { action: "continue" };
  }
}
 
interface SupervisorDecision {
  action: "continue" | "intervene" | "abort";
  reason?: string;
  strategy?: string;
}

// tool-fallback-chain.ts — Tool fallback chains
interface ToolFallbackConfig {
  primary: string;
  fallbacks: string[];
  defaultValue?: any;
  timeout: number;
}
 
class ResilientToolExecutor {
  private fallbackChains: Map<string, ToolFallbackConfig> = new Map();
  private circuitBreakers: Map<string, CircuitBreaker> = new Map();
 
  registerChain(toolName: string, config: ToolFallbackConfig) {
    this.fallbackChains.set(toolName, config);
    this.circuitBreakers.set(toolName, new CircuitBreaker({
      failureThreshold: 3,
      resetTimeout: 60000, // Reset after 1 minute
    }));
  }
 
  async execute(
    toolName: string,
    input: any
  ): Promise<{ result: any; usedFallback: boolean; toolUsed: string }> {
    const chain = this.fallbackChains.get(toolName);
    if (!chain) {
      // Execute directly if no fallback chain is defined
      return {
        result: await this.executeTool(toolName, input),
        usedFallback: false,
        toolUsed: toolName,
      };
    }
 
    // Try the primary tool first
    const breaker = this.circuitBreakers.get(toolName)!;
    if (!breaker.isOpen()) {
      try {
        const result = await Promise.race([
          this.executeTool(chain.primary, input),
          this.timeoutPromise(chain.timeout),
        ]);
        breaker.recordSuccess();
        return { result, usedFallback: false, toolUsed: chain.primary };
      } catch (error) {
        breaker.recordFailure();
        console.warn(
          `[Fallback] Primary tool "${chain.primary}" failed:`,
          error
        );
      }
    }
 
    // Try each fallback in order
    for (const fallback of chain.fallbacks) {
      try {
        const result = await Promise.race([
          this.executeTool(fallback, input),
          this.timeoutPromise(chain.timeout),
        ]);
        return { result, usedFallback: true, toolUsed: fallback };
      } catch (error) {
        console.warn(`[Fallback] "${fallback}" also failed:`, error);
      }
    }
 
    // Return default value if all tools failed
    if (chain.defaultValue !== undefined) {
      console.warn(
        `[Fallback] All tools failed. Using default value for "${toolName}"`
      );
      return {
        result: chain.defaultValue,
        usedFallback: true,
        toolUsed: "default",
      };
    }
 
    throw new Error(
      `All fallbacks exhausted for tool "${toolName}"`
    );
  }
 
  private async executeTool(name: string, input: any): Promise<any> {
    // Actual tool execution logic (implement per project)
    throw new Error("Not implemented");
  }
 
  private timeoutPromise(ms: number): Promise<never> {
    return new Promise((_, reject) =>
      setTimeout(() => reject(new Error("Tool execution timeout")), ms)
    );
  }
}
 
// Circuit breaker implementation
class CircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private state: "closed" | "open" | "half-open" = "closed";
  private config: { failureThreshold: number; resetTimeout: number };
 
  constructor(config: { failureThreshold: number; resetTimeout: number }) {
    this.config = config;
  }
 
  isOpen(): boolean {
    if (this.state === "open") {
      // Transition to half-open after reset timeout
      if (Date.now() - this.lastFailure > this.config.resetTimeout) {
        this.state = "half-open";
        return false;
      }
      return true;
    }
    return false;
  }
 
  recordSuccess() {
    this.failures = 0;
    this.state = "closed";
  }
 
  recordFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.config.failureThreshold) {
      this.state = "open";
    }
  }
}

// output-healing.ts — Automatic structured output repair
import { z } from "zod";
 
class OutputHealer {
  private client: Anthropic;
 
  constructor(client: Anthropic) {
    this.client = client;
  }
 
  async parseWithHealing<T>(
    rawOutput: string,
    schema: z.ZodSchema<T>,
    maxAttempts = 3
  ): Promise<T> {
    // 1. Try direct parsing first
    try {
      const parsed = JSON.parse(rawOutput);
      return schema.parse(parsed);
    } catch (firstError) {
      console.log("[OutputHealer] Initial parse failed. Attempting repair...");
    }
 
    // 2. Try basic JSON syntax repair
    const cleaned = this.cleanJsonString(rawOutput);
    try {
      const parsed = JSON.parse(cleaned);
      return schema.parse(parsed);
    } catch {
      // Continue to Claude-powered repair
    }
 
    // 3. Ask Claude to repair the output
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      try {
        const repaired = await this.repairWithClaude(
          rawOutput,
          schema,
          attempt
        );
        return schema.parse(JSON.parse(repaired));
      } catch (error) {
        if (attempt === maxAttempts) {
          throw new Error(
            `Output healing failed after ${maxAttempts} attempts: ${error}`
          );
        }
      }
    }
 
    throw new Error("Unreachable");
  }
 
  private cleanJsonString(raw: string): string {
    // Auto-fix common JSON error patterns
    let cleaned = raw
      .replace(/```json\n?/g, "")        // Remove markdown code blocks
      .replace(/```\n?/g, "")
      .replace(/,\s*}/g, "}")             // Remove trailing commas
      .replace(/,\s*]/g, "]")
      .replace(/'/g, '"')                 // Replace single quotes
      .replace(/\n/g, "\\n")             // Escape newlines
      .trim();
 
    // Extract only the JSON portion
    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
    if (jsonMatch) cleaned = jsonMatch[0];
 
    return cleaned;
  }
 
  private async repairWithClaude<T>(
    brokenOutput: string,
    schema: z.ZodSchema<T>,
    attempt: number
  ): Promise<string> {
    // Convert Zod schema to human-readable form
    const schemaDescription = JSON.stringify(
      (schema as any)._def,
      null,
      2
    );
 
    const response = await this.client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      system:
        "You are an expert at repairing broken JSON output. " +
        "Return ONLY valid JSON that fully conforms to the given schema. " +
        "No explanations — just the JSON.",
      messages: [
        {
          role: "user",
          content:
            `Broken output:\n${brokenOutput}\n\n` +
            `Expected schema:\n${schemaDescription}\n\n` +
            `Repair attempt: ${attempt}`,
        },
      ],
    });
 
    const text =
      response.content[0].type === "text" ? response.content[0].text : "";
    return this.cleanJsonString(text);
  }
}

// observability.ts — Self-healing observability pipeline
interface HealingEvent {
  timestamp: number;
  taskId: string;
  errorCategory: ErrorCategory;
  severity: string;
  strategy: string;
  success: boolean;
  duration: number;        // Time spent healing (ms)
  tokensUsed: number;      // Tokens consumed for healing
  degraded: boolean;       // Whether graceful degradation was applied
}
 
class MetricsCollector {
  private events: HealingEvent[] = [];
  private alertThresholds = {
    failureRate: 0.3,       // Alert if healing failure rate exceeds 30%
    healingFrequency: 10,   // Alert if 10+ healings in 10 minutes
    cascadeWindow: 60000,   // Cascade warning if same category fails 3x in 1 min
  };
 
  record(event: HealingEvent) {
    this.events.push(event);
 
    // Real-time alert checks
    this.checkAlerts();
 
    // Structured log output (JSON Lines format)
    console.log(JSON.stringify({
      type: "healing_event",
      ...event,
      // Expected output: {"type":"healing_event","timestamp":1711878000000,...}
    }));
  }
 
  // Dashboard-ready summary statistics
  getSummary(windowMs = 3600000): HealingSummary {
    const cutoff = Date.now() - windowMs;
    const recent = this.events.filter((e) => e.timestamp > cutoff);
 
    const total = recent.length;
    const successes = recent.filter((e) => e.success).length;
    const failures = total - successes;
 
    // Distribution by category
    const byCategory = recent.reduce(
      (acc, e) => {
        acc[e.errorCategory] = (acc[e.errorCategory] || 0) + 1;
        return acc;
      },
      {} as Record<string, number>
    );
 
    return {
      total,
      successRate: total > 0 ? successes / total : 1,
      failureRate: total > 0 ? failures / total : 0,
      avgHealingDuration:
        total > 0
          ? recent.reduce((sum, e) => sum + e.duration, 0) / total
          : 0,
      totalTokensUsed: recent.reduce((sum, e) => sum + e.tokensUsed, 0),
      byCategory,
      degradedCount: recent.filter((e) => e.degraded).length,
    };
  }
 
  private checkAlerts() {
    const summary = this.getSummary(600000); // 10-minute window
 
    if (summary.failureRate > this.alertThresholds.failureRate) {
      this.sendAlert(
        "HIGH",
        `Healing failure rate at ${(summary.failureRate * 100).toFixed(1)}%`
      );
    }
 
    if (summary.total > this.alertThresholds.healingFrequency) {
      this.sendAlert(
        "MEDIUM",
        `${summary.total} self-healing events in last 10 minutes`
      );
    }
  }
 
  private sendAlert(level: string, message: string) {
    // Connect to your alerting system (Slack, PagerDuty, etc.)
    console.error(`[ALERT:${level}] ${message}`);
  }
}
 
interface HealingSummary {
  total: number;
  successRate: number;
  failureRate: number;
  avgHealingDuration: number;
  totalTokensUsed: number;
  byCategory: Record<string, number>;
  degradedCount: number;
}

// graceful-degradation.ts — Progressive capability reduction
class GracefulDegradation {
  private client: Anthropic;
 
  constructor(client: Anthropic) {
    this.client = client;
  }
 
  async degrade(
    task: string,
    context: Anthropic.MessageParam[],
    failedCapabilities: string[]
  ): Promise<{ result: string; level: DegradationLevel }> {
    // Level 1: Try answering without tools
    if (failedCapabilities.includes("tools")) {
      try {
        const response = await this.client.messages.create({
          model: "claude-opus-4-6",
          max_tokens: 4096,
          system:
            "External tools are temporarily unavailable. " +
            "Answer as accurately as possible using only your knowledge. " +
            "Clearly indicate where tool access would have been needed.",
          messages: [
            ...context,
            {
              role: "user",
              content: `[System: Tools unavailable — knowledge-only mode] ${task}`,
            },
          ],
        });
 
        return {
          result: this.extractText(response) +
            "\n\n---\n⚠️ Some external data retrieval failed. " +
            "This response is based on AI knowledge. " +
            "Please verify with up-to-date sources.",
          level: "partial",
        };
      } catch {
        // Fall through to Level 2
      }
    }
 
    // Level 2: Fall back to a lighter model
    try {
      const response = await this.client.messages.create({
        model: "claude-haiku-4-5",
        max_tokens: 1024,
        messages: [
          {
            role: "user",
            content: `Please answer briefly: ${task}`,
          },
        ],
      });
 
      return {
        result: this.extractText(response) +
          "\n\n---\n⚠️ A simplified response due to temporary system limitations.",
        level: "minimal",
      };
    } catch {
      // Fall through to Level 3
    }
 
    // Level 3: Cached response or error message
    return {
      result:
        "We're sorry — the system is experiencing a temporary issue. " +
        "Please try again in a few minutes. " +
        "If the problem persists, contact support.",
      level: "unavailable",
    };
  }
 
  private extractText(response: Anthropic.Message): string {
    return response.content
      .filter((b): b is Anthropic.TextBlock => b.type === "text")
      .map((b) => b.text)
      .join("");
  }
}
 
type DegradationLevel = "full" | "partial" | "minimal" | "unavailable";

from dataclasses import dataclass
 
@dataclass
class AgentBudget:
    max_input_tokens: int
    max_output_tokens: int
    max_iterations: int = 20
    used_input: int = 0
    used_output: int = 0
    iterations: int = 0
 
    def record(self, usage):
        self.used_input += usage.input_tokens
        self.used_output += usage.output_tokens
        self.iterations += 1
 
    def exhausted(self) -> tuple[bool, str]:
        if self.iterations >= self.max_iterations:
            return True, f"hit iteration cap of {self.max_iterations}"
        if self.used_input >= self.max_input_tokens:
            return True, f"hit input-token cap of {self.max_input_tokens:,}"
        if self.used_output >= self.max_output_tokens:
            return True, f"hit output-token cap of {self.max_output_tokens:,}"
        return False, ""
 
    def nearly_done(self) -> bool:
        in_ratio = self.used_input / self.max_input_tokens
        out_ratio = self.used_output / self.max_output_tokens
        return max(in_ratio, out_ratio) > 0.8
 
 
def run_with_budget(client, user_request: str, tools, budget: AgentBudget) -> str:
    messages = [{"role": "user", "content": user_request}]
 
    while True:
        stop, reason = budget.exhausted()
        if stop:
            # Don't die silently — surface why it stopped, with the latest state
            return f"[budget reached: {reason}] latest state: {messages[-1]['content']}"
 
        # Under 20% left? Tell the model to wrap up instead of branching further
        hint = "\n[Budget nearly spent. Do not open new branches; converge to an answer.]" if budget.nearly_done() else ""
 
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=min(4096, budget.max_output_tokens - budget.used_output),
            tools=tools,
            system="You manage the task." + hint,
            messages=messages,
        )
        budget.record(response.usage)
 
        if response.stop_reason == "end_turn":
            return response.content[0].text
 
        messages.append({"role": "assistant", "content": response.content})
        # Appending tool results to messages is identical to the loop shown earlier