@fusengine/harness 0.1.86 → 0.1.88

package/dist/{handle-Dzf4JbrL.mjs → handle-DHhukRdh.mjs}

@@ -1,23 +1,23 @@
 import { a as resolveMaxLines, l as parseEnvInt, s as splitTarget } from "./limits-DG5pl-5s.mjs";
-import { s as resolveTtlSec } from "./dotenv-DoqNlALG.mjs";
+import { a as harnessHome, c as resolveTtlSec } from "./dotenv-BLBkBTww.mjs";
 import { r as projectLayout } from "./layout-KWoE_Mqn.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
 import { t as detectHarness } from "./harness-BMuLJ9lm.mjs";
-import { D as isVendorPath, G as isFileSizeScoped, K as resolveSolidRefFramework, W as computeEditResultLines, b as interfaceDeclLevel, et as detectFramework, g as conventionsMode, lt as requiredArchSkill, n as FAIL_CLOSED, ot as detectModularArchitecture, rt as maskCommentsAndStrings, st as detectProjectType$1, t as evaluate } from "./evaluate-9bUzRquQ.mjs";
+import { $ as matchPatterns, D as isVendorPath, G as isFileSizeScoped, J as GIT_BLOCKED, K as resolveSolidRefFramework, W as computeEditResultLines, b as interfaceDeclLevel, et as detectFramework, g as conventionsMode, lt as requiredArchSkill, n as FAIL_CLOSED, ot as detectModularArchitecture, rt as maskCommentsAndStrings, st as detectProjectType$1, t as evaluate } from "./evaluate-C1VSI5pb.mjs";
 import { a as sanitizeSessionId, c as sessionsDir, d as countFrameworkCodeLines, f as countLines, i as loadSessionState, l as PLUGINS_DIR, n as fuseHarnessHome, o as saveSessionState, p as evaluateFileSize, r as fusengineCache, t as claudeHome } from "./home-state-oUGFB4ds.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
 import { r as isDocConsulted } from "./doc-helpers-CWZegVdR.mjs";
-import { D as frameworkSolidGate, F as isExcludedSwiftPath, G as evaluateApex, H as PRE_AUTH_GATES, P as isExcludedJsPath, R as capVerbosity, S as parseField, T as usesTailwindUtilities, V as POST_AUTH_GATES, W as docConsultedGate, b as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, g as buildClaudeMdContext, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, p as apexAgentSteps, r as descFromText, s as parseEntry, t as isHtmlLike, v as apexDocName, w as skillTriggerGate, y as harnessHomeSegment, z as detectCreationIntent } from "./validate-C-TB06Mw.mjs";
-import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DhBGlQe3.mjs";
+import { D as frameworkSolidGate, F as isExcludedSwiftPath, G as evaluateApex, H as PRE_AUTH_GATES, P as isExcludedJsPath, R as capVerbosity, S as parseField, T as usesTailwindUtilities, V as POST_AUTH_GATES, W as docConsultedGate, b as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, g as buildClaudeMdContext, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, p as apexAgentSteps, r as descFromText, s as parseEntry, t as isHtmlLike, v as apexDocName, w as skillTriggerGate, y as harnessHomeSegment, z as detectCreationIntent } from "./validate-DZFtAbLP.mjs";
+import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DVML3zfp.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { a as nowStamp, l as throttleMs, n as readRoots, o as readState, s as setStateField, t as addRoot } from "./registry-IhHk2KlT.mjs";
 import { d as loadIndex, i as cacheLookupMeta, n as webfetchCacheWrite, o as cacheLookupSubstringMeta, t as mcpCacheWrite, u as extractText } from "./mcp-store-BkBDmuxN.mjs";
 import { t as loadRefs } from "./loader-AGz4nK7d.mjs";
-import { C as apexAuthorizationGate, S as trivialCount, _ as recordBrainstormRequired, a as journalLogPath, b as recordTarget, c as appendEvent, d as signTrack, f as verifyTrack, g as recordAgent, h as emptyTrack, i as withTrack, l as withTrackLockSync, m as agentsFresh, o as readTrackSync, p as writeLastNonce, r as trackJournalEnabled, s as diffTrackEvents, t as loadTrack, u as LOCK_FAILED, v as recordDoc, x as recordTrivialEdit, y as recordRefRead } from "./store-Dw08Amqh.mjs";
-import { n as parseApplyPatch, t as isBypassPermissions } from "./permission-mode-BN3MNgbm.mjs";
-import { _ as commandToString, d as collectFiles, f as pathExists, g as writeText, h as spawnCapture, i as denyResponse, l as systemMessage, m as sleep, n as blockResponse, p as readText$1, r as contextResponse, s as informResponse, t as attachSystemMessage } from "./claude-CEWX-8m9.mjs";
-import { i as toKimiResponse, n as kimiDenyResponse } from "./kimi-CqLkpg1A.mjs";
-import { r as toHermesResponse } from "./hermes-H6qePmBC.mjs";
+import { C as apexAuthorizationGate, S as trivialCount, _ as recordBrainstormRequired, a as journalLogPath, b as recordTarget, c as appendEvent, d as signTrack, f as verifyTrack, g as recordAgent, h as emptyTrack, i as withTrack, l as withTrackLockSync, m as agentsFresh, o as readTrackSync, p as writeLastNonce, r as trackJournalEnabled, s as diffTrackEvents, t as loadTrack, u as LOCK_FAILED, v as recordDoc, x as recordTrivialEdit, y as recordRefRead } from "./store-5-ZPKb0u.mjs";
+import { n as canonicalizeCodexShellTool, r as parseApplyPatch, t as isBypassPermissions } from "./permission-mode-B0MUl7FT.mjs";
+import { _ as commandToString, d as collectFiles, f as pathExists, g as writeText, h as spawnCapture, i as denyResponse, l as systemMessage, m as sleep, n as blockResponse, p as readText$1, r as contextResponse, s as informResponse, t as attachSystemMessage } from "./claude-5bC8TDAz.mjs";
+import { i as toKimiResponse, n as kimiDenyResponse } from "./kimi-D6X7b8wF.mjs";
+import { r as toHermesResponse } from "./hermes-kP6NUQlG.mjs";
 import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -90,7 +90,7 @@ function normalizeEvent(id, payload) {
 	}
 	const event = str(payload.hook_event_name) ?? "";
 	const input = payload.tool_input ?? payload;
-	const tool = str(payload.tool_name) ?? "";
+	const tool = canonicalizeCodexShellTool(id, str(payload.tool_name) ?? "");
 	const base = {
 		phase: /post|after/i.test(event) ? "post" : "pre",
 		tool,
@@ -600,6 +600,33 @@ function clearActiveDesignAgent(cacheDir) {
 	} catch {}
 }
 //#endregion
+//#region src/runtime/prompt-text.ts
+/** True for an object whose `text` property is a string (the only field this reads). */
+function hasTextField(value) {
+	return typeof value === "object" && value !== null && typeof value.text === "string";
+}
+/**
+* Coerce a hook payload's `prompt` field to plain text.
+*
+* - A string is returned AS-IS (same reference, no trim/normalize) — this is
+*   the identity branch that guarantees zero regression on Claude Code/Codex,
+*   whose `prompt` is already a string.
+* - An array (Kimi's content-block shape) is flattened: every element with a
+*   string `.text` is kept, joined with `"\n"` — one block per line, since
+*   downstream consumers ({@link detectCreationIntent}, {@link detectMode})
+*   only run `\b`-anchored regexes with no line-start/end assumption, so a
+*   newline join is safe and reads like the multi-turn/multi-block source.
+* - Anything else (`undefined`, `null`, a number, a plain object) yields `""`.
+*
+* @param value - The raw `prompt` field from a hook payload (unknown shape).
+* @returns The prompt text, or `""` when it cannot be recovered.
+*/
+function promptText(value) {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) return value.filter(hasTextField).map((b) => b.text).join("\n");
+	return "";
+}
+//#endregion
 //#region src/runtime/design-lifecycle.ts
 /**
 * Handle the design-agent SubagentStart/Stop lifecycle: init the pipeline state +
@@ -625,7 +652,7 @@ function designLifecycle(payload, cacheDir, cwd, stamp, now) {
 	if (event === "SubagentStart") {
 		if (!agentId) return false;
 		const dsExists = existsSync(join(cwd, "design-system.md"));
-		saveDesignState(cacheDir, initDesignState(agentId, detectMode(typeof payload.prompt === "string" ? payload.prompt : "", dsExists), dsExists));
+		saveDesignState(cacheDir, initDesignState(agentId, detectMode(promptText(payload.prompt), dsExists), dsExists));
 		setActiveDesignAgent(cacheDir, agentId);
 		return true;
 	}
@@ -893,12 +920,35 @@ function claudeMdKey(prompt, ctx) {
 	return `claude-md:${hashText(prompt)}:${hashText(ctx)}`;
 }
 /**
+* Extract the APEX preamble portion of a `buildClaudeMdContext` result, i.e.
+* everything BEFORE the `# <docName>\n` root-doc block it prepends on dev
+* prompts. Returns "" when `ctx` has no preamble (plain prompt: `ctx` starts
+* directly with the root-doc heading).
+* @param ctx - The full `buildClaudeMdContext` return value.
+* @param docName - Root doc file name (e.g. "AGENTS.md").
+* @returns The preamble text, or "" when absent.
+*/
+function extractApexPreamble(ctx, docName) {
+	const heading = `# ${docName}\n`;
+	if (ctx.startsWith(heading)) return "";
+	const sep = `\n\n${heading}`;
+	const idx = ctx.indexOf(sep);
+	return idx === -1 ? "" : ctx.slice(0, idx);
+}
+/**
 * UserPromptSubmit context injection: render the CLAUDE.md (+ optional APEX)
 * preamble as a Claude `additionalContext` response, or "" when nothing to emit.
 * Guarded by {@link oncePerWindow} via {@link claudeMdKey}: only a
 * near-simultaneous double-fire of the SAME turn (identical prompt AND identical
 * block, within {@link DEDUP_WINDOW_MS}) is suppressed. The invariant "CLAUDE.md
 * is emitted on EVERY message" is thus preserved.
+*
+* On kimi specifically, the root doc body is dropped from the emitted text:
+* Kimi loads `<kimiHome>/AGENTS.md` natively at session start (`apex-target.ts`),
+* so re-injecting its full body on every prompt is redundant terminal noise
+* (kimi has no model-only hook channel — `runtime/inform.ts`). The APEX
+* preamble, which is NOT part of `AGENTS.md`, is still emitted in full when the
+* prompt is dev-shaped; a plain prompt leaves only the notice.
 * @param prompt - The raw user prompt.
 * @param cwd - Project root (for project-type detection).
 * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
@@ -908,7 +958,12 @@ function promptSubmitContext(prompt, cwd, id = "claude-code") {
 	const ctx = buildClaudeMdContext(prompt, cwd, id);
 	if (!ctx) return "";
 	if (!oncePerWindow(claudeMdKey(prompt, ctx), 3e3)) return "";
-	return renderInform(id, "UserPromptSubmit", ctx, `${apexDocName(id)} injected`);
+	const notice = `${apexDocName(id)} injected`;
+	if (id === "kimi") {
+		const preamble = extractApexPreamble(ctx, apexDocName(id));
+		return preamble ? renderInform(id, "UserPromptSubmit", preamble, notice) : notice;
+	}
+	return renderInform(id, "UserPromptSubmit", ctx, notice);
 }
 /**
 * PreToolUse Task context injection: render the APEX sub-agent context as a
@@ -1092,6 +1147,45 @@ function sessionStartCore(cwd, home = homedir(), now = Date.now(), id = "claude-
 	return ctx ? attachSystemMessage(contextResponse("SessionStart", ctx), `${apexDocName(id)} injected`) : "";
 }
 //#endregion
+//#region src/runtime/lifecycle/kimi-rules-native.ts
+/**
+* Guard for the kimi notice-only rules injection. Kimi Code CLI has no
+* model-only hook channel (`src/runtime/inform.ts`) — every `UserPromptSubmit`
+* stdout is BOTH appended to the model's context AND rendered raw in the
+* user's terminal. `injectRules` (`inject-rules.ts`) normally re-injects the
+* full ~18 Ko rules corpus on every prompt; when the installer has already
+* merged that same corpus into `<kimiHome>/AGENTS.md` — which Kimi loads
+* natively at session start via its documented `${agents_md}` mechanism,
+* independent of hooks — the re-injection is pure noise the user has to
+* scroll past. Confirmed present, fenced, in the local install:
+* `~/.kimi-code/AGENTS.md:87` / `:335`.
+*
+* Fail-safe semantics: fences absent, file absent, or any read error ⟹
+* `false` — the caller then falls back to the full corpus. A dump is
+* verbose but never wrong; a false `true` would silently drop the rules.
+*/
+/** Opening fence the fusengine installer writes around the merged corpus. */
+const FENCE_START = "<!-- fusengine:kimi-rules:start -->";
+/** Closing fence the fusengine installer writes around the merged corpus. */
+const FENCE_END = "<!-- fusengine:kimi-rules:end -->";
+/**
+* Check whether the kimi rules corpus is already present, fenced, inside
+* `<kimiHome>/AGENTS.md`.
+* @param home - Kimi home dir override (defaults to `harnessHome("kimi")`,
+* which honors `KIMI_CODE_HOME`).
+* @returns `true` only when both fences are found in a readable file.
+*/
+function rulesInAgentsMd(home) {
+	try {
+		const agentsMd = join(home ?? harnessHome("kimi"), "AGENTS.md");
+		if (!existsSync(agentsMd)) return false;
+		const content = readFileSync(agentsMd, "utf-8");
+		return content.includes(FENCE_START) && content.includes(FENCE_END);
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/runtime/lifecycle/inject-rules.ts
 /** Read & concatenate all `*.md` files (sorted) under `rulesDir`. */
 function readRules(rulesDir) {
@@ -1115,6 +1209,13 @@ function readRules(rulesDir) {
 * with the *actual* `hookEventName` — the spec requires it to match the firing
 * event (a hardcoded "SessionStart" is non-conforming and may be dropped on
 * UserPromptSubmit/SubagentStart).
+*
+* On kimi's `UserPromptSubmit` specifically, when the corpus is already fenced
+* inside `<kimiHome>/AGENTS.md` (native load, {@link rulesInAgentsMd}), only the
+* notice is emitted — the re-injected corpus would otherwise dump into the
+* user's terminal on every single prompt for no model-context benefit.
+* `SessionStart`/`SubagentStart` always keep the full corpus (session bootstrap
+* / sub-agent contexts need it regardless of the native AGENTS.md load).
 * @param pluginRoot - `CLAUDE_PLUGIN_ROOT` of the claude-rules plugin.
 * @param event - The firing hook event name (e.g. "SessionStart").
 * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
@@ -1122,7 +1223,9 @@ function readRules(rulesDir) {
 */
 function injectRules(pluginRoot, event, id = "claude-code") {
 	const content = readRules(join(pluginRoot, "rules"));
-	return content ? renderInform(id, event, content, "rules 00-08 injected") : "";
+	if (!content) return "";
+	if (id === "kimi" && event === "UserPromptSubmit" && rulesInAgentsMd()) return "rules 00-08 injected";
+	return renderInform(id, event, content, "rules 00-08 injected");
 }
 //#endregion
 //#region src/runtime/lifecycle/solid-detect.ts
@@ -2417,6 +2520,114 @@ function harvestSubagentTrack(payload, cwd, now, baseDir = defaultStateDir(cwd))
 	}) === LOCK_FAILED) return;
 }
 //#endregion
+//#region src/runtime/confirm/confirm-subagent.ts
+/** Env var overriding the G0 cool-down window below (seconds). Unset = the 300s/5min default. */
+const CONFIRM_WINDOW_ENV_KEY = "FUSE_CONFIRM_SUBAGENT_WINDOW_SEC";
+/** Default G0 cool-down (seconds) when {@link CONFIRM_WINDOW_ENV_KEY} is unset/invalid — 300s (5min). */
+const DEFAULT_CONFIRM_WINDOW_SEC = 300;
+/**
+* G0 cool-down after the last SubagentStart/SubagentStop seen for this
+* session — {@link DEFAULT_CONFIRM_WINDOW_SEC} by default, overridable via
+* `FUSE_CONFIRM_SUBAGENT_WINDOW_SEC` (seconds) without a rebuild. Read this
+* doc before ever touching this value: it is NOT G0's primary protection,
+* and it is not sized to "safely cover a sub-agent's whole runtime".
+*
+* G0's PRIMARY protection is P0, measured live under Codex in a prior
+* session: a sub-agent never receives its own `UserPromptSubmit` — only a
+* human typing into the top-level session does — so a sub-agent is
+* STRUCTURALLY unable to place a CONFIRM token at all, regardless of this
+* window's value. This timestamp is a SECOND belt, covering only the
+* residual case where that structural property does not hold on some future
+* harness (Kimi: not yet measured either way).
+*
+* The default is a deliberate, owner-decided trade-off between over-refusal
+* and usability, NOT a safety-maximizing constant: sub-agents in this
+* ecosystem share the lead session's `session_id`, and the owner runs
+* sub-agents continuously — an earlier 30-minute window froze CONFIRM for
+* the entire session on every single sub-agent call, which neutralizes the
+* feature it protects (a guard that disables what it guards is not a good
+* guard). 5 minutes comfortably covers the case that actually matters — a
+* sub-agent genuinely in flight at the exact moment a human types a CONFIRM
+* code — without pinning a busy session shut. Do not read this value as "the
+* time G0 needs to be safe" — that safety comes from P0.
+*
+* This deliberately reuses {@link parseEnvInt} (`src/config/env.ts`) rather
+* than `resolveTtlSec`/`FUSE_ENFORCE_TTL_SEC` (`src/config/ttl.ts`): that TTL
+* governs APEX evidence freshness (120s default) — an unrelated concern
+* accidentally coupling the two would make lengthening the research-evidence
+* window also lengthen the confirmation cool-down. `resolveTtlSec` also
+* hardcodes its own fallback (`DEFAULT_TTL_SEC` = 120) regardless of which
+* env key is passed, so it cannot express a 300s default either — this key
+* gets its OWN env var and its OWN default via the same underlying
+* `parseEnvInt` primitive, with no new parsing logic.
+*
+* Mechanically this is still a single monotone "last seen" timestamp, NOT a
+* start/stop pair — a symmetric increment/decrement depth counter was tried
+* and rejected: the harness dispatches ONE real SubagentStart/SubagentStop
+* through MULTIPLE concurrent sibling plugin processes (the repo's own
+* "~11-process multi-plugin fan-out"), all doing UNLOCKED read-modify-write
+* on the same session-state file — a duplicated decrement can walk the
+* counter to 0 while a sub-agent is still running, and G0 would then wrongly
+* OPEN. Two ever-growing `starts`/`stops` counters were also rejected: if the
+* fan-out dispatches SubagentStart via N processes and SubagentStop via
+* M ≠ N, `starts > stops` stays true FOREVER and the session is frozen for
+* good — worse than any window.
+*
+* `Math.max(prevSeenAt, now)` avoids both failure modes: an LWW
+* (last-writer-wins) register merged with `max`, which is idempotent,
+* commutative, and associative — under ANY interleaving of concurrent
+* writers (lost updates included), the stored value converges to the
+* largest `now` any writer supplied, and every writer's `now` is a real
+* wall-clock read taken within milliseconds of the true event, so it can
+* never regress below a timestamp it already held. BOTH SubagentStart and
+* SubagentStop bump the SAME field this way — there is no decrement
+* anywhere in this file, so there is nothing for a duplicated event to
+* desynchronize; the flag falls only once this window elapses with no
+* further sighting.
+* @param env - Env map to resolve the override from (defaults to `process.env`; tests inject a plain object).
+*/
+function subagentWindowMs(env = process.env) {
+	return parseEnvInt(env[CONFIRM_WINDOW_ENV_KEY], DEFAULT_CONFIRM_WINDOW_SEC) * 1e3;
+}
+/**
+* G0: true within {@link subagentWindowMs} of the last SubagentStart/
+* SubagentStop seen for this session. An invalid/missing session id is
+* treated as active too — fail-closed, never pose a token when in doubt.
+*/
+function isSubagentActive(sessionIdRaw, now, home = homedir(), env = process.env) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid) return true;
+	const seenAt = loadSessionState(sid, home).subagentSeenAt;
+	return typeof seenAt === "number" && now - seenAt < subagentWindowMs(env);
+}
+/**
+* Record a SubagentStart OR SubagentStop sighting for this session as a
+* monotone max-write (see {@link subagentWindowMs}'s doc for why this can
+* never desync unsafely under concurrent racy writers). Both events call
+* this the SAME way — there is no separate "clear" path.
+*
+* Called unconditionally, BEFORE scope branching, on every SubagentStart/Stop
+* across every plugin (dispatch.ts) — never allowed to throw: a disk fault
+* here (full disk, unwritable home) must degrade to "sighting not recorded",
+* never crash sub-agent lifecycle dispatch for scopes that have nothing to do
+* with CONFIRM. Safe to swallow: G0's PRIMARY protection is P0 (a sub-agent
+* structurally never receives its own UserPromptSubmit, confirm-gate.ts's
+* doc) — this window is only a second belt, so losing one sighting degrades
+* that belt, it does not open the gate.
+*/
+function markSubagentSeen(sessionIdRaw, now, home = homedir()) {
+	try {
+		const sid = sanitizeSessionId(sessionIdRaw);
+		if (!sid) return;
+		const state = loadSessionState(sid, home);
+		const prev = typeof state.subagentSeenAt === "number" ? state.subagentSeenAt : 0;
+		saveSessionState(sid, {
+			...state,
+			subagentSeenAt: Math.max(prev, now)
+		}, home);
+	} catch {}
+}
+//#endregion
 //#region src/cli/doctor.ts
 /**
 * `harness doctor` — diagnose which `@fusengine/harness` is actually running.
@@ -5826,6 +6037,7 @@ function dispatchLifecycle(input) {
 			if (input.scope === "lessons") return dispatchLessons("UserPromptSubmit", input.payload, input.cwd, input.now, input.id ?? "claude-code");
 			return null;
 		case "SubagentStart":
+			markSubagentSeen(input.payload.session_id, input.now);
 			if (input.scope === "rules") return injectRules(resolveRulesRoot(input.id ?? "claude-code", input.cwd), input.event, input.id ?? "claude-code");
 			if (input.scope === "aipilot") return "";
 			if (input.scope === "lessons") return dispatchLessons("SubagentStart", input.payload, input.cwd, input.now, input.id ?? "claude-code");
@@ -5834,6 +6046,7 @@ function dispatchLifecycle(input) {
 			if (input.scope === "lessons") return dispatchLessons("Stop", input.payload, input.cwd, input.now, input.id ?? "claude-code");
 			return input.scope === "core" ? stopCore(input.payload, input.cwd, input.now) : null;
 		case "SubagentStop":
+			markSubagentSeen(input.payload.session_id, input.now);
 			if (input.scope === "aipilot") return "";
 			harvestSubagentTrack(input.payload, input.cwd, input.now);
 			return trackAgentMemory(input.payload, void 0, input.now);
@@ -8212,6 +8425,23 @@ function designSystemWriteGate(filePath, state, corpusRequired = false) {
 	if (state.screenshotsCount < needed) return deny(`BLOCKED: ${state.screenshotsCount}/${needed} screenshots for mode '${state.mode}'. RECOVERY: 1) Read the refs-design corpus (README.md + tokens-*.md) if not done 2) Take ${needed - state.screenshotsCount} more screenshots of REAL sector sites with mcp__fuse-browser__browser_screenshot (browser_shots_batch/browser_site_shots also count, 1 credit per call) 3) Use browser_open + browser_navigate + browser_screenshot fullPage:true 4) Then write design-system.md`);
 	return null;
 }
+/**
+* Gate writing .html/.css: PIPELINE gate (never `uiDesignSkillGate`/`UI_FILE_RE`
+* — owner-scoped out of the skill gate's remit). Requires phase >= 3 AND
+* designSystemValid (same two-condition defense as {@link geminiCreateGate})
+* AND `designSystemFileExists` (caller-computed via `findDesignSystem` — a
+* state can say phase 3 after the file was later deleted, or the file can
+* exist while a fresh agent's state is still phase 0).
+*/
+function htmlCssPipelineGate(filePath, state, designSystemFileExists) {
+	if (!/\.(html|css)$/.test(filePath)) return null;
+	if (state.currentPhase >= 3 && state.designSystemValid && designSystemFileExists) return null;
+	const gaps = [];
+	if (state.currentPhase < 3) gaps.push(`phase ${state.currentPhase}/3`);
+	if (!state.designSystemValid) gaps.push("design-system.md not validated");
+	if (!designSystemFileExists) gaps.push("design-system.md not found on disk");
+	return deny(`BLOCKED: cannot write '${filePath}' before the design-system pipeline is complete (${gaps.join(", ")}). RECOVERY: 1) Read identity templates from skills/design-system/ 2) Read design-inspiration.md 3) Read the refs-design corpus with the Read tool 4) Screenshot real sector sites with mcp__fuse-browser__browser_screenshot on a LIVE session 5) Write a valid design-system.md 6) Then write .html/.css`);
+}
 /** Gate Gemini create_frontend: requires phase >= 3 and a validated design system. */
 function geminiCreateGate(state) {
 	if (state.currentPhase < 3) return deny("BLOCKED: Cannot call Gemini create_frontend before phase 3. RECOVERY: 1) Complete the inspiration phase (refs-design corpus + sector screenshots) 2) Write a valid design-system.md 3) Then call mcp__gemini-design__create_frontend");
@@ -8246,12 +8476,28 @@ function browserNavigateGate(state, url) {
 function substituteLiteral(s, from, to, all) {
 	return all ? s.split(from).join(to) : s.replace(from, () => to);
 }
-/** Gate every file of a multi-file write primitive; the first violation blocks the envelope. */
-function designFilesGate(files, state, pluginsRoot, corpusRoot, corpusRequired, cwd) {
+/**
+* Gate every file of a multi-file write primitive; the first violation blocks
+* the envelope. `designSystemFileExists` is caller-computed (`findDesignSystem`
+* lives in `design-helpers.ts`, which itself imports `substituteLiteral` from
+* THIS module — importing it back here would cycle) so both write paths
+* (Write/Edit in `design.ts`, apply_patch here) consume the SAME disk read.
+*/
+function designFilesGate(files, state, pluginsRoot, corpusRoot, corpusRequired, cwd, designSystemFileExists) {
 	for (const f of files) {
 		const hit = pluginsWriteGuard(f.filePath, pluginsRoot, cwd) ?? stateFileGate(f.filePath);
 		if (hit) return hit;
 		if (f.op === "delete") continue;
+		const htmlCssHit = htmlCssOnlyGate(f.filePath);
+		if (htmlCssHit) return htmlCssHit;
+		const pipelineHit = htmlCssPipelineGate(f.filePath, state, designSystemFileExists);
+		if (pipelineHit) return pipelineHit;
+		if (geminiEnabled() && state.geminiCalls === 0 && /\.(html|css)$/.test(f.filePath)) return {
+			kind: "block",
+			title: "Design pipeline",
+			reason: "BLOCKED: generate the frontend via create_frontend before hand-writing HTML/CSS.",
+			actions: ["Call mcp__gemini-design__create_frontend first"]
+		};
 		if (!f.filePath.endsWith("design-system.md")) continue;
 		const gate = designSystemWriteGate(f.filePath, state, corpusRequired) ?? (f.op === "add" ? designSystemContentGate({
 			filePath: f.filePath,
@@ -8347,6 +8593,125 @@ function designSystemContentGate(i) {
 	return deny(`BLOCKED: design-system.md too generic. Missing: ${introduced.join(", ")}. RECOVERY: fix the content (read cited refs-design references with the Read tool), then retry.`);
 }
 //#endregion
+//#region src/policy/shell-read-refs.ts
+/**
+* @module shell-read-refs
+* Codex teammates frequently read skill/SOLID reference `.md` files through a
+* shell Bash call (`cat`, `head`, …) instead of a native `Read` — the
+* refsRead/ref-journal freshness gates only ever credited a native `Read`
+* (`src/runtime/activity.ts`'s `READ_TOOLS` branch), so a shell-read skill
+* consultation was invisible to every SOLID/skill gate. This detects the
+* `.md` paths a KNOWN read-only command targets in a Bash `command`, for a
+* caller to fold into the SAME `{kind:"ref", path, ts}` activity
+* `src/runtime/record.ts` already persists (no new store, no new gate).
+*
+* Fail-open by construction: only a whitelisted read-only command name
+* credits its `.md` arguments — a non-read command (`echo`, `mv`, `tee`, …)
+* sharing a chained/piped segment is never credited, and `sed -i`/
+* `--in-place` (a MUTATION despite the `sed` name) is explicitly excluded.
+* @packageDocumentation
+*/
+/** Read-only shell commands that can target a `.md` reference by path. */
+const READ_COMMANDS = /* @__PURE__ */ new Set([
+	"cat",
+	"head",
+	"tail",
+	"sed",
+	"rg",
+	"ripgrep",
+	"less",
+	"more",
+	"bat"
+]);
+/** POSIX shells whose `-c`-style argv (or inline string) wraps a real script. */
+const SHELL_BINS = /* @__PURE__ */ new Set([
+	"bash",
+	"sh",
+	"zsh",
+	"dash"
+]);
+/** `sed -i` / `sed --in-place` mutates the file in place — never a read. */
+const SED_INPLACE = /(^|\s)(-i\b|--in-place\b)/;
+/** Split a command string on `&&`, `||`, `;`, `|`, and newlines — each side scanned independently. */
+function segments(command) {
+	return command.split(/&&|\|\||[;|\n]/);
+}
+/** Strip a redirection (`>`, `>>`, `<`, `2>`, `&>`, …) and everything after — its target is WRITTEN, not read. */
+function beforeRedirect(segment) {
+	const m = segment.match(/\s(?:\d*>{1,2}|<|&>)\s*\S/);
+	return m ? segment.slice(0, m.index) : segment;
+}
+/** Naive shell tokenizer: whitespace-split, stripping one matching layer of quotes per token. */
+function tokenize(segment) {
+	return (segment.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? []).map((t) => /^(['"]).*\1$/.test(t) ? t.slice(1, -1) : t);
+}
+/** Index of the first token that isn't an env-assignment prefix (`KEY=VAL cmd …`). */
+function firstCommandIndex(tokens) {
+	let i = 0;
+	while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i] ?? "")) i++;
+	return i;
+}
+/** The inner script of a `sh|bash|zsh|dash -c <script>` wrapper (as ONE token, since {@link tokenize} keeps a quoted phrase whole), or undefined when `tokens` isn't that shape. */
+function unwrapShellC(tokens) {
+	const i = firstCommandIndex(tokens);
+	const bin = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+	if (!bin || !SHELL_BINS.has(bin)) return void 0;
+	const flag = tokens[i + 1];
+	if (!flag || !/^-[a-z]*c$/.test(flag)) return void 0;
+	return tokens[i + 2];
+}
+/** Credit the `.md` arguments of one segment if its command is a whitelisted read; recurses once into a `sh -c` wrapper. */
+function scanSegment(raw, out) {
+	const segment = beforeRedirect(raw);
+	const tokens = tokenize(segment);
+	const inner = unwrapShellC(tokens);
+	if (inner !== void 0) {
+		for (const s of segments(inner)) scanSegment(s, out);
+		return;
+	}
+	const i = firstCommandIndex(tokens);
+	const name = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
+	if (!name || !READ_COMMANDS.has(name)) return;
+	if (name === "sed" && SED_INPLACE.test(segment)) return;
+	for (const t of tokens.slice(i + 1)) if (t.endsWith(".md") && !t.startsWith("-")) out.push(t);
+}
+/**
+* The `.md` paths a read-only shell command reads in `command` (a Bash
+* `tool_input.command` — plain string or Codex's argv-array form, both
+* normalized via {@link commandToString}). Empty for a non-read command,
+* `sed -i` in-place, or an unparseable/absent command — fail-open, never a
+* false credit.
+* @param command - Raw `tool_input.command` value (string | string[] | unknown).
+*/
+function shellReadRefPaths(command) {
+	const str = commandToString(command);
+	if (!str) return [];
+	const out = [];
+	for (const seg of segments(str)) scanSegment(seg, out);
+	return out;
+}
+//#endregion
+//#region src/runtime/design-read-credit.ts
+/**
+* @module design-read-credit
+* Shared credit path for a design-corpus/ref read, reused by both the native
+* `Read` branch and the shell-read branch (Codex Code Mode `exec_command`,
+* canonicalized to `"Bash"` by `codex-shell-tool.ts`) in
+* `design-helpers.ts::recordPost`. Split out to keep that file within the
+* SOLID size budget — zero new parser, zero new store: both callers hit the
+* SAME `recordCorpusRead`/`recordRead` transitions.
+* @packageDocumentation
+*/
+/** Credit one read path as a corpus read (anchored + on-disk) or a plain ref read. */
+function creditRead(cacheDir, state, corpusRoot, corpusRequired, fp) {
+	if (classifyCorpusRead(fp, corpusRoot) && existsSync(fp)) saveDesignState(cacheDir, recordCorpusRead(state, fp.slice(corpusRoot.length + 1), corpusRequired));
+	else saveDesignState(cacheDir, recordRead(state, fp, corpusRequired));
+}
+/** Credit every `.md` path a read-only shell `command` targets, same path as {@link creditRead}. */
+function creditShellReads(cacheDir, state, corpusRoot, corpusRequired, command) {
+	for (const fp of shellReadRefPaths(command)) creditRead(cacheDir, state, corpusRoot, corpusRequired, fp);
+}
+//#endregion
 //#region src/runtime/design-helpers.ts
 /**
 * @module design-helpers
@@ -8383,11 +8748,9 @@ function recordPost(event, cacheDir, state, corpusRoot = "", corpusRequired = fa
 		...state,
 		geminiCalls: state.geminiCalls + 1
 	});
-	else if (event.tool === "Read") {
-		const fp = event.filePath ?? "";
-		if (classifyCorpusRead(fp, corpusRoot) && existsSync(fp)) saveDesignState(cacheDir, recordCorpusRead(state, fp.slice(corpusRoot.length + 1), corpusRequired));
-		else saveDesignState(cacheDir, recordRead(state, fp, corpusRequired));
-	} else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) {
+	else if (event.tool === "Read") creditRead(cacheDir, state, corpusRoot, corpusRequired, event.filePath ?? "");
+	else if (event.tool === "Bash" && event.command) creditShellReads(cacheDir, state, corpusRoot, corpusRequired, event.command);
+	else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) {
 		const fp = event.filePath ?? "";
 		let content;
 		try {
@@ -8435,6 +8798,14 @@ function designGate(payload, event, cacheDir, cwd, corpusRootOverride, pluginsRo
 		const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
 		if (skillBlock) return skillBlock;
 	}
+	if (event.phase !== "post" && event.files && event.files.length > 0) {
+		const evidence = collectDesignEvidence(event.sessionId, cwd);
+		for (const f of event.files) {
+			if (f.op === "delete") continue;
+			const skillBlock = uiDesignSkillGate(f.op === "add" ? "Write" : "Edit", f.filePath, f.content, evidence);
+			if (skillBlock) return skillBlock;
+		}
+	}
 	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
 	if (!agentId) return null;
 	const active = activeDesignAgent(cacheDir);
@@ -8465,7 +8836,7 @@ function designGate(payload, event, cacheDir, cwd, corpusRootOverride, pluginsRo
 	}
 	if (event.tool === "Write" || event.tool === "Edit") {
 		const fp = event.filePath ?? "";
-		const base = pluginsWriteGuard(fp, pluginsRoot) ?? stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? designSystemWriteGate(fp, state, corpusRequired) ?? designSystemContentGate({
+		const base = pluginsWriteGuard(fp, pluginsRoot) ?? stateFileGate(fp) ?? htmlCssOnlyGate(fp) ?? htmlCssPipelineGate(fp, state, findDesignSystem(cwd) !== "") ?? designSystemWriteGate(fp, state, corpusRequired) ?? designSystemContentGate({
 			filePath: fp,
 			tool: event.tool,
 			content: event.content ?? "",
@@ -8484,7 +8855,7 @@ function designGate(payload, event, cacheDir, cwd, corpusRootOverride, pluginsRo
 		};
 		return null;
 	}
-	if (event.files && event.files.length > 0) return designFilesGate(event.files, state, pluginsRoot, corpusRoot, corpusRequired, cwd);
+	if (event.files && event.files.length > 0) return designFilesGate(event.files, state, pluginsRoot, corpusRoot, corpusRequired, cwd, findDesignSystem(cwd) !== "");
 	if (event.tool === NAV) return browserNavigateGate(state, typeof event.input.url === "string" ? event.input.url : "");
 	if (event.tool === SHOT) return screenshotScrollGate(state);
 	if (event.tool === GEMINI) {
@@ -8830,6 +9201,191 @@ function applyPatchGate(files, cwd) {
 	return null;
 }
 //#endregion
+//#region src/runtime/confirm/confirm-code.ts
+/**
+* Full SHA-256 hex digest (64 chars) of an action string (the exact command
+* a deny prompt showed). This is the ONLY value ever compared to authorize a
+* confirmation (G3, confirm-state.ts) — collision-resistant, unlike the
+* 4-char {@link displayCodeForAction} below.
+* @param action - The command/content string a deny prompt showed.
+*/
+function hashForAction(action) {
+	return createHash("sha256").update(action).digest("hex");
+}
+/**
+* 4-hex-char PREFIX of {@link hashForAction}, for DISPLAY ONLY — never a
+* security boundary. It exists purely so a human has something short to
+* retype ("CONFIRM 4f2a"); at 16 bits it collides constantly across
+* unrelated actions (birthday bound ~a few hundred actions/session), and the
+* agent ALWAYS sees it too — `systemMessage` never reaches the user or model
+* under Codex (measured 2026-08-03: 0 occurrence in the rollout, nothing on
+* screen), so `permissionDecisionReason` is the only channel, and the model
+* reads its own code back in the very tool result that got blocked.
+*
+* What actually scopes a confirmation to ONE specific action is the full
+* hash recorded at deny time and re-checked at consume time (see
+* confirm-pending.ts / confirm-state.ts). What prevents an agent from typing
+* its own code back to self-approve is G0 (fail-closed while a sub-agent is
+* active) — never the code's secrecy, because it has none.
+* @param action - The command/content string to derive the display code from.
+*/
+function displayCodeForAction(action) {
+	return hashForAction(action).slice(0, 4);
+}
+//#endregion
+//#region src/runtime/confirm/confirm-irreversible.ts
+/**
+* A single flag token carrying BOTH `r` and `f` in either order (`-rf`,
+* `-fr`, `-rfv`, …) — same lookahead technique as patterns.ts's
+* `CLEAN_FD_FLAG`, reused here rather than re-derived (DRY).
+*/
+const RM_COMBINED_FLAG = /\s-(?=[a-zA-Z]*r)(?=[a-zA-Z]*f)[a-zA-Z]+(?:\s|=|$)/;
+/** Split flags `-r ... -f` (either order) within the SAME command segment (no `;&|` between). */
+const RM_SPLIT_FLAG = /\brm\b[^;&|\n]*\s-r\b[^;&|\n]*\s-f\b|\brm\b[^;&|\n]*\s-f\b[^;&|\n]*\s-r\b/;
+/**
+* Generic `rm -rf`/`-fr` (ANY target, not just `/`/`~`) — deliberately
+* broader than `src/codex-rules/rules/rm-variants.ts`'s root/system-path-only
+* forbidden list: G4 must treat every recursive force-delete as
+* never-confirmable, not only the ones aimed at a system path.
+*/
+function isRmRf(cmd) {
+	return /\brm\b/.test(cmd) && (RM_COMBINED_FLAG.test(cmd) || RM_SPLIT_FLAG.test(cmd));
+}
+/**
+* G4: commands NEVER unlockable by a CONFIRM token, regardless of a valid,
+* fresh, correctly-scoped one. Reuses {@link GIT_BLOCKED} (push --force,
+* reset --hard, clean -fd, branch -D, rebase --force — DRY, same list the
+* rest of the policy already enforces) plus a generic `rm -rf` check.
+* @param cmd - The command a prompt is about (empty/undefined = not irreversible).
+*/
+function isIrreversible(cmd) {
+	if (!cmd) return false;
+	return matchPatterns(cmd, GIT_BLOCKED) || isRmRf(cmd);
+}
+//#endregion
+//#region src/runtime/confirm/confirm-pending.ts
+/**
+* Record the action a deny prompt just showed (overwrites any previous
+* pending deny for this session — only the LAST blocked action can be
+* confirmed). Pure bookkeeping, no gate: every ask-turned-deny records one,
+* whether or not the user ever confirms it.
+* @param sessionIdRaw - Raw session id from the payload.
+* @param hash - Full {@link import("./confirm-code").hashForAction} of the command.
+* @param code - The short display code shown alongside it.
+* @param now - Epoch ms.
+* @param home - Test-only OS home override.
+*/
+function recordPendingDeny(sessionIdRaw, hash, code, now, home = homedir()) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid) return;
+	saveSessionState(sid, {
+		...loadSessionState(sid, home),
+		pendingDeny: {
+			hash,
+			code,
+			ts: now
+		}
+	}, home);
+}
+/** Read back the pending deny for a session (`undefined` when none/invalid session id). */
+function getPendingDeny(sessionIdRaw, home = homedir()) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid) return void 0;
+	return loadSessionState(sid, home).pendingDeny;
+}
+//#endregion
+//#region src/runtime/confirm/confirm-state.ts
+/** Confirmation freshness window (G2) — 5 minutes, matches the validated prototype. */
+const TTL_MS = 300 * 1e3;
+/**
+* Pose a confirmation token for this session's pending action. No-op while
+* {@link isSubagentActive} (G0, confirm-subagent.ts) — the sole gate that
+* stops an agent, which always sees the display code in its own blocked tool
+* result, from typing it back to self-approve.
+*/
+function placeConfirmToken(sessionIdRaw, hash, now, home = homedir(), env = process.env) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid || isSubagentActive(sid, now, home, env)) return;
+	saveSessionState(sid, {
+		...loadSessionState(sid, home),
+		confirmToken: {
+			hash,
+			ts: now
+		}
+	}, home);
+}
+/** Invalidate any pending token for this session (G5: an explicit refusal). */
+function dropConfirmToken(sessionIdRaw, home = homedir()) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid) return;
+	const state = loadSessionState(sid, home);
+	if (state.confirmToken === void 0) return;
+	const { confirmToken: _drop, ...rest } = state;
+	saveSessionState(sid, rest, home);
+}
+/**
+* Consume a token that matches `hash` exactly (G3), whether or not it's
+* fresh — a mismatched hash leaves the token untouched (it may still be
+* valid for the action it actually confirms). G1 (one-shot) + G2 (5-min TTL)
+* both apply only once the hash matches.
+* @returns true = allow (token consumed); false = deny (nothing changed, or
+* the matching token had expired and was dropped).
+*/
+function consumeConfirmToken(sessionIdRaw, hash, now, home = homedir()) {
+	const sid = sanitizeSessionId(sessionIdRaw);
+	if (!sid) return false;
+	const tok = loadSessionState(sid, home).confirmToken;
+	if (!tok || tok.hash !== hash) return false;
+	if (now - tok.ts > TTL_MS) {
+		dropConfirmToken(sid, home);
+		return false;
+	}
+	dropConfirmToken(sid, home);
+	return true;
+}
+//#endregion
+//#region src/runtime/confirm/confirm-gate.ts
+/**
+* Harnesses where `respond.ts` silently downgrades `kind: "ask"` to a hard
+* deny (Codex: `case "codex"`; Kimi: `toKimiResponse` maps `ask` to the same
+* `permissionDecision:"deny"` envelope as `block`). Claude Code keeps native
+* interactive `ask` — this mechanism NEVER applies there.
+*/
+const DEGRADES_ASK_TO_DENY = /* @__PURE__ */ new Set(["codex", "kimi"]);
+/**
+* Whether/how a CONFIRM token changes an `ask` prompt about to be downgraded
+* to a deny. Returns `null` when this mechanism doesn't apply AT ALL — any
+* harness other than codex/kimi, any prompt kind other than `ask`, no
+* command to key a hash off, or an irreversible command (G4) — in which case
+* the caller's ORIGINAL prompt/response path runs completely unchanged. That
+* `null` fast-path, hit on every claude-code call and every non-`ask` prompt,
+* IS the non-regression property.
+* @param id - Harness target id.
+* @param prompt - The prompt `gate()` returned.
+* @param command - `event.command` for the tool-use under judgment.
+* @param sessionId - `event.sessionId`.
+* @param now - Epoch ms.
+* @param home - Test-only OS home override.
+*/
+function confirmGate(id, prompt, command, sessionId, now, home) {
+	if (prompt.kind !== "ask" || !DEGRADES_ASK_TO_DENY.has(id) || !command || isIrreversible(command)) return null;
+	try {
+		const hash = hashForAction(command);
+		if (consumeConfirmToken(sessionId, hash, now, home)) return { allow: true };
+		const code = displayCodeForAction(command);
+		recordPendingDeny(sessionId, hash, code, now, home);
+		return {
+			allow: false,
+			prompt: {
+				...prompt,
+				reason: `${prompt.reason}\nPour autoriser, réponds : CONFIRM ${code}`
+			}
+		};
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/runtime/handle-pre.ts
 /**
 * Run the PreToolUse pipeline: MCP/WebFetch cache intercept, design gate, APEX Task context injection, then the stateless+APEX gate chain, returning the native hook outcome (deny/ask/inject or allow).
@@ -8838,6 +9394,7 @@ function applyPatchGate(files, cwd) {
 */
 async function handlePre(ctx) {
 	const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+	const designCacheDir = ctx.designCacheDir ?? mcpDir;
 	const intercept = mcpPreIntercept(id, event.tool, event.input, mcpDir, MCP_TTL_MS, opts.now);
 	if (intercept !== null) {
 		if (intercept.docSource) await recordActivity(file, {
@@ -8851,7 +9408,7 @@ async function handlePre(ctx) {
 			exit: 0
 		};
 	}
-	const designBlock = designGate(payload, event, mcpDir, opts.cwd, opts.corpusRoot);
+	const designBlock = designGate(payload, event, designCacheDir, opts.cwd, opts.corpusRoot);
 	if (designBlock) return {
 		stdout: withDenyNotice(id, respond(id, designBlock), designBlock, event.sessionId, dirname(file), opts.now),
 		exit: 0
@@ -8894,11 +9451,20 @@ async function handlePre(ctx) {
 		transcriptPath: typeof payload.transcript_path === "string" ? payload.transcript_path : void 0,
 		neverApproval: id === "codex" && isBypassPermissions(event.permissionMode)
 	});
-	if (prompt) return {
-		stdout: withDenyNotice(id, respond(id, prompt), prompt, event.sessionId, dirname(file), opts.now),
-		exit: 0
-	};
-	return allowOutcome(id, event, payload, mcpDir, opts.cwd, {
+	if (prompt) {
+		const confirm = confirmGate(id, prompt, event.command, event.sessionId, opts.now, opts.home);
+		if (confirm?.allow) return allowOutcome(id, event, payload, designCacheDir, opts.cwd, {
+			trackFile: file,
+			windowMs: opts.windowMs,
+			now: opts.now
+		}, opts.corpusRoot);
+		const finalPrompt = confirm ? confirm.prompt : prompt;
+		return {
+			stdout: withDenyNotice(id, respond(id, finalPrompt), finalPrompt, event.sessionId, dirname(file), opts.now),
+			exit: 0
+		};
+	}
+	return allowOutcome(id, event, payload, designCacheDir, opts.cwd, {
 		trackFile: file,
 		windowMs: opts.windowMs,
 		now: opts.now
@@ -8984,104 +9550,6 @@ function docFramework(input, fallback) {
 	return frameworkFromQuery(docQueryOf(input)) ?? fallback;
 }
 //#endregion
-//#region src/policy/shell-read-refs.ts
-/**
-* @module shell-read-refs
-* Codex teammates frequently read skill/SOLID reference `.md` files through a
-* shell Bash call (`cat`, `head`, …) instead of a native `Read` — the
-* refsRead/ref-journal freshness gates only ever credited a native `Read`
-* (`src/runtime/activity.ts`'s `READ_TOOLS` branch), so a shell-read skill
-* consultation was invisible to every SOLID/skill gate. This detects the
-* `.md` paths a KNOWN read-only command targets in a Bash `command`, for a
-* caller to fold into the SAME `{kind:"ref", path, ts}` activity
-* `src/runtime/record.ts` already persists (no new store, no new gate).
-*
-* Fail-open by construction: only a whitelisted read-only command name
-* credits its `.md` arguments — a non-read command (`echo`, `mv`, `tee`, …)
-* sharing a chained/piped segment is never credited, and `sed -i`/
-* `--in-place` (a MUTATION despite the `sed` name) is explicitly excluded.
-* @packageDocumentation
-*/
-/** Read-only shell commands that can target a `.md` reference by path. */
-const READ_COMMANDS = /* @__PURE__ */ new Set([
-	"cat",
-	"head",
-	"tail",
-	"sed",
-	"rg",
-	"ripgrep",
-	"less",
-	"more",
-	"bat"
-]);
-/** POSIX shells whose `-c`-style argv (or inline string) wraps a real script. */
-const SHELL_BINS = /* @__PURE__ */ new Set([
-	"bash",
-	"sh",
-	"zsh",
-	"dash"
-]);
-/** `sed -i` / `sed --in-place` mutates the file in place — never a read. */
-const SED_INPLACE = /(^|\s)(-i\b|--in-place\b)/;
-/** Split a command string on `&&`, `||`, `;`, `|`, and newlines — each side scanned independently. */
-function segments(command) {
-	return command.split(/&&|\|\||[;|\n]/);
-}
-/** Strip a redirection (`>`, `>>`, `<`, `2>`, `&>`, …) and everything after — its target is WRITTEN, not read. */
-function beforeRedirect(segment) {
-	const m = segment.match(/\s(?:\d*>{1,2}|<|&>)\s*\S/);
-	return m ? segment.slice(0, m.index) : segment;
-}
-/** Naive shell tokenizer: whitespace-split, stripping one matching layer of quotes per token. */
-function tokenize(segment) {
-	return (segment.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? []).map((t) => /^(['"]).*\1$/.test(t) ? t.slice(1, -1) : t);
-}
-/** Index of the first token that isn't an env-assignment prefix (`KEY=VAL cmd …`). */
-function firstCommandIndex(tokens) {
-	let i = 0;
-	while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i] ?? "")) i++;
-	return i;
-}
-/** The inner script of a `sh|bash|zsh|dash -c <script>` wrapper (as ONE token, since {@link tokenize} keeps a quoted phrase whole), or undefined when `tokens` isn't that shape. */
-function unwrapShellC(tokens) {
-	const i = firstCommandIndex(tokens);
-	const bin = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
-	if (!bin || !SHELL_BINS.has(bin)) return void 0;
-	const flag = tokens[i + 1];
-	if (!flag || !/^-[a-z]*c$/.test(flag)) return void 0;
-	return tokens[i + 2];
-}
-/** Credit the `.md` arguments of one segment if its command is a whitelisted read; recurses once into a `sh -c` wrapper. */
-function scanSegment(raw, out) {
-	const segment = beforeRedirect(raw);
-	const tokens = tokenize(segment);
-	const inner = unwrapShellC(tokens);
-	if (inner !== void 0) {
-		for (const s of segments(inner)) scanSegment(s, out);
-		return;
-	}
-	const i = firstCommandIndex(tokens);
-	const name = tokens[i]?.slice(tokens[i].lastIndexOf("/") + 1);
-	if (!name || !READ_COMMANDS.has(name)) return;
-	if (name === "sed" && SED_INPLACE.test(segment)) return;
-	for (const t of tokens.slice(i + 1)) if (t.endsWith(".md") && !t.startsWith("-")) out.push(t);
-}
-/**
-* The `.md` paths a read-only shell command reads in `command` (a Bash
-* `tool_input.command` — plain string or Codex's argv-array form, both
-* normalized via {@link commandToString}). Empty for a non-read command,
-* `sed -i` in-place, or an unparseable/absent command — fail-open, never a
-* false credit.
-* @param command - Raw `tool_input.command` value (string | string[] | unknown).
-*/
-function shellReadRefPaths(command) {
-	const str = commandToString(command);
-	if (!str) return [];
-	const out = [];
-	for (const seg of segments(str)) scanSegment(seg, out);
-	return out;
-}
-//#endregion
 //#region src/runtime/activity.ts
 /** Quality thresholds (chars): lead agent calls vs direct explore/research (parity Python `> 50`). */
 const AGENT_QUALITY_MIN = 500;
@@ -9400,17 +9868,29 @@ function firstFileMatch(files, check) {
 /**
 * Run the PostToolUse pipeline: store the MCP response, emit a design warning,
 * record the activity into the session track, apply per-scope side-effects (SEO
-* deny, aipilot task cache), then inject the post-edit context. Codex
-* `apply_patch` is fanned into per-file events ({@link fanOutFiles}) before the
-* per-file gates (tracking, SOLID size, Tailwind, post-edit context) run.
+* deny, aipilot task cache), then inject the post-edit context.
+*
+* POST is advisory-only for the design pipeline: it can never undo a tool
+* that already ran (the hard block lives in the PreToolUse `designFilesGate`).
+* `designGate` therefore stays on the RAW, un-fanned event — its
+* `recordPost` apply_patch branch is promote-only and resolves relative
+* `design-system.md` paths via `join(cwd, …)` (design-helpers.ts); fanning
+* that call would instead route the file through the Write/Edit branch,
+* which reads `event.filePath` UNRESOLVED (breaking cwd-relative promotion)
+* and can DEGRADE the state — both forbidden by the apply_patch promote-only
+* doctrine (see `design-files-gate.ts` module doc). Only `designPassNotice`
+* (pure formatting, no disk access, no state write) is fanned via
+* {@link fanOutFiles}, so `apply_patch` gets one notice line per real file
+* instead of none.
 * @param ctx - The resolved context (same shape as the pre pipeline).
 * @returns The native hook outcome.
 */
 async function handlePost(ctx) {
 	const { id, payload, event, framework, mcpDir, file, opts } = ctx;
+	const designCacheDir = ctx.designCacheDir ?? mcpDir;
 	const response = payload.tool_response ?? payload.tool_output;
 	mcpPostStore(event.tool, event.input, response, mcpDir);
-	const designWarn = designGate(payload, event, mcpDir, opts.cwd, opts.corpusRoot);
+	const designWarn = designGate(payload, event, designCacheDir, opts.cwd, opts.corpusRoot);
 	const activities = activityFor({
 		tool: event.tool,
 		input: event.input,
@@ -9462,14 +9942,25 @@ async function handlePost(ctx) {
 		extra = await postEditContext(opts.scope ?? "core", f, opts.now, id);
 		if (extra) break;
 	}
-	const notice = designPassNotice({
-		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
-		tool: event.tool,
-		filePath: event.filePath ?? "",
-		content: event.content ?? "",
-		url: "",
-		phase: "post"
-	}, mcpDir);
+	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
+	const noticeLines = [];
+	for (const f of files) {
+		const n = designPassNotice({
+			agentId,
+			tool: f.tool,
+			filePath: f.filePath ?? "",
+			content: f.content ?? "",
+			url: "",
+			phase: "post"
+		}, designCacheDir);
+		if (n?.userMessage) noticeLines.push(n.userMessage);
+	}
+	const notice = noticeLines.length ? {
+		kind: "inform",
+		title: "Design pipeline",
+		reason: "",
+		userMessage: noticeLines.join("\n")
+	} : null;
 	const refNotice = refCreditNoticeFor(activities, event.sessionId, opts.now, defaultStateDir(opts.cwd));
 	const userMessage = [notice?.userMessage, refNotice].filter(Boolean).join("\n") || void 0;
 	if (designWarn) return {
@@ -9532,6 +10023,53 @@ async function asyncScopeStdout(scope, event, payload, cwd, now, id = "claude-co
 	return null;
 }
 //#endregion
+//#region src/runtime/design-cache-resolve.ts
+/** `~/.fuse-harness/design-sessions/<sid>` — session-anchored design-state dir. */
+function sessionCacheDir(sid, home) {
+	return join(fuseHarnessHome(home), "design-sessions", sid);
+}
+/** True when `dir` already holds the design-agent flag or a `.design-state-*.json` snapshot. */
+function hasDesignState(dir) {
+	if (existsSync(join(dir, "design-agent-active"))) return true;
+	try {
+		return readdirSync(dir).some((name) => name.startsWith(".design-state-"));
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve the cache dir the design pipeline (active-agent flag +
+* `.design-state-<agentId>.json`) should read AND write for this hook call.
+*
+* Anchored on the session id, not the invoking process's `cwd`: a design
+* agent's `SubagentStart` and its later tool writes can run with different
+* `process.cwd()` values, and a cwd-keyed cache dir then silently misses the
+* flag/state — every design gate fails open (see MEMORY/LESSON.md).
+*
+* Contract (non-regression): `resolved = sessionDirIfPopulated ??
+* cwdDirIfPopulated ?? sessionDirDefault`. Before this fix the session-keyed
+* dir never existed, so for every session whose state already lives under
+* `cwdCacheDir` the FIRST branch is always empty and resolution falls through
+* to `cwdCacheDir` — byte-identical to the pre-fix value. Only a session with
+* NO state anywhere (today's silent-fail-open case, e.g. cwd drifted between
+* `SubagentStart` and the write) diverges, anchoring on the session dir
+* instead of silently missing the flag. Read and write always resolve through
+* this same function against the same two inputs, so they can never target
+* different locations mid-session.
+* @param sessionId - The hook event's session id (`NormalizedEvent.sessionId`).
+* @param cwdCacheDir - The legacy, cwd-derived cache dir (`projectLayout(cwd).cacheDir`).
+* @param home - OS home override (tests only).
+* @returns The cache dir to pass to the design flag/state/gate functions.
+*/
+function resolveDesignCacheDir(sessionId, cwdCacheDir, home) {
+	const sid = sanitizeSessionId(sessionId);
+	if (!sid) return cwdCacheDir;
+	const sessDir = sessionCacheDir(sid, home);
+	if (hasDesignState(sessDir)) return sessDir;
+	if (hasDesignState(cwdCacheDir)) return cwdCacheDir;
+	return sessDir;
+}
+//#endregion
 //#region src/runtime/lifecycle/codex-resync/lock.ts
 /** Stale-after window (ms) — survives a session crashing before its `finally`. */
 const STALE_MS = 3e4;
@@ -9918,6 +10456,39 @@ function attachBudgetRecap(stdout, rawEvent, sessionId, cwd, now) {
 	return attachSystemMessage(stdout, budgetReport(fragments));
 }
 //#endregion
+//#region src/runtime/confirm/confirm-submit.ts
+/** Common explicit-refusal words (fr/en), any of which invalidates a pending token (G5). */
+const REFUSAL_RE = /\b(non|no|stop|annule|cancel|abort|nope|laisse tomber|pas maintenant)\b/i;
+/** `CONFIRM <4-hex-chars>`, case-insensitive, tolerant of `confirm4f2a` / `Confirm-4f2a` / `confirm_4f2a`. */
+const CONFIRM_RE = /confirm[\s_-]*([0-9a-f]{4})\b/i;
+/**
+* Parse a submitted user prompt for `CONFIRM <code>` or an explicit refusal.
+* A refusal always wins (checked first) and drops any pending token (G5),
+* even if the same text also happens to contain a code. A confirm only
+* places a token when its 4-char code matches this session's LAST pending
+* deny (see confirm-pending.ts) — the code is looked up back to the full
+* hash that deny recorded, never compared as a code-to-code match (that
+* would reopen the collision {@link import("./confirm-code").displayCodeForAction}
+* warns about). Never throws — this runs inside a hook.
+* @param sessionId - The normalized event's session id.
+* @param text - The prompt text ({@link import("../prompt-text").promptText} output).
+* @param now - Epoch ms.
+* @param home - Test-only OS home override.
+*/
+function handleConfirmSubmit(sessionId, text, now, home) {
+	try {
+		if (REFUSAL_RE.test(text)) {
+			dropConfirmToken(sessionId, home);
+			return;
+		}
+		const typedCode = text.match(CONFIRM_RE)?.[1];
+		if (!typedCode) return;
+		const pending = getPendingDeny(sessionId, home);
+		if (!pending || pending.code.toLowerCase() !== typedCode.toLowerCase()) return;
+		placeConfirmToken(sessionId, pending.hash, now, home);
+	} catch {}
+}
+//#endregion
 //#region src/runtime/handle.ts
 /** Raw Claude hook event name from a payload (empty when absent). */
 function rawEventName(payload) {
@@ -9935,8 +10506,9 @@ async function handleHook(id, payload, opts) {
 	const layout = projectLayout(opts.cwd);
 	const file = trackFile(event.sessionId, defaultStateDir(opts.cwd));
 	const mcpDir = layout.cacheDir;
+	const designCacheDir = resolveDesignCacheDir(event.sessionId, mcpDir, opts.home);
 	const framework = detectFramework(event.filePath ?? "", event.content ?? "", opts.cwd);
-	if ((id === "claude-code" || id === "codex") && designLifecycle(payload, mcpDir, opts.cwd, String(opts.now), opts.now)) return {
+	if ((id === "claude-code" || id === "codex") && designLifecycle(payload, designCacheDir, opts.cwd, String(opts.now), opts.now)) return {
 		stdout: "",
 		exit: 0
 	};
@@ -9951,8 +10523,10 @@ async function handleHook(id, payload, opts) {
 		stdout: id === "claude-code" ? attachBudgetRecap(life, rawEventName(payload), event.sessionId, opts.cwd, opts.now) : life,
 		exit: 0
 	};
-	const userPrompt = typeof payload.prompt === "string" ? payload.prompt : void 0;
+	const rawPrompt = payload.prompt;
+	const userPrompt = typeof rawPrompt === "string" || Array.isArray(rawPrompt) ? promptText(rawPrompt) : void 0;
 	if (userPrompt !== void 0) {
+		handleConfirmSubmit(event.sessionId, userPrompt, opts.now, opts.home);
 		await withTrack(file, (track) => recordBrainstormRequired(track, detectCreationIntent(userPrompt)));
 		return {
 			stdout: promptSubmitContext(userPrompt, opts.cwd, id),
@@ -9965,6 +10539,7 @@ async function handleHook(id, payload, opts) {
 		event,
 		framework,
 		mcpDir,
+		designCacheDir,
 		file,
 		opts
 	});
@@ -9974,6 +10549,7 @@ async function handleHook(id, payload, opts) {
 		event,
 		framework,
 		mcpDir,
+		designCacheDir,
 		file,
 		opts
 	});