fix(subagent): enforce outcome-aware escalation contract

- ask_director rejects a missing escalation instead of parking on prompt
  prose; the wire schema gains real properties and a classification enum
- terminalOutcome is copied by cloneSession and replaceable only through
  an explicit worker verification report, never by a decision grant
- wait/list JSON expose assessment and terminal_outcome; structured
  resolutions carry questionId and reject stale answers
- declines record a consistent outcome; the renderer bounds each field on
  a character boundary and always keeps the authority and send_input lines
- wake and panel keep the worker question; routine evaluations are
  recorded for audit
- parked classifications require alternative content; recommendation and
  safeDefault are independent; requested mechanism differs from minimum
  authority

Author: bwachman

src/subagent/agent-fleet.ts

@@ -79,7 +79,7 @@ import {
 } from "./lifecycle.js";
 import type {
   EscalationAssessment,
-  VerificationBlockedOutcome,
+  TerminalOutcome,
 } from "./escalation-policy.js";
 import { getProcessAdmissionQueue, type AdmissionQueue } from "./admission.js";
 import type {
@@ -146,7 +146,7 @@ interface FleetRecord {
   question?: string;
   questionId?: string;
   assessment?: EscalationAssessment;
-  terminalOutcome?: VerificationBlockedOutcome;
+  terminalOutcome?: TerminalOutcome;
   description?: string;
 }
 
@@ -1588,7 +1588,7 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
                 const ok = deps.sessions.registerAsk(session.id, {
                   question,
                   questionId,
-                  ...(assessment !== undefined ? { assessment } : {}),
+                  assessment,
                   ...(grantRequestId !== undefined ? { grantRequestId } : {}),
                   resolve: hold.resolve,
                   reject: hold.reject,
@@ -1606,6 +1606,9 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
               cancel: (reason) => {
                 deps.sessions.cancelAsk(session.id, reason);
               },
+              recordRoutineEvaluation: (assessment) => {
+                deps.sessions.recordRoutineEvaluation(session.id, assessment);
+              },
             },
             onAgentReady: ({ close, interrupt, followup, deliver }) => {
               deps.sessions.registerClose(session.id, async (deadlineMs) => {
@@ -1883,6 +1886,12 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
             ...(record.questionId !== undefined
               ? { question_id: record.questionId }
               : {}),
+            ...(record.assessment !== undefined
+              ? { assessment: record.assessment }
+              : {}),
+            ...(record.terminalOutcome !== undefined
+              ? { terminal_outcome: record.terminalOutcome }
+              : {}),
             ...(record.description !== undefined
               ? { description: record.description }
               : {}),
@@ -1915,6 +1924,12 @@ export function createWaitAgentsTool(deps: WaitAgentsDeps): AgentTool {
           ...(record.questionId !== undefined
             ? { question_id: record.questionId }
             : {}),
+          ...(record.assessment !== undefined
+            ? { assessment: record.assessment }
+            : {}),
+          ...(record.terminalOutcome !== undefined
+            ? { terminal_outcome: record.terminalOutcome }
+            : {}),
         };
       });
 
@@ -2024,6 +2039,12 @@ export function createListAgentsTool(deps: WaitAgentsDeps): AgentTool {
           record.questionId !== undefined
             ? { question_id: record.questionId }
             : {}),
+          ...(record?.assessment !== undefined
+            ? { assessment: record.assessment }
+            : {}),
+          ...(record?.terminalOutcome !== undefined
+            ? { terminal_outcome: record.terminalOutcome }
+            : {}),
         };
       });
       if (parked.length > 0) {

src/subagent/ask-director.ts

@@ -20,28 +20,32 @@ export function createAskDirectorState(): AskDirectorState {
 
 export interface AskDirectorInput {
   question: unknown;
-  escalation?: unknown;
+  escalation: unknown;
   state: AskDirectorState;
 }
 
 export interface AskDirectorPort {
   register: (input: {
     question: string;
     questionId: string;
-    assessment?: EscalationAssessment;
+    assessment: EscalationAssessment;
     grantRequestId?: string;
   }) => Promise<string>;
   cancel: (reason: string) => void;
+  /** Routine evaluations are recorded for audit; they never register or wake. */
+  recordRoutineEvaluation?: (assessment: EscalationAssessment) => void;
 }
 
-/** Over-cap / second-ask returns `ok: false` so the worker does not suspend. */
-export function evaluateAskDirector(input: AskDirectorInput): {
-  ok: boolean;
-  message: string;
-  question?: string;
-  assessment?: EscalationAssessment;
-  continueInternal?: true;
-} {
+/** Non-terminal by design: over-cap / second-ask returns `ok: false` so the worker does not suspend. */
+export function evaluateAskDirector(input: AskDirectorInput):
+  | { ok: false; message: string }
+  | {
+      ok: true;
+      message: string;
+      question: string;
+      assessment: EscalationAssessment;
+      continueInternal?: true;
+    } {
   if (typeof input.question !== "string") {
     return {
       ok: false,
@@ -75,11 +79,16 @@ 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.`,
     };
   }
-// Direct callers predate the tool schema. The wire schema in run.ts still
-  // requires escalation; this preserves the legacy unit/integration port API.
+// The policy contract is mandatory at the tool boundary: a worker that
+  // omits `escalation` is rejected and must never park a prompt-prose-only
+  // question. The wire schema also lists these fields, but the local tool
+  // wrapper does no schema validation, so the runtime check is the gate.
   if (input.escalation === undefined) {
-    input.state.pending = true;
-    return { ok: true, message: "ok", question };
+    return {
+      ok: false,
+      message:
+        "Error: ask_director requires escalation (object) with policyVersion, classification, blockedOutcome, unavailableDirectorPath, permittedAlternatives, minimumAddition, and declineConsequence.",
+    };
   }
   const assessment = parseEscalationAssessment(input.escalation);
   if (assessment instanceof Error) {
@@ -90,6 +99,7 @@ export function evaluateAskDirector(input: AskDirectorInput): {
       ok: true,
       message:
         "Continue with the recorded permitted alternative; do not park or escalate. Report its result in the final outcome.",
+      question,
       assessment,
       continueInternal: true,
     };
@@ -152,8 +162,10 @@ export async function handleAskDirector(args: {
     state: args.state,
   });
   if (!outcome.ok) return outcome.message;
-  if (outcome.continueInternal === true) return outcome.message;
-  if (outcome.question === undefined) return outcome.message;
+  if (outcome.continueInternal === true) {
+    args.port.recordRoutineEvaluation?.(outcome.assessment);
+    return outcome.message;
+  }
   try {
     const onAbort = (): void => {
       args.port.cancel("ask_director aborted");
@@ -171,9 +183,7 @@ export async function handleAskDirector(args: {
       const answerP = args.port.register({
         question: outcome.question,
         questionId,
-        ...(outcome.assessment !== undefined
-          ? { assessment: outcome.assessment }
-          : {}),
+        assessment: outcome.assessment,
         ...(grantRequestId !== undefined ? { grantRequestId } : {}),
       });
       if (args.signal.aborted) {

src/subagent/escalation-policy.ts

@@ -40,10 +40,26 @@ export interface EscalationAssessment {
 }
 
 export type EscalationResolution =
-  | { readonly kind: "director_answer"; readonly answer: string }
-  | { readonly kind: "declined"; readonly answer: string }
-  | { readonly kind: "unavailable"; readonly answer: string }
-  | { readonly kind: "minimum_grant_available"; readonly answer: string };
+  | {
+      readonly kind: "director_answer";
+      readonly answer: string;
+      readonly questionId: string;
+    }
+  | {
+      readonly kind: "declined";
+      readonly answer: string;
+      readonly questionId: string;
+    }
+  | {
+      readonly kind: "unavailable";
+      readonly answer: string;
+      readonly questionId: string;
+    }
+  | {
+      readonly kind: "minimum_grant_available";
+      readonly answer: string;
+      readonly questionId: string;
+    };
 
 export type EscalationDirective =
   | {
@@ -63,15 +79,42 @@ export interface VerificationBlockedOutcome {
   readonly recommendation?: string;
 }
 
+/** A decline/unavailability on a non-verification ask still records an outcome. */
+export interface DeclinedOutcome {
+  readonly kind: "declined";
+  readonly resolution: "declined" | "unavailable";
+  readonly declineConsequence: string;
+  readonly recommendation?: string;
+}
+
+/** Explicit worker-reported successful verification replaces a blocked outcome. */
+export interface VerifiedOutcome {
+  readonly kind: "verified";
+  readonly verificationOutcome: string;
+}
+
+export type TerminalOutcome =
+  | VerificationBlockedOutcome
+  | DeclinedOutcome
+  | VerifiedOutcome;
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 const nonEmpty = (value: unknown): value is string =>
   typeof value === "string" && value.trim().length > 0;
+/** Byte-bounded on a character boundary so a slice never splits a code point. */
 const bounded = (value: string): string => {
-  const encoded = new TextEncoder().encode(value);
-  return encoded.byteLength <= ESCALATION_TEXT_MAX_BYTES
-    ? value
-    : new TextDecoder().decode(encoded.slice(0, ESCALATION_TEXT_MAX_BYTES));
+  if (new TextEncoder().encode(value).byteLength <= ESCALATION_TEXT_MAX_BYTES)
+    return value;
+  let kept = "";
+  let bytes = 0;
+  for (const ch of Array.from(value)) {
+    const size = new TextEncoder().encode(ch).byteLength;
+    if (bytes + size > ESCALATION_TEXT_MAX_BYTES) break;
+    kept += ch;
+    bytes += size;
+  }
+  return kept;
 };
 const text = (value: unknown, field: string): string | Error =>
   nonEmpty(value)
@@ -90,10 +133,15 @@ export function parseEscalationResolution(
     kind !== "unavailable" &&
     kind !== "minimum_grant_available"
   ) {
-    return new Error("resolution.kind is invalid.");
+    return new Error(
+      "resolution.kind must be one of: director_answer, declined, unavailable, minimum_grant_available.",
+    );
   }
+  const questionId = text(raw.questionId, "resolution.questionId");
+  if (questionId instanceof Error) return questionId;
   const answer = text(raw.answer, "resolution.answer");
-  return answer instanceof Error ? answer : { kind, answer };
+  if (answer instanceof Error) return answer;
+  return { kind, answer, questionId };
 }
 
 /** Validates tool-boundary data before it can create a parked parent ask. */
@@ -153,6 +201,14 @@ export function parseEscalationAssessment(
       comparableConfidence: alternative.comparableConfidence,
     });
   }
+  // Fact 3 content is mandatory for every parked/surfaced classification:
+  // an empty alternatives list would let a worker park without showing the
+  // permitted paths already considered. `routine` instead requires a
+  // comparable alternative below.
+  if (classification !== "routine" && alternatives.length === 0)
+    return new Error(
+      "parked escalation requires at least one permitted alternative considered.",
+    );
   const optionalText = (field: string): string | Error | undefined =>
     raw[field] === undefined ? undefined : text(raw[field], field);
   const requestedMechanism = optionalText("requestedMechanism");
@@ -170,9 +226,13 @@ export function parseEscalationAssessment(
   const minimumAuthorityValue = minimumAuthority as string | undefined;
   const recommendationValue = recommendation as string | undefined;
   const safeDefaultValue = safeDefault as string | undefined;
-  if ((recommendation === undefined) !== (safeDefault === undefined))
+  if (
+    requestedMechanismValue !== undefined &&
+    minimumAuthorityValue !== undefined &&
+    requestedMechanismValue === minimumAuthorityValue
+  )
     return new Error(
-      "escalation recommendation and safeDefault must be provided together when asserted.",
+      "escalation.requestedMechanism must differ from minimumAuthority.",
     );
   if (
     (classification === "operator_decision_required" ||
@@ -239,10 +299,10 @@ export function parseEscalationAssessment(
       ? { minimumAuthority: minimumAuthorityValue }
       : {}),
     ...(recommendationValue !== undefined
-      ? {
-          recommendation: recommendationValue,
-          safeDefault: safeDefaultValue as string,
-        }
+      ? { recommendation: recommendationValue }
+      : {}),
+    ...(safeDefaultValue !== undefined
+      ? { safeDefault: safeDefaultValue }
       : {}),
     ...(verification !== undefined ? { verification } : {}),
   };
@@ -281,6 +341,30 @@ export const deriveVerificationBlockedOutcome = (
   };
 };
 
+/**
+ * Records a consistent decline/unavailability outcome for every ask. A
+ * verification ask derives the typed `verification_blocked` outcome; any other
+ * parked ask records the decline consequence so a structured decline can never
+ * settle silently.
+ */
+export const deriveTerminalOutcome = (
+  assessment: EscalationAssessment,
+  resolution: EscalationResolution,
+): TerminalOutcome | undefined => {
+  if (resolution.kind !== "declined" && resolution.kind !== "unavailable")
+    return undefined;
+  if (assessment.verification !== undefined)
+    return deriveVerificationBlockedOutcome(assessment, resolution);
+  return {
+    kind: "declined",
+    resolution: resolution.kind,
+    declineConsequence: assessment.declineConsequence,
+    ...(assessment.recommendation !== undefined
+      ? { recommendation: assessment.recommendation }
+      : {}),
+  };
+};
+
 /** Stable parent-facing text. It carries facts only; it cannot convey authority. */
 export const renderEscalationDecision = (input: {
   sessionId: string;
@@ -297,19 +381,22 @@ export const renderEscalationDecision = (input: {
               `${alternative.attempted}: ${alternative.result} (${alternative.comparableConfidence ? "comparable" : "not comparable"})`,
           )
           .join("; ");
-  return bounded(
-    [
-      `Worker decision required (${a.classification})`,
-      `Target: ${input.sessionId} / ${input.questionId}`,
-      `Blocked outcome/verification: ${a.blockedOutcome}`,
-      `Unavailable director path: ${a.unavailableDirectorPath}`,
-      `Permitted alternatives considered: ${alternatives}`,
-      `Minimum addition: ${a.minimumAddition}`,
-      `Decline/proceed-without consequence: ${a.declineConsequence}`,
-      `Safe default/recommendation: ${a.recommendation ?? "none recorded"}`,
-      `Requested mechanism: ${a.requestedMechanism ?? "none recorded"}`,
-      `Minimum authority/decision: ${a.minimumAuthority ?? "none recorded"}`,
-      "Reply with send_input (plain text or a structured resolution); this does not grant or retry a tool.",
-    ].join("\n"),
-  );
+  // Bound every field on its own (character-boundary) so a long field can
+  // never truncate the mechanism-vs-authority separation or the send_input
+  // instruction that follow it.
+  const field = (label: string, value: string): string =>
+    `${label} ${bounded(value)}`;
+  return [
+    `Worker decision required (${a.classification})`,
+    `Target: ${input.sessionId} / ${input.questionId}`,
+    field("Blocked outcome/verification:", a.blockedOutcome),
+    field("Unavailable director path:", a.unavailableDirectorPath),
+    field("Permitted alternatives considered:", alternatives),
+    field("Minimum addition:", a.minimumAddition),
+    field("Decline/proceed-without consequence:", a.declineConsequence),
+    field("Safe default/recommendation:", a.recommendation ?? "none recorded"),
+    field("Requested mechanism:", a.requestedMechanism ?? "none recorded"),
+    field("Minimum authority/decision:", a.minimumAuthority ?? "none recorded"),
+    "Reply with send_input (plain text or a structured resolution); this does not grant or retry a tool.",
+  ].join("\n");
 };