feat: add deterministic escalation policy and explain evidence (#16)

* feat: add deterministic escalation policy and explain evidence

* fix: address PR review comments on escalation policy constants

* docs: link release-log entry to PR #16

---------

Co-authored-by: Hanna Rosengren <4538260+hannasoderstromdev@users.noreply.github.com>

Author: hannasdev

docs/release-log.md

@@ -1,5 +1,13 @@
 ## Unreleased
 
+### 2026-05-10 — Add deterministic escalation policy and escalation evidence in explain output
+
+- What changed: Added explicit escalation policy handling for low-confidence turns, user corrections, repeated failures, and high-risk implementation; propagated escalation fields into route evidence and human explain output.
+- Why it matters: Makes routing behavior less implicit and easier to audit by showing why a stronger target was selected.
+- Who is affected: Switchboard users and maintainers reviewing route decisions.
+- Action needed: None.
+- PR: https://github.com/hannasdev/model-switchboard/pull/16
+
 ### 2026-05-10 — Harden CI security defaults and supply-chain hygiene
 
 - What changed: Added a security policy and CODEOWNERS, introduced Dependabot updates, tightened GitHub Actions permissions, and pinned core GitHub Actions to immutable SHAs.

src/router/data/fixtures.json

@@ -103,7 +103,7 @@
     "session": { "mode": "plan", "cost_posture": "balanced" },
     "expected": {
       "mode": "plan",
-      "label": "balanced",
+      "label": "best coder",
       "requiredCapabilities": ["chat", "reasoning", "structured_output"],
       "explanationIncludes": ["planning/tradeoff analysis"],
       "classificationReason": "user_correction_signal"

src/router/router.js

@@ -34,6 +34,8 @@ const LABEL_TO_CLASS_RANK = {
   "best coder": 4
 };
 
+const LOW_CONFIDENCE_THRESHOLD = 0.7;
+
 const PRIVACY_TIER_RANK = {
   external: 1,
   standard: 2,
@@ -276,6 +278,84 @@ function buildConstraintInputs(session = {}) {
   };
 }
 
+function strongerClass(currentClass, candidateClass) {
+  const currentRank = LABEL_TO_CLASS_RANK[CLASS_TO_LABEL[currentClass]] || 0;
+  const candidateRank = LABEL_TO_CLASS_RANK[CLASS_TO_LABEL[candidateClass]] || 0;
+  return candidateRank > currentRank ? candidateClass : currentClass;
+}
+
+function preferredLabelOrderFor(desiredLabel) {
+  let fallbackOrder;
+  if (desiredLabel === "best coder") {
+    fallbackOrder = ["best coder", "deep reasoning", "balanced", "quick"];
+  } else if (desiredLabel === "deep reasoning") {
+    fallbackOrder = ["deep reasoning", "best coder", "balanced", "quick"];
+  } else if (desiredLabel === "quick") {
+    fallbackOrder = ["quick", "balanced", "deep reasoning", "best coder"];
+  } else {
+    fallbackOrder = ["balanced", "deep reasoning", "best coder", "quick"];
+  }
+
+  return [desiredLabel, ...fallbackOrder.filter((label) => label !== desiredLabel)];
+}
+
+function resolveEscalationPolicy({ classification = {}, session = {}, mode }) {
+  let desiredClass = MODE_TO_CLASS[mode] || "medium_reasoning";
+  const reasons = [];
+
+  const lowConfidence = Number(classification.confidence || 0) < LOW_CONFIDENCE_THRESHOLD;
+  const userCorrection = classification.reason === "user_correction_signal";
+  const repeatedFailures =
+    Number(session?.failureSignals?.recentToolFailures || 0) +
+      Number(session?.failureSignals?.recentTestFailures || 0) >=
+    2;
+  const highRiskImplementation = mode === "implement" && session.riskLevel === "high";
+
+  if (userCorrection) {
+    desiredClass = strongerClass(desiredClass, "strong_reasoning");
+    reasons.push("user_correction");
+  }
+
+  if (repeatedFailures && mode !== "summarize") {
+    const repeatedFailureClass = ["implement", "debug"].includes(mode)
+      ? "strong_coding"
+      : "strong_reasoning";
+    desiredClass = strongerClass(desiredClass, repeatedFailureClass);
+    reasons.push("repeated_failures");
+  }
+
+  if (highRiskImplementation) {
+    desiredClass = strongerClass(desiredClass, "strong_coding");
+    reasons.push("high_risk_implementation");
+  }
+
+  if (lowConfidence && ["implement", "debug", "review"].includes(mode)) {
+    const lowConfidenceClass = mode === "review" ? "strong_reasoning" : "strong_coding";
+    desiredClass = strongerClass(desiredClass, lowConfidenceClass);
+    reasons.push("low_confidence");
+  }
+
+  if (classification.escalate) {
+    const escalatedClass = strongerClass(desiredClass, classification.escalate);
+    if (escalatedClass !== desiredClass) {
+      desiredClass = escalatedClass;
+      reasons.push("classification_escalation");
+    }
+  }
+
+  return {
+    applied: reasons.length > 0,
+    reasons,
+    desiredClass,
+    signals: {
+      lowConfidence,
+      userCorrection,
+      repeatedFailures,
+      highRiskImplementation
+    }
+  };
+}
+
 function describeCurrentTargetStatus({ session, targets = [], eligible = [], blocked = [] }) {
   const currentTargetId = session.currentTargetId || null;
   if (!currentTargetId) {
@@ -440,7 +520,8 @@ export function routePrompt({
   const modeResolution = resolveSessionMode(session, classification);
   const mode = modeResolution.resolvedMode;
   const requiredCapabilities = buildRequiredCapabilities(mode, classification.taskType);
-  const desiredClass = classification.escalate || MODE_TO_CLASS[mode] || "medium_reasoning";
+  const escalationPolicy = resolveEscalationPolicy({ classification, session, mode });
+  const desiredClass = escalationPolicy.desiredClass;
   const projectOverrideLabel = resolveProjectOverrideLabel(session, mode);
   const desiredLabel = projectOverrideLabel || CLASS_TO_LABEL[desiredClass] || "balanced";
 
@@ -461,7 +542,7 @@ export function routePrompt({
   }
 
   const overrideSelection = applyRoutingOverride({ eligible, desiredLabel, session, targets, blocked });
-  const preferredOrder = [desiredLabel, "balanced", "deep reasoning", "best coder", "quick"];
+  const preferredOrder = preferredLabelOrderFor(desiredLabel);
   const preferredTarget = overrideSelection.target || selectByLabelPriority(eligible, preferredOrder);
   const continuitySelection = applyContinuitySwitchPolicy({
     selectedTarget: preferredTarget,
@@ -491,6 +572,7 @@ export function routePrompt({
       classification,
       modeResolution,
       policyInputs: constraintInputs,
+      escalationPolicy,
       routingOverride: {
         requested: overrideSelection.override,
         applied: overrideSelection.overrideApplied,
@@ -514,6 +596,10 @@ export function routePrompt({
   if (requiredCapabilities.includes("file_edit")) whyParts.push("repo edits");
   if (requiredCapabilities.includes("test_execution")) whyParts.push("test execution");
 
+  if (escalationPolicy.applied) {
+    whyParts.push(`escalation(${escalationPolicy.reasons.join(",")})`);
+  }
+
   return {
     status: "ok",
     action,
@@ -529,6 +615,7 @@ export function routePrompt({
     classification,
     modeResolution,
     policyInputs: constraintInputs,
+    escalationPolicy,
     routingOverride: {
       requested: overrideSelection.override,
       applied: overrideSelection.overrideApplied,

src/switchboard/cli.js

@@ -68,6 +68,10 @@ function printHumanExplain(explanation, stdout) {
   stdout.write(`Claude session: ${explanation.selectedClaude?.sessionId || "unknown"}\n`);
   stdout.write(`Claude target: ${explanation.selectedClaude?.model || "unknown"}/${explanation.selectedClaude?.effort || "unknown"}\n`);
   stdout.write(`Route: ${explanation.routeDecision?.label || "unknown"} (${explanation.routeDecision?.mode || "unknown"})\n`);
+  const escalation = explanation.routeDecision?.escalationPolicy;
+  if (escalation?.applied && Array.isArray(escalation.reasons) && escalation.reasons.length > 0) {
+    stdout.write(`Escalation: ${escalation.reasons.join(",")}\n`);
+  }
   stdout.write(`Route context: ${explanation.routeContext.status}\n`);
   stdout.write(`Hook events: ${explanation.hookEvents.length}\n`);
   for (const event of explanation.hookEvents) {

src/switchboard/workflow.js

@@ -85,6 +85,7 @@ function routeDecisionSummary(plan) {
     routingOverride: route.routingOverride || null,
     modeResolution: route.modeResolution || null,
     policyInputs: route.policyInputs || null,
+    escalationPolicy: route.escalationPolicy || null,
     explanation: route.explanation || null
   };
 }

test/router.test.js

@@ -277,3 +277,105 @@ test("stay override reports hard constraint blockers for ineligible current targ
   assert.equal(result.routingOverride.applied, false);
   assert.equal(result.routingOverride.reason, "current_target_blocked_by_hard_constraints");
 });
+
+test("low confidence escalates review routing", () => {
+  const result = routePrompt({
+    input: "Could you sanity check this?",
+    session: {
+      mode: "review"
+    },
+    targets: openaiTargets,
+    executionSupported: false
+  });
+
+  assert.equal(result.status, "ok");
+  assert.equal(result.mode, "review");
+  assert.equal(result.escalationPolicy.applied, true);
+  assert.equal(result.escalationPolicy.reasons.includes("low_confidence"), true);
+  assert.equal(result.selectedTarget?.label, "best coder");
+});
+
+test("repeated failures trigger escalation", () => {
+  const result = routePrompt({
+    input: "Plan the rollout in phases with tradeoffs.",
+    session: {
+      mode: "plan",
+      failureSignals: {
+        recentToolFailures: 1,
+        recentTestFailures: 2
+      }
+    },
+    targets: openaiTargets,
+    executionSupported: false
+  });
+
+  assert.equal(result.status, "ok");
+  assert.equal(result.escalationPolicy.applied, true);
+  assert.equal(result.escalationPolicy.reasons.includes("repeated_failures"), true);
+  assert.equal(result.selectedTarget?.label, "best coder");
+});
+
+test("user correction trigger is explicit in escalation policy", () => {
+  const result = routePrompt({
+    input: "That is a wrong assumption. Compare alternatives again.",
+    session: {
+      mode: "plan"
+    },
+    targets: openaiTargets,
+    executionSupported: false
+  });
+
+  assert.equal(result.status, "ok");
+  assert.equal(result.escalationPolicy.applied, true);
+  assert.equal(result.escalationPolicy.reasons.includes("user_correction"), true);
+  assert.equal(result.escalationPolicy.reasons.includes("classification_escalation"), false);
+  assert.equal(result.selectedTarget?.label, "best coder");
+});
+
+test("high-risk implementation is explicitly escalated", () => {
+  const result = routePrompt({
+    input: "Implement the plan.",
+    session: {
+      mode: "plan",
+      riskLevel: "high"
+    },
+    targets: openaiTargets,
+    executionSupported: false
+  });
+
+  assert.equal(result.status, "ok");
+  assert.equal(result.mode, "implement");
+  assert.equal(result.escalationPolicy.applied, true);
+  assert.equal(result.escalationPolicy.reasons.includes("high_risk_implementation"), true);
+  assert.equal(result.selectedTarget?.label, "best coder");
+});
+
+test("project override custom forceLabel is prioritized before fallback labels", () => {
+  const balancedTarget = openaiTargets.find((target) => target.label === "balanced");
+  assert.ok(balancedTarget, "expected balanced target fixture");
+
+  const targets = [
+    {
+      ...balancedTarget,
+      id: "custom-team-default",
+      label: "team-default"
+    },
+    ...openaiTargets
+  ];
+
+  const result = routePrompt({
+    input: "Plan the rollout in phases with tradeoffs.",
+    session: {
+      mode: "plan",
+      projectOverride: {
+        forceLabel: "team-default"
+      }
+    },
+    targets,
+    executionSupported: false
+  });
+
+  assert.equal(result.status, "ok");
+  assert.equal(result.selectedTarget?.id, "custom-team-default");
+  assert.equal(result.selectedTarget?.label, "team-default");
+});

test/switchboard-cli.test.js

@@ -82,7 +82,7 @@ test("switchboard explain summarizes latest route context and hook events", () =
       paths.logPath,
       "--route-context-path",
       paths.routeContextPath,
-      "Implement the plan."
+      "That is a wrong assumption. Compare alternatives again."
     ],
     turnIo
   );
@@ -124,6 +124,7 @@ test("switchboard explain summarizes latest route context and hook events", () =
 
   assert.equal(exitCode, 0);
   assert.match(explainIo.stdoutText, /Route: best coder/);
+  assert.match(explainIo.stdoutText, /Escalation: .*user_correction/);
   assert.match(explainIo.stdoutText, /Route context: matched/);
   assert.match(explainIo.stdoutText, /Hook events: 1/);
   assert.match(explainIo.stdoutText, /PreToolUse correlation=matched allow/);

test/switchboard-workflow.test.js

@@ -43,6 +43,7 @@ test("Switchboard turn plans Claude launch and records separable evidence", () =
   assert.equal(result.routeDecision.continuityCost, "low");
   assert.equal(result.routeDecision.modeResolution.resolvedMode, "implement");
   assert.equal(result.routeDecision.policyInputs.hardConstraints.privacy, "off");
+  assert.deepEqual(result.routeDecision.escalationPolicy?.reasons, []);
   assert.equal(result.selectedClaude.model, "sonnet");
   assert.equal(result.selectedClaude.effort, "high");
   assert.equal(result.selectedClaude.sessionId, "claude-session-1");
@@ -55,6 +56,7 @@ test("Switchboard turn plans Claude launch and records separable evidence", () =
   assert.equal(entry.userPrompt, "Implement the plan.");
   assert.equal(entry.wrapperContext.kind, "switchboard_context");
   assert.equal(entry.routeDecision.label, "best coder");
+  assert.deepEqual(entry.routeDecision.escalationPolicy?.reasons, []);
   assert.equal(entry.selectedClaude.effort, "high");
   assert.equal(entry.session.claudeSessionId, "claude-session-1");
 
@@ -64,6 +66,28 @@ test("Switchboard turn plans Claude launch and records separable evidence", () =
   assert.equal(routeContext["claude-session-1"].latest.model, "sonnet");
 });
 
+test("Switchboard logs escalation policy details for escalated turns", () => {
+  const { storePath, logPath, routeContextPath } = tempPaths();
+  const result = planSwitchboardTurn({
+    input: "That is a wrong assumption. Compare alternatives again.",
+    threadId: "thread-escalation",
+    sessionId: "claude-session-escalation",
+    cwd: "/repo",
+    storePath,
+    logPath,
+    routeContextPath
+  });
+
+  assert.equal(result.status, "planned");
+  assert.equal(result.routeDecision.label, "best coder");
+  assert.equal(result.routeDecision.escalationPolicy?.applied, true);
+  assert.equal(result.routeDecision.escalationPolicy?.reasons.includes("user_correction"), true);
+
+  const [entry] = readLog(logPath);
+  assert.equal(entry.routeDecision.escalationPolicy?.applied, true);
+  assert.equal(entry.routeDecision.escalationPolicy?.reasons.includes("user_correction"), true);
+});
+
 test("Switchboard continuity probe preserves Claude session while route changes", () => {
   const { storePath, logPath, routeContextPath } = tempPaths();
   const result = planSwitchboardContinuityProbe({