@widnyana/design-thinking 0.0.6 → 0.1.0

package/extensions/design-thinking.ts

@@ -1,28 +1,59 @@
 /**
  * Design Thinking — pi extension
  *
- * Adopts the three pillars:
- *   - Design Thinking : the mindset (§1–§10 pipeline, problem-first)
- *   - Design Graph    : the artifact (annotated call graph of a concrete problem)
- *   - Graph Protocol  : the notation spec (fixed sections, fixed markers)
+ * Adopts r17x's three methods (one shape, three materials):
+ *   - Design Thinking : code, X → Graph → Effect<A, E, R> (§1-§10 pipeline)
+ *   - Design Graph    : interface, Job → Flow → Surface<C, V, N>
+ *   - Graph Protocol  : delegation, AGENT SUBGRAPH in, IMPLEMENTED GRAPH out
  *
  * When /dt mode is active, every turn appends a compact distilled block to the
- * system prompt so design/plan/review answers render as Design Graphs in
- * Graph Protocol form. Full specs live in the package's references/ directory,
+ * system prompt so design/plan/review answers render as an annotated call
+ * graph in the Design Thinking output format. Full specs live in the package's references/ directory,
  * loaded on demand — not inlined here, to keep the injected prompt small.
+ * Separately, an ALWAYS-ON LSP reminder composes into every run's system
+ * prompt while the harness exposes an `lsp` tool (mode-independent); without
+ * one, the user is told once per session how to enable it.
  *
  * Commands:
+ *   /research-prompt <msg>  Meta Research Prompt Generator (references/meta-research.md)
  *   /dt            toggle Design Thinking mode
  *   /dt on|off     set explicitly
- *   /dt status     show current state
- *   /dt approve|deny  arm/revoke file edits for the next agent run
- *   /dt <prompt>   turn mode ON (never off), then run <prompt> as a user
- *                  message — graph + clarifying questions before implementation
+ *   /dt approve|deny  manual arm/revoke fallback (headless / no-UI sessions)
+ *   After a gated run presents a design graph, a review dialog opens
+ *   automatically: Approve (arm + implement), Refine (send feedback), or
+ *   Deny (keep file edits blocked). /dt <prompt> turns the mode ON (never
+ *   off) and runs the prompt — graph + clarifying questions before code.
+ *
+ * Approval gate design (one state machine, one owner):
+ *   - The gate is `{ mode: "off" | "on", approval: "none" | "armed" }`. Every
+ *     change goes through a transition function; handlers never touch the
+ *     fields directly.
+ *   - Approval is scoped to ONE human turn. It survives the many runs of
+ *     implementing an approved design, and is re-locked (relock()) when a new
+ *     user instruction arrives — a genuine `input` event, not the extension's
+ *     own go-ahead / refine messages. The next instruction is a refinement:
+ *     the agent updates and re-presents the graph, then the dialog re-opens.
+ *   - At most one review dialog exists. Each offer carries an epoch; a dialog
+ *     decision is applied only if its epoch is still current AND the gate is
+ *     still on AND still unapproved. Stale decisions are discarded, not
+ *     applied.
+ *   - The dialog opens at run end when the agent presented a design graph
+ *     (VERDICT + section headers) OR ended the turn asking for approval in
+ *     prose — the human always gets a button, never a prose-only ask.
+ *   - Dialogs are opened with an extension-owned AbortSignal: omp binds
+ *     handler-opened dialogs to the handler's 30s abort scope, and a floating
+ *     promise does not escape that binding. If the dialog is still dismissed
+ *     (runtime kill, or the agent's own dialog displacing it), the offer is
+ *     retracted and a fresh one opens at the next run end. No reopen loops,
+ *     no timing heuristics.
+ *   - An explicit Deny latches until a NEW graph is presented: deny means
+ *     stop asking.
  *
  * Stack-agnostic: no language detection, no auto-enable. Adapt the vocabulary
  * to whatever stack the project uses; never the discipline.
  */
 
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -48,7 +79,7 @@ const DISTILLED = `
 DESIGN THINKING MODE — active.
 Read the problem. Draw the data flow as a call graph. Write code that IS the graph.
 
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ R: what each node needs      (§5)
 │              │   │  └──── E: where the graph breaks    (§4)
@@ -62,65 +93,287 @@ Pipeline: shapes → graph(A) → cardinality → E(⟳retry ↯escape ☠die)
 🔒 parse at boundaries → ⛈ orthogonal behavior → scope → test-R → verdict.
 
 Rules:
-- ANY turn that will end in code or file edits (feature, change, fix,
+- ANY turn that will end in code or file changes (feature, change, fix,
   refactor — the model does NOT get to reclassify the request): render the
-  Design Graph in Graph Protocol form and any clarifying questions FIRST;
-  ZERO file edits until the user approves the design. Reading/exploring code
-  first is fine; the FIRST edit is not allowed before the graph. Once the
-  user runs /dt approve, edits are armed for the NEXT run: implement the
-  approved design without re-presenting the graph.
-- Design, plan, and review answers must render a Design Graph — fixed
+  graph in the Design Thinking output format and any clarifying questions FIRST;
+  ZERO mutations until the user approves the design — no file edits, no
+  shell commands, no code execution. Reading/exploring code first is fine,
+  via read-only tools only (read/grep/glob; read-only MCP devices such as
+  qmd and codegraph exploration also pass). If any tool call is blocked by
+  the gate, STOP: do NOT route the change around it via bash, eval, scripts,
+  or subagents — present or update the graph and end the turn. End the turn
+  after the graph with NO prose approval request — no "approve and I'll…", no
+  "let me know", no go-ahead questions. A review dialog opens automatically
+  when the run ends — never mid-run: approve (implement the presented design
+  without re-presenting the graph), refine (present an updated graph), or
+  deny (stay blocked).
+- Design, plan, and review answers must render the graph, fixed
   sections: PROBLEM, SHAPES, GRAPH, CARDINALITY, BOUNDARIES, BEHAVIOR, SCOPE,
   TEST LAYERS, VERDICT.
 - The happy path (A) stays readable; failure handling lives at defined join points.
 - Each layer scopes its own E; inner errors never leak through.
 - If the code doesn't match the call graph, the implementation is wrong.
 - Adapt vocabulary to the current language/stack; never the discipline.
+- Interface work uses the Design Graph (Surface<C, V, N>) skeleton.
+- Delegating to subagents or workers follows Graph Protocol: AGENT SUBGRAPH
+  in, IMPLEMENTED GRAPH out, compared before the work counts as done.
 
 Full specs — read these when a section needs detail:
-- ${REF_DIR}/protocol.md      (Graph Protocol: notation spec + worked example)
-- ${REF_DIR}/method.md        (the §1–§10 method, generalized)
-- ${REF_DIR}/design-graph.md  (the artifact spec + completeness checklist)
-Skills load BY NAME into the agent (/skill:<name>); the files above are named
-by stem, NOT by skill name. Exact mapping:
-  /skill:graph-protocol → protocol.md   /skill:design-method → method.md
-  /skill:design-graph → design-graph.md
-  The extension blocks write/edit tools mechanically until the user runs
-  /dt approve — it arms the NEXT run, cleared when that run ends. Re-approve
-  per implementation round. Present the graph first.
+- ${REF_DIR}/design-thinking.md  (the code method, §1-§10)
+- ${REF_DIR}/output-format.md    (sections, markers, call graph block, checklist)
+- ${REF_DIR}/design-graph.md     (the interface method + skeleton)
+- ${REF_DIR}/graph-protocol.md   (delegation: execution graph, AGENT SUBGRAPH, RETURN)
+  The extension blocks file edits, shells (bash/powershell), and code
+  execution (eval) mechanically until the user approves — a review dialog
+  opens when a graph-presenting run ends. Approval covers
+  ONE human turn: it stays armed across the many runs it takes to implement
+  the approved design, and drops the moment the user sends a new instruction.
+  Treat that next instruction as a refinement of the current design: UPDATE
+  the existing design graph to fold it in and re-present it (do not start a
+  blank graph unless the goal itself changed), then end the turn and wait for
+  the dialog. /dt deny or mode off also re-lock.
+  NEVER ask the user to run /dt approve, /dt deny, or any approval command:
+  the dialog is automatic, and mentioning commands just confuses the flow.
 NEVER read references/<skill-name>.md — no such files exist.
 `.trim();
 
-// pi's file-edit tools — the mechanical gate's scope ("file edits"). Bash
-// stays open for read-only exploration. apply_patch/multiedit are Claude Code
-// tool names that never fire in pi; keep this list to real pi mutators.
+// pi + omp mutation tools — the mechanical gate's scope. While unapproved,
+// these are blocked outright: file edits (write, edit), shells (bash, and
+// powershell on Windows), and omp's code-execution kernel (eval). Names a
+// harness lacks never fire — a no-op there (powershell on unix, eval on pi).
+// Bash is NOT pattern-gated: a deny-list of shell mutators is porous by
+// construction (redirects, package managers, interpreters — `go mod init` is
+// the proof), and the design turn should execute nothing anyway. Read-only
+// exploration keeps its dedicated tools (read/grep/find/ls/glob); read-only
+// MCP devices routed through write on omp pass too (see READONLY_MCP_PATH).
 const MUTATING_TOOLS: Record<string, true> = {
 	write: true,
 	edit: true,
+	bash: true,
+	powershell: true,
+	eval: true,
+};
+// omp executes MCP tools through the `write` tool as `xd://mcp__<tool>`
+// device paths; the blanket write block would eat them. Pure knowledge
+// lookups are carved out in the tool_call handler: qmd (retrieve/search)
+// and codegraph's read-only actions. Everything else stays blocked — file
+// writes and execution devices (ast_edit, lsp, debug, browser,
+// chrome_devtools, codegraph init/index/sync/unlock); unknown codegraph
+// actions and unparsable device args default to blocked.
+const READONLY_MCP_PATH =
+	/^xd:\/\/mcp__(?:[\w-]+__)?(?:qmd_(?:get|multi_get|query|status|search)|codegraph_explore)$/;
+
+const READONLY_CODEGRAPH_ACTIONS: Record<string, true> = {
+	explore: true,
+	node: true,
+	search: true,
+	files: true,
+	status: true,
+	callers: true,
+	callees: true,
+	impact: true,
+	affected: true,
+	help: true,
 };
 
 interface DtState {
 	enabled: boolean;
 }
 
+
+
 const GATE_REASON =
-	"Design Thinking mode is ON: present the Design Graph (Graph Protocol) and wait for user approval before file edits. The user arms the NEXT run with /dt approve; the approval clears when that run ends.";
+	"Design Thinking mode is ON: file edits, shell commands, and code execution are blocked until the user approves the presented design. Do NOT attempt this change through any other channel — no bash or shell commands, no eval/scripts, no subagent delegation. Explore with read-only tools (read/grep/glob), present (or update and re-present) the design graph, then END YOUR TURN with NO prose approval request — an approval dialog opens for the user automatically when the run ends. NEVER ask the user to run /dt approve, /dt deny, or any command; NEVER re-attempt the blocked action this turn.";
+
+const REVIEW_OPTIONS = [
+	"Approve — implement now",
+	"Refine — ask the agent for changes",
+	"Deny — keep file edits blocked",
+] as const;
+
+const GO_AHEAD_MESSAGE =
+	"Approved — implement the presented design now. (Design Thinking gate is armed; go straight to implementation, no graph re-presentation.)";
+
+/** Always-on LSP discipline block — mode-INDEPENDENT: it composes into every
+ *  run's system prompt while a language server exists, whether or not /dt is
+ *  on. */
+const LSP_REMINDER = `
+LSP FIRST — a language server is available in this session.
+- definition, type_definition, implementation, references, hover, symbols,
+  rename, rename_file, code_actions, diagnostics: use the \`lsp\` tool.
+- NEVER hand-grep for definitions/references or hand-edit cross-file renames
+  when \`lsp\` answers the same question — it follows shadowing and re-exports
+  that text search misses.
+- Imports and quick-fixes: list \`code_actions\`, apply one.
+- If \`lsp\` reports no configured servers for this project, tell the user ONCE
+  this session how to enable one (project lsp.json or server install), then
+  continue without repeating it.
+`.trim();
+
+const LSP_SUGGESTION_OMP =
+	"LSP Reminder: no `lsp` tool in this session — LSP is disabled. Enable it in settings, or add a server for this project (lsp.json; auto-detect needs a root marker plus the server binary on PATH). Until then, code intelligence falls back to text search.";
+
+const LSP_SUGGESTION_PI =
+	"LSP Reminder: pi has no LSP integration — code intelligence falls back to text search. omp provides a built-in `lsp` tool.";
+
+// Output-format section headers (code and interface skeletons). A real graph renders the fixed set;
+// VERDICT is mandatory. Requiring VERDICT + ≥3 others avoids tripping on a bare
+// mention of the word "verdict" in prose, and still fires on a graph rendered
+// without that exact literal elsewhere.
+const SECTION_HEADER =
+	/^[ \t]*#{0,4}[ \t>*-]*(PROBLEM|SHAPES|GRAPH|CARDINALITY|BOUNDARIES|BEHAVIOR|SCOPE|TEST LAYERS|JOB|SURFACES|FLOW|VOID|NEEDS|BOUNDARY|ATTENTION|PROOF|VERDICT)\b/gm;
+
+/** The agent is asking the human for a go-ahead in prose — narrow on purpose so
+ *  an ordinary closing sentence does not trip it. */
+const APPROVAL_ASK =
+	/\b(approve|go[- ]?ahead|await(?:ing)? (?:your )?(?:approval|go)|shall i (?:implement|proceed|write|build|start)|should i (?:implement|proceed|write|build|start)|want me to (?:implement|write|build|start|proceed)|ready to implement)\b/i;
+
+/** Flatten an AgentMessage's content to plain text (string or content parts). */
+function messageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) =>
+			part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
+				? (part as { text: string }).text
+				: "",
+		)
+		.join("\n");
+}
+
+/** Does an assistant message render a design graph (code or interface skeleton)? */
+function presentsGraph(message: { role: string; content?: unknown }): boolean {
+	if (message.role !== "assistant") return false;
+	const seen = new Set<string>();
+	for (const m of messageText(message.content).matchAll(SECTION_HEADER)) seen.add(m[1]);
+	return seen.has("VERDICT") && seen.size >= 4;
+}
+
+/** Did the agent end its turn asking the human to approve, in prose? */
+function asksApproval(message: { role: string; content?: unknown }): boolean {
+	return message.role === "assistant" && APPROVAL_ASK.test(messageText(message.content));
+}
+
+interface Offer {
+	epoch: number;
+	abort: AbortController;
+}
 
 export default function designThinkingExtension(pi: ExtensionAPI) {
-	let enabled = false;
-	// Armed by /dt approve for the NEXT agent run. Cleared when that run ends
-	// (agent_end), by /dt deny, or when the mode turns off. Not persisted.
-	let editsApproved = false;
+	// ── Gate state — the ONLY mutable state; change it via the transitions
+	// below, never inline in a handler. ─────────────────────────────────────
+	let mode: "off" | "on" = "off";
+	// "armed" lets mutating tools through. Approval is NOT consumed by runs:
+	// implementing an approved design spans many runs, and re-arming per run
+	// only produced approval loops. It is re-locked by relock() when a new user
+	// instruction arrives, when a NEW design graph is presented, by /dt deny, or
+	// when the mode turns off.
+	let approval: "none" | "armed" = "none";
+	// A design graph was presented in the CURRENT design cycle. Reset by
+	// relock() — i.e. when a new user instruction arrives. Approval is scoped to
+	// one human turn: it survives the many runs of implementing an approved
+	// design, and drops the moment the user speaks again (a new goal, or a
+	// refinement of the current one → re-graph, re-approve).
+	let cycleGraphSeen = false;
+	// Set by an explicit deny (dialog or /dt deny). Latches until a NEW graph
+	// is presented — deny means stop asking.
+	let graphDenied = false;
+	// Dialog offers. Monotonic epoch; a decision applies only when its epoch
+	// matches the live offer and the gate still allows arming.
+	let nextEpoch = 1;
+	let offer: Offer | undefined;
+	// How many messages of the session have already been scanned for VERDICT.
+	let scannedMessages = 0;
+
+	// ── LSP reminder state — always-on, independent of dt mode ───────────────
+	// Probed once per session; the suggestion fires at most once per session
+	// (reset on session_start). Probing uses pi.getAllTools(), present on both
+	// pi 0.84.3 and omp; omp is detected via its pi.logger surface (absent on
+	// pi) only to pick the suggestion text.
+	let lspProbed = false;
+	let lspCapable = false;
+	let lspSuggested = false;
+
+	function isOmp(): boolean {
+		return typeof (pi as ExtensionAPI & { logger?: unknown }).logger === "object";
+	}
+
+	function probeLsp(): void {
+		lspProbed = true;
+		try {
+			const tools: Array<{ name?: string }> =
+				(pi as ExtensionAPI & { getAllTools?: () => unknown[] }).getAllTools?.() ?? [];
+			lspCapable = tools.some((t) => t?.name === "lsp");
+		} catch {
+			lspCapable = false;
+		}
+	}
+
+	function maybeSuggestLsp(ctx: ExtensionContext): void {
+		if (lspSuggested || lspCapable || !ctx.hasUI) return;
+		lspSuggested = true;
+		ctx.ui.notify(isOmp() ? LSP_SUGGESTION_OMP : LSP_SUGGESTION_PI, "info");
+	}
+
+	// omp-only pi.logger surface; absent on pi 0.84.3.
+	const logger = (pi as ExtensionAPI & { logger?: { warn?: (msg: string) => void } }).logger;
+
+	// ── Transitions ─────────────────────────────────────────────────────────
+	function setMode(on: boolean): void {
+		mode = on ? "on" : "off";
+		if (!on) {
+			approval = "none";
+			cycleGraphSeen = false;
+			graphDenied = false;
+			retractOffer();
+		}
+	}
+
+	/** Arm the gate. Fails when the mode is off or an approval is already in
+	 *  effect — the caller decides how to surface that. */
+	function arm(): boolean {
+		if (mode !== "on" || approval !== "none") return false;
+		approval = "armed";
+		retractOffer();
+		return true;
+	}
+
+	/** Explicit revoke (/dt deny). Latches graph review until a new graph. */
+	function revoke(): void {
+		approval = "none";
+		graphDenied = true;
+		retractOffer();
+	}
+
+	/** A new user instruction opens a fresh design decision: re-lock the gate so
+	 *  the agent must present (or update and re-present) the graph and get a new
+	 *  approval before editing. Not called for the extension's own go-ahead /
+	 *  refine messages. */
+	function relock(): void {
+		if (mode !== "on") return;
+		approval = "none";
+		cycleGraphSeen = false;
+		graphDenied = false;
+		retractOffer();
+	}
+
+	function retractOffer(): void {
+		offer?.abort.abort();
+		offer = undefined;
+	}
+
+	/** May a dialog decision from `epoch` still be applied? */
+	function decisionApplies(epoch: number): boolean {
+		return offer?.epoch === epoch && mode === "on" && approval === "none";
+	}
 
+	// ── Session plumbing ────────────────────────────────────────────────────
 	function applyStatus(ctx: ExtensionContext) {
-		ctx.ui.setStatus(
-			"design-thinking",
-			enabled ? "design-thinking: on" : undefined,
-		);
+		ctx.ui.setStatus("design-thinking", mode === "on" ? "design-thinking: on" : undefined);
 	}
 
 	function persist() {
-		pi.appendEntry<DtState>(STATE_TYPE, { enabled });
+		pi.appendEntry<DtState>(STATE_TYPE, { enabled: mode === "on" });
 	}
 
 	function restore(ctx: ExtensionContext) {
@@ -134,13 +387,15 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 				}
 			}
 		}
-		if (restored !== undefined) {
-			enabled = restored;
-		}
+		if (restored !== undefined) setMode(restored);
 	}
 
-	// Restore toggle state when a session starts, loads, or reloads.
 	pi.on("session_start", async (_event, ctx) => {
+		// A new session gets one fresh LSP probe and suggestion.
+		lspProbed = false;
+		lspSuggested = false;
+		probeLsp();
+		maybeSuggestLsp(ctx);
 		restore(ctx);
 		applyStatus(ctx);
 	});
@@ -149,82 +404,242 @@ export default function designThinkingExtension(pi: ExtensionAPI) {
 		ctx.ui.setStatus("design-thinking", undefined);
 	});
 
-	// /dt — the Design Thinking tool. Toggles mode; on|off|status set/query;
-	// approve|deny arm/revoke file edits; anything else runs as a prompt with mode on.
+	// ── /dt command ─────────────────────────────────────────────────────────
 	pi.registerCommand("dt", {
-		description: "Design Thinking mode: /dt toggles, on|off|status set/query, approve arms the next run for file edits, deny revokes; anything else runs as a prompt with mode on",
+		description: "Design Thinking mode: /dt toggles, on|off|status set/query, approve asks then implements, deny re-locks; anything else runs as a prompt with mode on",
 		handler: async (args, ctx) => {
 			const arg = (args ?? "").trim();
 			const lower = arg.toLowerCase();
 
 			if (lower === "status") {
-				ctx.ui.notify(`Design Thinking mode: ${enabled ? "on" : "off"}${editsApproved ? " (file edits armed for the next run)" : ""}`, "info");
+				ctx.ui.notify(`Design Thinking mode: ${mode === "on" ? "on" : "off"}${approval === "armed" ? " (gate armed)" : ""}`, "info");
 				return;
 			}
 
 			if (lower === "approve") {
-				if (!enabled) {
+				if (mode !== "on") {
 					ctx.ui.notify("Design Thinking is OFF — nothing to approve. Run /dt on first.", "info");
 					return;
 				}
-				editsApproved = true;
-				ctx.ui.notify("Design Thinking: file edits armed (current or next run) — it may implement the approved design without re-presenting the graph", "info");
+				// Direct arm: the interactive approve/refine/deny dialog opens
+				// automatically after a gated run ends; this command is the
+				// headless/scripting path, so no nested dialog here.
+				if (!arm()) {
+					ctx.ui.notify("Design Thinking: gate is already armed", "info");
+					return;
+				}
+				ctx.ui.notify("Design Thinking: gate armed — implementing the approved design without re-presenting the graph", "info");
+				// Arming alone leaves the session idle: the agent never learns approval
+				// happened and the user sees "nothing happened". Send the go-ahead so
+				// the armed run starts now (steer if mid-run).
+				await pi.sendUserMessage(GO_AHEAD_MESSAGE, { deliverAs: "steer" });
 				return;
 			}
 			if (lower === "deny") {
-				if (!editsApproved) {
-					ctx.ui.notify("Design Thinking: no approval in effect — file edits are already blocked", "info");
+				if (approval !== "armed") {
+					ctx.ui.notify("Design Thinking: no approval in effect — mutations are already blocked", "info");
 					return;
 				}
-				editsApproved = false;
-				ctx.ui.notify("Design Thinking: file edits blocked again", "info");
+				revoke();
+				ctx.ui.notify("Design Thinking: mutations blocked again", "info");
 				return;
 			}
-
 			// "on"/"off" set explicitly; anything else is a prompt to run in this
 			// mode and always turns the mode ON (never toggles it off); bare /dt toggles.
 			const prompt = /^(on|off|status)$/.test(lower) ? "" : arg;
-			enabled = lower === "on" || prompt ? true : lower === "off" ? false : !enabled;
-			if (!enabled) editsApproved = false;
+			const on = lower === "on" || prompt ? true : lower === "off" ? false : mode === "off";
+			setMode(on);
 			persist();
 			applyStatus(ctx);
 			ctx.ui.notify(
-				enabled
-					? "Design Thinking ON — plans and reviews will render as Design Graphs (Graph Protocol)"
+				on
+					? "Design Thinking ON — plans and reviews will render as annotated call graphs"
 					: "Design Thinking OFF",
 				"info",
 			);
 
 			if (prompt) {
+				// A prompt via /dt is a new goal: re-lock so the graph comes first
+				// (the input handler skips this — sendUserMessage is source "extension").
+				relock();
 				// deliverAs "steer": sends immediately when idle, queues mid-stream.
 				await pi.sendUserMessage(
-					`${prompt}\n\n(Design Thinking is ON: before implementing, present the Design Graph (Graph Protocol) and any clarifying questions, then wait for my go-ahead.)`,
+					`${prompt}\n\n(Design Thinking is ON: before implementing, present the design graph and any clarifying questions, then wait for my go-ahead.)`,
 					{ deliverAs: "steer" },
 				);
 			}
 		},
 	});
 
-	// While active, append the distilled block to the system prompt every run.
-	pi.on("before_agent_start", async (event) => {
-		if (!enabled) return undefined;
-		return {
-			systemPrompt: event.systemPrompt + "\n\n" + DISTILLED + "\n",
-		};
+	// ── /research-prompt command ────────────────────────────────────────────
+	// r17x's Meta Research Prompt Generator. The template ships in references/;
+	// pi prompts cannot read package files, so the command reads it and sends
+	// it with the user's message (§6 boundary: file → text, read once here).
+	pi.registerCommand("research-prompt", {
+		description: "Meta Research Prompt Generator: writes ./research/projects/<NAME>/.<NAME>.research.prompt and prints the run command",
+		handler: async (args, ctx) => {
+			let generator: string;
+			try {
+				generator = fs.readFileSync(path.join(REF_DIR, "meta-research.md"), "utf8");
+			} catch (err) {
+				ctx.ui.notify(`research-prompt: cannot read ${REF_DIR}/meta-research.md (${(err as Error).message})`, "error");
+				return;
+			}
+			const harness = isOmp() ? "omp" : "pi";
+			await pi.sendUserMessage(
+				`${generator}\n\n---\n\nYou run inside ${harness}: in step 8 print only the ${harness} command.\n\nUser message:\n${(args ?? "").trim()}`,
+				{ deliverAs: "steer" },
+			);
+		},
+	});
+
+	// ── Run hooks ───────────────────────────────────────────────────────────
+	// A genuine user instruction re-locks the gate: the previous approval covered
+	// the previous turn's work only. Our own go-ahead / refine messages arrive as
+	// source "extension" and must NOT re-lock.
+	pi.on("input", async (event) => {
+		if (mode !== "on") return undefined;
+		if (event.source === "extension") return undefined;
+		relock();
+		return undefined;
 	});
 
-	// An approved run consumes the approval: clear it when the run ends so
-	// later runs are gated again until the user re-approves with /dt approve.
-	pi.on("agent_end", async () => {
-		editsApproved = false;
+	// Compose the system prompt: the distilled block is dt-mode-scoped, the
+	// LSP reminder is always-on. Either may be absent.
+	pi.on("before_agent_start", async (event) => {
+		if (!lspProbed) probeLsp();
+		const parts = [event.systemPrompt];
+		if (mode === "on") parts.push(DISTILLED + "\n");
+		if (lspCapable) parts.push(LSP_REMINDER + "\n");
+		if (parts.length === 1) return undefined;
+		return { systemPrompt: parts.join("\n\n") };
 	});
 
-	// Hard gate: while enabled, file-edit tools are blocked until the user
-	// arms the next run with /dt approve. Prompt-level rules alone proved
-	// insufficient — this is the mechanical backstop.
 	pi.on("tool_call", async (event) => {
-		if (!enabled || editsApproved) return undefined;
+		if (mode !== "on") return undefined;
 		if (!MUTATING_TOOLS[event.toolName]) return undefined;
+		if (approval === "armed") return undefined;
+		// omp routes MCP calls through `write` (xd://mcp__… device paths); let
+		// read-only devices through. qmd devices are pure reads; codegraph
+		// only for its read-only actions — init/index/sync/unlock and
+		// unparsable args stay blocked.
+		if (event.toolName === "write") {
+			const input = event.input as { path?: unknown; content?: unknown } | undefined;
+			const path = input?.path;
+			if (typeof path === "string" && READONLY_MCP_PATH.test(path)) {
+				const isCodegraph = path.includes("codegraph_explore");
+				let action = "explore"; // codegraph's default action is a read
+				if (isCodegraph) {
+					try {
+						action = (JSON.parse(String(input?.content ?? "{}")) as { action?: string })
+							.action ?? "explore";
+					} catch {
+						action = "init"; // unparsable device args → treat as mutating
+					}
+				}
+				if (!isCodegraph || READONLY_CODEGRAPH_ACTIONS[action]) return undefined;
+			}
+		}
+		// Block only — NEVER open the review dialog here. Mid-run, the agent is
+		// still streaming, and a UI-up-while-the-agent-acts is the failure this
+		// mode exists to prevent. A blocked mutation returns the stop-and-do-not-
+		// route-around reason; agent_end offers the dialog (a graph seen earlier
+		// this cycle re-offers there too), so the UI appears only after the run
+		// ends and the agent has stopped.
 		return { block: true, reason: GATE_REASON };
 	});
+
+	// Run-end housekeeping: offer the review dialog when the agent presented a
+	// graph this cycle, or ended the turn asking for approval in prose (so the
+	// human always gets a button, never a prose-only ask). While an approval
+	// holds, edits stay open and no dialog is offered.
+	pi.on("agent_end", async (event, ctx) => {
+		// Keep the scan cursor in sync even while off, so re-enabling does not
+		// rescan or mis-slice history.
+		const messages = event.messages;
+		if (mode !== "on") {
+			scannedMessages = messages.length;
+			return;
+		}
+
+		// Incremental scan — only messages since the last run end. A long
+		// session never re-scans old history.
+		const fresh = messages.slice(Math.min(scannedMessages, messages.length));
+		scannedMessages = messages.length;
+		if (fresh.some(presentsGraph)) {
+			cycleGraphSeen = true;
+			graphDenied = false;
+			approval = "none"; // a presented graph always means: awaiting approval
+		}
+
+		if (approval === "armed") return;
+		if (graphDenied) return;
+		if (offer) return; // a dialog is already live
+		// Open the dialog on a presented graph, or a prose approval ask.
+		if (!cycleGraphSeen && !fresh.some(asksApproval)) return;
+		if (!ctx.hasUI) {
+			ctx.ui.notify("Design Thinking: review the presented design, then run /dt approve or /dt deny", "info");
+			return;
+		}
+		offerReview(ctx);
+	});
+
+	// ── Review dialog ───────────────────────────────────────────────────────
+	// One dialog per offer. Extension-owned AbortSignal: omp dismisses
+	// handler-opened dialogs when the handler's 30s budget expires, and a
+	// detached promise does not escape that binding — the signal replaces it.
+	// If the dialog is dismissed anyway (runtime kill, or the agent's own
+	// dialog displacing it), the offer is retracted; the next run end makes a
+	// fresh offer. A dismissed dialog is NOT a deny.
+	function offerReview(ctx: ExtensionContext): void {
+		const epoch = nextEpoch++;
+		const abort = new AbortController();
+		offer = { epoch, abort };
+
+		void (async () => {
+			const choice = await ctx.ui.select("Review the presented design", [...REVIEW_OPTIONS], {
+				signal: abort.signal,
+			});
+			if (!decisionApplies(epoch)) return; // superseded; discard silently
+
+			if (choice === undefined) {
+				// Dismissed, not decided. File edits stay blocked; a fresh offer
+				// opens at the next run end.
+				retractOffer();
+				return;
+			}
+			if (choice.startsWith("Deny")) {
+				graphDenied = true;
+				retractOffer();
+				ctx.ui.notify("Design Thinking: mutations blocked — nothing approved", "info");
+				return;
+			}
+			if (choice.startsWith("Approve")) {
+				if (!arm()) return; // gate changed while the human was deciding
+				ctx.ui.notify("Design Thinking: gate armed — implementing the approved design", "info");
+				await pi.sendUserMessage(GO_AHEAD_MESSAGE, { deliverAs: "steer" });
+				return;
+			}
+			// Refine: collect feedback and send it back; the dialog re-opens
+			// after the refined plan is presented.
+			const feedback = await ctx.ui.input(
+				"What should change in the design?",
+				"e.g. too complex — drop the cache layer",
+				{ signal: abort.signal },
+			);
+			if (!decisionApplies(epoch)) return;
+			if (feedback === undefined || !feedback.trim()) {
+				retractOffer();
+				return;
+			}
+			retractOffer();
+			await pi.sendUserMessage(
+				`Refine the presented design (do not implement yet): ${feedback.trim()}\n\n(Design Thinking: update the design graph per this feedback and present it again. Mutations stay blocked.)`,
+				{ deliverAs: "steer" },
+			);
+		})().catch((err: unknown) => {
+			if (offer?.epoch === epoch) retractOffer();
+			logger?.warn?.(`design-thinking: review dialog failed: ${String(err)}`);
+		});
+	}
 }