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

package/src/recursive_closeout.tool.ts

@@ -1,35 +1,36 @@
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
-import type { RecursiveRuntime } from './runtime.ts'
-
-/**
- * `recursive_closeout` — scaffold a Phase 4/5/6/7/8 closeout receipt under the
- * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
- * via the session agent's cwd -> workspace registry; a runId outside the current
- * workspace is rejected.
- */
-export function createRecursiveCloseoutTool(recursive: RecursiveRuntime) {
-  return defineTool({
-    name: 'recursive_closeout',
-    description: 'Scaffold a closeout receipt stub (Phase 4/5/6/7/8 delta receipt) for a run in the CURRENT session workspace only. Workspace-scoped: refuses runIds outside the session\'s workspace. Delegates to the RecursiveRuntime service.',
-    parameters: {
-      phase: { type: 'string', description: 'Closeout phase to scaffold: 04, 05, 06, 07, or 08 (e.g. \'06\' for 06-decisions-update.md). Required.' },
-      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required. Must resolve inside the current workspace.' },
-    },
-    output: {
-      schema: { type: 'json' },
-      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
-    },
-    async execute(args: { phase?: string; runId?: string }, exec) {
-      if (!args.phase || !args.runId || args.runId.trim() === '') {
-        return { error: 'phase and runId are required' } as const
-      }
-      const root = await recursive.resolveWorkspaceRoot(exec.agent)
-      if (!root) {
-        return { error: 'session is not attached to a registered workspace (cannot resolve control-plane root)' } as const
-      }
-      const result = recursive.closeoutRun(root, args.runId.trim(), args.phase.trim())
-      return result as unknown as JsonValue
-    },
-  })
-}
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { toolError } from './errors.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * `recursive_closeout` — scaffold a Phase 0-8 closeout receipt under the
+ * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
+ * via the session agent's cwd -> workspace registry; a runId outside the current
+ * workspace is rejected.
+ */
+export function createRecursiveCloseoutTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_closeout',
+    description: 'REPORT what a closeout phase artifact is missing (Phase 4-8): it reads the artifact, lists the required sections and gates that are absent, and records a closeout receipt of its own. It NEVER writes the phase document. For a run in the CURRENT session workspace only. Workspace-scoped: refuses runIds outside the session\'s workspace. Delegates to the RecursiveRuntime service.',
+    parameters: {
+    phase: { type: 'string', description: 'Closeout phase to report on: 04, 05, 06, 07 or 08 (the same phase keys recursive_status prints). Phase 08 additionally fires the training trigger when it has been closed out before.' },
+      runId: { type: 'string', description: 'Run id (e.g. 03-something). Required. Must resolve inside the current workspace.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { phase?: string; runId?: string }, exec) {
+      if (!args.phase || !args.runId || args.runId.trim() === '') {
+        return { error: toolError('MISSING_PHASE_AND_RUN') } as const
+      }
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) {
+        return { error: toolError('NO_WORKSPACE') } as const
+      }
+      const result = await recursive.closeoutRun(root, args.runId.trim(), args.phase.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      return result as unknown as JsonValue
+    },
+  })
+}

package/src/recursive_delegate.tool.ts

@@ -0,0 +1,194 @@
+/**
+ * `recursive_delegate` — FU-17: the reachable caller that lets the main agent hand a phase's ACTUAL WORK to a
+ * child, read what came back, and send feedback to the SAME child so it repairs with its working set intact.
+ *
+ * ⚠ WHY THIS IS NOT `recursive_review`, and the difference is the whole point. A review JUDGES an artifact that
+ * exists. Work PRODUCES it. Three consequences follow, and each of them is a defect if ignored:
+ *
+ *  1. THIS TOOL DOES NOT REQUIRE THE ARTIFACT TO EXIST. Phase 01 as-is is delegated BEFORE its artifact does —
+ *     the work is what creates it — so requiring the file would make the tool refuse exactly the case it is for.
+ *  2. THE CHILD IS BRIEFED ON THE STANDARD, NOT ON ANTI-PATTERNS. `buildWorkSlice` composes the required
+ *     sections from the phase rules, so the child is told what its output will be linted against. A worker that
+ *     has never seen the gate cannot meet it.
+ *  3. THE CHILD IS GIVEN A WRITE-CAPABLE FILTER. `delegateReview` defaults to
+ *     `{ allow: ['fs_read', 'grep', 'glob'] }` — correct for a reviewer, fatal for a worker, and SILENT either
+ *     way: a worker with a read-only filter reports a perfectly healthy delegation while being unable to write a
+ *     single file. See `WORK_TOOL_FILTER` for why the override is a deny list.
+ *
+ * ⚠ THE PARENT KEEPS THE DECISION. This tool starts work and reports what came back; it never writes the phase
+ * artifact itself and never locks anything. The main agent reads the reply, verifies it, and either accepts it —
+ * recording that in `## Subagent Contribution Verification` — or calls this tool again with `feedback`, which
+ * goes to the same child. That division is what the phase contract is built on.
+ *
+ * ⚠ ONE TRANSITION PER CALL, like `recursive_review` and `recursive_audit_team`: the harness has no parent-side
+ * await-settlement promise, so this cannot be one call that waits for a deliverable that arrives on a later turn.
+ * The durable state carries the child id between calls.
+ */
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { toLosslessJson } from './json-safe.ts'
+import type { RecursiveRuntime } from './runtime.ts'
+import { codeRuntimeRefusal, toolError } from './errors.ts'
+import { buildWorkSlice } from './handoff.ts'
+import { advanceReview } from './review-round.ts'
+import { settlementRoundObserver } from './settlement.ts'
+import { CURRENT_WORKFLOW_PROFILE, getArtifactRequiredSections } from './phase-rules.ts'
+import type { SubagentParentHandle, SubagentsRuntimeLike } from './delegation.ts'
+import { readReplyText, toContinuable } from './recursive_review.tool.ts'
+
+/**
+ * ⚠ FU-17 — THE WORK TOOL FILTER, AND WHY IT IS A DENY LIST RATHER THAN AN ALLOW LIST.
+ *
+ * `delegateReview` applies `input.toolFilter ?? defaultReviewToolFilter()` and that default is
+ * `{ allow: ['fs_read', 'grep', 'glob'] }`. So a work delegation that passes nothing receives a child that
+ * cannot write — and nothing about the outcome would say so.
+ *
+ * The obvious fix is an allow list of the writing tools, and it is the wrong one: it has to name EVERY tool a
+ * worker might need (`bash`, `pwsh`, `str_replace_editor`, `session_search`, `session_event_read`, `skill`,
+ * `load_workspace_dependencies`, `present`, …) and it SILENTLY REMOVES capability for each name forgotten.
+ * That is the same defect class this project has already fixed ten times: a surface that cannot express what
+ * the system can do, failing quietly.
+ *
+ * `deny` states the actual posture instead: a delegated worker may use everything EXCEPT spawning its own
+ * children and driving the team board. That is what the workflow wants — no recursive fan-out from a worker and
+ * no contention over the audit board — and it cannot lose a tool by omission. The host accepts `allow` and/or
+ * `deny` (`subagent/src/descriptor.ts`), throwing only when neither is declared.
+ */
+export const WORK_TOOL_FILTER: unknown = {
+  deny: ['spawn_teammate', 'team_task_create', 'team_task_update', 'interrupt_agent'],
+}
+
+export function createRecursiveDelegateTool(recursive: RecursiveRuntime, subagents?: SubagentsRuntimeLike) {
+  return defineTool({
+    name: 'recursive_delegate',
+    description:
+      'Delegate the WORK of a phase to a durable continuable subagent: it produces the content and writes its '
+      + 'submission to reply.md, and YOU remain the judge. Unlike recursive_review this does NOT require the '
+      + 'artifact to exist — delegating the work for a phase whose artifact is empty or absent is the normal '
+      + 'case. It reports `submitted` when the child delivered, `reviewing` while it is still working, and '
+      + '`unavailable` when no continuable child could be used. When the work is not good enough, call this tool '
+      + 'again with `feedback`: it is delivered to the SAME child, which repairs with its context intact. It '
+      + 'never writes the artifact and never locks anything.',
+    parameters: {
+      runId: { type: 'string', description: 'Optional run id (defaults to the latest run by mtime).' },
+      phase: { type: 'string', description: 'Phase key whose work is being delegated (e.g. 03). Defaults to the run\'s current phase.' },
+      role: { type: 'string', description: 'Worker role to route (default: analyst). Must be enabled in the router policy, or the router falls back to self-audit and says so.' },
+      instruction: { type: 'string', description: 'What the child must produce, in your words. Required to start work; omit it when only resuming or sending feedback.' },
+      feedback: { type: 'string', description: 'What is wrong with the submitted work. Delivered to the SAME child, which repairs it.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(
+      args: { runId?: string; phase?: string; role?: string; instruction?: string; feedback?: string },
+      exec,
+    ) {
+      try {
+        const root = await recursive.resolveWorkspaceRoot(exec.agent)
+        if (!root) return { error: toolError('NO_WORKSPACE') } as const
+
+        const status = await recursive.status(args.runId, exec.agent)
+        if (!status) return { error: toolError('NO_RUN') } as const
+        const runId = status.runId
+
+        const phase = args.phase?.trim() || status.currentPhase?.key || ''
+        if (phase === '') return { error: toolError('NO_PHASE') } as const
+        const row = status.phases.find((p) => p.key === phase)
+        // ⚠ NO `row.exists` CHECK — and that is deliberate, not an omission. A review needs an artifact to judge;
+        // work is often what CREATES one. The FILE NAME is what this tool needs, and the status row carries it
+        // whether or not the file is on disk yet.
+        if (row === undefined) {
+          return { error: toolError('NO_PHASE', 'unknown phase ' + phase + ' for this run') } as const
+        }
+
+        const running = args.feedback === undefined || args.feedback.trim() === ''
+        // ⚠ NO REFUSAL FOR A MISSING INSTRUCTION, and this is a design choice rather than laziness. The brief
+        // already carries the real requirement — the phase's required sections, composed from the phase rules —
+        // so a caller with nothing extra to say still gets a child that knows what to produce. Inventing a new
+        // refusal code would also mean a new registry entry (`TOOL_ERRORS`, whose codes are grouped and asserted
+        // unique), for a case that is better served by a default than by an error.
+        const instruction = (args.instruction ?? '').trim() !== ''
+          ? (args.instruction ?? '').trim()
+          : 'Produce the content this phase\'s artifact requires, following the required sections in your brief.'
+        void running
+
+        const role = args.role?.trim() || 'analyst'
+        const delegationId = phase + '-work'
+        const runDir = join(root, '.recursive', 'run', runId)
+        const artifactPath = join(runDir, row.file)
+        const parent = exec.agent as unknown as SubagentParentHandle
+
+        const outcome = await advanceReview({
+          runDir,
+          delegationId,
+          phase,
+          role,
+          // ⚠ FU-17 — THE KIND IS WHAT SEPARATES A DELIVERABLE FROM A VERDICT. A work round must not have an
+          // APPROVE read out of prose that was never a verdict.
+          kind: 'work',
+          // The main agent's feedback, when it has any: delivered to the SAME child by the driver.
+          ...(args.feedback === undefined ? {} : { instruction: args.feedback }),
+          delegate: async ({ resumeChild }) => {
+            // A resumed round keeps the child it was given; a fresh round reserves an id up front so the
+            // brief/prompt paths and the session agree from the first call (`ctx.agents.create` accepts a
+            // reserved id).
+            const childId = resumeChild ?? randomUUID()
+            // ⚠ FU-18 — AND THE RUNTIME IS TOLD IT IS A CONTINUATION. Without this the delegation carries the
+            // same operation identity as the round that already ran, the T19 guard sees an accepted operation
+            // against an unchanged artifact and REFUSES — which is precisely the call that starts a repair.
+            const continuing = resumeChild !== undefined
+            const work = await recursive.delegateReview({
+              root,
+              runId,
+              phase,
+              role,
+              delegationId,
+              childId,
+              artifactPath,
+              upstreamArtifacts: [],
+              auditQuestions: [],
+              requiredOutput: 'Write your submission to reply.md, then call the report tool citing reply.md.',
+              // ⚠ THE BRIEF IS THE PHASE STANDARD, composed from the same source the linter reads. Building a
+              // second copy here is how a brief and a linter drift apart. On a RESUME the child already has its
+              // brief, so the slice is omitted rather than rewritten.
+              ...(resumeChild === undefined
+                ? {
+                  slice: buildWorkSlice({
+                    instruction,
+                    artifactFile: row.file,
+                    phase,
+                    requiredSections: getArtifactRequiredSections(row.file, CURRENT_WORKFLOW_PROFILE),
+                  }),
+                }
+                : {}),
+              // ⚠ AND THE CHILD MAY WRITE. Without this the worker is a reviewer with a read-only filter.
+              toolFilter: WORK_TOOL_FILTER,
+              subagents,
+              parent,
+              mode: 'continuable',
+              kind: 'work',
+              continuing,
+              awaitRoundResult: settlementRoundObserver(runDir),
+            })
+            return toContinuable(work)
+          },
+          readReply: (childId) => readReplyText(root, runId, delegationId, childId),
+          sendRepair: async (childId, repair) => {
+            const followup = subagents?.followup
+            if (followup === undefined) throw new Error('no continuable followup seam')
+            await followup(parent, childId, [{ type: 'text', text: repair }], {
+              source: { kind: 'coordinator', form: 'relay', senderSessionId: parent?.id ?? '' },
+            })
+          },
+        })
+        const projected = toLosslessJson(outcome)
+        return (projected ?? { error: codeRuntimeRefusal('the delegation produced no JSON-representable result') }) as JsonValue
+      } catch (err) {
+        return { error: codeRuntimeRefusal(err instanceof Error ? err.message : String(err)) } as const
+      }
+    },
+  })
+}

package/src/recursive_init.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import { codeRuntimeRefusal, toolError } from './errors.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
 export function createRecursiveInitTool(recursive: RecursiveRuntime) {
@@ -17,7 +18,7 @@ export function createRecursiveInitTool(recursive: RecursiveRuntime) {
     },
     async execute(args: { runId?: string; createWorktree?: boolean; baseBranch?: string }, exec) {
       if (!args.runId || args.runId.trim() === '') {
-        return { error: 'runId is required' } as const
+        return { error: toolError('MISSING_RUN_ID') } as const
       }
       try {
         const result = await recursive.initRun(
@@ -27,7 +28,7 @@ export function createRecursiveInitTool(recursive: RecursiveRuntime) {
         )
         return result as unknown as JsonValue
       } catch (err) {
-        return { error: err instanceof Error ? err.message : String(err) } as const
+        return { error: codeRuntimeRefusal(err instanceof Error ? err.message : String(err)) } as const
       }
     },
   })

package/src/recursive_lint.tool.ts

@@ -1,28 +1,103 @@
+/**
+ * T24 — bounded, coded results and refusals for `recursive_lint`.
+ *
+ * Two contracts are enforced here:
+ *
+ *  1. THE RESULT IS BOUNDED. `errors`/`warnings` are clipped to a named cap and
+ *     every clip is reported through `elided[]` (`src/result-cap.ts`), so a
+ *     reader can always tell a complete result from a clipped one. `mode`
+ *     chooses the budget: `full` (default, up to MAX_FINDINGS_FULL per list) or
+ *     `summary` (a few findings plus the true totals, for a turn that only needs
+ *     to know whether the artifact passes).
+ *
+ *  2. EVERY REFUSAL IS CODED AND ROUTED. Errors come from `src/errors.ts`, so a
+ *     failure is one greppable sentence naming the call that resolves it. A
+ *     runtime refusal is WRAPPED rather than passed through raw: a bare thrown
+ *     message carries no stable code for a consumer to branch on, and the
+ *     wrapper preserves the original sentence as its detail.
+ */
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
+import { codeRuntimeRefusal, toolError } from './errors.ts'
+import { DEFAULT_BUDGETS } from './enforcement.ts'
+import { MAX_FINDINGS_FULL, MAX_FINDINGS_SUMMARY, elideFindings, capPayloadBytes, type ElisionMeta } from './result-cap.ts'
+
+type LintMode = 'summary' | 'full'
+
+/** The wire shape this tool returns (bounded by construction). */
+interface CappedLintResult {
+  artifact: string
+  runId: string
+  passed: boolean
+  mode: LintMode
+  /** Totals BEFORE clipping — a reader must be able to see the real size. */
+  failCount: number
+  warnCount: number
+  errors: string[]
+  warnings: string[]
+  /** Empty when nothing was clipped; otherwise one marker per clipped list. */
+  elided: ElisionMeta[]
+}
 
 export function createRecursiveLintTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_lint',
-    description: 'Lint a recursive-mode run artifact for phase-specific issues (gates, TODO, traceability, diff audit). Delegates to the RecursiveRuntime service.',
+    description: 'Lint a recursive-mode run artifact for phase-specific issues (gates, TODO, traceability, diff audit). Delegates to the RecursiveRuntime service. The result is bounded: when findings are clipped, `elided` says how many and how to see the rest.',
     parameters: {
       runId: { type: 'string', description: 'Run id. Required.' },
       artifact: { type: 'string', description: 'Optional artifact file name; defaults to the current phase.' },
+      mode: { type: 'string', description: "Result budget: 'full' (default, up to 200 findings per list) or 'summary' (a few findings plus the true totals)." },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args: { runId?: string; artifact?: string }, exec) {
+    async execute(args: { runId?: string; artifact?: string; mode?: string }, exec) {
       if (!args.runId || args.runId.trim() === '') {
-        return { error: 'runId is required' } as const
+        return { error: toolError('MISSING_RUN_ID') } as const
       }
+      const mode: LintMode = args.mode === 'summary' ? 'summary' : 'full'
+      const cap = mode === 'summary' ? MAX_FINDINGS_SUMMARY : MAX_FINDINGS_FULL
       try {
         const result = await recursive.lintArtifact(args.runId.trim(), args.artifact?.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
-        return result as unknown as JsonValue
+        const raw = result as unknown as { artifact?: string; runId?: string; passed?: boolean; errors?: string[]; warnings?: string[] }
+        const sourceErrors = raw.errors ?? []
+        const sourceWarnings = raw.warnings ?? []
+        const errors = elideFindings('errors', sourceErrors, cap)
+        const warnings = elideFindings('warnings', sourceWarnings, cap)
+        const elided: ElisionMeta[] = []
+        if (errors.meta) elided.push(errors.meta)
+        if (warnings.meta) elided.push(warnings.meta)
+        const bounded: CappedLintResult = {
+          artifact: String(raw.artifact ?? args.artifact ?? ''),
+          runId: String(raw.runId ?? args.runId.trim()),
+          passed: Boolean(raw.passed),
+          mode,
+          // Totals, never the clipped length: a reader must see the real size.
+          failCount: sourceErrors.length,
+          warnCount: sourceWarnings.length,
+          errors: errors.kept,
+          warnings: warnings.kept,
+          elided,
+        }
+        // T28: the BYTE budget, applied after the count budget. T24's cap bounds how
+        // MANY findings come back and cannot see size, so one enormous finding passes
+        // it; this bounds the serialized payload. Both report through `elided[]`, so a
+        // reader can always tell a complete result from a clipped one.
+        // T28: the byte budget comes from the config, so it is reviewable and
+        // configurable rather than another hardcoded constant.
+        //
+        // Read DEFENSIVELY: this tool only needs `lintArtifact`, and a caller that
+        // supplies a narrower runtime (a test stub, a host that mounts the tool
+        // without the full service) must still get a bounded result. An unavailable
+        // config falls back to the documented default instead of throwing — the cap
+        // is a safety bound, and a safety bound that can be disabled by an absent
+        // config is not one.
+        const maxResultBytes = recursive.enforcementConfig?.budgets?.maxResultBytes ?? DEFAULT_BUDGETS.maxResultBytes
+        return capPayloadBytes(bounded, maxResultBytes) as unknown as JsonValue
       } catch (err) {
-        return { error: err instanceof Error ? err.message : String(err) } as const
+        return { error: codeRuntimeRefusal(err instanceof Error ? err.message : String(err)) } as const
       }
     },
   })

package/src/recursive_lock.tool.ts

@@ -1,5 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import { codeRuntimeRefusal, toolError } from './errors.ts'
+import { buildAskQuestion } from './recursive_ask.tool.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
 export function createRecursiveLockTool(recursive: RecursiveRuntime) {
@@ -17,16 +19,31 @@ export function createRecursiveLockTool(recursive: RecursiveRuntime) {
     },
     async execute(args: { runId?: string; artifact?: string; reopen?: boolean }, exec) {
       if (!args.runId || args.runId.trim() === '') {
-        return { error: 'runId is required' } as const
+        return { error: toolError('MISSING_RUN_ID') } as const
       }
       if (!args.artifact || args.artifact.trim() === '') {
-        return { error: 'artifact is required' } as const
+        return { error: toolError('MISSING_ARTIFACT') } as const
       }
       try {
         const result = await recursive.lockArtifact(args.runId.trim(), args.artifact.trim(), args.reopen === true, exec.agent as { session?: { header?: { cwd?: string } } } | null)
         return result as unknown as JsonValue
       } catch (err) {
-        return { error: err instanceof Error ? err.message : String(err) } as const
+        const message = err instanceof Error ? err.message : String(err)
+        const refusal = codeRuntimeRefusal(message)
+        // FU-7 — THE GATE-BLOCK CALL POINT, and this is the moment it belongs to: a lock was REFUSED, so
+        // the run is blocked and a person has to choose how to unblock it. Returning only the sentence
+        // makes the caller parse prose to find the decision; the options are what turn it into a choice.
+        //
+        // ⚠ IT IS ATTACHED TO THE ORDERING REFUSAL SPECIFICALLY (`Prerequisite blockers:`), because that
+        // is the one a human resolves. A missing run id or an already-locked artifact is a caller mistake
+        // with a mechanical fix, and offering "reopen / abandon the run" for those would be noise.
+        if (message.startsWith('Prerequisite blockers:')) {
+          return {
+            error: refusal,
+            ask: { gate: 'gate-block', ...buildAskQuestion('gate-block'), artifact: args.artifact ?? '', blocked: message },
+          } as unknown as JsonValue
+        }
+        return { error: refusal } as const
       }
     },
   })

package/src/recursive_phase.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import { toolError } from './errors.ts'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
 /**
@@ -22,7 +23,7 @@ export function createRecursivePhaseTool(recursive: RecursiveRuntime) {
     },
     async execute(args: { runId?: string }, exec) {
       const result = await recursive.phaseRules(args.runId, exec.agent as { session?: { header?: { cwd?: string } } } | null)
-      if (!result) return { error: 'no recursive phase found' } as const
+      if (!result) return { error: toolError('NO_PHASE') } as const
       return result as unknown as JsonValue
     },
   })

package/src/recursive_preview.tool.ts

@@ -0,0 +1,142 @@
+/**
+ * T26 — `recursive_preview`: see the enforcement contract BEFORE it fires.
+ *
+ * WHY. There is no way to see what the policy section will render, which rule a tool call will match,
+ * or what the next legal transition requires — until it happens. That makes *enforce, don't just
+ * describe* unverifiable by the person it is enforced on: a rule nobody can inspect in advance is
+ * indistinguishable from a rule that does not exist.
+ *
+ * ⚠ IT MAKES NO MODEL CALL, and that is a property rather than a happy accident: every part of this
+ * module is filesystem reads plus the SAME pure functions the enforcement path uses
+ * (`renderStableContract` / `renderPhaseTail` / `contractDigest` from T22, `getNextLegalPhase` from
+ * the lock chain, `phaseRulesFor` from the lint rules, `evaluateToolGuard` from the guard). A preview
+ * that asked a model what would happen would be a DESCRIPTION of enforcement, which is exactly what
+ * the item exists to replace.
+ *
+ * ⚠ AND IT REUSES THE ENFORCEMENT PATH RATHER THAN RESTATING IT. The probe calls `evaluateToolGuard`
+ * — the same function the real `pre-execute` listener calls — so the rule it names is the rule that
+ * WOULD fire, not a second opinion that can drift from it.
+ */
+import { existsSync } from 'node:fs'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { toolError } from './errors.ts'
+import { evaluateToolGuard } from './enforcement.ts'
+import { getNextLegalPhase } from './lock.ts'
+import { phaseRulesFor } from './phase-rules.ts'
+import { renderStableContract, renderPhaseTail, contractDigest } from './policy.ts'
+import type { EnforcementConfig } from './enforcement.ts'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/** A tool call the caller wants to preview the guard's decision for. */
+export interface PreviewProbe {
+  name: string
+  arguments?: Record<string, unknown>
+}
+
+export interface PreviewResult {
+  /** T22: the byte-identical prefix, the per-phase tail, and the local identifier. */
+  policy: { stable: string; tail: string; digest: string }
+  /** What the phase being worked on requires, from the same rules the linter enforces. */
+  phase: { file: string; requiredSections: string[]; audited: boolean; tdd: boolean; qa: boolean } | null
+  /** The next legal transition, or null when nothing is pending. */
+  next: { phase: string; requiredSections: string[] } | null
+  /** What the guard WOULD decide for a probe call — the rule that would fire, by name. */
+  probe: { kind: string; rule: string; reason?: string } | null
+}
+
+/**
+ * Build the preview. Pure apart from the run-directory reads it is given.
+ *
+ * `next` is `null` for a completed run rather than a fabricated phase: "nothing is pending" is a fact
+ * a reader needs, and inventing the last phase as "next" would be the opposite of a preview.
+ */
+export function buildPreview(input: {
+  root: string
+  runId: string
+  config: EnforcementConfig
+  probe?: PreviewProbe
+}): PreviewResult {
+  const nextPhase = getNextLegalPhase(input.root + '/.recursive/run/' + input.runId) ?? null
+  const rules = nextPhase === null ? null : phaseRulesFor(nextPhase)
+
+  const probe = input.probe === undefined
+    ? null
+    : (() => {
+        const decision = evaluateToolGuard(
+          { name: input.probe.name, arguments: input.probe.arguments ?? {} } as never,
+          input.root,
+          input.runId,
+          input.config.toolGuards,
+        )
+        const asRecord = decision as unknown as { kind: string; rule?: string; reason?: string }
+        return {
+          kind: asRecord.kind,
+          // A decision with no rule is reported as `none` rather than omitted, so "no rule matched"
+          // and "the preview forgot to look" cannot be confused.
+          rule: asRecord.rule ?? 'none',
+          ...(asRecord.reason === undefined ? {} : { reason: asRecord.reason }),
+        }
+      })()
+
+  return {
+    policy: {
+      stable: renderStableContract(input.config),
+      tail: renderPhaseTail(null),
+      digest: contractDigest(input.config),
+    },
+    phase: rules === null
+      ? null
+      : {
+          file: rules.fileName,
+          requiredSections: [...rules.requiredSections],
+          audited: rules.audited,
+          tdd: rules.tdd,
+          qa: rules.qa,
+        },
+    next: nextPhase === null || rules === null
+      ? null
+      : { phase: nextPhase, requiredSections: [...rules.requiredSections] },
+    probe,
+  }
+}
+
+/** `recursive_preview` — the read-only view, registered as a tool so it is one call away. */
+export function createRecursivePreviewTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_preview',
+    description: 'Show what the recursive-mode enforcement contract will do BEFORE it fires: the rendered policy prefix and its digest, the current phase\'s required sections and gates, the next legal transition, and the guard rule a probe tool call would match. Read-only: it reads the run directory and the same pure functions the enforcement path uses, and makes no model call.',
+    parameters: {
+      runId: { type: 'string', description: 'Run id. Required; must resolve inside the current workspace.' },
+      probeTool: { type: 'string', description: 'Optional tool name to preview the guard decision for (e.g. recursive_lock).' },
+      probeArguments: { type: 'string', description: 'Optional JSON object of arguments for the probe call.' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string; probeTool?: string; probeArguments?: string }, exec) {
+      const runId = args.runId?.trim() ?? ''
+      if (runId === '') return { error: toolError('MISSING_RUN_ID') } as const
+      const root = await recursive.resolveWorkspaceRoot(exec.agent)
+      if (!root) return { error: toolError('NO_WORKSPACE') } as const
+      if (!existsSync(root + '/.recursive/run/' + runId)) {
+        return { error: toolError('MISSING_RUN_ID', 'no run directory for ' + runId) } as const
+      }
+      let probe: PreviewProbe | undefined
+      if (args.probeTool !== undefined && args.probeTool.trim() !== '') {
+        let parsed: Record<string, unknown> = {}
+        if (args.probeArguments !== undefined && args.probeArguments.trim() !== '') {
+          try {
+            parsed = JSON.parse(args.probeArguments) as Record<string, unknown>
+          } catch {
+            return { error: toolError('BAD_PROBE_ARGUMENTS') } as const
+          }
+        }
+        probe = { name: args.probeTool.trim(), arguments: parsed }
+      }
+      const preview = buildPreview({ root, runId, config: recursive.enforcementConfig, ...(probe === undefined ? {} : { probe }) })
+      return preview as unknown as JsonValue
+    },
+  })
+}