Error Escalation

Not every error is fixable by Claude. A missing environment variable, a network-dependent API failure, a dependency version conflict, or a fundamental architectural constraint cannot be resolved by editing source code. The quality loop needs an escalation path for errors that exceed Claude's resolution capability.

Escalation tiers mirror the error recovery pattern from skill design. Tier 1: Claude attempts to fix the error autonomously within the quality loop — this handles the vast majority of type errors, lint violations, and test failures. Tier 2: Claude cannot fix the error after three attempts, so the hook pauses the loop and presents the user with a structured escalation report: what was attempted, what failed, what the remaining error is, and a suggested course of action. Tier 3: the error is in infrastructure (missing env var, wrong Node version, broken dependency) — the hook detects the error category and provides a specific remediation command rather than asking Claude to fix code.

Implementing Tier 3 requires error classification in your hook script. Parse the error output and categorize it. TypeScript errors (error TS followed by a number) are Tier 1 — Claude can fix them. Missing module errors ("Cannot find module") might be Tier 1 (wrong import path) or Tier 3 (missing dependency — run npm install). Environment errors ("EACCES," "ENOENT," "ECONNREFUSED") are Tier 3 — they require system changes, not code changes.

The classification does not need to be perfect. It needs to catch the obvious infrastructure errors that would otherwise trap Claude in a fix loop. A hook that recognizes "ECONNREFUSED" and tells the user "The database connection was refused — verify that the database server is running" saves more time than a hook that asks Claude to fix a network error by editing TypeScript.