@try-works/dsh-recursive-mode 0.2.3 → 0.3.0

package/src/client/styles.ts

@@ -532,6 +532,316 @@ const BOARD_CSS = `
   color: var(--board-muted-fg);
 }
 
+/* ===== Per-phase doc viewer (0.2.4, inside the inspector detail body) ===== */
+
+/* View phase ghost button on each present phase row. */
+.rec-phase-view {
+  flex: none;
+  padding: 3px 10px;
+  font-size: var(--board-text-xs);
+  color: var(--board-info);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-phase-view:hover {
+  background: var(--board-accent);
+}
+
+/* Viewer shell: fills the inspector detail body (the panel owns data-theme). */
+.rec-doc {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  gap: var(--board-space-12);
+  color: var(--board-fg);
+  font-family: var(--board-font-sans);
+  background: var(--board-bg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-xl);
+  overflow: hidden;
+}
+
+.rec-doc-header {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-12) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-heading {
+  display: flex;
+  align-items: baseline;
+  gap: var(--board-space-12);
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-badge {
+  flex: none;
+  padding: 2px 10px;
+  font-size: 11px;
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  border-radius: 999px;
+  background: var(--board-accent);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-title {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  font-weight: var(--board-fw-semibold);
+  letter-spacing: var(--board-tracking-tight);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.rec-doc-run {
+  flex: none;
+  font-family: var(--board-font-mono);
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-btn {
+  flex: none;
+  padding: 5px 12px;
+  font-size: var(--board-text-xs);
+  color: var(--board-fg);
+  background: transparent;
+  border: 1px solid var(--board-border);
+  border-radius: 999px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.rec-doc-btn:hover {
+  background: var(--board-accent);
+}
+
+/* Search bar (/ to open). */
+.rec-doc-search {
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-12);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-bottom: 1px solid var(--board-border);
+  flex: none;
+}
+
+.rec-doc-search-input {
+  flex: 1 1 auto;
+  background: var(--board-muted);
+  color: var(--board-fg);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  padding: 5px 10px;
+  font-size: var(--board-text-xs);
+  font-family: inherit;
+  min-width: 0;
+}
+
+.rec-doc-search-input::placeholder {
+  color: var(--board-muted-fg);
+  opacity: 1;
+}
+
+.rec-doc-search-count {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  white-space: nowrap;
+}
+
+/* Body: scrollable line list. */
+.rec-doc-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: var(--board-space-12) var(--board-space-16) var(--board-space-16);
+}
+
+.rec-doc-line {
+  font-size: var(--board-text-sm);
+  line-height: 1.7;
+  padding: 0 6px;
+  border-left: 2px solid transparent;
+}
+
+.rec-doc-line-current {
+  background: var(--board-muted);
+  border-left-color: var(--board-info);
+}
+
+.rec-doc-blank {
+  height: 10px;
+}
+
+.rec-doc-plain {
+  white-space: pre-wrap;
+}
+
+.rec-doc-h1 {
+  font-size: 22px;
+  font-weight: 700;
+  margin: 8px 0 6px;
+  line-height: 1.3;
+}
+
+.rec-doc-h2 {
+  font-size: 18px;
+  font-weight: 600;
+  margin: 12px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h3 {
+  font-size: 15px;
+  font-weight: 600;
+  margin: 10px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-h4 {
+  font-size: 14px;
+  font-weight: 600;
+  margin: 8px 0 4px;
+  line-height: 1.3;
+}
+
+.rec-doc-li {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  font-size: var(--board-text-sm);
+  line-height: 1.65;
+  margin: 0 0 4px;
+}
+
+.rec-doc-bullet {
+  flex: none;
+  color: var(--board-muted-fg);
+  width: 14px;
+  text-align: center;
+}
+
+.rec-doc-li-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.rec-doc-pre {
+  margin: 6px 0;
+  padding: var(--board-space-12);
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: var(--board-radius-md);
+  overflow-x: auto;
+}
+
+.rec-doc-code,
+.rec-doc-inline-code {
+  font-family: var(--board-font-mono);
+  font-size: 12.5px;
+  letter-spacing: var(--board-tracking-mono);
+}
+
+.rec-doc-inline-code {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 0 4px;
+}
+
+.rec-doc-inline-link {
+  color: var(--board-info);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.rec-doc-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 6px 0;
+  font-size: var(--board-text-xs);
+}
+
+.rec-doc-table th,
+.rec-doc-table td {
+  border: 1px solid var(--board-border);
+  padding: 4px 8px;
+  text-align: left;
+}
+
+.rec-doc-table th {
+  background: var(--board-muted);
+  color: var(--board-muted-fg);
+  font-weight: var(--board-fw-semibold);
+}
+
+/* Footer: status + key hints. */
+.rec-doc-footer {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: var(--board-space-16);
+  padding: var(--board-space-8) var(--board-space-16);
+  border-top: 1px solid var(--board-border);
+  flex-wrap: wrap;
+}
+
+.rec-doc-status {
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+  min-width: 120px;
+}
+
+.rec-doc-status-error {
+  color: var(--board-error);
+}
+
+.rec-doc-status-ok {
+  color: var(--board-success);
+}
+
+.rec-doc-hints {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex-wrap: wrap;
+  font-size: var(--board-text-xs);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-hints kbd {
+  background: var(--board-muted);
+  border: 1px solid var(--board-border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-family: inherit;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--board-fg);
+  margin: 0 3px 0 8px;
+}
+
+.rec-doc-text {
+  margin: 0;
+  font-size: var(--board-text-sm);
+  color: var(--board-muted-fg);
+}
+
+.rec-doc-error {
+  color: var(--board-error);
+}
+
 /* ===== Strip (session dock) — keeps the shell --dsw-* theme ===== */
 .rec-badge {
   flex: none;

package/src/delegation.ts

@@ -11,11 +11,53 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
 import { contentSha256 } from './review.ts'
 
+/**
+ * Opaque handle to the live direct-parent Agent. The live continuable service
+ * authorizes by EXACT live object identity — `ctx.agents.get(parent.id) ===
+ * parent` (authorizeLineage), `ancestry.has(parent)` (interrupt/drain), and a
+ * `WeakSet` of live ancestry — so this must be the real live `Agent`, never a
+ * structural `{ id }` copy. The seam only ever reads `id`/`session.header.cwd`
+ * for attribution, and never serializes or inspects the live object.
+ */
+export interface SubagentParentHandle {
+  readonly id?: string
+  readonly session?: { readonly header?: { readonly cwd?: string } }
+}
+
+/** Durable identity of one continuable child session (string-branded in the host). */
+export type ContinuableChildId = string
+
+/** Durable identity of one accepted inbox message (string-branded in the host). */
+export type ContinuableMessageId = string
+
+/**
+ * Attribution for a model coordinator's follow-up to one of its children (the
+ * live `CoordinatorMessageSource` subset — see subagent/src/continuation.ts).
+ */
+export interface CoordinatorSourceLike {
+  readonly kind: 'coordinator'
+  readonly form: 'relay'
+  readonly senderSessionId: string
+}
+
+/** Uniform outcome for the interrupt/drain kill-switch helpers. */
+export interface ContinuableOpResult {
+  ok: boolean
+  reason?: string
+}
+
 /** Minimal host-realm contract for ctx.subagents (the seam we call). */
 export interface SubagentsRuntimeLike {
   start(name: string, request: SubagentStartRequestLike): Promise<SubagentResultLike>
   getProvider?(name: string): unknown
   list?(): unknown
+  /** T4: continuable child lifecycle (startContinuable / followup / interrupt / drain). */
+  startContinuable?(spec: ContinuableStartSpecLike): Promise<ContinuableStartLike>
+  /** The parent MUST be the exact live Agent (object-identity authority), never a `{ id }` copy. */
+  followup?(parent: SubagentParentHandle, childId: ContinuableChildId, content: readonly { type: 'text'; text: string }[], options: SubagentFollowupOptionsLike): Promise<ContinuableMessageId>
+  interrupt?(targetSessionId: ContinuableChildId, authority: SubagentInterruptAuthorityLike): void
+  drainContinuableChildren?(parent: SubagentParentHandle, childIds: readonly ContinuableChildId[]): Promise<void>
+  drainContinuableDescendants?(parents: readonly SubagentParentHandle[]): Promise<void>
 }
 
 export interface SubagentStartRequestLike {
@@ -116,11 +158,305 @@ export async function delegate(input: {
   }
 }
 
+/**
+ * T4: continuable-child delegation — ONE durable child receives the initial
+ * prompt (startContinuable), each REVISE is delivered as a followup to the SAME
+ * child (FIFO, working set retained), and the parent observes each round's
+ * settlement through the injected `awaitRoundResult` seam (in live usage the
+ * child's settlement lands in the parent's inbox — `reportFrom` is the
+ * CHILD-side API, so the parent-side loop collects via settlement, not by
+ * calling it). A hung reviewer is cancelled with `interruptContinuable`
+ * (keepInbox: the child's pending inbox survives). Falls back to one-shot
+ * `delegate` when the seam has no continuable methods.
+ */
+
+/** What the caller asks for when starting a continuable background child (structural subset). */
+export interface ContinuableStartSpecLike {
+  /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */
+  readonly provider: string
+  /** The initial delegation's short `description`, persisted as the child's creation label. */
+  readonly label: string
+  /** Optional caller-reserved child identity. */
+  childId?: ContinuableChildId
+  /** The delegation request (prompt + parent + toolFilter + maxDepth; no label/signal/outputSchema). */
+  readonly request: Omit<SubagentStartRequestLike, 'label' | 'signal' | 'outputSchema'>
+  /** Caller cancellation, owning the operation only until inbox acceptance. */
+  readonly signal?: AbortSignalLike
+}
+
+/** Minimal cancellation shape (a live AbortSignal satisfies it). */
+export interface AbortSignalLike {
+  readonly throwIfAborted: () => void
+}
+
+/** Identities returned once a continuable child accepted its initial prompt. */
+export interface ContinuableStartLike {
+  /** The durable child session id, stable across activations. */
+  readonly childId: ContinuableChildId
+  /** The accepted initial prompt's inbox message id. */
+  readonly messageId: ContinuableMessageId
+}
+
+/** Options for following up with one continuable child (structural subset). */
+export interface SubagentFollowupOptionsLike {
+  /** Durable attribution retained on the delivered message. */
+  readonly source: CoordinatorSourceLike
+  /** Caller cancellation, owning the operation only until inbox acceptance. */
+  readonly signal?: AbortSignalLike
+}
+
+/** Authority under which one interrupt request is admitted. */
+export type SubagentInterruptAuthorityLike =
+  | { readonly kind: 'user'; readonly parentSessionId: string }
+  | { readonly kind: 'ancestor'; readonly agent: SubagentParentHandle }
+
+/** One round of a continuable child: the delivered text plus the observed outcome. */
+export interface ContinuableRoundLike {
+  /** The message text delivered as this round's user prompt. */
+  text: string
+  /** The child's observed outcome for this round. */
+  result?: SubagentResultLike
+  /** True when this round's verdict was REVISE (a repair followup followed). */
+  revise?: boolean
+  /** The repair instruction delivered in the followup (only when revise). */
+  repair?: string
+}
+
+/** The full T4 delegation outcome. */
+export interface ContinuableDelegationLike {
+  ok: boolean
+  reason?: string
+  /** The durable child session id (stable across rounds). */
+  childId?: ContinuableChildId
+  /** Inbox message ids: [initial acceptance, ...followups]. */
+  messageIds?: ContinuableMessageId[]
+  rounds: ContinuableRoundLike[]
+  /** Final outcome accepted (last verdict APPROVE + result accepted). */
+  accepted: boolean
+  /** True when the fallback one-shot `delegate()` was used (no continuable seam). */
+  fellBackToOneShot?: boolean
+}
+
+/** Verdict vocabulary shared by T3/T4 (matches the delegated review schema). */
+export type DelegationVerdict = 'APPROVE' | 'REVISE' | 'REJECT'
+
+/** Read the verdict from a review-schema structured result (pure). */
+export function readVerdictFromStructured(result: SubagentResultLike): DelegationVerdict {
+  // SAFETY: reviewOutputSchema() defines verdict as a string enum; the cast reads
+  // one leaf field only, never mutates, and falls back on a non-matching value.
+  const verdict = (result.structured as { verdict?: unknown } | undefined)?.verdict
+  if (verdict === 'APPROVE' || verdict === 'REVISE' || verdict === 'REJECT') return verdict
+  // No structured verdict: a completed run with text output is a provisional APPROVE
+  // candidate, but delegation acceptance stays strict (caller evaluates).
+  return 'APPROVE'
+}
+
+/** Read the repair instruction from a review-schema structured result (pure). */
+export function readRepairFromStructured(result: SubagentResultLike): string {
+  // SAFETY: reviewOutputSchema() defines findings as an array of {severity,title,
+  // detail}; the cast reads leaf fields only (no live data, no mutation). The
+  // repair instruction is ALWAYS synthesized from the findings — a child cannot
+  // inject arbitrary instruction text (prompt-injection hygiene).
+  const findings = (result.structured as { findings?: Array<{ title?: string }> } | undefined)?.findings
+  const titles = Array.isArray(findings) ? findings.map(f => f.title ?? '').filter(Boolean) : []
+  if (titles.length > 0) return 'Address the findings: ' + titles.join('; ')
+  return 'REVISE: address the review findings and re-submit.'
+}
+
+/**
+ * Run a multi-round delegated task on ONE durable continuable child:
+ * 1. `startContinuable` (initial prompt) — `start()` is never called.
+ * 2. `awaitRoundResult` observes the child's settlement for that round.
+ * 3. On REVISE: `followup` delivers the repair instruction to the SAME child.
+ * 4. On APPROVE/REJECT: finish (accepted only when the verdict is APPROVE and
+ *    the result evaluates as accepted).
+ *
+ * `awaitRoundResult(childId, messageId)` is the ONLY parent-side observation
+ * seam: in live usage it waits for the child's settlement notice (the child's
+ * `reportFrom` lands in the parent's inbox); in tests it is a fake queue.
+ */
+export async function delegateContinuable(input: {
+  subagents: SubagentsRuntimeLike
+  provider: string
+  label: string
+  prompt: string
+  parent?: SubagentParentHandle
+  toolFilter?: unknown
+  maxDepth?: number
+  childId?: ContinuableChildId
+  maxRounds?: number
+  readVerdict?: (result: SubagentResultLike) => DelegationVerdict
+  readRepair?: (result: SubagentResultLike) => string | undefined
+  awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>
+}): Promise<ContinuableDelegationLike> {
+  const { subagents, provider, label, prompt, parent, toolFilter, maxDepth } = input
+  const maxRounds = input.maxRounds ?? 3
+  const readVerdict = input.readVerdict ?? readVerdictFromStructured
+  const readRepair = input.readRepair ?? readRepairFromStructured
+
+  const startContinuable = subagents?.startContinuable
+  const followup = subagents?.followup
+  // A continuable loop MUST observe the child's real settlement AND hold the
+  // exact live parent Agent (the live service authorizes followup by object
+  // identity). When either is missing, fall back to one-shot (which returns the
+  // actual result) rather than fabricating authority and silently APPROVE-ing.
+  const hasContinuableSeam = startContinuable !== undefined && followup !== undefined && input.awaitRoundResult !== undefined
+  if (!hasContinuableSeam || subagents === undefined || parent === undefined) {
+    // Fall back to one-shot delegation (self-audit-safe): never silently drop.
+    try {
+      const oneShot = await delegate({
+        subagents,
+        provider,
+        request: {
+          prompt: [{ type: 'text', text: prompt }],
+          label,
+          toolFilter,
+          maxDepth,
+          parent,
+        },
+      })
+      const verdict = readVerdict(oneShot)
+      return {
+        ok: true,
+        rounds: [{ text: prompt, result: oneShot }],
+        accepted: verdict === 'APPROVE' && evaluateDelegationResult(oneShot).accepted,
+        fellBackToOneShot: true,
+      }
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : String(err), rounds: [], accepted: false, fellBackToOneShot: true }
+    }
+  }
+
+  const messageIds: ContinuableMessageId[] = []
+  const rounds: ContinuableRoundLike[] = []
+  let childId: ContinuableChildId | undefined
+
+  const request: ContinuableStartSpecLike['request'] = {
+    prompt: [{ type: 'text', text: prompt }],
+    parent,
+  }
+  if (toolFilter !== undefined) request.toolFilter = toolFilter
+  if (maxDepth !== undefined) request.maxDepth = maxDepth
+
+  const spec: ContinuableStartSpecLike = {
+    provider,
+    label,
+    request,
+  }
+  if (input.childId !== undefined) spec.childId = input.childId
+  try {
+    const started = await startContinuable(spec)
+    childId = started.childId
+    messageIds.push(started.messageId)
+    rounds.push({ text: prompt })
+
+    for (let round = 0; round < maxRounds; round += 1) {
+      const current = rounds[round]
+      const observed = await input.awaitRoundResult!(childId, messageIds[messageIds.length - 1])
+      if (observed === null) {
+        return { ok: false, reason: 'continuable child produced no settlement for round ' + (round + 1), childId, messageIds, rounds, accepted: false }
+      }
+      current.result = observed
+      const verdict = readVerdict(observed)
+      if (verdict !== 'REVISE') {
+        const accepted = verdict === 'APPROVE' && evaluateDelegationResult(observed).accepted
+        return {
+          ok: accepted,
+          reason: accepted ? 'delegation completed' : 'delegation stopped with verdict ' + verdict,
+          childId,
+          messageIds,
+          rounds,
+          accepted,
+        }
+      }
+      // REVISE: send the repair instruction to the SAME child (FIFO, context retained).
+      const repair = readRepair(observed)
+      if (!repair) {
+        return { ok: false, reason: 'REVISE verdict without a repair instruction', childId, messageIds, rounds, accepted: false }
+      }
+      const followupId = await followup(
+        parent,
+        childId,
+        [{ type: 'text', text: repair }],
+        { source: { kind: 'coordinator', form: 'relay', senderSessionId: parent.id ?? '' } },
+      )
+      messageIds.push(followupId)
+      current.revise = true
+      current.repair = repair
+      rounds.push({ text: repair })
+    }
+    return { ok: false, reason: 'max rounds reached without an APPROVE', childId, messageIds, rounds, accepted: false }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    // Failure preserves the child (a later followup may still resume it); the
+    // kill switch is explicit (interruptContinuable), never implicit.
+    return { ok: false, reason: message, childId, messageIds, rounds, accepted: false }
+  }
+}
+
+/**
+ * T4 kill switch: interrupt one live continuable child's current turn. Admission
+ * is synchronous, the effect asynchronous, and the child's pending inbox is
+ * preserved (keepInbox semantics) — a followup later resumes the parked queue.
+ */
+export function interruptContinuable(
+  subagents: SubagentsRuntimeLike,
+  childId: ContinuableChildId,
+  parentSessionId: string,
+): ContinuableOpResult {
+  const interrupt = subagents?.interrupt
+  if (interrupt === undefined) {
+    return { ok: false, reason: 'no continuable interrupt seam' }
+  }
+  try {
+    interrupt(childId, { kind: 'user', parentSessionId })
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+/**
+ * T4 closeout: release one continuable child (host drains its Activation and
+ * disposes its handle). No-op when the seam lacks the method (one-shot hosts).
+ */
+export async function drainContinuableChildren(
+  subagents: SubagentsRuntimeLike,
+  parent: SubagentParentHandle,
+  childIds: readonly ContinuableChildId[],
+): Promise<ContinuableOpResult> {
+  if (subagents?.drainContinuableChildren === undefined || childIds.length === 0) return { ok: true }
+  try {
+    await subagents.drainContinuableChildren(parent, childIds)
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+/**
+ * T4 closeout (host teardown path): release every continuable descendant below
+ * the given live parents (mirrors the live `drainContinuableDescendants`).
+ * No-op when the seam lacks the method; the host owns this at session teardown.
+ */
+export async function drainContinuableDescendants(
+  subagents: SubagentsRuntimeLike | null,
+  parents: readonly SubagentParentHandle[],
+): Promise<ContinuableOpResult> {
+  const drain = subagents?.drainContinuableDescendants
+  if (drain === undefined || parents.length === 0) return { ok: true }
+  try {
+    await drain(parents)
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}
+
 export interface Reference {
   path: string
   lineRange?: string
 }
-
 export interface ReferenceCheck {
   ok: boolean
   failures: string[]

package/src/enforcement.ts

@@ -46,7 +46,7 @@ const LOCK_TOOL_NAMES = new Set(['recursive_lock', 'recursive_lock_phase'])
  * Pure predicate: inspects the pending tool execution (name + args) against
  * the run tree under the given worktree root.
  */
-export type ToolGuardDecision = { kind: 'allow' } | { kind: 'deny'; reason: string } | { kind: 'ask'; reason?: string }
+export type ToolGuardDecision = { kind: 'allow'; warn?: string } | { kind: 'deny'; reason: string } | { kind: 'ask'; reason?: string }
 
 export interface ToolExecLike {
   name: string
@@ -108,6 +108,21 @@ export function evaluateToolGuard(
   return { kind: 'allow' }
 }
 
+/**
+ * T6 (approval ask→policy bridge): an `ask` decision must never be a silent
+ * allow. Under `strict` it coerces to `deny`; under `advisory` it stays `allow`
+ * but flags a `warn` so the caller never lets it through unlogged. Non-ask
+ * decisions pass through unchanged.
+ */
+export function coerceAskToDecision(decision: ToolGuardDecision, mode: EnforcementMode = 'advisory'): ToolGuardDecision {
+  if (decision.kind !== 'ask') return decision
+  if (mode === 'strict') {
+    return { kind: 'deny', reason: decision.reason ?? 'ask under strict enforcement denies' }
+  }
+  // advisory: allow, but carry the warning so the caller logs (never silent).
+  return { kind: 'allow', warn: decision.reason ?? 'ask under advisory enforcement allows' }
+}
+
 /** Resolve a tool-target path to an absolute path under the worktree root. */
 function resolveTargetPath(target: string, worktreeRoot: string): string | null {
   const normalized = target.replace(/\\/g, '/')