Add Runtime Limits to Claude Agent Workflows

upstream handlers to distinguish between hard failures and policy-enforced stops, enabling graceful degradation instead of unhandled exceptions. 4. Async-Safe Enforcement: The guard integrates with AbortController to propagate cancellation signals to pending I/O operations, preventing orphaned network requests or dangling tool calls.

Implementation

import { AbortController } from "node:stream/web";

interface ExecutionPolicy {
  maxDurationMs: number;
  maxIterations: number;
  maxToolInvocations: number;
}

interface ExecutionTelemetry {
  startedAt: number;
  iterations: number;
  toolCalls: number;
  aborted: boolean;
}

class RuntimeBoundaryController {
  private readonly policy: ExecutionPolicy;
  private readonly telemetry: ExecutionTelemetry;
  private readonly abortController: AbortController;

  constructor(policy: ExecutionPolicy) {
    this.policy = policy;
    this.telemetry = {
      startedAt: Date.now(),
      iterations: 0,
      toolCalls: 0,
      aborted: false,
    };
    this.abortController = new AbortController();
  }

  get signal(): AbortSignal {
    return this.abortController.signal;
  }

  recordIteration(): void {
    this.telemetry.iterations += 1;
  }

  recordToolCall(): void {
    this.telemetry.toolCalls += 1;
  }

  validate(): void {
    if (this.telemetry.aborted) {
      throw new Error("Execution already terminated");
    }

    const elapsed = Date.now() - this.telemetry.startedAt;
    const violations: string[] = [];

    if (elapsed > this.policy.maxDurationMs) {
      violations.push(`Duration exceeded: ${elapsed}ms > ${this.policy.maxDurationMs}ms`);
    }
    if (this.telemetry.iterations > this.policy.maxIterations) {
      violations.push(`Iteration count exceeded: ${this.telemetry.iterations} > ${this.policy.maxIterations}`);
    }
    if (this.telemetry.toolCalls > this.policy.maxToolInvocations) {
      violations.push(`Tool calls exceeded: ${this.telemetry.toolCalls} > ${this.policy.maxToolInvocations}`);
    }

    if (violations.length > 0) {
      this.telemetry.aborted = true;
      this.abortController.abort();
      throw new RuntimeLimitError(violations, this.telemetry);
    }
  }

  reset(): void {
    this.telemetry.startedAt = Date.now();
    this.telemetry.iterations = 0;
    this.telemetry.toolCalls = 0;
    this.telemetry.aborted = false;
    this.abortController = new AbortController();
  }
}

class RuntimeLimitError extends Error {
  constructor(
    public readonly violations: string[],
    public readonly telemetry: ExecutionTelemetry
  ) {
    super("Runtime boundaries breached");
    this.name = "RuntimeLimitError";
  }
}

Integration Pattern

The controller wraps the agent execution loop. Each iteration validates constraints before invoking the model, and telemetry is updated based on response metadata.

async function runBoundedAgent(
  policy: ExecutionPolicy,
  agentExecutor: (signal: AbortSignal) => Promise<{ done: boolean; usedTool: boolean }>
): Promise<void> {
  const guard = new RuntimeBoundaryController(policy);

  try {
    while (true) {
      guard.validate();

      const result = await agentExecutor(guard.signal);
      guard.recordIteration();

      if (result.usedTool) {
        guard.recordToolCall();
      }

      if (result.done) {
        break;
      }
    }
  } catch (error) {
    if (error instanceof RuntimeLimitError) {
      console.warn("Execution halted by policy:", error.violations);
      // Trigger fallback routing, state persistence, or user notification
      return;
    }
    throw error;
  }
}

Why This Architecture Works

• Separation of Concerns: The guard handles governance; the agent handles reasoning. This prevents policy logic from polluting business workflows.
• Abort Propagation: Passing the AbortSignal to downstream I/O ensures that pending HTTP requests, database queries, or external tool calls terminate cleanly when limits are breached.
• Typed Violations: Returning structured error metadata enables downstream systems to implement tiered recovery strategies (e.g., switch to a cheaper model, truncate context, or escalate to human review).
• Reset Capability: The reset() method supports batch processing or retry scenarios without instantiating new controllers, reducing memory pressure in high-throughput environments.

Pitfall Guide

1. Hard Timeouts Without Resource Cleanup

Explanation: Using setTimeout or raw AbortController without finally blocks leaves network connections, database transactions, or file handles open. This causes connection pool exhaustion and memory leaks. Fix: Always wrap agent execution in try/finally blocks. Ensure all I/O operations accept abort signals and release resources explicitly. Implement connection pooling with idle timeout configuration.

2. Ignoring Tool Call Velocity

Explanation: Limiting total tool calls does not prevent rapid-fire invocations of a single expensive tool (e.g., web search, code execution). Burst patterns can saturate downstream APIs before the global limit triggers. Fix: Implement per-tool rate limiting alongside global caps. Track invocation frequency using a sliding window counter. Apply exponential backoff when velocity thresholds are approached.

3. Static Limits for Dynamic Workloads

Explanation: Hardcoded thresholds fail when task complexity varies. A simple data extraction task may require 3 steps, while a multi-document synthesis may legitimately need 12. Static limits cause false positives or allow runaway execution on complex tasks. Fix: Use adaptive thresholds based on task classification, input size, or historical telemetry. Implement tiered policies (e.g., simple, standard, complex) selected at runtime via a lightweight classifier or routing layer.

4. Treating Limits as Failures Instead of Signals

Explanation: Throwing unhandled exceptions on limit breach forces the entire workflow to crash. This discards partial results, loses context, and degrades user experience. Fix: Catch RuntimeLimitError explicitly. Persist intermediate state, truncate context to the most recent N turns, and route to a fallback executor. Treat policy enforcement as a control flow signal, not an error condition.

5. Missing Observability Hooks

Explanation: Limits are enforced silently. Teams cannot distinguish between normal termination and policy interruption, making capacity planning and cost attribution impossible. Fix: Emit structured metrics on every limit check. Include tags for policy type, violation reason, task ID, and tenant. Integrate with OpenTelemetry or equivalent tracing systems to correlate limit breaches with downstream latency and error rates.

6. Over-Constraining Early Iterations

Explanation: Aggressive limits in development or staging mask legitimate agent behavior. Engineers tune prompts to satisfy constraints rather than solving the actual problem, creating false confidence. Fix: Use relaxed thresholds in non-production environments. Implement environment-aware policy loading. Log warning-level events when approaching limits instead of hard-failing, allowing teams to calibrate before production deployment.

7. Context Window Blindness

Explanation: Runtime limits track time and steps but ignore token accumulation. Agents can stay within step limits while continuously expanding context, eventually hitting model context windows and triggering silent truncation or API errors. Fix: Monitor token velocity alongside iteration counts. Implement context pruning strategies (e.g., sliding window, summary injection, or relevance scoring) when token count approaches 80% of the model's limit.

Production Bundle

Action Checklist

• Define execution policy: Set maxDurationMs, maxIterations, and maxToolInvocations based on SLA requirements and cost budgets.
• Instrument state tracking: Integrate RuntimeBoundaryController into the agent loop and ensure telemetry updates on every iteration and tool call.
• Implement graceful degradation: Catch RuntimeLimitError and route to fallback handlers, context truncation, or human escalation paths.
• Propagate abort signals: Pass the controller's AbortSignal to all downstream I/O operations to prevent orphaned requests.
• Add observability hooks: Emit metrics and traces on limit checks, violations, and recovery actions. Tag with tenant and task metadata.
• Calibrate thresholds: Run load tests with representative workloads. Adjust limits to balance capability preservation and operational safety.
• Document failure contracts: Define expected behavior when limits are breached. Ensure downstream systems handle partial results and interruption signals correctly.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-volume, low-complexity tasks	Strict static limits with fast fallback	Predictable latency, minimal overhead	Low (reduces wasted inference)
Variable-complexity research workflows	Adaptive thresholds + context pruning	Accommodates legitimate long runs while preventing drift	Medium (requires routing logic)
Multi-tenant SaaS platform	Tenant-aware budgets + per-tool rate limiting	Prevents noisy neighbor issues and cost leakage	High initial setup, long-term savings
Real-time user-facing agents	Low iteration cap + streaming fallback	Maintains UX responsiveness, avoids timeout frustration	Low (improves p95 latency)
Batch processing pipelines	Relaxed limits + async checkpointing	Allows completion of legitimate long jobs with recovery	Medium (storage overhead for checkpoints)

Configuration Template

// runtime-policy.config.ts
import type { ExecutionPolicy } from "./RuntimeBoundaryController";

export const POLICY_PRESETS = {
  development: {
    maxDurationMs: 60_000,
    maxIterations: 25,
    maxToolInvocations: 20,
  } as ExecutionPolicy,

  production: {
    maxDurationMs: 30_000,
    maxIterations: 15,
    maxToolInvocations: 10,
  } as ExecutionPolicy,

  costSensitive: {
    maxDurationMs: 15_000,
    maxIterations: 8,
    maxToolInvocations: 5,
  } as ExecutionPolicy,
} as const;

export function resolvePolicy(
  environment: "development" | "production" | "costSensitive",
  overrides?: Partial<ExecutionPolicy>
): ExecutionPolicy {
  const base = POLICY_PRESETS[environment];
  return { ...base, ...overrides };
}

Quick Start Guide

1. Install dependencies: Ensure your project supports TypeScript 5.0+ and Node.js 18+ (for native AbortController). No external packages are required.
2. Create the controller: Copy the RuntimeBoundaryController and RuntimeLimitError classes into your codebase. Import them into your agent orchestration module.
3. Wrap your execution loop: Replace your existing while or recursive agent loop with the runBoundedAgent pattern. Pass your model executor and tool invoker through the agentExecutor callback.
4. Handle interruption: Add a catch block for RuntimeLimitError. Implement your fallback strategy (context truncation, model downgrade, or user notification). Log the telemetry payload for post-run analysis.
5. Deploy and monitor: Start with development presets. Enable metrics emission. Adjust thresholds based on p95 latency and cost-per-task dashboards. Promote to production presets once stability is validated.