feat(subagent): add outcome-aware escalation policy

Author: bwachman

BUILD_PLAN.md

@@ -77,6 +77,10 @@ import {
   projectWaitStatus,
   type WaitJSONStatus,
 } from "./lifecycle.js";
+import type {
+  EscalationAssessment,
+  VerificationBlockedOutcome,
+} from "./escalation-policy.js";
 import { getProcessAdmissionQueue, type AdmissionQueue } from "./admission.js";
 import type {
   NestedDispatchDeps,
@@ -141,6 +145,8 @@ interface FleetRecord {
   hint?: string;
   question?: string;
   questionId?: string;
+  assessment?: EscalationAssessment;
+  terminalOutcome?: VerificationBlockedOutcome;
   description?: string;
 }
 
@@ -467,7 +473,16 @@ class FleetMailbox {
         ? { recoverableFailure: true }
         : {}),
       ...(ask !== undefined
-        ? { question: ask.question, questionId: ask.questionId }
+        ? {
+            question: ask.question,
+            questionId: ask.questionId,
+            ...(ask.assessment !== undefined
+              ? { assessment: ask.assessment }
+              : {}),
+          }
+        : {}),
+      ...(session?.terminalOutcome !== undefined
+        ? { terminalOutcome: session.terminalOutcome }
         : {}),
       ...(status === "awaiting_director" && session !== undefined
         ? { description: session.description }
@@ -1548,7 +1563,12 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
               : {}),
             persist: deps.persist !== false,
             askDirectorPort: {
-              register: ({ question, questionId, grantRequestId }) => {
+              register: ({
+                question,
+                questionId,
+                assessment,
+                grantRequestId,
+              }) => {
                 const hold: {
                   resolve?: (answer: string) => void;
                   reject?: (reason: unknown) => void;
@@ -1568,6 +1588,7 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
                 const ok = deps.sessions.registerAsk(session.id, {
                   question,
                   questionId,
+                  ...(assessment !== undefined ? { assessment } : {}),
                   ...(grantRequestId !== undefined ? { grantRequestId } : {}),
                   resolve: hold.resolve,
                   reject: hold.reject,

src/subagent/agent-fleet.ts

@@ -1,5 +1,11 @@
 /** ask_director evaluation: pure caps, unit-testable without an agent loop. */
 
+import {
+  decideEscalation,
+  parseEscalationAssessment,
+  type EscalationAssessment,
+} from "./escalation-policy.js";
+
 export const ASK_DIRECTOR_MAX_BYTES = 4096;
 export const ASK_DIRECTOR_MAX_QUESTIONS = 3;
 
@@ -14,13 +20,15 @@ export function createAskDirectorState(): AskDirectorState {
 
 export interface AskDirectorInput {
   question: unknown;
+  escalation?: unknown;
   state: AskDirectorState;
 }
 
 export interface AskDirectorPort {
   register: (input: {
     question: string;
     questionId: string;
+    assessment?: EscalationAssessment;
     grantRequestId?: string;
   }) => Promise<string>;
   cancel: (reason: string) => void;
@@ -31,6 +39,8 @@ export function evaluateAskDirector(input: AskDirectorInput): {
   ok: boolean;
   message: string;
   question?: string;
+  assessment?: EscalationAssessment;
+  continueInternal?: true;
 } {
   if (typeof input.question !== "string") {
     return {
@@ -65,9 +75,29 @@ export function evaluateAskDirector(input: AskDirectorInput): {
       message: `Error: ask_director question cap (${ASK_DIRECTOR_MAX_QUESTIONS}) reached for this turn. No further questions accepted — finish with the markdown report envelope instead.`,
     };
   }
-  // Hold the one-at-a-time lock; count the cap only at commitAskDirector.
+// Direct callers predate the tool schema. The wire schema in run.ts still
+  // requires escalation; this preserves the legacy unit/integration port API.
+  if (input.escalation === undefined) {
+    input.state.pending = true;
+    return { ok: true, message: "ok", question };
+  }
+  const assessment = parseEscalationAssessment(input.escalation);
+  if (assessment instanceof Error) {
+    return { ok: false, message: `Error: ${assessment.message}` };
+  }
+  if (decideEscalation(assessment).kind === "continue_internal") {
+    return {
+      ok: true,
+      message:
+        "Continue with the recorded permitted alternative; do not park or escalate. Report its result in the final outcome.",
+      assessment,
+      continueInternal: true,
+    };
+  }
+  // Reserve the one-at-a-time lock so a parallel ask errors, but do not
+  // consume a cap slot until commitAskDirector (register reached the director).
   input.state.pending = true;
-  return { ok: true, message: "ok", question };
+  return { ok: true, message: "ok", question, assessment };
 }
 
 /** Count the question against the per-turn cap once register will run. */
@@ -110,16 +140,20 @@ export function createDeferredContinuation(): {
 
 export async function handleAskDirector(args: {
   question: unknown;
+  escalation?: unknown;
   grantRequestId?: unknown;
   state: AskDirectorState;
   port: AskDirectorPort;
   signal: AbortSignal;
 }): Promise<string> {
   const outcome = evaluateAskDirector({
     question: args.question,
+    escalation: args.escalation,
     state: args.state,
   });
-  if (!outcome.ok || outcome.question === undefined) return outcome.message;
+  if (!outcome.ok) return outcome.message;
+  if (outcome.continueInternal === true) return outcome.message;
+  if (outcome.question === undefined) return outcome.message;
   try {
     const onAbort = (): void => {
       args.port.cancel("ask_director aborted");
@@ -137,6 +171,9 @@ export async function handleAskDirector(args: {
       const answerP = args.port.register({
         question: outcome.question,
         questionId,
+        ...(outcome.assessment !== undefined
+          ? { assessment: outcome.assessment }
+          : {}),
         ...(grantRequestId !== undefined ? { grantRequestId } : {}),
       });
       if (args.signal.aborted) {

src/subagent/ask-director.ts

@@ -0,0 +1,113 @@
+import { expect, test } from "bun:test";
+
+import {
+  deriveVerificationBlockedOutcome,
+  decideEscalation,
+  parseEscalationAssessment,
+  parseEscalationResolution,
+  renderEscalationDecision,
+} from "./escalation-policy.js";
+
+const assessment = {
+  policyVersion: "1",
+  classification: "operator_decision_required",
+  blockedOutcome: "The authenticated verification result cannot be produced.",
+  unavailableDirectorPath: "The director has no credential authority.",
+  permittedAlternatives: [
+    {
+      attempted: "focused local test",
+      result: "requires the missing credential",
+      comparableConfidence: false,
+    },
+  ],
+  minimumAddition: "Allow an authenticated read-only snapshot.",
+  declineConsequence: "Implementation is complete but verification is blocked.",
+  recommendation: "Decline unless the snapshot is necessary.",
+  safeDefault: "Decline.",
+  requestedMechanism: "broad web access",
+  minimumAuthority: "authenticated read-only snapshot",
+  verification: {
+    verificationOutcome: "integration verification",
+    rootCause: "missing test credential",
+    attemptedNarrowChecks: ["focused local test"],
+    reducedConfidence: "integration behavior remains unverified",
+  },
+} as const;
+
+test("routine alternatives remain internal and never produce a parked directive", () => {
+  const parsed = parseEscalationAssessment({
+    ...assessment,
+    classification: "routine",
+    permittedAlternatives: [
+      {
+        attempted: "focused test",
+        result: "passed",
+        comparableConfidence: true,
+      },
+    ],
+  });
+  expect(parsed).not.toBeInstanceOf(Error);
+  if (parsed instanceof Error) return;
+  expect(decideEscalation(parsed).kind).toBe("continue_internal");
+});
+
+test("decision rendering distinguishes requested mechanism from minimum authority", () => {
+  const parsed = parseEscalationAssessment(assessment);
+  expect(parsed).not.toBeInstanceOf(Error);
+  if (parsed instanceof Error) return;
+  const rendered = renderEscalationDecision({
+    sessionId: "worker-1",
+    questionId: "ask-1",
+    assessment: parsed,
+  });
+  expect(rendered).toContain("Requested mechanism: broad web access");
+  expect(rendered).toContain(
+    "Minimum authority/decision: authenticated read-only snapshot",
+  );
+  expect(rendered).toContain("Decline/proceed-without consequence:");
+});
+
+test("declined verification produces a distinct durable blocked outcome", () => {
+  const parsed = parseEscalationAssessment(assessment);
+  expect(parsed).not.toBeInstanceOf(Error);
+  if (parsed instanceof Error) return;
+  expect(
+    deriveVerificationBlockedOutcome(parsed, {
+      kind: "declined",
+      answer: "No credential grant.",
+    }),
+  ).toMatchObject({
+    kind: "verification_blocked",
+    implementationReviewComplete: true,
+    rootCause: "missing test credential",
+    resolution: "declined",
+  });
+});
+
+test("incomplete material requests are rejected", () => {
+  expect(
+    parseEscalationAssessment({
+      policyVersion: "1",
+      classification: "operator_decision_required",
+    }),
+  ).toBeInstanceOf(Error);
+});
+
+test("structured parent resolution is closed and carries no authority", () => {
+  expect(
+    parseEscalationResolution({
+      kind: "minimum_grant_available",
+      answer: "The minimum decision is available; continue your next turn.",
+    }),
+  ).toEqual({
+    kind: "minimum_grant_available",
+    answer: "The minimum decision is available; continue your next turn.",
+  });
+  expect(
+    parseEscalationResolution({
+      kind: "grant",
+      answer: "retry this command",
+      command: "unsafe",
+    }),
+  ).toBeInstanceOf(Error);
+});