@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/src/policy-write.ts

@@ -0,0 +1,210 @@
+/**
+ * ⚠ FU-19 — WRITING THE USER'S PROVIDER/MODEL CHOICES BACK TO THE POLICY FILE.
+ *
+ * `recursive-router.json` is the plugin's own declarative config, and `bootstrap.ts` already writes it once when a
+ * workspace is scaffolded. This module is the second writer: it changes ONE level of ONE thing and leaves every
+ * other byte of the file alone.
+ *
+ * ## Three rules, each of which exists because the opposite would be a defect
+ *
+ * 1. **PRESERVE WHAT WE DO NOT UNDERSTAND.** The file is read as `Record<string, unknown>` and mutated in place,
+ *    never rebuilt from our types. A policy carrying a field this version has never heard of — a hand-written
+ *    `cli_overrides`, a future schema addition — keeps it. Rebuilding from the schema would silently delete a
+ *    user's configuration the first time they used a verb, which is the worst kind of data loss because it looks
+ *    like the verb worked.
+ *
+ * 2. **`clear` MEANS ABSENCE, NOT EMPTINESS.** The schema's own rule is that an absent field DEFERS to the next
+ *    level of precedence. So clearing must DELETE the key rather than set it to null or to an empty string: a
+ *    present-but-empty value would stop the deferral and pin the choice to nothing, which is a different state
+ *    from "unconfigured" and not one a user can see. Absence is the honest representation of "I have no opinion".
+ *
+ * 3. **WRITE ATOMICALLY.** A temp file and a rename, the same pattern the preset installer uses. A policy file
+ *    half-written because a process died mid-write would make `loadRouterPolicy` fall back to the built-in
+ *    self-audit policy — and it does that SILENTLY, on purpose (it never throws). So a torn write here would look
+ *    exactly like "the user configured nothing", for every role, until someone read the file.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { routerPolicyPath } from './router.ts'
+
+/** Which level a write targets. The narrowest matching level wins at resolution time. */
+export type SelectionScope = 'general' | 'phase' | 'role'
+
+/** What to write. Every field is optional; omitting one leaves that field alone. */
+export interface SelectionPatch {
+  scope: SelectionScope
+  /** Required for `phase` and `role`. */
+  phase?: string
+  /** Required for `role`. */
+  role?: string
+  /** The SUBAGENT provider — who creates the child. */
+  provider?: string
+  /** The model id. */
+  model?: string
+  /** The LLM provider — who SERVES the model. Not the same thing as `provider` above. */
+  modelProvider?: string
+  /** Remove the named fields instead of setting them. With no field names, removes the whole level. */
+  clear?: boolean
+}
+
+export interface SelectionWriteResult {
+  path: string
+  /** One sentence, naming the level, what changed, and the rule that history is untouched. */
+  message: string
+  /** Whether anything actually changed — a no-op write still rewrites the file, but says it was already so. */
+  changed: boolean
+}
+
+const SCOPED_FIELDS = ['provider', 'model', 'modelProvider'] as const
+
+/**
+ * A selector name, cleaned of the quotes a shell-typed argument often carries. `--role ""` must mean "no role"
+ * rather than a route literally named two quote characters — a defect this writer's own spec caught when the verb
+ * was wired to it.
+ */
+function cleanName(value: string | undefined): string {
+  return (value ?? '').replace(/^["']|["']$/g, '').trim()
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null
+}
+
+/** Where a scope's patch lives inside the policy object, creating the container only when a write needs it. */
+function containerFor(policy: Record<string, unknown>, patch: SelectionPatch): Record<string, unknown> | null {
+  if (patch.scope === 'general') {
+    return asRecord(policy.defaults) ?? null
+  }
+  if (patch.scope === 'phase') {
+    const key = cleanName(patch.phase)
+    if (key === '') return null
+    const routes = asRecord(policy.phase_routes) ?? {}
+    const existing = asRecord(routes[key]) ?? {}
+    routes[key] = existing
+    policy.phase_routes = routes
+    return existing
+  }
+  const role = cleanName(patch.role)
+  if (role === '') return null
+  const routes = asRecord(policy.role_routes) ?? {}
+  const existing = asRecord(routes[role]) ?? {}
+  routes[role] = existing
+  policy.role_routes = routes
+  return existing
+}
+
+/** Apply one patch to a policy object IN PLACE. Returns whether anything changed, or a refusal reason. */
+export function applySelectionPatch(
+  policy: Record<string, unknown>,
+  patch: SelectionPatch,
+): { changed: boolean } | { refused: string } {
+  if (patch.scope === 'phase' && cleanName(patch.phase) === '') {
+    return { refused: 'a phase-scoped choice needs a phase, e.g. --phase 03' }
+  }
+  if (patch.scope === 'role' && cleanName(patch.role) === '') {
+    return { refused: 'a role-scoped choice needs a role, e.g. --role code-reviewer' }
+  }
+
+  // A role route carries `model` at its own top level (that is where the pre-FU-19 schema put it), so the fields
+  // are written there and NOT nested under a `subagent` object the way the general default is.
+  const target = patch.scope === 'general'
+    ? (() => {
+      const defaults = asRecord(policy.defaults) ?? {}
+      policy.defaults = defaults
+      const subagent = asRecord(defaults.subagent) ?? {}
+      defaults.subagent = subagent
+      return subagent
+    })()
+    : containerFor(policy, patch)
+  if (target === null) return { refused: 'the policy target could not be created' }
+
+  const names = SCOPED_FIELDS.filter((field) => patch[field] !== undefined)
+  let changed = false
+
+  if (patch.clear === true) {
+    // Clear the named fields, or the whole level when none were named. DELETE, never blank — see rule 2 above.
+    const removals = names.length > 0 ? names : [...SCOPED_FIELDS]
+    for (const field of removals) {
+      if (field in target) {
+        delete target[field]
+        changed = true
+      }
+    }
+    // And drop a now-empty general container, so "cleared" leaves no residue that could shadow a lower level.
+    if (patch.scope === 'general') {
+      const defaults = asRecord(policy.defaults)
+      const subagent = defaults === null ? null : asRecord(defaults.subagent)
+      if (subagent !== null && Object.keys(subagent).length === 0) {
+        delete defaults!.subagent
+        changed = true
+      }
+    }
+    return { changed }
+  }
+
+  for (const field of names) {
+    const value = patch[field]
+    const next = typeof value === 'string' && value.trim() !== '' ? value.trim() : null
+    if (next === null) {
+      // An empty string is not a choice: treat it as "clear this field" rather than storing a blank that would
+      // stop the deferral to the next level.
+      if (field in target) {
+        delete target[field]
+        changed = true
+      }
+      continue
+    }
+    if (target[field] !== next) {
+      target[field] = next
+      changed = true
+    }
+  }
+  return { changed }
+}
+
+/**
+ * Write a selection patch to a workspace's policy file.
+ *
+ * Returns a refusal instead of throwing when the patch is incomplete, and a message that always states the rule
+ * the objective names: this applies to future delegations and never rewrites a run's recorded history.
+ */
+export function writePolicySelection(
+  root: string,
+  patch: SelectionPatch,
+  options: { path?: string } = {},
+): SelectionWriteResult | { refused: string } {
+  const path = options.path ?? routerPolicyPath(root)
+  let policy: Record<string, unknown> = {}
+  if (existsSync(path)) {
+    try {
+      policy = asRecord(JSON.parse(readFileSync(path, 'utf8'))) ?? {}
+    } catch {
+      return { refused: 'the policy file at ' + path + ' is not readable JSON, so it was left untouched rather than overwritten' }
+    }
+  }
+
+  const applied = applySelectionPatch(policy, patch)
+  if ('refused' in applied) return applied
+
+  const level = patch.scope === 'general'
+    ? 'the general subagent default'
+    : patch.scope === 'phase'
+      ? 'the phase ' + (patch.phase ?? '') + ' override'
+      : 'the ' + (patch.role ?? '') + ' role route'
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    const tmp = join(dirname(path), '.recursive-router.json.tmp')
+    writeFileSync(tmp, JSON.stringify(policy, null, 2) + '\n', 'utf8')
+    renameSync(tmp, path)
+  } catch (err) {
+    return { refused: 'the policy could not be written: ' + (err instanceof Error ? err.message : String(err)) }
+  }
+
+  return {
+    path,
+    changed: applied.changed,
+    message: (applied.changed ? 'updated ' : 'already as requested: ') + level
+      + '. This applies to FUTURE delegations only — it never rewrites a run\'s recorded history.',
+  }
+}

package/src/policy.ts

@@ -7,6 +7,7 @@
  * machine gates enforce (no prompt/gate contradiction).
  */
 import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { join } from 'node:path'
 import { PHASE_SEQUENCE, getLockStatus } from './lock.ts'
 import { foldRun } from './status.ts'
@@ -43,12 +44,17 @@ export function renderRecursivePolicy(context: PolicyContext | null): string {
   }
 
   const strictness = (gate: EnforcementConfig[keyof EnforcementConfig]) => gate
+  // T22 — THE STABLE PREFIX COMES FIRST, then the per-phase tail.
+  //
+  // ⚠ The four lines that used to open this array were the phase-independent contract, rendered
+  // inline; they now come from `renderStableContract`, so the contract has ONE definition and the
+  // prefix is byte-identical for the whole run — which is the precondition for any provider-side
+  // caching, whatever the provider does with it. The current phase and its next artifact move to
+  // `renderPhaseTail`, because they are precisely what changes between phases; a prefix that carried
+  // them would be stable in name only.
   const lines = [
-    'You are in a recursive-mode session (enforcement active).',
-    '- Current phase: ' + (currentPhase || 'unknown'),
-    '- Next required artifact: ' + (nextRequired || 'none - run complete'),
-    '- Lock chain: phases lock monotonically (' + PHASE_SEQUENCE.join(' -> ') + ').',
-    '- Gates in force: pre-step ' + strictness(config.preStep) + ', tool guards ' + strictness(config.toolGuards) + ', tamper ' + strictness(config.tamper) + '.',
+    renderStableContract(config),
+    renderPhaseTail(status?.currentPhase ?? null),
     '- A transition that fails its gates is BLOCKED (strict) or warns (advisory); no rejected transition advances state.',
     '- Writes to a Status: LOCKED phase doc are denied/asked; reopen explicitly to edit.',
     '- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA sign-off for human/hybrid modes.',
@@ -78,4 +84,63 @@ export function renderRecursivePolicy(context: PolicyContext | null): string {
   }
 
   return lines.join('\n')
+}
+
+/**
+ * T22 — the STABLE contract: the part of the policy section that does not depend on the phase.
+ *
+ * WHY A SPLIT AT ALL, given the item's own premise check: the mechanism this was modelled on
+ * (iii's `system_sections` + `cache_boundary` + `cache_intent.surface_digest`) does **not** exist in
+ * DSH as a plugin-visible seam — the harness's only cache concepts live in the provider layer
+ * (`llm-pi-ai` accepts prompt-cache MARKERS and a retention preference), and whether any provider
+ * caches the prefix is **provider-side and unverified**. The item **withdrew its "largest cost
+ * lever" label for exactly that reason**, and this module keeps only what survives the check:
+ * **a byte-identical prefix is a PRECONDITION for any provider-side caching**, whatever the provider
+ * does with it — and a stable prefix costs nothing to produce.
+ *
+ * ⚠ THE CONTRACT DEPENDS ON THE CONFIG, NOT ON THE PHASE, and that distinction is the whole point:
+ * the enforcement modes and the lock rules are fixed for a RUN, so they belong in the prefix; the
+ * current phase, its required sections and its gate checklist change per phase and belong in the
+ * tail. A prefix that varied with the phase would be stable in name only.
+ */
+export function renderStableContract(config: EnforcementConfig = DEFAULT_ENFORCEMENT): string {
+  return [
+    'You are in a recursive-mode session (enforcement active).',
+    '- Lock chain: phases lock monotonically (' + PHASE_SEQUENCE.join(' -> ') + ').',
+    '- Gates in force: pre-step ' + config.preStep + ', tool guards ' + config.toolGuards
+      + ', tamper detection ' + config.tamper + '.',
+    '- A transition that fails its gates is BLOCKED (strict) or warns (advisory); no rejected transition proceeds silently.',
+    '- Writes to a Status: LOCKED phase doc are denied/asked; reopen explicitly to edit.',
+    '- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA evidence.',
+    '- The control-plane root is resolved STRICTLY from this session workspace (never scanned from another).',
+  ].join('\n')
+}
+
+/**
+ * T22 — a LOCAL identifier for the contract, not a cache directive.
+ *
+ * The item's rescope is explicit that the digest is worth computing as a **local identifier**: it is
+ * stable within a run and changes when the contract changes, which is what makes "did the contract
+ * change under me?" answerable from the prompt alone. It claims **nothing** about provider caching —
+ * a digest that implied one would be the withdrawn label wearing a hash.
+ */
+export function contractDigest(config: EnforcementConfig = DEFAULT_ENFORCEMENT): string {
+  return createHash('sha256').update(renderStableContract(config), 'utf8').digest('hex').slice(0, 16)
+}
+
+/**
+ * T22 — the per-phase TAIL: everything that legitimately changes between phases.
+ *
+ * Kept as its own name so the split is a fact in the code rather than a convention: a caller that
+ * wants a cacheable prefix takes {@link renderStableContract} and puts this after it.
+ */
+export function renderPhaseTail(
+  phase: { label: string; phaseName: string; status: string; key?: string } | null,
+): string {
+  if (phase === null) return '- Current phase: unknown\n- Next required artifact: none - run complete'
+  // The key is part of the original wording (`phaseName (key)`), so it is carried when present
+  // rather than dropped — a recomposition must not quietly lose information a reader had.
+  const next = phase.key === undefined ? phase.phaseName : phase.phaseName + ' (' + phase.key + ')'
+  return '- Current phase: ' + phase.label + ' (' + phase.status + ')\n'
+    + '- Next required artifact: ' + next
 }

package/src/recursive_ask.tool.ts

@@ -0,0 +1,276 @@
+/**
+ * T23 — `recursive_ask`: the three human gates as STRUCTURED decisions, not prose.
+ *
+ * WHY. Three points in this workflow genuinely block on a person, and all three are prose today:
+ * the `TDD Mode: strict|pragmatic` choice at phase-3 entry, QA sign-off at phase 5, and resolving a
+ * gate block. Prose means the answer arrives as free text in a transcript — unvalidated, unciteable,
+ * and impossible to write back into the artifact as a fact. Asking as a STRUCTURED question gives
+ * the answer a shape the workflow can consume, and the harness renders that shape as a card.
+ *
+ * ⚠ WHAT IS MEASURED AND WHAT IS NOT. The ask flow is a CLIENT concern: the harness renders these
+ * questions as cards (`ui-user-questions`, the ask-question card model), so the plugin's job is to
+ * produce a well-formed question and to record the answer — not to draw anything. The LENGTH LIMITS
+ * below are therefore the plugin's OWN documented bounds rather than a claimed mirror of a harness
+ * constant I did not measure; what matters for the workflow is that an over-long field is refused
+ * **with its field path**, which is what the item's RED asks for.
+ *
+ * ⚠ ONE ASK PER STEP. A step that asks twice produces two cards for one decision, and the second
+ * answer silently overwrites the first — a decision the workflow never sees. The guard refuses the
+ * second ask in the same step rather than letting the last writer win.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import type { RecursiveRuntime } from './runtime.ts'
+import { toolError } from './errors.ts'
+
+
+/** The identifiers the workflow uses for its three human gates. */
+export const ASK_GATE_IDS = ['tdd-mode', 'qa-signoff', 'gate-block'] as const
+export type AskGateId = (typeof ASK_GATE_IDS)[number]
+
+/** The plugin's own documented bounds — see the module comment on why these are not a claimed mirror. */
+export const MAX_HEADER_CHARS = 12
+export const MAX_LABEL_CHARS = 30
+export const MAX_DESCRIPTION_CHARS = 200
+
+export interface AskOption {
+  label: string
+  description?: string
+}
+
+/** A structured question, in the shape the ask flow renders as a card. */
+export interface AskQuestion {
+  id: string
+  header: string
+  question: string
+  options: AskOption[]
+}
+
+/** One of the three gates, as data: what to ask, what the options mean, and what the answer means. */
+export interface AskGate {
+  id: AskGateId
+  header: string
+  question: string
+  options: AskOption[]
+  /** The artifact marker name the answer is written under. */
+  marker: string
+}
+
+export const ASK_GATES: Record<AskGateId, AskGate> = {
+  'tdd-mode': {
+    id: 'tdd-mode',
+    header: 'TDD Mode',
+    question: 'How should phase 3 handle test evidence?',
+    options: [
+      { label: 'strict', description: 'RED and GREEN evidence paths are required before the phase can lock.' },
+      { label: 'pragmatic', description: 'A written rationale is accepted in place of evidence paths.' },
+    ],
+    marker: 'TDD Mode',
+  },
+  'qa-signoff': {
+    id: 'qa-signoff',
+    header: 'QA sign-off',
+    question: 'Who signs off the manual QA phase?',
+    options: [
+      { label: 'human', description: 'A person runs and signs the QA checklist.' },
+      { label: 'agent-operated', description: 'The agent runs it and records the results.' },
+      { label: 'hybrid', description: 'The agent runs it; a person signs the result.' },
+    ],
+    marker: 'QA Execution Mode',
+  },
+  'gate-block': {
+    id: 'gate-block',
+    header: 'Gate block',
+    question: 'A gate is blocking this transition. How should it be resolved?',
+    options: [
+      { label: 'fix', description: 'Return to the phase and satisfy the gate.' },
+      { label: 'reopen', description: 'Reopen an earlier locked artifact and repair it there.' },
+      { label: 'abandon', description: 'Stop the run; the block is not resolvable now.' },
+    ],
+    marker: 'Gate Resolution',
+  },
+}
+
+/** Thrown for a request the ask flow would refuse; carries the FAILING FIELD PATH. */
+export class AskValidationError extends Error {
+  readonly field: string
+  constructor(field: string, message: string) {
+    super(field + ': ' + message)
+    this.name = 'AskValidationError'
+    this.field = field
+  }
+}
+
+/**
+ * Validate a question and return it unchanged.
+ *
+ * The FIELD PATH travels in the error because a caller fixing an over-long header needs to know
+ * WHICH field — a bare "too long" for a request with four fields is a puzzle, not a diagnostic.
+ */
+export function validateAskQuestion(question: AskQuestion): AskQuestion {
+  if (question.header.trim() === '') throw new AskValidationError('header', 'must not be empty')
+  if (question.header.length > MAX_HEADER_CHARS) {
+    throw new AskValidationError('header', 'is ' + question.header.length + ' characters, over the ' + MAX_HEADER_CHARS + '-character limit')
+  }
+  if (question.question.trim() === '') throw new AskValidationError('question', 'must not be empty')
+  if (question.options.length === 0) throw new AskValidationError('options', 'at least one option is required')
+  question.options.forEach((option, index) => {
+    if (option.label.trim() === '') throw new AskValidationError('options[' + index + '].label', 'must not be empty')
+    if (option.label.length > MAX_LABEL_CHARS) {
+      throw new AskValidationError('options[' + index + '].label', 'is ' + option.label.length + ' characters, over the ' + MAX_LABEL_CHARS + '-character limit')
+    }
+    if (option.description !== undefined && option.description.length > MAX_DESCRIPTION_CHARS) {
+      throw new AskValidationError('options[' + index + '].description', 'is ' + option.description.length + ' characters, over the ' + MAX_DESCRIPTION_CHARS + '-character limit')
+    }
+  })
+  return question
+}
+
+/** Build the question for a gate, validated. */
+export function buildAskQuestion(gateId: AskGateId): AskQuestion {
+  const gate = ASK_GATES[gateId]
+  return validateAskQuestion({
+    id: gate.id,
+    header: gate.header,
+    question: gate.question,
+    options: gate.options.map((option) => ({ ...option })),
+  })
+}
+
+/**
+ * Validate an answer against its gate.
+ *
+ * An answer that is not one of the offered labels is REFUSED rather than recorded: a marker saying
+ * `TDD Mode: maybe` would look like a decision and be a transcription error.
+ */
+export function validateAskAnswer(gateId: AskGateId, answer: string): string {
+  const gate = ASK_GATES[gateId]
+  if (!gate.options.some((option) => option.label === answer)) {
+    throw new AskValidationError('answer', 'must be one of ' + gate.options.map((option) => option.label).join(' | ') + ' (got ' + JSON.stringify(answer) + ')')
+  }
+  return answer
+}
+
+/** The durable marker an accepted answer is written back as — a fact, not a chat aside. */
+export function answerMarker(gateId: AskGateId, answer: string): string {
+  const gate = ASK_GATES[gateId]
+  return '- ' + gate.marker + ': ' + answer
+}
+
+/**
+ * One-ask-per-step guard.
+ *
+ * A step that asks twice yields two cards for one decision and the second answer silently wins —
+ * so the second ask is REFUSED, naming the gate already asked this step.
+ */
+export function createAskLedger(): { claim(gateId: AskGateId): void; asked(): AskGateId[] } {
+  const asked: AskGateId[] = []
+  return {
+    claim(gateId: AskGateId): void {
+      if (asked.includes(gateId)) {
+        throw new AskValidationError('gate', 'the ' + gateId + ' gate was already asked in this step; one ask per step')
+      }
+      if (asked.length > 0) {
+        throw new AskValidationError('gate', 'this step already asked ' + asked.join(', ') + '; answer it before asking again')
+      }
+      asked.push(gateId)
+    },
+    asked: () => [...asked],
+  }
+}
+
+/** Which artifact each gate's answer belongs in, when the caller does not name one. */
+export const GATE_DEFAULT_ARTIFACT: Record<AskGateId, string> = {
+  'tdd-mode': '03-implementation-summary.md',
+  'qa-signoff': '05-manual-qa.md',
+  // A gate block can happen at any phase, so its marker belongs where the caller says.
+  'gate-block': '',
+}
+
+/**
+ * FU-7 — THE CALL POINTS: which gate, if any, a phase ENTRY still owes.
+ *
+ * ⚠ THE ARTIFACT IS THE RECORD, so no ledger is needed to ask once: if the document already carries the
+ * gate's marker line, the question has been answered and is not asked again. That is the same
+ * "once per run at entry" property T29 got from riding an existing gate — one mechanism, not two.
+ *
+ * ⚠ AND AN UNKNOWN PHASE OWES NOTHING. Returning a gate for a phase that has no such decision would ask a
+ * person a question the workflow does not act on, which is worse than not asking at all.
+ */
+export function pendingGateFor(artifactFile: string, artifactText: string | null): AskGateId | null {
+  const gate = (Object.keys(GATE_DEFAULT_ARTIFACT) as AskGateId[])
+    .find((id) => GATE_DEFAULT_ARTIFACT[id] === artifactFile)
+  if (gate === undefined) return null
+  const marker = ASK_GATES[gate].marker
+  // Already answered: the marker is in the document, so the decision is settled.
+  if (artifactText !== null && new RegExp('^- ' + marker + ':', 'm').test(artifactText)) return null
+  return gate
+}
+
+/**
+ * T23 — the tool.
+ *
+ * TWO BRANCHES, and the split is the point: called WITHOUT an answer it ASKS (returning the validated
+ * question, which the host renders as a card), and called WITH one it RECORDS — validating the label,
+ * writing the marker into the artifact, and reporting the line it wrote. A tool that did both in one
+ * call would have to invent the answer.
+ *
+ * ⚠ THE WRITE-BACK IS A MARKER LINE, REPLACED IN PLACE when the artifact already carries one. A
+ * second `TDD Mode:` line would leave two answers to one question and make "what was decided?"
+ * depend on which a reader found first.
+ */
+export function createRecursiveAskTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_ask',
+    description: 'Ask one of the three human gates as a structured decision (tdd-mode, qa-signoff, gate-block), or record the answer. Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. One ask per step.',
+    parameters: {
+      gate: { type: 'string', description: 'tdd-mode | qa-signoff | gate-block. Required.' },
+      runId: { type: 'string', description: 'Run id. Required; must resolve inside the current workspace.' },
+      artifact: { type: 'string', description: 'Artifact file the answer belongs in. Optional; defaults per gate (gate-block has none, so it is required for that gate).' },
+      answer: { type: 'string', description: 'One of the gate\'s option labels. Omit to ASK.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { gate?: string; runId?: string; artifact?: string; answer?: string }, exec) {
+      const gateId = (args.gate ?? '').trim() as AskGateId
+      const runId = args.runId?.trim() ?? ''
+      if (runId === '') return { error: toolError('MISSING_RUN_ID') } as const
+      if (!ASK_GATE_IDS.includes(gateId)) {
+        return { error: toolError('BAD_ASK_GATE', 'gate must be one of ' + ASK_GATE_IDS.join(' | ')) } as const
+      }
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) return { error: toolError('NO_WORKSPACE') } as const
+
+      const artifact = (args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim()
+      let question: AskQuestion
+      try {
+        question = buildAskQuestion(gateId)
+      } catch (err) {
+        // The plugin's own gate data failing validation is a defect, so it is reported as one
+        // rather than asked: a malformed card would be answered by a person who cannot fix it.
+        return { error: toolError('BAD_ASK_GATE', err instanceof Error ? err.message : String(err)) } as const
+      }
+
+      // ASK.
+      if (args.answer === undefined) {
+        return { gate: gateId, marker: ASK_GATES[gateId].marker, artifact, question } as unknown as JsonValue
+      }
+
+      // RECORD.
+      let answer: string
+      try {
+        answer = validateAskAnswer(gateId, args.answer)
+      } catch (err) {
+        return { error: toolError('BAD_ASK_ANSWER', err instanceof Error ? err.message : String(err)) } as const
+      }
+      if (artifact === '') {
+        return { error: toolError('MISSING_ASK_ARTIFACT', 'this gate needs an explicit artifact to record into') } as const
+      }
+      const marker = answerMarker(gateId, answer)
+      const written = recursive.recordAskAnswer(root, runId, artifact, marker)
+      return { gate: gateId, answer, marker, artifact, path: written.path, replaced: written.replaced } as unknown as JsonValue
+    },
+  })
+}

package/src/recursive_audit_team.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import { codeRuntimeRefusal } from './errors.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type {
   TeamRuntimeLike,
   TeamCallerHandle,
@@ -40,9 +41,12 @@ function taskViewToJson(view: TeamTaskViewLike): JsonValue {
   }
 }
 
-/** Wrap a non-JSON-pure value in the standard error envelope. */
+/** Wrap a non-JSON-pure value in the standard error envelope, coded for greppability. */
 function errorJson(message: string): JsonValue {
-  return { error: message }
+  // T24: every refusal must begin with a stable code so a consumer can branch on
+  // it. `codeRuntimeRefusal` wraps the teams loop's own uncoded messages and
+  // passes an already-coded one through rather than nesting it.
+  return { error: codeRuntimeRefusal(message) }
 }
 
 export function createRecursiveAuditTeamTool(teams: TeamRuntimeLike | null) {