iterate-plugin 2.11.0 → 2.12.1

package/README.md

@@ -1,5 +1,8 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
+> dsh 桌面端的 iterate 收敛面板、UI 分诊与审查闭环插件。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面。
+> The iterate ecosystem's convergence dashboard, triage UI, and review/fix loop, natively embedded inside the DeepSeek Harness (dsh) desktop client.
+
 <p align="center">
   <a href="README.md"><strong>English</strong></a> ·
   <a href="README.zh-CN.md"><strong>简体中文</strong></a>
@@ -11,9 +14,44 @@
   <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
   <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=Main%20Repo%20Star" alt="Main Repo Stars"></a>
   <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
+  <a href="https://github.com/jingzhao-l/iterate-plugin/releases"><img src="https://img.shields.io/github/v/release/jingzhao-l/iterate-plugin" alt="GitHub release"></a>
 </p>
 
-> ⭐ If this helps your dsh workflow, give the main repo a star — it means a lot!
+> ⭐ If this helps your dsh workflow, give the main repo a star — it means a lot to open-source maintenance!
+
+---
+
+## The iterate Ecosystem / iterate 生态一览
+
+**iterate** is not one single binary — it is a **skill ecosystem** that layers a strict multi-round code gate on top of your existing AI assistants, IDEs, and scripts. It never replaces your tools; it adds an audit-and-close-the-loop layer on them. The whole ecosystem ships as **three interchangeable components sharing one `iterate.config.yaml` + one review-dimension system**:
+
+| Component | Form & Source | Target Scenario |
+|---|---|---|
+| **[Core Skill + CLI](https://github.com/jingzhao-l/iterate-skill)** | Portable AI skill `/iterate` + `iterate` CLI (source: iterate-skill monorepo root) | Conversation-driven multi-round iteration inside Trae / Claude Code / Cursor / Copilot / Codex and 25+ other assistants |
+| **[iterate-harness](https://github.com/jingzhao-l/iterate-harness)** | Standalone headless engine, command `ih` (npm: `iterate-harness`) | Run the EXACT same loop in terminal / CI / git hooks, without any conversational assistant required |
+| **iterate-plugin (this repo)** | dsh desktop-client plugin (npm: `iterate-plugin`) | Plug the harness runtime **into the dsh UI**: convergence dashboard, triage panel, round progress — all surfaced as native dsh widgets |
+
+How they fit together: **Core Skill** is the canonical, assistant-agnostic review/fix engine (the "brains"). **iterate-harness** is the same engine wrapped as a headless CLI + WebUI for unattended runs. **iterate-plugin** (this repository) wraps that harness runtime as a dsh plugin, rendering the triage UI and convergence dashboard directly inside the dsh desktop client. Configuration (`iterate.config.yaml`) and the 9-dimension review system are **identical across all three** — learn one, use them all.
+
+Quick install / entry points for the rest of the ecosystem:
+
+```bash
+# Core Skill + CLI (install into 25+ AI assistants)
+npx iterate-skill-installer
+
+# iterate-harness: headless engine (npm wrapper, simplest)
+npm install -g iterate-harness
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash
+ih iterate init && ih iterate review
+
+# iterate-plugin: dsh desktop plugin (this repo — commands repeated under Installation below)
+dsh plugin --profile web add iterate-plugin
+```
+
+> This document focuses on **iterate-plugin (this repo)**. For Core Skill docs see the [iterate-skill monorepo](https://github.com/jingzhao-l/iterate-skill); for headless engine docs see [iterate-harness](https://github.com/jingzhao-l/iterate-harness).
+
+---
 
 ## About This Plugin
 
@@ -199,6 +237,8 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
 .iterate/
   decision-log.jsonl      # append-only decision log (plan/review/fix/revert…)
   checkpoint.json         # iteration breakpoint (resume)
+  transcript.json         # runtime-observatory manifest (per-reviewer threads, trend, fixes, timeline, nudge)
+  transcript-live.ndjson  # append-only near-real-time reviewer-activity feed (read/fix/rollback/validate…), byte-capped
   fixes/
     registry.json         # fix registry (list of FixRecords, grouped by round)
     <fix-id>_<ts>.bak     # original file backup before each fix

package/README.zh-CN.md

@@ -1,5 +1,8 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
+> dsh 桌面端的 iterate 收敛面板、UI 分诊与审查闭环插件。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面。
+> The iterate ecosystem's convergence dashboard, triage UI, and review/fix loop, natively embedded inside the DeepSeek Harness (dsh) desktop client.
+
 <p align="center">
   <a href="README.md"><strong>English</strong></a> ·
   <a href="README.zh-CN.md"><strong>简体中文</strong></a>
@@ -11,9 +14,44 @@
   <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
   <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=主仓库%20Star" alt="主仓库 Stars"></a>
   <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a>
+  <a href="https://github.com/jingzhao-l/iterate-plugin/releases"><img src="https://img.shields.io/github/v/release/jingzhao-l/iterate-plugin" alt="GitHub release"></a>
 </p>
 
-> ⭐ 如果这个插件对你的 dsh 工作流有帮助，欢迎为主仓库点亮 Star，这是对开源维护最大的支持！
+> ⭐ 如果这个插件对你的 dsh 工作流有帮助，欢迎为主仓库点亮 Star，这是对开源维护最大的支持！你的 Star 能让 iterate 被更多开发者看见。
+
+---
+
+## iterate 生态一览 / The iterate Ecosystem
+
+**iterate 不是一个独立的工具，而是一套附着在现有 AI 助手之上的技能生态。** 它不会替换你的 IDE 或 AI 工具，而是在你已有的工作流里，叠加一层"严格的代码收尾与把关"。整个生态由**三个可互换组件构成，共用同一套 `iterate.config.yaml` 与同一套 9 维度审查体系**：
+
+| 组件 | 形态与位置 | 面向场景 |
+|---|---|---|
+| **[Core Skill + CLI / 核心技能与命令行](https://github.com/jingzhao-l/iterate-skill)** | 可移植 AI 技能 `/iterate` + `iterate` CLI（源码：iterate-skill 主仓库根目录） | 在 Trae / Claude Code / Cursor / Copilot / Codex 等 25+ 助手中以对话方式进行多轮迭代 |
+| **[iterate-harness / 无头引擎](https://github.com/jingzhao-l/iterate-harness)** | 独立无头引擎，命令 `ih`（npm: `iterate-harness`） | 在终端 / CI / Git 钩子里**脱离对话式助手**，运行同一套闭环 |
+| **iterate-plugin / dsh 桌面插件（本仓库）** | dsh 桌面客户端插件（npm: `iterate-plugin`） | 把 harness 运行时**直接接入 dsh 界面**：收敛看板、分诊面板、轮次进度，均以原生 dsh 控件形式展示 |
+
+三者关系：**Core Skill** 是最通用的跨助手审查/修复引擎（"大脑"）；**iterate-harness** 是同一引擎封装为无头 CLI + WebUI，适合跑在无需交互的场景；**iterate-plugin**（本仓库）把 harness 运行时进一步封装为 dsh 插件，直接在 dsh 桌面客户端内渲染分诊 UI 与收敛看板。配置（`iterate.config.yaml`）与 9 维度审查体系**三者完全一致**——理解其一，即可举一反三。
+
+生态其余组件的快速安装/入口：
+
+```bash
+# Core Skill + CLI（一键安装到 25+ AI 编程助手）
+npx iterate-skill-installer
+
+# iterate-harness：无头引擎（npm 包装器，最简）
+npm install -g iterate-harness
+curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash
+ih iterate init && ih iterate review
+
+# iterate-plugin：dsh 桌面插件（本仓库，安装命令在下文「安装」一节重复列出）
+dsh plugin --profile web add iterate-plugin
+```
+
+> 本文档从下一节开始聚焦 **iterate-plugin（本仓库）**。核心技能文档见 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill)，无头引擎文档见 [iterate-harness 独立仓库](https://github.com/jingzhao-l/iterate-harness)。
+
+---
 
 ## 这是什么 / About This Plugin
 

package/dist/approval-gate.js

@@ -0,0 +1,92 @@
+/**
+ * src/approval-gate.ts — pure policy gate for destructive iterate tool calls.
+ *
+ * Feeds dsh's `tools/pre-execute` waterfall (registered in `session-hooks.ts`).
+ * The gate classifies a tool execution and returns a typed decision without
+ * any I/O, so it is fully unit-testable:
+ *
+ *   - `{ kind: 'allow' }`        → run the call.
+ *   - `{ kind: 'ask', reason }`  → prompt the human via the dsh approval service.
+ *   - `{ kind: 'deny', reason }` → refuse; the caller surfaces the reason.
+ *
+ * Policy (config `observatory.approval`, default 'ask'):
+ *   - `allow` → destructive iterate calls always run (debug/trusted).
+ *   - `deny`  → destructive iterate calls are always refused (fail-closed).
+ *   - `ask`   → destructive iterate calls prompt the human first.
+ *
+ * Destructive calls are exactly the ones that mutate the workspace:
+ * `iterate_fix` (writes files), `iterate_rollback` (restores from backups),
+ * and `iterate_prune` with `dryRun !== true` (deletes `.iterate/` artifacts).
+ * Read-only calls are always allowed. Non-iterate calls are untouched — the
+ * gate only ever inspects iterate tools so it cannot alter unrelated behavior.
+ */
+/** Destructive iterate tools subject to the gate. */
+const DESTRUCTIVE_TOOLS = new Set(['iterate_fix', 'iterate_rollback', 'iterate_prune']);
+/** Human-readable reason rendered in the approval prompt. */
+function describe(toolName, arguments0) {
+    const file = arguments0 && typeof arguments0.file === 'string'
+        ? `\`${arguments0.file}\``
+        : 'the workspace';
+    switch (toolName) {
+        case 'iterate_fix':
+            return `Apply an atomic fix to ${file}`;
+        case 'iterate_rollback': {
+            const id = arguments0 && typeof arguments0.id === 'string' ? ` \`${arguments0.id}\`` : '';
+            return `Revert fix${id} (restore ${file} from backup)`;
+        }
+        case 'iterate_prune':
+            return 'Delete stale `.iterate/` runtime artifacts';
+        default:
+            return `Run ${toolName}`;
+    }
+}
+/**
+ * Decide whether a tool execution may proceed under the given policy.
+ * Returns `allow` for read-only prune (`dryRun: true`), for `allow`-policy
+ * deployments, and for any non-iterate tool.
+ */
+export function decideApproval(execution, policy) {
+    const name = typeof execution?.name === 'string' ? execution.name : '';
+    if (!name)
+        return { kind: 'allow' };
+    if (!DESTRUCTIVE_TOOLS.has(name))
+        return { kind: 'allow' };
+    const rawArgs = execution.arguments;
+    const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs)
+        ? rawArgs
+        : {};
+    // `iterate_prune` is read-only in its default dry-run mode — no gate needed.
+    if (name === 'iterate_prune' && args.dryRun === false) {
+        // falls through to the destructive path below
+    }
+    else if (name === 'iterate_prune') {
+        return { kind: 'allow' };
+    }
+    if (policy === 'allow')
+        return { kind: 'allow' };
+    const reason = describe(name, args);
+    if (policy === 'deny')
+        return { kind: 'deny', reason };
+    return { kind: 'ask', reason };
+}
+/** True when any destructive iterate tool is listed in a name set. */
+export function isDestructiveIterateTool(name) {
+    return typeof name === 'string' && DESTRUCTIVE_TOOLS.has(name);
+}
+/**
+ * Evaluate an iterate tool's own boundary gate for a destructive call.
+ * `approvedArg` is the caller-supplied `approved: true` flag (human consent
+ * already obtained). Returns a run / refuse result without any I/O.
+ */
+export function toolGate(policy, execution, approvedArg) {
+    const decision = decideApproval(execution, policy);
+    if (decision.kind === 'allow')
+        return { ok: true };
+    if (decision.kind === 'deny') {
+        return { ok: false, error: `Blocked by observatory approval policy: ${decision.reason}` };
+    }
+    // ask
+    if (approvedArg === true)
+        return { ok: true };
+    return { ok: false, requiresApproval: true, reason: decision.reason };
+}

package/dist/config-loader.js

@@ -55,6 +55,10 @@ export function defaultConfig() {
             coverage_validation: true,
             scope_chunk_size: 25,
         },
+        observatory: {
+            capture: true,
+            approval: 'ask',
+        },
     };
 }
 /**

package/dist/index.js

@@ -2,13 +2,15 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 13 tools (config, validate, decision-log, context, review,
- *   triage, fix, diff, rollback, checkpoint, status, history, prune)
+ * - The plugin registers 14 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune, transcript)
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
- *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
+ * - Subagents use the 14 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune, transcript)
+ * - A `tools/pre-execute` hook gates destructive iterate calls behind human approval
+ *   (F8 observatory approval policy: ask / deny / allow).
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -32,11 +34,14 @@ import { registerFixTool, registerDiffTool, registerRollbackTool } from "./tools
 import { registerCheckpointTool, registerStatusTool } from "./tools/checkpoint.js";
 import { registerHistoryTool } from "./tools/history.js";
 import { registerPruneTool } from "./tools/prune.js";
+import { registerTranscriptTool } from "./tools/transcript.js";
+import { registerSessionHooks } from "./session-hooks.js";
+import { registerLiveCapture } from "./live.js";
 import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 1. Register the 13 tools
+    // 1. Register the 14 tools
     registerConfigTool(ctx);
     registerValidateTool(ctx);
     registerDecisionLogTool(ctx);
@@ -50,6 +55,11 @@ export function apply(ctx) {
     registerStatusTool(ctx);
     registerHistoryTool(ctx);
     registerPruneTool(ctx);
+    registerTranscriptTool(ctx);
+    // 2. Wire the observatory approval gate onto dsh's tools/pre-execute waterfall,
+    //    and the live reviewer-activity feed onto tools/result.
+    registerSessionHooks(ctx);
+    registerLiveCapture(ctx);
     // 2. Inject the iterate skill prompt as a system prompt section
     // This teaches the model how to write iterate workflow scripts using the tools.
     ctx.systemPrompt.section({

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/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/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();
+    });
+}