@fusengine/harness 0.1.47 → 0.1.49

package/dist/{handle-DUlUbhyF.mjs → handle-D1hHqHvh.mjs}

@@ -1,17 +1,19 @@
 import { a as parseEnvInt, i as splitTarget, r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { B as detectFramework, C as resolveSkillPath, D as frameworkSolidGate, G as requiredArchSkill, H as detectModularArchitecture, I as docConsultedGate, L as evaluateApex, M as capVerbosity, N as detectCreationIntent, O as isExcludedJsPath, S as usesTailwindUtilities, T as readPluginMeta, U as detectProjectType$1, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as isExcludedSwiftPath, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as findMarketplacePlugins, x as skillTriggerGate, y as parseField } from "./validate-DVV4nRfr.mjs";
-import { F as PLUGINS_DIR, L as countFrameworkCodeLines, R as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-qYC5xClb.mjs";
+import { A as detectCreationIntent, E as isExcludedSwiftPath, F as docConsultedGate, H as detectProjectType$1, I as evaluateApex, M as POST_AUTH_GATES, N as PRE_AUTH_GATES, S as usesTailwindUtilities, T as isExcludedJsPath, V as detectModularArchitecture, W as requiredArchSkill, _ as scanPlugin, c as EXCLUDE_DIRS$1, d as buildApexTaskInjection, h as buildClaudeMdContext, k as capVerbosity, l as PROJECT_INDICATORS, n as missingSeoElements, o as parseEnrichment, r as descFromText, s as parseEntry, t as isHtmlLike, w as frameworkSolidGate, x as skillTriggerGate, y as parseField, z as detectFramework } from "./validate-DCQ8dkdL.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, r as fusengineCache, t as claudeHome } from "./home-state-D0RLWP8J.mjs";
+import { n as FAIL_CLOSED, t as evaluate } from "./evaluate-CNAzgxnN.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
-import { a as sanitizeSessionId, c as sessionsDir, i as loadSessionState, n as fuseHarnessHome, o as saveSessionState, r as fusengineCache, t as claudeHome } from "./home-state-mKZxP4oZ.mjs";
 import { r as isDocConsulted } from "./doc-helpers-CWZegVdR.mjs";
+import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DhItkBzk.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-CymilZiZ.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 recordDoc, d as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTrivialEdit } from "./store-CNjFenWe.mjs";
-import { d as readText, f as sleep, l as collectFiles, m as writeText, n as contextResponse, p as spawnCapture, r as denyResponse, s as systemMessage, t as blockResponse, u as pathExists } from "./claude-U1KTaRG4.mjs";
+import { c as recordDoc, d as recordTrivialEdit, f as trivialCount, i as agentsFresh, l as recordRefRead, n as saveTrack, o as recordAgent, p as apexAuthorizationGate, r as verifyTrack, s as recordBrainstormRequired, t as loadTrack, u as recordTarget } from "./store-QSSTO3lY.mjs";
+import { 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, r as contextResponse, s as informResponse, t as attachSystemMessage } from "./claude-BxC9semG.mjs";
+import { r as toHermesResponse } from "./hermes-DWXCRFZU.mjs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -3529,6 +3531,50 @@ async function postEditContext(scope, event, now) {
 	return contextResponse("PostToolUse", `${additionalContextOf(sniper)}\n\n${additionalContextOf(lint)}`);
 }
 //#endregion
+//#region src/policy/trivial-edits.ts
+/**
+* Pre-filters of the ported enforce-apex-phases.ts hook, in Python order
+* (lines 48-65): protected-path guard first, then the dependency/build-dir
+* skip, then the trivial-edit fast path. The trivial COUNTER itself lives in
+* the SessionTrack (`trivialEdits`, see recordTrivialEdit/trivialCount) — no
+* separate state file.
+*/
+/** Hook-managed state paths — Write/Edit always denied (parity enforce-apex-phases.ts PROTECTED_PATHS). */
+const PROTECTED_PATHS = /\.claude\/(plugins\/(marketplaces|cache)|logs\/00-apex|fusengine-cache\/skill-tracking)/;
+/** Dependency/build dirs the APEX gates skip entirely (parity enforce-apex-phases.ts SKIP_DIRS). */
+const SKIP_DIRS = /(node_modules|vendor|dist|build|\.next|DerivedData)/;
+/**
+* Absolute deny on Write/Edit of hook-managed state paths, with the Python
+* wording byte-for-byte. Runs BEFORE the code-ext/skip-dirs filters (parity
+* enforce-apex-phases.ts:48-54), so non-code files under the protected roots
+* are covered too.
+* @param tool - The harness tool name (only Write/Edit are policed).
+* @param filePath - Target path of the edit (or undefined).
+* @returns A blocking prompt, or null to fall through.
+*/
+function protectedPathGate(tool, filePath) {
+	if (tool !== "Write" && tool !== "Edit" || !filePath || !PROTECTED_PATHS.test(filePath)) return null;
+	return {
+		kind: "block",
+		title: "APEX Hook Guard: protected path",
+		reason: "[APEX Hook Guard] Write blocked — this path is managed automatically by APEX hooks. Manual edits are forbidden and would corrupt tracked state."
+	};
+}
+/**
+* True when this tool-use qualifies for the trivial fast path (parity
+* enforce-apex-phases.ts:58-65): only an Edit (a Write always creates or
+* replaces a file wholesale), NEVER `replace_all`, and a new_string under
+* {@link TRIVIAL_MAX_LINES} lines. Absent content is NOT trivial (fail closed
+* — the full gates run).
+* @param tool - The harness tool name.
+* @param content - The Edit's new_string (adapter-normalized).
+* @param isReplaceAll - The Edit's replace_all flag.
+*/
+function isTrivialEdit(tool, content, isReplaceAll) {
+	if (tool !== "Edit" || isReplaceAll === true || content === void 0) return false;
+	return content.split("\n").length < 5;
+}
+//#endregion
 //#region src/runtime/gate-helpers.ts
 /** Source extensions the APEX gates apply to (parity: require-apex-agents.py CODE_EXT). */
 const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|dart|vue|svelte|astro)$/;
@@ -4113,7 +4159,14 @@ function geminiMcpGate(tool, filePath, content, ev) {
 //#region src/freshness/explore-tools.ts
 /** Native exploration tools (parity `apex_constants.EXPLORE_TOOLS`). */
 const EXPLORE_TOOLS = /* @__PURE__ */ new Set(["Glob", "Grep"]);
-/** Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`). */
+/**
+* Research tools — MCP docs + web (parity `apex_constants.RESEARCH_TOOLS`).
+* The fuse-browser fast-path entries are a deliberate TS addition: CLAUDE.md
+* mandates fuse-browser FIRST for web research, and `docSourceOf` (activity.ts)
+* already credits it for doc consultation — without them here, an agent
+* following the rules would never satisfy the freshness gate (same
+* cross-consumer inconsistency class as the solidReadGate lesson).
+*/
 const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
 	"mcp__context7__query-docs",
 	"mcp__context7__resolve-library-id",
@@ -4121,7 +4174,11 @@ const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
 	"mcp__exa__get_code_context_exa",
 	"mcp__exa__deep_researcher_start",
 	"WebSearch",
-	"WebFetch"
+	"WebFetch",
+	"mcp__fuse-browser__browser_fetch",
+	"mcp__fuse-browser__browser_fetch_batch",
+	"mcp__fuse-browser__browser_crawl",
+	"mcp__fuse-browser__browser_serp_batch"
 ]);
 /** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
 const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
@@ -4136,9 +4193,17 @@ const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
 	"head",
 	"tail"
 ]);
-/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
+/** Legacy Python cache names still credited (parity `CACHE_READ_RE` + doc-helpers). */
 const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
 /**
+* Real TS cache stores: `<root>/.harness/cache/<fnv16>.md` (core MCP store,
+* `projectLayout().cacheDir`) and `~/.fuse-harness/cache/**` (ai-pilot doc
+* caches, `cache-base.cacheBaseDir`). Segment-matched — not resolved against
+* `homedir()` — so tilde-prefixed and absolute paths both hit; the `.md`
+* suffix keeps session-state JSON reads from counting as research.
+*/
+const TS_CACHE_READ_RE = /\.(?:fuse-)?harness[\\/]cache[\\/].*\.md$/;
+/**
 * First non-assignment shell token's basename, or "" — mirrors Python
 * `_bash_executable` (skips leading `VAR=value` env prefixes, e.g. `FOO=1 grep`).
 * @param cmd - Raw Bash `command` string.
@@ -4170,7 +4235,7 @@ function classifyExplore(tool, input) {
 	};
 	if (tool === "Read") {
 		const path = String(input?.file_path ?? input?.path ?? "");
-		if (path && CACHE_READ_RE.test(path)) return {
+		if (path && (CACHE_READ_RE.test(path) || TS_CACHE_READ_RE.test(path))) return {
 			phase: "research-expert",
 			cacheHit: true
 		};
@@ -4261,25 +4326,120 @@ function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
 	return names.every((n) => found.has(n));
 }
 //#endregion
+//#region src/freshness/agent-evidence-record.ts
+/**
+* Session-track agent evidence — writer (parity track-subagent-research.py) +
+* reader scan (parity apex_agent_helpers._scan_agents). Sub-agent hooks fire
+* with the LEAD's `session_id`, so evidence recorded here lands in the ONE
+* session track the freshness gate scans FIRST — sidechain research and
+* Workflow-spawned agents count, unlike the lead-transcript scan.
+*/
+/** Tools the existing Task tracking already credits as agent LAUNCHES. */
+const AGENT_LAUNCH_TOOLS = /* @__PURE__ */ new Set(["Task", "Agent"]);
+/**
+* `JSON.stringify` length of the raw `tool_response` OBJECT (parity Python
+* `len(str(tool_response))`); 0 when absent or unserializable (circular).
+*/
+function responseJsonLength(toolResponse) {
+	if (toolResponse === void 0 || toolResponse === null) return 0;
+	try {
+		return (JSON.stringify(toolResponse) ?? "").length;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Classify one PostToolUse call into session evidence, or null when it is
+* neither exploration nor research (parity track-subagent-research._classify,
+* reusing the shared {@link classifyExplore} tables — research/explore/Bash/
+* cache-read). ANTI-DOUBLE-COUNT: calls classified as agent launches
+* (`Task`/`Agent`) are skipped — the existing Task tracking credits those; the
+* criterion is the CALL's classification, never its provenance (lead vs sub).
+* @param tool - Harness tool name (e.g. "Glob", "Bash", "Read").
+* @param input - Raw tool input payload.
+* @param toolResponse - Raw `tool_response` OBJECT from the hook payload.
+* @returns The evidence to record, or null to skip.
+*/
+function classifyAgentEvidence(tool, input, toolResponse) {
+	if (AGENT_LAUNCH_TOOLS.has(tool)) return null;
+	const hit = classifyExplore(tool, input);
+	if (!hit) return null;
+	return {
+		name: hit.phase === "explore-codebase" ? "subagent-explore-codebase" : "subagent-research-expert",
+		quality: hit.cacheHit || responseJsonLength(toolResponse) > 50 ? "sufficient" : "insufficient"
+	};
+}
+/**
+* Persist evidence into the SESSION track via {@link recordAgent} — keyed by
+* `session_id` alone (sub-agent hooks carry the lead's `session_id`); the TTL
+* anchors on `ts`, the tool call's own timestamp. `agentId` is tagged as
+* metadata when present, NEVER used as a condition (unreliable field —
+* anthropics/claude-code#22348).
+* @param file - Session track file path.
+* @param evidence - Classified evidence from {@link classifyAgentEvidence}.
+* @param ts - Epoch-ms timestamp of the tool call (the hook event's `now`).
+* @param agentId - Optional Claude `agent_id` — metadata tag only.
+*/
+async function recordAgentEvidence(file, evidence, ts, agentId) {
+	const next = recordAgent(await loadTrack(file), evidence.name, ts, evidence.quality);
+	const last = next.agents[next.agents.length - 1];
+	if (agentId && last) {
+		const tagged = {
+			...last,
+			agentId
+		};
+		next.agents[next.agents.length - 1] = tagged;
+	}
+	await saveTrack(file, next);
+}
+/**
+* Parity `_scan_agents` (apex_agent_helpers.py): reverse-scan `track.agents`,
+* STOPPING at the first entry older than `windowMs` (entries append in time
+* order), matching each required name by SUBSTRING (`research-expert` matches
+* `subagent-research-expert`) and counting ONLY `quality === "sufficient"`.
+* @param track - The loaded session track.
+* @param names - Required agent names — ALL must match to return true.
+* @param windowMs - Freshness window (ms), anchored on each entry's `ts`.
+* @param now - Current epoch ms.
+* @returns True when every required name has fresh, sufficient evidence.
+*/
+function agentsFreshInTrack(track, names, windowMs, now) {
+	const found = /* @__PURE__ */ new Set();
+	for (let i = track.agents.length - 1; i >= 0; i--) {
+		const entry = track.agents[i];
+		if (!entry) continue;
+		if (now - entry.ts > windowMs) break;
+		if (entry.quality !== "sufficient") continue;
+		for (const req of names) if (entry.name.includes(req)) found.add(req);
+		if (found.size === names.length) return true;
+	}
+	return names.every((n) => found.has(n));
+}
+//#endregion
 //#region src/runtime/gate-apex.ts
 /**
-* The APEX-scoped portion of {@link gate}: a trivial-edit fast path, then the
-* freshness/doc/SOLID gates fed from the session track. Freshness prefers
-* platform-authored transcript evidence (an agent cannot forge a `Task` in the
-* runtime-owned transcript); the self-recorded track is only a fallback when no
-* transcript path is available (tests / other harnesses).
+* The APEX-scoped portion of {@link gate}, in the Python enforce-apex-phases.ts
+* order: protected-paths guard, skip-dirs allow, trivial-edit fast path, then
+* brainstorm/freshness, Check 1 (per-framework doc authorization — a deny
+* persists `track.target` so recordDoc can cross-credit the framework) and
+* Check 2 + SOLID refs. Freshness scans the SESSION track first (parity
+* _scan_agents: sub-agent hooks share the lead's session_id, so sidechain/
+* Workflow research is visible); the platform-authored transcript scan and the
+* legacy exact-name track check are fallbacks.
 * @param input - The tool-use to gate.
 * @param track - The loaded session track.
 * @param window - Freshness window in ms.
 * @returns The first blocking prompt, or null to fall through to the DRY check.
 */
 async function apexScopedGate(input, track, window) {
-	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
-	if (input.tool === "Edit" && !input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
+	const protectedDeny = protectedPathGate(input.tool, input.filePath);
+	if (protectedDeny) return protectedDeny;
+	if (SKIP_DIRS.test(input.filePath ?? "")) return null;
+	if (isTrivialEdit(input.tool, input.content, input.isReplaceAll) && trivialCount(track, window, input.now) < 4) {
 		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
 		return null;
 	}
-	const freshnessFor = (names, windowMs = window) => input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now);
+	const freshnessFor = (names, windowMs = window) => agentsFreshInTrack(track, names, windowMs, input.now) || (input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, windowMs, input.now) : agentsFresh(track, names, windowMs, input.now));
 	const ctx = {
 		sessionId: input.sessionId,
 		framework: input.framework,
@@ -4288,6 +4448,8 @@ async function apexScopedGate(input, track, window) {
 		authorizations: track.authorizations,
 		refs: input.refs,
 		refsRead: track.refsRead,
+		refsReadAt: track.refsReadAt,
+		now: input.now,
 		agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
 		missingAgents: REQUIRED_AGENTS.filter((name) => !freshnessFor([name])),
 		windowMs: window,
@@ -4295,7 +4457,20 @@ async function apexScopedGate(input, track, window) {
 		brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
 	};
 	try {
-		return evaluateApex(ctx);
+		const pre = evaluateApex(ctx, PRE_AUTH_GATES);
+		if (pre) return pre;
+		const authDeny = apexAuthorizationGate(ctx);
+		if (authDeny) {
+			const set_at = new Date(input.now).toISOString();
+			await saveTrack(input.trackFile, recordTarget(track, {
+				project: input.cwd ?? "",
+				framework: input.framework,
+				set_by: "apex-authorization",
+				set_at
+			}));
+			return authDeny;
+		}
+		return evaluateApex(ctx, POST_AUTH_GATES);
 	} catch {
 		return FAIL_CLOSED;
 	}
@@ -4321,6 +4496,8 @@ const TRIVIAL_BUDGET = 4;
 async function gate(input) {
 	const precommit = preCommitGate(input.tool, input.command, input.cwd);
 	if (precommit) return precommit;
+	const protectedDeny = protectedPathGate(input.tool, input.filePath);
+	if (protectedDeny) return protectedDeny;
 	const { raw: existingLines, code: existingCodeLines } = existingLineCounts(input.filePath);
 	let quick;
 	try {
@@ -4483,7 +4660,7 @@ function mcpPostStore(tool, input, response, dir, now = Date.now()) {
 /** Apply an activity to a session's track and persist it (PostToolUse path). */
 async function recordActivity(file, activity) {
 	const track = await loadTrack(file);
-	await saveTrack(file, activity.kind === "agent" ? recordAgent(track, activity.name, activity.ts, activity.quality) : activity.kind === "doc" ? recordDoc(track, activity.framework, activity.sessionId, activity.source) : recordRefRead(track, activity.path));
+	await saveTrack(file, activity.kind === "agent" ? recordAgent(track, activity.name, activity.ts, activity.quality) : activity.kind === "doc" ? recordDoc(track, activity.framework, activity.sessionId, activity.source, activity.ts) : recordRefRead(track, activity.path, activity.ts));
 }
 //#endregion
 //#region src/runtime/respond.ts
@@ -4491,51 +4668,81 @@ async function recordActivity(file, activity) {
 * Map a portable {@link Prompt} to a harness's native hook response, honoring
 * all 3 prompt kinds (`block`/`ask`/`inform`) instead of collapsing `ask` and
 * `inform` together. Reuses the Claude adapter's `denyResponse`/
-* `contextResponse` builders for claude-code/codex (same hook shape) to avoid
-* duplicating the JSON.
+* `contextResponse`/`informResponse` builders for claude-code/codex (same hook
+* shape) to avoid duplicating the JSON.
 * - claude-code/codex: `block` -> deny, `ask` -> interactive
 *   `permissionDecision:"ask"`, `inform` -> non-blocking `additionalContext`.
 * - gemini-cli/cline: their real hook schemas have no interactive "ask"
 *   state (deny is the only blocking outcome), so `ask` and `inform` already
 *   both resolve to non-blocking context injection — unchanged.
-* - cursor: `ask` keeps its current best-effort `permission:"ask"` shape
-*   (unverified against Cursor's exact hook docs); only `inform` is fixed to
-*   a non-blocking `permission:"allow"` note, since it was wrongly conflated
-*   with `ask` before.
+* - cursor: `ask` keeps its current best-effort `permission:"ask"` shape;
+*   only `inform` is fixed to a non-blocking `permission:"allow"` note.
+* - hermes: delegated to the adapter's `toHermesResponse` — `block` ->
+*   `{decision:"block",reason}`; `ask`/`inform` degrade to non-blocking
+*   `{context}` (Hermes has no interactive "ask" state).
+*
+* User-visible pass notices (`prompt.userMessage`, Python `hook_output.allow_pass`
+* / `post_pass` parity), by harness:
+* - claude-code/codex: top-level `systemMessage` ("warning message shown to the
+*   user"); a pure notice (empty `reason`) emits `{systemMessage}` alone. Codex
+*   consumes the Claude hook schema, so it rides the same field.
+* - gemini-cli: common `systemMessage` output field ("displayed immediately to
+*   the user in the terminal") — the notice rides there.
+* - cursor: `user_message` is its user-visible channel (see case comment).
+* - cline: NO user-visible channel (`cancel`/`contextModification`/
+*   `errorMessage`-on-cancel only) — the notice is dropped silently (a pure
+*   notice returns "" = plain allow).
 */
 function respond(id, prompt) {
 	const message = formatPrompt(prompt);
-	const { kind } = prompt;
+	const { kind, userMessage, reason } = prompt;
 	switch (id) {
 		case "claude-code":
 		case "codex":
 			if (kind === "block") return denyResponse("PreToolUse", message);
-			if (kind === "inform") return contextResponse("PreToolUse", message);
+			if (kind === "inform") return userMessage ? informResponse("PreToolUse", userMessage, reason ? message : "") : contextResponse("PreToolUse", message);
 			return JSON.stringify({ hookSpecificOutput: {
 				hookEventName: "PreToolUse",
 				permissionDecision: "ask",
 				permissionDecisionReason: message
 			} });
-		case "gemini-cli": return JSON.stringify(kind === "block" ? {
-			decision: "deny",
-			reason: message
-		} : { hookSpecificOutput: { additionalContext: message } });
-		case "cursor":
-			if (kind === "inform") return JSON.stringify({
-				permission: "allow",
-				userMessage: message,
-				agentMessage: message
+		case "gemini-cli":
+			if (kind === "block") return JSON.stringify({
+				decision: "deny",
+				reason: message
 			});
+			if (userMessage) return JSON.stringify({
+				...reason ? { hookSpecificOutput: { additionalContext: message } } : {},
+				systemMessage: userMessage
+			});
+			return JSON.stringify({ hookSpecificOutput: { additionalContext: message } });
+		case "cursor":
+			if (kind === "inform") {
+				if (userMessage) return JSON.stringify({
+					permission: "allow",
+					user_message: userMessage,
+					...reason ? { agent_message: message } : {}
+				});
+				return JSON.stringify({
+					permission: "allow",
+					user_message: message,
+					agent_message: message
+				});
+			}
 			return JSON.stringify({
 				permission: kind === "block" ? "deny" : "ask",
 				continue: false,
-				userMessage: message,
-				agentMessage: message
+				user_message: message,
+				agent_message: message
 			});
-		case "cline": return JSON.stringify(kind === "block" ? {
-			cancel: true,
-			errorMessage: message
-		} : { contextModification: message });
+		case "hermes": return toHermesResponse(prompt);
+		case "cline":
+			if (kind === "block") return JSON.stringify({
+				cancel: true,
+				errorMessage: message
+			});
+			if (userMessage && !reason) return "";
+			return JSON.stringify({ contextModification: message });
 		default: return "";
 	}
 }
@@ -4723,10 +4930,10 @@ function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
 * `design.ts` to keep that file within the SOLID size budget (SRP).
 * @packageDocumentation
 */
-const NAV$1 = "mcp__fuse-browser__browser_navigate";
-const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const NAV$2 = "mcp__fuse-browser__browser_navigate";
+const SHOT$2 = "mcp__fuse-browser__browser_screenshot";
 const SCROLL = "mcp__fuse-browser__browser_scroll";
-const GEMINI$1 = "mcp__gemini-design__create_frontend";
+const GEMINI$2 = "mcp__gemini-design__create_frontend";
 /** Read design-system.md walking up to 6 parents from `cwd` ("" if absent/unreadable). */
 function findDesignSystem(cwd) {
 	let dir = cwd;
@@ -4745,10 +4952,10 @@ function findDesignSystem(cwd) {
 }
 /** Apply a PostToolUse fuse-browser transition to the design state. */
 function recordPost(event, cacheDir, state) {
-	if (event.tool === SHOT$1) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
-	else if (event.tool === NAV$1) saveDesignState(cacheDir, recordNavigate(state));
+	if (event.tool === SHOT$2) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
+	else if (event.tool === NAV$2) saveDesignState(cacheDir, recordNavigate(state));
 	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
-	else if (event.tool === GEMINI$1) saveDesignState(cacheDir, {
+	else if (event.tool === GEMINI$2) saveDesignState(cacheDir, {
 		...state,
 		geminiCalls: state.geminiCalls + 1
 	});
@@ -4771,6 +4978,9 @@ const FORBIDDEN_FONTS = [
 	"Open Sans"
 ];
 const OKLCH_RE = /oklch\(\s*[\d.]+%?\s+0\.0*[1-9]/;
+const NAV$1 = "mcp__fuse-browser__browser_navigate";
+const SHOT$1 = "mcp__fuse-browser__browser_screenshot";
+const GEMINI$1 = "mcp__gemini-design__create_frontend";
 const deny = (reason) => ({
 	kind: "block",
 	title: "Design pipeline",
@@ -4804,6 +5014,40 @@ function geminiEnabled() {
 	const v = process.env.FUSE_DESIGN_GEMINI;
 	return v === "1" || v === "true";
 }
+/**
+* Python-parity pass notices (`hook_output.allow_pass`/`post_pass`): the
+* user-visible `script: detail` lines the old plugins printed on EVERY passing
+* design hook. Call AFTER the gates allowed the event; returns an `inform`
+* Prompt carrying only `userMessage` (for the human, never agent context), or
+* null when nothing applies. The check-design-skill line fires for ANY agent
+* on a UI write; the rest only inside the active design-agent context.
+*/
+function designPassNotice(i, cacheDir) {
+	const isWrite = i.tool === "Write" || i.tool === "Edit";
+	const fp = i.filePath;
+	const lines = [];
+	if (i.phase === "pre" && isUiWrite(i.tool, fp, i.content)) {
+		const domains = SKILL_TRIGGERS.filter((t) => t.patterns.some((re) => re.test(i.content))).map((t) => t.skill).join(", ");
+		lines.push(`check-design-skill: pass (domain: ${domains || "base"})`);
+	}
+	const state = i.agentId && activeDesignAgent(cacheDir) === i.agentId ? loadDesignState(cacheDir, i.agentId) : null;
+	if (state && i.phase === "pre") {
+		if (isWrite && fp && !EXEMPT_DIRS.some((d) => fp.includes(d)) && ALLOWED_WRITE.test(fp)) lines.push(`enforce-html-css-only: allowed: ${basename(fp)}`);
+		if (i.tool === NAV$1) lines.push(`check-inspiration-read: pass (${i.url})`);
+		if (i.tool === GEMINI$1 && geminiEnabled()) lines.push("validate-design-system: design-system.md ok");
+		if (isWrite || i.tool === NAV$1 || i.tool === SHOT$1 || i.tool === GEMINI$1) lines.push(`pipeline-gate: phase ${state.currentPhase} ok`);
+	}
+	if (state && i.phase === "post" && isWrite) {
+		if (basename(fp) === "design-system.md") lines.push("validate-design: design-system.md → phase 3");
+		else if (/\.(tsx|jsx|css)$/.test(fp)) lines.push("validate-design: design ok");
+	}
+	return lines.length ? {
+		kind: "inform",
+		title: "Design pipeline",
+		reason: "",
+		userMessage: lines.join("\n")
+	} : null;
+}
 //#endregion
 //#region src/policy/design/gates-pipeline.ts
 const SKILLS = `${PLUGINS_DIR}/design-expert/skills`;
@@ -4947,13 +5191,10 @@ async function handlePre(ctx) {
 		stdout: securityAdvisory(event.tool, event.filePath ?? "", opts.now),
 		exit: 0
 	};
-	if (opts.scope === "solid" && event.filePath) {
-		const solidDeny = validateSolidGate(event.tool, event.filePath, event.content ?? "");
-		if (solidDeny) return {
-			stdout: solidDeny,
-			exit: 0
-		};
-	}
+	if (opts.scope === "solid") return {
+		stdout: validateSolidGate(event.tool, event.filePath ?? "", event.content ?? ""),
+		exit: 0
+	};
 	if (event.tool === "Task") {
 		const taskCtx = taskContext(opts.cwd);
 		if (taskCtx) return {
@@ -4978,15 +5219,103 @@ async function handlePre(ctx) {
 		trackFile: file,
 		transcriptPath: typeof payload.transcript_path === "string" ? payload.transcript_path : void 0
 	});
-	return prompt ? {
+	if (prompt) return {
 		stdout: respond(id, prompt),
 		exit: 0
-	} : {
-		stdout: "",
+	};
+	const notice = designPassNotice({
+		agentId: typeof payload.agent_id === "string" ? payload.agent_id : "",
+		tool: event.tool,
+		filePath: event.filePath ?? "",
+		content: event.content ?? "",
+		url: typeof event.input.url === "string" ? event.input.url : "",
+		phase: "pre"
+	}, mcpDir);
+	return {
+		stdout: notice ? respond(id, notice) : "",
 		exit: 0
 	};
 }
 //#endregion
+//#region src/freshness/query-framework.ts
+/**
+* Framework classification for doc consultations, keyed on the QUERY text
+* (parity ai-pilot/scripts/track_doc_helpers.py::detect_framework): an MCP
+* doc call (context7/exa/web) has no filePath, so the file-based
+* `detectFramework()` always yields "generic" — the query keywords are the
+* only framework signal a doc consultation carries.
+*/
+/**
+* Ordered patterns, EXACT parity with the Python list (same order, same
+* case-sensitive alternations, substring search — only `go` is word-bounded).
+* Quirks are inherited deliberately: "javascript" hits `java` (but only after
+* nextjs/react/laravel/swift/tailwind all missed) and all-caps "NEXT" misses.
+* The output domain matches `detectFramework()` exactly, so every credit
+* lands on a key the apex authorization gate actually reads.
+*/
+const QUERY_FRAMEWORKS = [
+	[/(next|nextjs|Next)/, "nextjs"],
+	[/(react|React)/, "react"],
+	[/(laravel|Laravel|php|PHP)/, "laravel"],
+	[/(swift|Swift|swiftui|SwiftUI)/, "swift"],
+	[/(tailwind|Tailwind)/, "tailwind"],
+	[/(java|Java|spring|Spring)/, "java"],
+	[/\b(go|Go|golang)\b/, "go"],
+	[/(ruby|Ruby|rails|Rails)/, "ruby"],
+	[/(rust|Rust|cargo|Cargo)/, "rust"]
+];
+/**
+* The framework a doc query targets, or null when no keyword matches (the
+* Python returns "generic"; null here lets the caller fall back to the
+* event's file-detected framework instead of hardcoding generic).
+* @param query - The query/url/prompt text of the doc tool call.
+*/
+function frameworkFromQuery(query) {
+	for (const [re, fw] of QUERY_FRAMEWORKS) if (re.test(query)) return fw;
+	return null;
+}
+/**
+* tool_input fields carrying query text across doc tools: context7
+* (`libraryId`/`libraryName`, parity extract_tool_info), exa/WebSearch
+* (`query`), fuse-browser serp (`queries[]`), WebFetch (`url` + `prompt`).
+*/
+const QUERY_FIELDS = [
+	"query",
+	"queries",
+	"libraryId",
+	"libraryName",
+	"prompt",
+	"url"
+];
+/**
+* Fold every query-ish tool_input field into one searchable string. Distinct
+* from mcp-key.ts `queryOf`, which picks a SINGLE field to key the response
+* cache — classification wants ALL the text (e.g. WebFetch url + prompt).
+* @param input - The normalized tool_input (absent on some harnesses).
+*/
+function docQueryOf(input) {
+	if (!input) return "";
+	const parts = [];
+	for (const key of QUERY_FIELDS) {
+		const v = input[key];
+		if (typeof v === "string") parts.push(v);
+		else if (Array.isArray(v)) {
+			for (const s of v) if (typeof s === "string") parts.push(s);
+		}
+	}
+	return parts.join(" ");
+}
+/**
+* The framework to credit for a doc consultation: the query's framework when
+* a keyword matches (query wins over file-based detection), else `fallback`
+* (the event's framework — "generic" for pathless MCP calls).
+* @param input - The doc tool's tool_input.
+* @param fallback - The event's file-detected framework.
+*/
+function docFramework(input, fallback) {
+	return frameworkFromQuery(docQueryOf(input)) ?? fallback;
+}
+//#endregion
 //#region src/runtime/activity.ts
 /** Min response length (chars) for a lead agent call to count as `sufficient`. */
 const AGENT_QUALITY_MIN = 500;
@@ -5045,9 +5374,10 @@ function activityFor(event) {
 	const docSource = docSourceOf(event.tool);
 	if (docSource) out.push({
 		kind: "doc",
-		framework: event.framework,
+		framework: docFramework(event.input, event.framework),
 		sessionId: event.sessionId,
-		source: docSource
+		source: docSource,
+		ts: event.now
 	});
 	if (event.tool === "Task" || event.tool === "Agent") {
 		const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
@@ -5062,7 +5392,8 @@ function activityFor(event) {
 		const path = String(event.input?.file_path ?? event.input?.path ?? "");
 		if (path.endsWith(".md")) out.push({
 			kind: "ref",
-			path
+			path,
+			ts: event.now
 		});
 	}
 	return out;
@@ -5090,6 +5421,8 @@ async function handlePost(ctx) {
 		responseLength: extractText(response).length
 	});
 	for (const activity of activities) await recordActivity(file, activity);
+	const evidence = classifyAgentEvidence(event.tool, event.input, response);
+	if (evidence) await recordAgentEvidence(file, evidence, opts.now, typeof payload.agent_id === "string" ? payload.agent_id : void 0);
 	postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
 	const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
 	if (seoDeny) return {
@@ -5118,8 +5451,35 @@ async function handlePost(ctx) {
 		};
 	}
 	const extra = await postEditContext(opts.scope ?? "core", event, opts.now);
+	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);
+	if (designWarn) return {
+		stdout: respond(id, notice?.userMessage ? {
+			...designWarn,
+			userMessage: notice.userMessage
+		} : designWarn),
+		exit: 0
+	};
+	if (!notice?.userMessage) return {
+		stdout: extra,
+		exit: 0
+	};
+	if (!extra) return {
+		stdout: respond(id, notice),
+		exit: 0
+	};
+	if (id === "claude-code" || id === "codex") return {
+		stdout: attachSystemMessage(extra, notice.userMessage),
+		exit: 0
+	};
 	return {
-		stdout: designWarn ? respond(id, designWarn) : extra,
+		stdout: respond(id, notice) || extra,
 		exit: 0
 	};
 }