iterate-plugin 2.10.0 → 2.12.0

package/dist/live.js

@@ -0,0 +1,155 @@
+/**
+ * src/live.ts — live reviewer-activity feed for the iterate observatory (F1 live).
+ *
+ * Watches `tools/result` and, for tool calls we can attribute to a project root
+ * (the caller agent's session cwd), appends one line to an append-only NDJSON
+ * file `.iterate/transcript-live.ndjson`. The `iterate_transcript` tool then
+ * mixes the most recent entries into its `read` / `capture` results so the
+ * client observatory shows what reviewers are doing in near-real-time (which
+ * files they read, which fixes/rollbacks/diffs land, where the run is).
+ *
+ * Why project-scoped (not per-thread):
+ *   Tool executions carry the calling agent's session cwd but NOT the workflow
+ *   sub-agent's `dimension` / `round` label, so we cannot reliably attribute a
+ *   read to a specific reviewer thread without inventing data. We therefore
+ *   record honest project-level activity and never fabricate an attribution.
+ *   Per-thread narration stays the job of the final `iterate_transcript capture`.
+ *
+ * Safety:
+ *   - Read-only observer: never mutates source files; writes only the NDJSON
+ *     live file under `.iterate/`.
+ *   - The live file is byte-capped (rewrite to last N lines when it grows too
+ *     large) so it can never grow unbounded.
+ *   - Any capture failure is swallowed (fire-and-forget) so it can never block
+ *     or crash a tool call.
+ */
+import { mkdir, readFile, writeFile, stat, appendFile, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveProjectRoot } from "./config-loader.js";
+/** Keep at most this many live activity entries. */
+export const LIVE_MAX_ENTRIES = 300;
+/** Rewrite the live file when its byte size exceeds this threshold. */
+export const LIVE_MAX_BYTES = 64 * 1024;
+/** File path of the live NDJSON feed for a project root. */
+export function liveFilePath(projectRoot) {
+    return join(projectRoot, '.iterate', 'transcript-live.ndjson');
+}
+/** Resolve the project root a tool execution belongs to, if any. */
+function projectRootOf(exec) {
+    const cwd = exec.agent?.session?.header?.cwd;
+    if (!cwd)
+        return null;
+    const resolved = resolveProjectRoot(undefined, cwd);
+    return resolved.ok ? resolved.root : null;
+}
+/** Classify a settled tool call into a live activity entry, or null to skip. */
+export function classifyTool(name, args, projectRoot) {
+    // `read_file` is the dsh-native file reader reviewers use to inspect code.
+    if (name === 'read_file') {
+        const file = args && typeof args === 'object' && typeof args.path === 'string'
+            ? args.path
+            : '';
+        return file ? { ts: new Date().toISOString(), type: 'read', tool: name, target: file } : null;
+    }
+    // The iterate plugin's own tools — surface what the workflow is doing live.
+    const records = {
+        iterate_fix: 'fix',
+        iterate_rollback: 'rollback',
+        iterate_diff: 'diff',
+        iterate_review: 'review',
+        iterate_triage: 'triage',
+        iterate_checkpoint: 'checkpoint',
+        iterate_validate: 'validate',
+        iterate_decision_log: 'log',
+        iterate_history: 'info',
+        iterate_prune: 'prune',
+        iterate_transcript: 'log',
+        iterate_status: 'info',
+        iterate_config: 'info',
+        iterate_context: 'info',
+    };
+    const type = records[name];
+    if (!type)
+        return null;
+    let target = '';
+    if (args && typeof args === 'object') {
+        const a = args;
+        if (typeof a.file === 'string' && a.file)
+            target = a.file;
+        else if (typeof a.path === 'string' && a.path)
+            target = a.path;
+        else if (typeof a.operation === 'string' && a.operation)
+            target = a.operation;
+        else if (name === 'iterate_rollback' && typeof a.id === 'string' && a.id) {
+            target = `fix ${a.id}`;
+        }
+    }
+    if (!target)
+        target = name;
+    return { ts: new Date().toISOString(), type, tool: name, target };
+}
+/** Append one activity record to the project's live feed (byte-capped). */
+export async function appendLive(projectRoot, entry) {
+    const file = liveFilePath(projectRoot);
+    const line = JSON.stringify(entry) + '\n';
+    await mkdir(join(projectRoot, '.iterate'), { recursive: true });
+    // Amortized O(1): only read+rewrite when the file has grown past the cap.
+    try {
+        const st = await stat(file).catch(() => null);
+        if (st && st.size > LIVE_MAX_BYTES) {
+            const raw = await readFile(file, 'utf-8');
+            const lines = raw.split('\n').filter(Boolean);
+            const tail = lines.slice(-LIVE_MAX_ENTRIES);
+            const tmp = `${file}.trim.tmp`;
+            await writeFile(tmp, tail.join('\n') + '\n', 'utf-8');
+            await rename(tmp, file);
+        }
+        await appendFile(file, line, 'utf-8');
+    }
+    catch {
+        // Fire-and-forget: never let live capture break a tool call.
+    }
+}
+/** Read the live feed (newest first), capped at the last LIVE_MAX_ENTRIES. */
+export async function readLive(projectRoot) {
+    const file = liveFilePath(projectRoot);
+    if (!existsSync(file))
+        return [];
+    try {
+        const raw = await readFile(file, 'utf-8');
+        const entries = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed && typeof parsed.ts === 'string' && typeof parsed.type === 'string') {
+                    entries.push(parsed);
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return entries.slice(-LIVE_MAX_ENTRIES).reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Register a `tools/result` observer that captures reviewer activity into the
+ * project's live feed. Fire-and-forget; failures are swallowed.
+ */
+export function registerLiveCapture(ctx) {
+    ctx.on('tools/result', (exec) => {
+        const root = projectRootOf(exec);
+        if (!root)
+            return;
+        const entry = classifyTool(exec.name, exec.arguments, root);
+        if (!entry)
+            return;
+        void appendLive(root, entry);
+    });
+}

package/dist/meta-review.js

@@ -14,8 +14,13 @@
  * lives here.
  */
 import { sortFindings } from "./review.js";
-/** Number of distinct consistency checks performed by `metaReviewReport`. */
-export const META_REVIEW_CHECKS = 6;
+/**
+ * Number of distinct consistency checks performed by `metaReviewReport`.
+ * The check set is: COUNT_MATCH, SEVERITY_SUM, DIMENSION_SUM, DIMENSION_UNKNOWN,
+ * SORT_ORDER, CONVERGENCE_SUM, CONVERGENCE_FLAG, ROUND_NUMBER, ROUND_EMPTY,
+ * ROUND_GAP.
+ */
+export const META_REVIEW_CHECKS = 10;
 /**
  * How many uncovered scope files are listed in a COVERAGE_GAP hint before the
  * remainder is folded into a "+N more" suffix.
@@ -146,9 +151,18 @@ export function metaReviewReport(report) {
                 'which finding nothing new is the expected success signal.');
         }
     }
-    for (let i = 1; i <= rounds.length; i++) {
-        if (!seenRounds.has(i)) {
-            add('ROUND_GAP', 'medium', `Round ${i} is missing from the round sequence`, `rounds present: ${[...seenRounds].sort((a, b) => a - b).join(', ') || 'none'}.`);
+    // ROUND_GAP: only flag gaps WITHIN the range of actually-present round
+    // numbers. Non-contiguous starts (e.g. a resumed run beginning at round 5)
+    // and arbitrary round numbering are supported by the aggregate engine, so
+    // missing 1..N prefixes are NOT defects. Checks min..max of present rounds.
+    const present = [...seenRounds].sort((a, b) => a - b);
+    if (present.length > 0) {
+        const min = present[0];
+        const max = present[present.length - 1];
+        for (let i = min; i <= max; i++) {
+            if (!seenRounds.has(i)) {
+                add('ROUND_GAP', 'medium', `Round ${i} is missing from the round sequence`, `rounds present: ${present.join(', ')}.`);
+            }
         }
     }
     const passed = issues.length === 0;

package/dist/method-scope.js

@@ -70,6 +70,8 @@ const SIGNATURE_PATTERNS = [
 export function collectMethodSignatures(text) {
     const lines = text.split('\n');
     const out = [];
+    // Set lookup instead of scanning the growing array (O(S²) → O(S)).
+    const seen = new Set();
     for (let i = 0; i < lines.length; i++) {
         const raw = lines[i];
         const line = i + 1;
@@ -81,8 +83,10 @@ export function collectMethodSignatures(text) {
             if (!name || RESERVED_WORDS.has(name) || CALLABLE_NOISE.has(name))
                 continue;
             // Avoid two patterns claiming the same line (e.g. TS method + arrow).
-            if (out.some((s) => s.line === line && s.name === name))
+            const key = `${line}|${name}`;
+            if (seen.has(key))
                 break;
+            seen.add(key);
             out.push({ name, line });
             break;
         }

package/dist/paths.js

@@ -30,3 +30,7 @@ export function fixBackupPath(projectRoot, id, timestamp) {
 export function checkpointPath(projectRoot) {
     return join(iterateDir(projectRoot), 'checkpoint.json');
 }
+/** Runtime-observatory transcript file (JSON). */
+export function transcriptPath(projectRoot) {
+    return join(iterateDir(projectRoot), 'transcript.json');
+}

package/dist/review-scope.js

@@ -99,22 +99,25 @@ function collectChanged(changedFiles) {
     return [...out].sort();
 }
 function collectFull(root) {
-    // Deterministic recursive walk built on Node's fs; a code reviewer never
-    // anchors findings to lock files, images, or vendored builds.
+    // Deterministic iterative walk (explicit stack — unbounded recursion could
+    // overflow on pathologically deep trees); a code reviewer never anchors
+    // findings to lock files, images, or vendored builds.
     const out = [];
-    const walk = (dir) => {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            return;
+            continue;
         }
         for (const entry of entries) {
             const abs = join(dir, entry.name);
             if (entry.isDirectory()) {
                 if (!isIgnoredDir(entry.name))
-                    walk(abs);
+                    stack.push(abs);
                 continue;
             }
             if (!entry.isFile())
@@ -124,13 +127,14 @@ function collectFull(root) {
             const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs;
             out.push(rel.split(SEP).join(SEP));
         }
-    };
-    walk(root);
+    }
     return out.sort();
 }
 /** Split `files` into stable batches, keeping directory runs together. */
 export function chunkFiles(files, perChunk) {
-    const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk;
+    // Number.isFinite: NaN fails `perChunk < 1` and would yield one unbounded
+    // chunk (current.length >= NaN is never true).
+    const size = Number.isFinite(perChunk) && perChunk >= 1 ? perChunk : DEFAULT_SCOPE_CHUNK_SIZE;
     const ordered = [...files].sort();
     const chunks = [];
     let current = [];

package/dist/review.js

@@ -35,10 +35,12 @@ export function sortFindings(findings) {
         const bySeverity = rankA - rankB;
         if (bySeverity !== 0)
             return bySeverity;
-        const byFile = a.file.localeCompare(b.file);
+        // Defensive coercion: `file`/`line` can be wrong-typed when schema
+        // validation is disabled — String()/Number() keep the comparator total.
+        const byFile = String(a.file ?? '').localeCompare(String(b.file ?? ''));
         if (byFile !== 0)
             return byFile;
-        return (a.line ?? 0) - (b.line ?? 0);
+        return (Number(a.line) || 0) - (Number(b.line) || 0);
     });
 }
 /** Normalize a summary so near-identical duplicates collapse to one key. */
@@ -48,9 +50,15 @@ export function normalizeSummary(summary) {
         .toLowerCase()
         .replace(/[\s\n\t]+/g, ' ');
 }
-/** Dedupe key: same file + same dimension + similar summary. */
+/**
+ * Dedupe key: same file + same dimension + similar summary + explicit line.
+ * Including the line keeps two genuine issues with identical wording at
+ * different locations from collapsing into one (the line is omitted only when
+ * neither side anchors one, i.e. whole-file findings).
+ */
 export function findingKey(f) {
-    return `${f.file}|${f.dimension}|${normalizeSummary(f.summary)}`;
+    const line = typeof f.line === 'number' && f.line > 0 ? f.line : 0;
+    return `${f.file}|${f.dimension}|${line}|${normalizeSummary(f.summary)}`;
 }
 /**
  * Remove duplicate findings within a list.
@@ -109,14 +117,22 @@ export function aggregateRounds(rounds, maxReviewRounds) {
     const firstRoundByKey = new Map();
     const merged = [];
     // Guard: round numbers are expected to be positive integers. Skip malformed
-    // entries defensively rather than letting `firstRoundByKey` key on NaN/0.
+    // entries defensively rather than letting `firstRoundByKey` key on NaN/0 or
+    // crashing on null / non-array findings.
+    // Hard ceiling: round numbers are model-authored JSON; an absurd round (e.g.
+    // 1e9) would otherwise allocate an array of that size below (OOM). Round
+    // numbers above the configured cap are clamped to the cap.
     let maxRound = 0;
+    const roundCap = Math.max(1, maxReviewRounds);
     for (const round of rounds) {
+        if (!round || typeof round !== 'object')
+            continue;
         if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
             continue;
+        const findings = Array.isArray(round.findings) ? round.findings : [];
         if (round.round > maxRound)
             maxRound = round.round;
-        for (const f of round.findings) {
+        for (const f of findings) {
             const key = findingKey(f);
             if (seen.has(key))
                 continue;
@@ -125,8 +141,10 @@ export function aggregateRounds(rounds, maxReviewRounds) {
             merged.push(f);
         }
     }
+    // Clamp the allocation bound so a hostile round number cannot OOM the tool.
+    const effectiveMax = Math.min(maxRound, Math.max(1, roundCap * 2));
     const findingsByRound = [];
-    for (let r = 1; r <= maxRound; r++) {
+    for (let r = 1; r <= effectiveMax; r++) {
         let count = 0;
         for (const key of firstRoundByKey.keys()) {
             if (firstRoundByKey.get(key) === r)
@@ -143,11 +161,20 @@ export function computeConvergence(rounds, maxReviewRounds) {
     const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds);
     const totalRounds = rounds.length;
     // `findingsByRound` is indexed by the actual round number (round r → index
-    // r-1), so convergence must read the LAST PRESENT round's count using its
-    // reported round number — not `totalRounds - 1`, which is only valid for
-    // contiguous 1..N round numbers.
-    const lastRound = totalRounds > 0 ? rounds[totalRounds - 1].round : 0;
-    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    // r-1), sized to the highest present round (clamped). Convergence must read
+    // the HIGHEST PRESENT round's count — not the last array element (rounds
+    // may arrive unsorted) and not `totalRounds - 1` (only valid for contiguous
+    // 1..N). The count index is bounded by the array length aggregateRounds
+    // actually allocated.
+    let lastRound = 0;
+    for (const round of rounds) {
+        if (!round || typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
+            continue;
+        if (round.round > lastRound)
+            lastRound = round.round;
+    }
+    const idx = Math.min(lastRound, findingsByRound.length) - 1;
+    const lastRoundCount = idx >= 0 ? (findingsByRound[idx] ?? 0) : 0;
     const converged = totalRounds > 0 && lastRoundCount === 0;
     return {
         totalRounds,
@@ -193,8 +220,9 @@ function summarize(findings) {
 export function buildReviewReport(input) {
     // 1. Filter known-intentional per round (before cross-round dedupe).
     const filteredRounds = input.rounds.map((r) => ({
-        round: r.round,
-        findings: filterKnownIntentional(r.findings, input.knownIntentional),
+        round: typeof r?.round === 'number' ? r.round : 0,
+        findings: filterKnownIntentional(Array.isArray(r?.findings) ? r.findings : [], input.knownIntentional),
+        readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
     }));
     // 2. Cross-round dedupe + per-round "first seen" tracking.
     const { findings, findingsByRound } = aggregateRounds(filteredRounds, input.maxReviewRounds);
@@ -221,6 +249,9 @@ export function buildReviewReport(input) {
         maxReviewRounds: input.maxReviewRounds,
         rounds: filteredRounds,
         findings: sorted,
+        // Aggregate of every round's self-reported reads, so the meta-review
+        // coverage gate can compare against the assigned inventory.
+        readFiles: [].concat(...filteredRounds.map((r) => r.readFiles ?? [])),
         convergence: {
             totalRounds: filteredRounds.length,
             findingsByRound,
@@ -394,8 +425,8 @@ export function validateFindingsSchema(input) {
  */
 export function validateRoundsSchema(rounds) {
     return rounds.map((r) => {
-        const issues = validateFindingsSchema(r.findings);
-        return { round: r.round, valid: issues.length === 0, issues };
+        const issues = validateFindingsSchema(Array.isArray(r?.findings) ? r.findings : []);
+        return { round: typeof r?.round === 'number' ? r.round : 0, valid: issues.length === 0, issues };
     });
 }
 /**
@@ -411,19 +442,25 @@ export function validateRoundsSchema(rounds) {
  */
 export function sanitizeRounds(rounds, schemaValidation) {
     return rounds.map((r, i) => {
+        // Defensive: malformed rounds must never crash the deterministic core.
+        const findings = Array.isArray(r?.findings) ? r.findings : [];
+        const roundNo = typeof r?.round === 'number' ? r.round : 0;
+        const readFiles = Array.isArray(r?.readFiles) ? r.readFiles : [];
         if (schemaValidation) {
             const issues = schemaValidation[i]?.issues ?? [];
             if (issues.some((iss) => iss.index === -1))
-                return { round: r.round, findings: [] };
+                return { round: roundNo, findings: [], readFiles };
             const bad = new Set(issues.map((iss) => iss.index));
             return {
-                round: r.round,
-                findings: r.findings.filter((_, fi) => !bad.has(fi)),
+                round: roundNo,
+                findings: findings.filter((_, fi) => !bad.has(fi)),
+                readFiles,
             };
         }
         return {
-            round: r.round,
-            findings: r.findings.filter((f) => Boolean(f) && typeof f === 'object' && !Array.isArray(f)),
+            round: roundNo,
+            findings: findings.filter((f) => Boolean(f) && typeof f === 'object' && !Array.isArray(f)),
+            readFiles,
         };
     });
 }
@@ -435,6 +472,9 @@ export function sanitizeRounds(rounds, schemaValidation) {
 export function reviewerTaskPrompt(input) {
     const parts = [];
     parts.push(`You are the "${input.dimension}" reviewer for the iterate review.`, `Goal: ${input.goal}`, `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`);
+    if (input.focus) {
+        parts.push(`FOCUS: ${input.focus}`);
+    }
     if (input.scopeFiles && input.scopeFiles.length > 0) {
         parts.push('COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
             'assigned to review. You MUST open EVERY file in this inventory with ' +
@@ -465,9 +505,9 @@ export function reviewerTaskPrompt(input) {
         'disqualifying failure, and fabricated line numbers are treated as ' +
         'poisoned evidence. Anchor every finding to real code.');
     parts.push(`Return a JSON object: {"findings": [...], "readFiles": [...]}.`, `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
-        'line (REQUIRED positive integer — the exact line you READ for an ' +
-        'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
-        'issues), severity (critical/high/medium/low), summary (one line), ' +
+        'line (optional; the exact line you READ for a line-targeted issue; ' +
+        '0 or omitted for whole-file/module-level issues), ' +
+        'severity (critical/high/medium/low), summary (one line), ' +
         'failure_scenario (how/when it fails, backed by the code you actually ' +
         'read), suggested_fix (the concrete fix), ' +
         `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`, `Write summaries and details in ${input.outputLanguage}.`);
@@ -508,6 +548,17 @@ export function buildReviewPlan(input) {
         batches = [undefined];
     }
     const dimensionTasks = [];
+    // personalization.dimension_focus: [{dimension, focus}] — appended to the
+    // matching dimension's reviewer prompt.
+    const focusMap = new Map();
+    const pf = input.config.personalization;
+    if (pf && Array.isArray(pf.dimension_focus)) {
+        for (const entry of pf.dimension_focus) {
+            if (entry && typeof entry.dimension === 'string' && typeof entry.focus === 'string' && entry.focus) {
+                focusMap.set(entry.dimension, entry.focus);
+            }
+        }
+    }
     for (const d of dimensions) {
         batches.forEach((batch, index) => {
             const dimensionId = batches.length === 1 ? d : `${d}#${index + 1}`;
@@ -523,6 +574,7 @@ export function buildReviewPlan(input) {
                     maxLines,
                     changedFiles: effectiveChangedOnly ? changedFiles : undefined,
                     scopeFiles: batch,
+                    focus: focusMap.get(d),
                 }),
                 findingsSchema: findingsSchema(),
             });

package/dist/session-hooks.js

@@ -0,0 +1,89 @@
+/**
+ * src/session-hooks.ts — dsh pipeline hooks for the iterate observatory (F8).
+ *
+ * Wires the {@link decideApproval} policy gate to dsh's `tools/pre-execute`
+ * waterfall. This is the AUTHORITATIVE approval seam for destructive iterate
+ * tools (`iterate_fix` / `iterate_rollback` / `iterate_prune` with dryRun:false):
+ *
+ *   - `allow` policy      → the call runs.
+ *   - `deny`  policy      → the call is refused (fail-closed), surfaced as an
+ *                           error to the model.
+ *   - `ask`   policy      → return `{ kind: 'ask', reason }`; dsh's own
+ *                           scheduler routes it through the `approval` service
+ *                           (see `@deepseek-ai/dsh-user-approval`), which
+ *                           prompts the human and audits an approve/deny pair
+ *                           on the session.
+ *
+ * We deliberately do NOT also add `approved` flags inside the tool bodies:
+ * the pre-execute waterfall consumes the human decision before the tool runs,
+ * so a second tool-internal gate would double-ask. This one gate is enough and
+ * stays dsh-native.
+ *
+ * Safety properties:
+ *   - Read-only tools and non-iterate tools are always allowed (the gate only
+ *     inspects the three destructive iterate toolnames).
+ *   - If the project root / observatory config cannot be resolved, the policy
+ *     degrades to `ask` (fail-safe: destructive writes always require consent).
+ */
+import { loadEffectiveConfig, resolveProjectRoot } from "./config-loader.js";
+import { decideApproval, isDestructiveIterateTool } from "./approval-gate.js";
+/**
+ * Build the per-call approval decision for a tool execution.
+ * Returns a dsh `PreToolDecision` so the caller can short-circuit the caller.
+ */
+export function gateDecision(exec) {
+    // Importing the decision, and only inspecting our own tools, keeps unrelated
+    // tooling untouched. Anything we cannot classify is allowed by default.
+    if (!isDestructiveIterateTool(exec.name))
+        return { kind: 'allow' };
+    // Resolve the project root (use the call's own `path` arg, else the agent's
+    // session cwd) to read the effective observatory policy.
+    const argPath = typeof exec.arguments === 'object' && exec.arguments && !Array.isArray(exec.arguments)
+        && typeof exec.arguments.path === 'string'
+        ? exec.arguments.path
+        : undefined;
+    const sessionCwd = exec.agent?.session?.header?.cwd;
+    const resolved = resolveProjectRoot(argPath, sessionCwd);
+    let policy = 'ask';
+    if (resolved.ok) {
+        const { config } = loadEffectiveConfig(resolved.root);
+        const p = config.observatory?.approval;
+        if (p === 'deny')
+            policy = 'deny';
+        else if (p === 'allow')
+            policy = 'allow';
+        // anything else (including a corrupt/missing `ask`) → 'ask'
+    }
+    const decision = decideApproval(exec, policy);
+    if (decision.kind === 'deny')
+        return { kind: 'deny', reason: decision.reason };
+    if (decision.kind === 'ask')
+        return { kind: 'ask', reason: decision.reason };
+    return { kind: 'allow' };
+}
+/**
+ * Register the `tools/pre-execute` waterfall listener that applies the
+ * observatory approval gate to every destructive iterate tool call.
+ */
+export function registerSessionHooks(ctx) {
+    ctx.on('tools/pre-execute', (exec, next) => {
+        // Never let a throwing gate break the pipeline — degrade to allow.
+        let decision;
+        try {
+            decision = gateDecision(exec);
+        }
+        catch {
+            return next();
+        }
+        if (decision.kind === 'ask') {
+            // Delegate the actual human-consent prompt + audit to dsh's approval
+            // service via the scheduler's `ask` path. `next()` here would short-circuit
+            // to allow, which would bypass consent — so return our ask decision.
+            return Promise.resolve(decision);
+        }
+        if (decision.kind === 'deny') {
+            return Promise.resolve(decision);
+        }
+        return next();
+    });
+}