@tech-leads-club/harness-toolkit 0.2.1

package/src/core/ship/ship.service.ts

@@ -0,0 +1,137 @@
+import type { Decision } from "../../contracts/decision.ts";
+import { isUnderCodePaths } from "../policy/policy.loader.ts";
+import { hasRecentEvidence } from "./ship.ledger.ts";
+import type { ShipClaim } from "./ship.types.ts";
+
+const STRUCTURED = /(?:^|\n)\s*HARNESS_SHIP_CLAIM:\s*(.+?)\s*(?=\n|$)/;
+
+export function detectShipClaim(text: string): ShipClaim | null {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const structured = trimmed.match(STRUCTURED);
+  const body = structured?.[1]?.trim();
+  if (!body) {
+    return null;
+  }
+  return {
+    kind: "structured",
+    snippet: `HARNESS_SHIP_CLAIM: ${body}`.slice(0, 280),
+  };
+}
+
+export function pathExcluded(relativePath: string, excludes: string[]): boolean {
+  const norm = relativePath.replace(/\\/g, "/");
+  for (const raw of excludes) {
+    const pattern = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!pattern) {
+      continue;
+    }
+    if (pattern.endsWith("/**")) {
+      const base = pattern.slice(0, -3);
+      if (norm === base || norm.startsWith(`${base}/`)) {
+        return true;
+      }
+      continue;
+    }
+    if (pattern.endsWith("/")) {
+      if (norm.startsWith(pattern) || norm.startsWith(`${pattern.slice(0, -1)}/`)) {
+        return true;
+      }
+      continue;
+    }
+    if (pattern.includes("*")) {
+      const re = new RegExp(
+        `^${pattern
+          .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+          .replace(/\*\*/g, ".*")
+          .replace(/\*/g, "[^/]*")}$`,
+      );
+      if (re.test(norm)) {
+        return true;
+      }
+      continue;
+    }
+    if (norm === pattern || norm.startsWith(`${pattern}/`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function touchesRuntime(relativePaths: string[], prefixes: string[], excludes: string[]): boolean {
+  return relativePaths.some((path) => {
+    if (pathExcluded(path, excludes)) {
+      return false;
+    }
+    return isUnderCodePaths(path, prefixes) || /^Dockerfile(\.|$)/.test(path);
+  });
+}
+
+export function recentShipClaimActive(
+  lastShipClaimAt: string | undefined,
+  windowMinutes: number,
+  now = Date.now(),
+): boolean {
+  if (!lastShipClaimAt) {
+    return false;
+  }
+  const at = Date.parse(lastShipClaimAt);
+  if (Number.isNaN(at)) {
+    return false;
+  }
+  return now - at < windowMinutes * 60 * 1000;
+}
+
+export function evaluateEmptyDiffAntiShip(args: {
+  enabled: boolean;
+  recentShipClaim: boolean;
+  changedFilesCount: number;
+}): Decision {
+  if (args.enabled && args.recentShipClaim && args.changedFilesCount === 0) {
+    return {
+      kind: "continue",
+      text: [
+        "BLOCKED: HARNESS_SHIP_CLAIM with no file diff.",
+        "TRIED: inspected git working tree / changed files.",
+        "NEED: either implement the remaining work or remove the ship claim — do not claim ship on an empty diff.",
+      ].join("\n"),
+    };
+  }
+  return { kind: "abstain" };
+}
+
+export function evaluateShipEvidenceGate(args: {
+  enabled: boolean;
+  recentShipClaim: boolean;
+  changedFiles: string[];
+  runtimePathPrefixes: string[];
+  runtimePathExcludes: string[];
+  evidenceDir: string | null;
+  evidenceMaxAgeHours: number;
+  /** Newest mtime among the turn's changed code files. Evidence written before it certifies an older tree. */
+  evidenceNotBeforeMs?: number;
+}): Decision {
+  if (!args.enabled || !args.recentShipClaim || args.changedFiles.length === 0) {
+    return { kind: "abstain" };
+  }
+  if (!touchesRuntime(args.changedFiles, args.runtimePathPrefixes, args.runtimePathExcludes)) {
+    return { kind: "abstain" };
+  }
+  const hasEvidence =
+    args.evidenceDir !== null &&
+    hasRecentEvidence(args.evidenceDir, args.evidenceMaxAgeHours, args.evidenceNotBeforeMs);
+  if (hasEvidence) {
+    return { kind: "abstain" };
+  }
+  return {
+    kind: "continue",
+    text: [
+      "BLOCKED: HARNESS_SHIP_CLAIM without recent production PASS evidence.",
+      `TRIED: checked ${args.evidenceDir ?? "(no evidenceDir configured)"}/*/90-verdict.txt.`,
+      // why: producer form. It names the move to make rather than the move to avoid.
+      "NEED: run the verification after the last code change, then cite the verdict path — evidence written before the change certifies the older tree.",
+    ].join("\n"),
+  };
+}

package/src/core/ship/ship.types.ts

@@ -0,0 +1,19 @@
+export type ShipClaimKind = "structured";
+
+export type ShipClaim = {
+  kind: ShipClaimKind;
+  snippet: string;
+};
+
+export type ShipLedgerEvent = "claim" | "challenge" | "pass";
+
+export type ShipLedgerRow = {
+  ts: string;
+  provider: string;
+  event: ShipLedgerEvent;
+  claimKind?: ShipClaimKind;
+  gate?: "ship" | "empty-diff";
+  files?: string[];
+  evidenceDir?: string | null;
+  detail?: string;
+};

package/src/core/stagnation/stagnation.resolution.ts

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectStateDir } from "../../platform/paths.ts";
+
+/**
+ * The harness computes an identity for a failure, counts its repeats to detect stagnation, and used to delete the
+ * record at the exact moment the gate went green — destroying the pairing of *that failure* with *what resolved
+ * it*. That pairing is the one thing nothing else has, because nothing else holds a failure fingerprint and the
+ * diff in the same process ([/decisions/ad-028.md](/decisions/ad-028.md)).
+ *
+ * invariant: this is history, never instruction. AD-024 established that a plan names files from evidence and
+ * never from proximity; a previous resolution is evidence, and presenting it as "edit these" would reintroduce
+ * exactly the harm that decision removed.
+ */
+export type Resolution = {
+  /** Files that changed between the failing state and the passing one. */
+  files: string[];
+  /** ISO timestamp of the resolution, so the most recent one wins when a fingerprint is resolved twice. */
+  at: string;
+  /** How the gate was named when it failed, so a reader knows which gate this history belongs to. */
+  gate: string;
+};
+
+export type ResolutionStore = Record<string, Resolution>;
+
+/**
+ * why: bounded because this file is read on the failure path, which runs while an operator waits. The bound is
+ * applied by dropping the oldest resolutions, so a long-lived repository keeps the recent ones rather than the
+ * first ones it ever saw.
+ */
+export const MAX_RESOLUTIONS = 200;
+
+/** why: at most eight, matching the plan's own file-list cap. A longer list stops being a lead and becomes noise. */
+export const MAX_FILES_PER_RESOLUTION = 8;
+
+function storePath(root: string): string {
+  return join(projectStateDir(root), "fingerprint-resolutions.json");
+}
+
+export function readResolutions(root: string): ResolutionStore {
+  const path = storePath(root);
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as ResolutionStore;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function prune(store: ResolutionStore): ResolutionStore {
+  const entries = Object.entries(store);
+  if (entries.length <= MAX_RESOLUTIONS) {
+    return store;
+  }
+  const kept = entries.sort((a, b) => b[1].at.localeCompare(a[1].at)).slice(0, MAX_RESOLUTIONS);
+  return Object.fromEntries(kept);
+}
+
+export function recordResolution(root: string, fingerprint: string, resolution: Resolution): ResolutionStore {
+  const store = readResolutions(root);
+  store[fingerprint] = {
+    ...resolution,
+    files: resolution.files.slice(0, MAX_FILES_PER_RESOLUTION),
+  };
+  const pruned = prune(store);
+  try {
+    mkdirSync(projectStateDir(root), { recursive: true });
+    writeFileSync(storePath(root), `${JSON.stringify(pruned, null, 2)}\n`, "utf8");
+  } catch {}
+  return pruned;
+}
+
+export function resolutionFor(root: string, fingerprint: string): Resolution | null {
+  return readResolutions(root)[fingerprint] ?? null;
+}
+
+/**
+ * invariant: past tense, and no imperative. The wording is the whole safeguard here — the same list phrased as an
+ * instruction would send an agent to edit files that may be irrelevant this time, which is the AD-021 and AD-024
+ * harm arriving through a third door.
+ */
+export function resolutionHistoryLine(resolution: Resolution): string {
+  return `History: this same ${resolution.gate} failure was resolved once before, after changes to ${resolution.files.join(", ")}. That is a record of what happened, not a list to edit — confirm it against this failure before acting on it.`;
+}

package/src/core/stagnation/stagnation.service.ts

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+
+export function computeFingerprint(parts: {
+  files: string[];
+  gate: string;
+  exitCode: number;
+  output: string;
+}): string {
+  const normalizedOutput = parts.output
+    .replace(/\d{4}-\d{2}-\d{2}T[\d:.]+Z/g, "<ts>")
+    .replace(/\b\d{5,}\b/g, "<n>")
+    .slice(0, 1500);
+  const raw = JSON.stringify({
+    files: [...parts.files].sort(),
+    gate: parts.gate,
+    exitCode: parts.exitCode,
+    output: normalizedOutput,
+  });
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}

package/src/core/stagnation/stagnation.store.ts

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectStateDir } from "../../platform/paths.ts";
+import type { FingerprintStore } from "./stagnation.types.ts";
+
+function storePath(root: string): string {
+  return join(projectStateDir(root), "fingerprint.json");
+}
+
+function readStore(root: string): FingerprintStore {
+  const path = storePath(root);
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as FingerprintStore;
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(root: string, store: FingerprintStore): void {
+  try {
+    mkdirSync(projectStateDir(root), { recursive: true });
+    writeFileSync(storePath(root), `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  } catch {}
+}
+
+export function trackFingerprint(root: string, sessionKey: string, fingerprint: string): number {
+  const store = readStore(root);
+  const current = store[sessionKey] ?? { hits: 0 };
+  const next =
+    current.last === fingerprint
+      ? { last: fingerprint, hits: current.hits + 1 }
+      : { last: fingerprint, hits: 1 };
+  store[sessionKey] = next;
+  writeStore(root, store);
+  return next.hits;
+}
+
+export function fingerprintHits(root: string, sessionKey: string): number {
+  return readStore(root)[sessionKey]?.hits ?? 0;
+}
+
+export function clearFingerprint(root: string, sessionKey: string): void {
+  const store = readStore(root);
+  store[sessionKey] = { hits: 0 };
+  writeStore(root, store);
+}

package/src/core/stagnation/stagnation.types.ts

@@ -0,0 +1,12 @@
+export type FingerprintEntry = {
+  last?: string;
+  hits: number;
+};
+
+export type FingerprintStore = Record<string, FingerprintEntry>;
+
+export const STAGNATION_FOLLOWUP = [
+  "BLOCKED: identical validation fingerprint repeated — no progress between attempts.",
+  "TRIED: same gate failure signature as the previous stop loop.",
+  "NEED: change approach. Do not repeat the same fix. Inspect root cause, try a different path, or escalate with BLOCKED/TRIED/NEED.",
+].join("\n");

package/src/core/subagent-policy/subagent-policy.parent-model.ts

@@ -0,0 +1,202 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectStateDir } from "../../platform/paths.ts";
+import type { ModelParam, ParentModelSnapshot } from "./subagent-policy.types.ts";
+
+const PARENT_MODEL_SCHEMA = "harness.parent-model.v1" as const;
+
+type ParentModelFile = {
+  schema: typeof PARENT_MODEL_SCHEMA;
+  bySession: Record<string, ParentModelSnapshot>;
+};
+
+function parentModelPath(root: string): string {
+  return join(projectStateDir(root), "parent-model.json");
+}
+
+function readFile(root: string): ParentModelFile {
+  const path = parentModelPath(root);
+  if (!existsSync(path)) {
+    return { schema: PARENT_MODEL_SCHEMA, bySession: {} };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as ParentModelFile;
+    if (parsed?.schema === PARENT_MODEL_SCHEMA && parsed.bySession) {
+      return parsed;
+    }
+  } catch {}
+  return { schema: PARENT_MODEL_SCHEMA, bySession: {} };
+}
+
+function writeFile(root: string, file: ParentModelFile): void {
+  try {
+    mkdirSync(projectStateDir(root), { recursive: true });
+    writeFileSync(parentModelPath(root), `${JSON.stringify(file, null, 2)}\n`, "utf8");
+  } catch {}
+}
+
+export function isFastParamTrue(params: unknown): boolean {
+  if (!Array.isArray(params)) {
+    return false;
+  }
+  for (const entry of params) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const row = entry as ModelParam;
+    if (String(row.id ?? "").toLowerCase() === "fast" && String(row.value ?? "").toLowerCase() === "true") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseBracketParams(model: string): { base: string; params: Record<string, string> } | null {
+  const trimmed = model.trim();
+  const match = /^([^[\]]+)\[([^\]]*)\]$/.exec(trimmed);
+  const base = match?.[1];
+  const rawParams = match?.[2];
+  if (base === undefined || rawParams === undefined) {
+    return null;
+  }
+  const params: Record<string, string> = {};
+  for (const part of rawParams.split(",")) {
+    const piece = part.trim();
+    if (!piece) {
+      continue;
+    }
+    const eq = piece.indexOf("=");
+    if (eq < 0) {
+      params[piece.toLowerCase()] = "true";
+      continue;
+    }
+    const key = piece.slice(0, eq).trim().toLowerCase();
+    const value = piece
+      .slice(eq + 1)
+      .trim()
+      .toLowerCase();
+    if (key) {
+      params[key] = value;
+    }
+  }
+  return { base, params };
+}
+
+export function modelHasFastBracket(model: string): boolean {
+  const parsed = parseBracketParams(model);
+  return parsed?.params.fast === "true";
+}
+
+export function modelMatchesBlocked(model: string, patterns: string[]): string | null {
+  const value = model.trim();
+  if (!value) {
+    return null;
+  }
+  if (modelHasFastBracket(value)) {
+    return "fast=true";
+  }
+  for (const pattern of patterns) {
+    try {
+      if (new RegExp(pattern, "i").test(value)) {
+        return pattern;
+      }
+    } catch {
+      if (value.toLowerCase().includes(pattern.toLowerCase())) {
+        return pattern;
+      }
+    }
+  }
+  return null;
+}
+
+export function isModelAllowlisted(model: string, allowed: string[]): boolean {
+  if (!model) {
+    return false;
+  }
+  if (modelHasFastBracket(model)) {
+    return false;
+  }
+  return allowed.some((entry) => entry === model || model.startsWith(`${entry}[`));
+}
+
+export function computeFastFlag(model: string, modelParams: unknown, patterns: string[]): boolean {
+  if (isFastParamTrue(modelParams)) {
+    return true;
+  }
+  return modelMatchesBlocked(model, patterns) !== null;
+}
+
+export function candidateModelBlocked(
+  model: string,
+  patterns: string[],
+  modelParams?: unknown,
+): string | null {
+  const fromSlug = modelMatchesBlocked(model, patterns);
+  if (fromSlug) {
+    return fromSlug;
+  }
+  if (isFastParamTrue(modelParams)) {
+    return "model_params.fast=true";
+  }
+  return null;
+}
+
+export function upsertParentModelState(
+  projectDir: string,
+  sessionKey: string | undefined,
+  input: { model?: string; model_params?: unknown },
+  patterns: string[],
+): ParentModelSnapshot | null {
+  const key = sessionKey?.trim();
+  if (!key) {
+    return null;
+  }
+  const model = typeof input.model === "string" ? input.model : "";
+  const hasParams = Array.isArray(input.model_params);
+  if (!model && !hasParams) {
+    return null;
+  }
+  const model_params = hasParams ? (input.model_params as ModelParam[]) : null;
+  const fast = computeFastFlag(model, model_params, patterns);
+  const snapshot: ParentModelSnapshot = {
+    model,
+    model_params,
+    fast,
+    updated_at: new Date().toISOString(),
+  };
+
+  const file = readFile(projectDir);
+  file.bySession[key] = snapshot;
+  writeFile(projectDir, file);
+  return snapshot;
+}
+
+export function readParentModelState(
+  projectDir: string,
+  sessionKey: string | undefined,
+): ParentModelSnapshot | null {
+  const key = sessionKey?.trim();
+  if (!key) {
+    return null;
+  }
+  return readFile(projectDir).bySession[key] ?? null;
+}
+
+export function shouldDenyParentFast(opts: {
+  enabled: boolean;
+  projectDir: string;
+  sessionKey: string | undefined;
+  patterns: string[];
+}): boolean {
+  if (!opts.enabled) {
+    return false;
+  }
+  const snap = readParentModelState(opts.projectDir, opts.sessionKey);
+  if (!snap) {
+    return false;
+  }
+  if (snap.fast) {
+    return true;
+  }
+  return computeFastFlag(snap.model, snap.model_params, opts.patterns);
+}

package/src/core/subagent-policy/subagent-policy.service.ts

@@ -0,0 +1,139 @@
+import type { Decision } from "../../contracts/decision.ts";
+import type { EffortLevel } from "../../contracts/effort.ts";
+import { compareEffort, isEffortLevel } from "../../contracts/effort.ts";
+import { forProvider, type ProviderScoped } from "../policy/policy.types.ts";
+import {
+  candidateModelBlocked,
+  isModelAllowlisted,
+  shouldDenyParentFast,
+} from "./subagent-policy.parent-model.ts";
+
+export type EvaluateSubagentSpawnArgs = {
+  provider: string;
+  sessionKey: string;
+  projectDir: string;
+  model: string;
+  modelParams?: unknown;
+  effort?: string;
+  allowedModels: ProviderScoped<string>;
+  blockedPatterns: ProviderScoped<string>;
+  minEffort: EffortLevel | null;
+  requireModel: boolean;
+  enforceAllowlist: boolean;
+  blockParentFast: boolean;
+  blockMode?: "deny" | "ask";
+};
+
+/** The key an operator edits. Named in the refusal, because the list is theirs and nothing else supplies one. */
+export const ALLOWLIST_KEY = "subagents.allowedModels";
+
+/**
+ * hazard: the refusal was `Use one of: <list>` and named no source. An operator whose own config read
+ * `"allowedModels": []` was being refused by a shipped list, opened the file, saw an empty array, and concluded
+ * that empty means none — then offered to switch the rail off. The list has no other source now, and the message
+ * says which key holds it ([/decisions/ad-053.md](/decisions/ad-053.md)).
+ */
+export function allowlistRefusal(model: string, allowed: readonly string[]): string {
+  const base = `"${model}" is not in \`${ALLOWLIST_KEY}\`. Use one of: ${allowed.join(", ")}.`;
+  // why: `inherit` is not a model name — it means the parent's model — so listing slugs answers a question it did
+  // not ask. It is a value the operator may put on the list, and saying so is the route that works ([/decisions/ad-047.md](/decisions/ad-047.md)).
+  return model === "inherit"
+    ? `${base} \`inherit\` is a value that list may contain; add it there to permit it.`
+    : base;
+}
+
+/**
+ * why: one rule per reason a spawn is refused, not one for the aggregate. `obs report` attributes refusals by rule
+ * and `tlc harness why` reads the same field, so "blocked by the allowlist" and "blocked because the parent is in
+ * Fast mode" have to be distinguishable — a teammate hit the first and spent the loop guessing which
+ * ([/decisions/ad-061.md](/decisions/ad-061.md)).
+ */
+export const SUBAGENT_RULES = {
+  blockedPattern: "subagent-blocked-pattern",
+  modelRequired: "subagent-model-required",
+  allowlist: "subagent-allowlist",
+  minEffort: "subagent-min-effort",
+  parentFast: "subagent-parent-fast",
+} as const;
+
+export function evaluateSubagentSpawn(args: EvaluateSubagentSpawnArgs): Decision {
+  const patterns = forProvider(args.blockedPatterns, args.provider) ?? [];
+  const block = (reason: string, userNote: string, rule: string): Decision =>
+    args.blockMode === "ask"
+      ? { kind: "ask", reason, userNote, rule }
+      : { kind: "deny", reason, userNote, rule };
+
+  const blockedBy = candidateModelBlocked(args.model, patterns, args.modelParams);
+  if (blockedBy) {
+    return block(
+      `Do not use *-fast models. Pattern hit: ${blockedBy}.`,
+      `Blocked subagent model "${args.model}" (matches ${blockedBy}).`,
+      SUBAGENT_RULES.blockedPattern,
+    );
+  }
+
+  if (args.requireModel && !args.model.trim()) {
+    return block(
+      "Set model explicitly on every Task spawn. Do not omit model.",
+      "Subagent spawned without an explicit model.",
+      SUBAGENT_RULES.modelRequired,
+    );
+  }
+
+  const allowed = forProvider(args.allowedModels, args.provider);
+  // hazard: an empty list used to deny every model, because `[]` is not `null`. With no shipped fallback that
+  // would refuse every spawn from a rule naming nothing — which is what the reader who reported this mistook for
+  // a bug, correctly. `doctor` reports the combination instead ([/decisions/ad-053.md](/decisions/ad-053.md)).
+  if (
+    args.enforceAllowlist &&
+    args.model &&
+    allowed !== null &&
+    allowed.length > 0 &&
+    !isModelAllowlisted(args.model, allowed)
+  ) {
+    return block(
+      allowlistRefusal(args.model, allowed),
+      `Subagent model "${args.model}" is not on the allowlist.`,
+      SUBAGENT_RULES.allowlist,
+    );
+  }
+
+  if (
+    args.minEffort &&
+    args.effort !== undefined &&
+    isEffortLevel(args.effort) &&
+    compareEffort(args.effort, args.minEffort) < 0
+  ) {
+    return block(
+      `Subagent effort "${args.effort}" is below the required minimum "${args.minEffort}".`,
+      `Raise the subagent effort to at least "${args.minEffort}" and retry.`,
+      SUBAGENT_RULES.minEffort,
+    );
+  }
+
+  if (
+    shouldDenyParentFast({
+      enabled: args.blockParentFast,
+      projectDir: args.projectDir,
+      sessionKey: args.sessionKey,
+      patterns,
+    })
+  ) {
+    return block(
+      "Parent Fast mode is forbidden for Task/subagent spawns. Turn Fast off on the parent model and retry.",
+      "Blocked subagent spawn: parent conversation is in Fast mode.",
+      SUBAGENT_RULES.parentFast,
+    );
+  }
+
+  return { kind: "allow" };
+}
+
+export {
+  candidateModelBlocked,
+  isModelAllowlisted,
+  modelMatchesBlocked,
+  readParentModelState,
+  shouldDenyParentFast,
+  upsertParentModelState,
+} from "./subagent-policy.parent-model.ts";

package/src/core/subagent-policy/subagent-policy.types.ts

@@ -0,0 +1,22 @@
+export type ModelParam = { id?: string; value?: string };
+
+export type ParentModelSnapshot = {
+  model: string;
+  model_params: ModelParam[] | null;
+  fast: boolean;
+  updated_at: string;
+};
+
+export type SubagentDenialReason =
+  | "blocked_pattern"
+  | "missing_model"
+  | "not_allowlisted"
+  | "min_effort"
+  | "parent_fast";
+
+export type SubagentDecisionDetail =
+  | { reason: "blocked_pattern"; pattern: string }
+  | { reason: "missing_model" }
+  | { reason: "not_allowlisted"; allowed: string[] }
+  | { reason: "min_effort"; observed: string | null; required: string }
+  | { reason: "parent_fast" };