@fusengine/harness 0.1.39 → 0.1.41

package/dist/{handle-t-lQuQc7.mjs → handle-VhWQxvyN.mjs}

@@ -1,15 +1,18 @@
 import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { r as projectLayout } from "./layout-C0jaaCQC.mjs";
+import { t as HOME_DIR } from "./dotenv-DGyLln7U.mjs";
 import { i as walkUpFor, n as projectRoot, r as projectRootOrNull, t as isCodeFile } from "./project-root-3kk7gCOp.mjs";
-import { A as evaluateApex, E as detectCreationIntent, L as requiredArchSkill, P as detectModularArchitecture, S as frameworkSolidGate, T as capVerbosity, _ as buildClaudeMdContext, b as skillTriggerGate, c as parseBodyDesc, d as PROJECT_INDICATORS, l as parseField, n as missingSeoElements, o as parseEnrichment, p as buildApexTaskInjection, r as descFromText, s as parseEntry, t as isHtmlLike, u as EXCLUDE_DIRS$1 } from "./validate-osn-huLZ.mjs";
-import { j as detectFramework, k as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-za4vT-p7.mjs";
+import { t as detectHarness } from "./harness-C8Nxxyn_.mjs";
+import { A as evaluateApex, E as detectCreationIntent, L as requiredArchSkill, P as detectModularArchitecture, S as frameworkSolidGate, T as capVerbosity, _ as buildClaudeMdContext, b as skillTriggerGate, c as parseBodyDesc, d as PROJECT_INDICATORS, l as parseField, n as missingSeoElements, o as parseEnrichment, p as buildApexTaskInjection, r as descFromText, s as parseEntry, t as isHtmlLike, u as EXCLUDE_DIRS$1 } from "./validate-B3wkqEoN.mjs";
+import { N as detectFramework, j as countLines, n as FAIL_CLOSED, t as evaluate } from "./evaluate-B1n1ti0N.mjs";
+import { r as isDocConsulted } from "./doc-helpers-BhzDmJ18.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-BkoEbdec.mjs";
-import { a as extractText, o as loadIndex, r as cacheStore, t as cacheLookup } from "./store-PrNPm6So.mjs";
+import { c as extractText, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, r as cacheLookup, t as mcpCacheWrite } from "./mcp-store-CDUVqtJ0.mjs";
 import { a as writeJsonFile, i as readJsonFile, r as hashText, t as atomicWrite } from "./json-io-CvSumjtz.mjs";
-import { t as loadRefs } from "./loader-CyAoJv2W.mjs";
-import { a as recordAgent, c as recordRefRead, l as recordTrivialEdit, n as saveTrack, o as recordBrainstormRequired, r as agentsFresh, s as recordDoc, t as loadTrack, u as trivialCount } from "./store-7j02oGjt.mjs";
-import { c as pathExists, d as spawnCapture, f as writeText, l as readText, n as denyResponse, s as collectFiles, t as contextResponse, u as sleep } from "./claude-ZgTC5yDS.mjs";
+import { t as loadRefs } from "./loader-Bn-DbZmt.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-3WBr37Xz.mjs";
+import { c as collectFiles, d as sleep, f as spawnCapture, l as pathExists, n as contextResponse, p as writeText, t as blockResponse, u as readText } from "./claude-BnFrSfMo.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";
@@ -98,57 +101,173 @@ function saveSecurityState(state, now = Date.now(), home = homedir()) {
 	writeFileSync(securityStatePath(now, home), JSON.stringify(state, null, 2), "utf-8");
 }
 //#endregion
+//#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`). */
+const RESEARCH_TOOLS = /* @__PURE__ */ new Set([
+	"mcp__context7__query-docs",
+	"mcp__context7__resolve-library-id",
+	"mcp__exa__web_search_exa",
+	"mcp__exa__get_code_context_exa",
+	"mcp__exa__deep_researcher_start",
+	"WebSearch",
+	"WebFetch"
+]);
+/** Bash executables that count as exploration (parity `EXPLORE_BASH_CMDS`). */
+const EXPLORE_BASH_CMDS = /* @__PURE__ */ new Set([
+	"grep",
+	"rg",
+	"find",
+	"ls",
+	"fd",
+	"ast-grep",
+	"tree",
+	"cat",
+	"head",
+	"tail"
+]);
+/** Cached MCP result reads count as research (parity `CACHE_READ_RE` + doc-helpers). */
+const CACHE_READ_RE = /\/context\/mcp\/(exa-search|exa-code-context|context7)-/;
+/**
+* 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.
+* @returns The executable basename, or "" when none.
+*/
+function bashExecutable(cmd) {
+	for (const token of cmd.trim().split(/\s+/)) {
+		if (!token) continue;
+		const last = token.split("/").pop() ?? token;
+		if (!last.includes("=")) return last;
+	}
+	return "";
+}
+/**
+* Classify a direct tool use into an APEX phase, or `null` when it is neither
+* exploration nor research. Mirrors Python `track-subagent-research._classify`.
+* @param tool - Harness tool name (e.g. "Glob", "Bash", "WebSearch").
+* @param input - Tool input payload.
+* @returns The credited phase + cache flag, or `null`.
+*/
+function classifyExplore(tool, input) {
+	if (RESEARCH_TOOLS.has(tool)) return {
+		phase: "research-expert",
+		cacheHit: false
+	};
+	if (EXPLORE_TOOLS.has(tool)) return {
+		phase: "explore-codebase",
+		cacheHit: false
+	};
+	if (tool === "Read") {
+		const path = String(input?.file_path ?? input?.path ?? "");
+		if (path && CACHE_READ_RE.test(path)) return {
+			phase: "research-expert",
+			cacheHit: true
+		};
+		return null;
+	}
+	if (tool === "Bash") {
+		const cmd = String(input?.command ?? "").trim();
+		if (EXPLORE_BASH_CMDS.has(bashExecutable(cmd))) return {
+			phase: "explore-codebase",
+			cacheHit: false
+		};
+	}
+	return null;
+}
+//#endregion
 //#region src/runtime/activity.ts
 /** Min response length (chars) for a lead agent call to count as `sufficient`. */
 const AGENT_QUALITY_MIN = 500;
+/** Min response length (chars) for direct exploration/research (parity Python `> 50`). */
+const EXPLORE_QUALITY_MIN = 50;
 /** Read tools across harnesses (Claude `Read`, Gemini/Cline `read_file`, …). */
 const READ_TOOLS = /* @__PURE__ */ new Set([
 	"Read",
 	"read_file",
 	"read_many_files"
 ]);
+/** Grade a response length against a threshold; `undefined` when length is unknown. */
+function qualityFor(len, min) {
+	return len === void 0 ? void 0 : len > min ? "sufficient" : "insufficient";
+}
+/** Build an `agent` activity, attaching `quality` only when graded. */
+function agentActivity(name, ts, quality) {
+	return quality ? {
+		kind: "agent",
+		name,
+		ts,
+		quality
+	} : {
+		kind: "agent",
+		name,
+		ts
+	};
+}
+/**
+* The documentation source a tool satisfies for the doc-consultation gate, or
+* undefined. Context7/Exa are the primary sources; fuse-browser is the fallback
+* when Exa is down (`browser_fetch`/`browser_crawl`/`browser_serp_batch`); the
+* built-in WebSearch/WebFetch also count.
+* @param tool - The harness tool name.
+*/
+function docSourceOf$1(tool) {
+	if (/context7/i.test(tool)) return "context7";
+	if (/exa/i.test(tool)) return "exa";
+	if (/browser_(fetch|crawl|serp)/i.test(tool)) return "fuse-browser";
+	if (tool === "WebSearch") return "websearch";
+	if (tool === "WebFetch") return "webfetch";
+}
 /**
 * Map a live tool-use to the activity to record, or null when nothing is
 * tracked. Works across harnesses — tool names are globally distinct:
 * - MCP doc calls (`context7` / `exa`, any separator) → `doc`
-* - `Task` + `subagent_type` (Claude/Cursor) → `agent` (bare agent name)
+* - `Task`/`Agent` + `subagent_type` (Claude/Cursor) → `agent` (bare agent name)
+* - direct exploration/research (Glob/Grep, explore Bash, web, MCP cache reads)
+*   → `agent` credited to the matching REQUIRED_AGENTS phase
 * - a read tool opening a `.md` reference → `ref`
 */
 function activityFor(event) {
-	if (/context7|exa/i.test(event.tool)) return {
+	const out = [];
+	const docSource = docSourceOf$1(event.tool);
+	if (docSource) out.push({
 		kind: "doc",
 		framework: event.framework,
 		sessionId: event.sessionId,
-		source: /exa/i.test(event.tool) ? "exa" : "context7"
-	};
-	if (event.tool === "Task") {
-		const name = String(event.input?.subagent_type ?? "").split(":").pop() ?? "";
-		if (!name) return null;
-		const quality = event.responseLength === void 0 ? void 0 : event.responseLength > AGENT_QUALITY_MIN ? "sufficient" : "insufficient";
-		return quality ? {
-			kind: "agent",
-			name,
-			ts: event.now,
-			quality
-		} : {
-			kind: "agent",
-			name,
-			ts: event.now
-		};
+		source: docSource
+	});
+	if (event.tool === "Task" || event.tool === "Agent") {
+		const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
+		if (name) out.push(agentActivity(name, event.now, qualityFor(event.responseLength, AGENT_QUALITY_MIN)));
+		return out;
 	}
-	if (READ_TOOLS.has(event.tool)) {
+	const hit = classifyExplore(event.tool, event.input);
+	if (hit) {
+		const quality = hit.cacheHit ? "sufficient" : qualityFor(event.responseLength, EXPLORE_QUALITY_MIN);
+		out.push(agentActivity(hit.phase, event.now, quality));
+	} else if (READ_TOOLS.has(event.tool)) {
 		const path = String(event.input?.file_path ?? event.input?.path ?? "");
-		if (path.endsWith(".md")) return {
+		if (path.endsWith(".md")) out.push({
 			kind: "ref",
 			path
-		};
+		});
 	}
-	return null;
+	return out;
 }
 //#endregion
-//#region src/runtime/mcp.ts
-/** Default freshness for cached MCP/WebFetch results (48h). */
+//#region src/runtime/mcp-key.ts
+/** Cache-key + tool-class helpers for the MCP/WebFetch interception pipeline. */
+/** Default freshness for cached MCP doc results (48h). */
 const MCP_TTL_MS = 1728e5;
+/** WebFetch freshness — pages go stale faster than docs (24h, parity with Python). */
+const WEBFETCH_TTL_MS = 864e5;
+/** WebFetch prompt slice folded into its cache key (parity with Python prompt[:500]). */
+const PROMPT_TRUNC = 500;
+/** True for the WebFetch tool (exact name). */
+function isWebFetch(tool) {
+	return tool === "WebFetch";
+}
 /** MCP doc tools + WebFetch whose calls are cached / verbosity-capped. */
 function isMcpTool(tool) {
 	return /context7|exa|webfetch|web_fetch/i.test(tool) || tool === "WebFetch";
@@ -158,6 +277,17 @@ function queryOf(input) {
 	const q = input.query ?? input.url ?? input.libraryId ?? "";
 	return typeof q === "string" ? q : JSON.stringify(q);
 }
+/**
+* The string that keys the cache for `tool`. WebFetch folds `url + "\n" +
+* prompt[:500]` (parity with Python) so distinct prompts on the same URL never
+* collide; every other tool keys on {@link queryOf}.
+*/
+function cacheQueryOf(tool, input) {
+	if (!isWebFetch(tool)) return queryOf(input);
+	return `${typeof input.url === "string" ? input.url.trim() : ""}\n${(typeof input.prompt === "string" ? input.prompt : "").slice(0, PROMPT_TRUNC)}`;
+}
+//#endregion
+//#region src/runtime/mcp.ts
 function denyWith(id, content) {
 	if (id === "claude-code" || id === "codex") return JSON.stringify({ hookSpecificOutput: {
 		hookEventName: "PreToolUse",
@@ -191,7 +321,10 @@ function docSourceOf(tool) {
 */
 function mcpPreIntercept(id, tool, input, dir, ttlMs, now) {
 	if (!isMcpTool(tool)) return null;
-	const cached = cacheLookup(dir, tool, queryOf(input), ttlMs, now);
+	const web = isWebFetch(tool);
+	const ttl = web ? WEBFETCH_TTL_MS : ttlMs;
+	const key = cacheQueryOf(tool, input);
+	const cached = cacheLookup(dir, tool, key, ttl, now) ?? (web ? null : cacheLookupSubstring(dir, key, ttl, now));
 	if (cached) {
 		const served = denyWith(id, cached);
 		if (served) return {
@@ -206,10 +339,18 @@ function mcpPreIntercept(id, tool, input, dir, ttlMs, now) {
 	}
 	return null;
 }
-/** Post-event: store the MCP/WebFetch response (extracted to markdown) in the cache. */
-function mcpPostStore(tool, input, response, dir) {
+/**
+* Post-event: persist the MCP/WebFetch response (extracted to markdown). MCP docs
+* go through {@link mcpCacheWrite} (compact + Jaccard-dedup + `index.json`);
+* WebFetch uses {@link webfetchCacheWrite} (compact, exact key, no index).
+* @param now - Current epoch ms (timestamp source; defaults to `Date.now()`).
+*/
+function mcpPostStore(tool, input, response, dir, now = Date.now()) {
 	if (!isMcpTool(tool)) return;
-	cacheStore(dir, tool, queryOf(input), extractText(response));
+	const text = extractText(response);
+	const key = cacheQueryOf(tool, input);
+	if (isWebFetch(tool)) webfetchCacheWrite(dir, tool, key, text, now);
+	else mcpCacheWrite(dir, tool, key, text, now);
 }
 //#endregion
 //#region src/runtime/normalize.ts
@@ -536,6 +677,117 @@ function runDesignChecks(content) {
 	];
 }
 //#endregion
+//#region src/policy/design/skill-gate.ts
+/** UI source files the gate polices (.html/.css are handled by the pipeline gate, not here). */
+const UI_FILE_RE = /\.(tsx|jsx|scss|vue|svelte)$/;
+/** Generated/vendored paths that never need a design skill (match at start or mid-path). */
+const EXEMPT_RE = /(^|\/)(node_modules|dist|build)\/|\.claude\//;
+/** UI-intent path fragments (ports the Python `UI_PATH_PATTERNS`). */
+const UI_PATH_RE = /(components|ui|styles|page|layout|content|view|feature|section|hero|footer|header|sidebar|nav|modal|dialog)/;
+/** Tailwind utility usage in JSX `className` (ports the Python `has_jsx_tailwind`). */
+const TAILWIND_RE = /className\s*=.*(?:flex|grid|p-|m-|bg-|text-|rounded|shadow|border|gap-|w-|h-)/;
+/** A read reference path that counts as "a design skill was consulted". */
+const DESIGN_SKILL_RE = /skills\/([0-9]-)?(designing-systems|generating-components|solid-react|solid-nextjs|design|impeccable|frontend-design)/i;
+/** True when this Write/Edit targets a UI file in a UI-ish path or with Tailwind classes. */
+function isUiWrite(tool, filePath, content) {
+	if (tool !== "Write" && tool !== "Edit") return false;
+	if (!UI_FILE_RE.test(filePath) || EXEMPT_RE.test(filePath)) return false;
+	return UI_PATH_RE.test(filePath) || TAILWIND_RE.test(content);
+}
+/** True when a design skill reference was read this session (scans the `refsRead` track). */
+function designSkillRead(refsRead) {
+	return refsRead.some((p) => DESIGN_SKILL_RE.test(p));
+}
+const block$1 = (reason, action) => ({
+	kind: "block",
+	title: "Design skill",
+	reason,
+	actions: [action]
+});
+/**
+* Gate a UI write: require a design-skill read AND any doc source. Returns a
+* blocking {@link Prompt}, or `null` to allow. NEVER requires Gemini.
+* @param tool - the tool name ("Write" | "Edit" | ...).
+* @param filePath - the written file path.
+* @param content - the written content (snippet on Edit, full file on Write).
+* @param ev - the session evidence (refsRead + docConsulted).
+*/
+function uiDesignSkillGate(tool, filePath, content, ev) {
+	if (!isUiWrite(tool, filePath, content)) return null;
+	if (!designSkillRead(ev.refsRead)) return block$1("BLOCKED: design skill not consulted before writing UI. Read a design SKILL.md (solid-react, generating-components, or designing-systems), then retry.", "Read a design skill reference, then retry");
+	if (!ev.docConsulted) return block$1("BLOCKED: no documentation consulted. Use ANY ONE of mcp__context7__query-docs, mcp__exa__web_search_exa, WebSearch, or WebFetch. Gemini is NOT required.", "Consult Context7, Exa, or web docs (Gemini not required), then retry");
+	return null;
+}
+//#endregion
+//#region src/policy/design/skill-evidence.ts
+/**
+* @module design/skill-evidence
+* IO side of the UI design-skill gate: read the verified session track and
+* derive {@link DesignEvidence} (read references + doc-consulted) for
+* {@link uiDesignSkillGate}. Kept separate from the pure gate logic (SRP).
+* @packageDocumentation
+*/
+/**
+* Read the verified session track and derive {@link DesignEvidence}. Fail-closed
+* on a missing/corrupt/tampered track (no evidence → the gate blocks).
+* @param sessionId - the Claude session id.
+* @param cwd - the project root (selects the per-project state dir).
+* @param baseDir - override the track base dir (tests); defaults to the project state dir.
+*/
+function collectDesignEvidence(sessionId, cwd, baseDir = defaultStateDir(cwd)) {
+	let track = null;
+	try {
+		track = verifyTrack(JSON.parse(readFileSync(trackFile(sessionId, baseDir), "utf8")));
+	} catch {
+		track = null;
+	}
+	return {
+		refsRead: track?.refsRead ?? [],
+		docConsulted: track ? isDocConsulted(track.authorizations, sessionId) : false
+	};
+}
+//#endregion
+//#region src/runtime/design-helpers.ts
+/**
+* @module design-helpers
+* Effectful helpers for the design pipeline gate: locate design-system.md and
+* apply PostToolUse fuse-browser transitions to the design state. Split out of
+* `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 SCROLL = "mcp__fuse-browser__browser_scroll";
+const GEMINI$1 = "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;
+	for (let i = 0; i < 6; i++) {
+		const p = join(dir, "design-system.md");
+		if (existsSync(p)) try {
+			return readFileSync(p, "utf8");
+		} catch {
+			return "";
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return "";
+}
+/** 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));
+	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
+	else if (event.tool === GEMINI$1) saveDesignState(cacheDir, {
+		...state,
+		geminiCalls: state.geminiCalls + 1
+	});
+	else if (event.tool === "Read") saveDesignState(cacheDir, recordRead(state, event.filePath ?? ""));
+	else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) saveDesignState(cacheDir, recordValidDesignSystem(state));
+}
+//#endregion
 //#region src/policy/design/gates.ts
 const ALLOWED_WRITE = /\.(html|css|md|json)$/;
 const EXEMPT_DIRS = [
@@ -620,48 +872,28 @@ function geminiEnabled() {
 //#region src/runtime/design.ts
 const NAV = "mcp__fuse-browser__browser_navigate";
 const SHOT = "mcp__fuse-browser__browser_screenshot";
-const SCROLL = "mcp__fuse-browser__browser_scroll";
 const GEMINI = "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;
-	for (let i = 0; i < 6; i++) {
-		const p = join(dir, "design-system.md");
-		if (existsSync(p)) try {
-			return readFileSync(p, "utf8");
-		} catch {
-			return "";
-		}
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return "";
-}
-/** Apply a PostToolUse fuse-browser transition to the design state. */
-function recordPost(event, cacheDir, state) {
-	if (event.tool === SHOT) saveDesignState(cacheDir, recordScreenshot(state, MIN_SCREENSHOTS[state.mode]));
-	else if (event.tool === NAV) saveDesignState(cacheDir, recordNavigate(state));
-	else if (event.tool === SCROLL) saveDesignState(cacheDir, recordScroll(state));
-	else if (event.tool === GEMINI) saveDesignState(cacheDir, {
-		...state,
-		geminiCalls: state.geminiCalls + 1
-	});
-	else if (event.tool === "Read") saveDesignState(cacheDir, recordRead(state, event.filePath ?? ""));
-	else if ((event.tool === "Write" || event.tool === "Edit") && (event.filePath ?? "").endsWith("design-system.md")) saveDesignState(cacheDir, recordValidDesignSystem(state));
-}
 /**
 * Design-pipeline gate (effectful: reads/writes the design state + design-system.md).
 * Returns a Prompt to block, or null when this isn't a design-agent context / nothing fires.
 */
 function designGate(payload, event, cacheDir, cwd) {
+	if (event.phase !== "post" && (event.tool === "Write" || event.tool === "Edit")) {
+		const skillBlock = uiDesignSkillGate(event.tool, event.filePath ?? "", event.content ?? "", collectDesignEvidence(event.sessionId, cwd));
+		if (skillBlock) return skillBlock;
+	}
 	const agentId = typeof payload.agent_id === "string" ? payload.agent_id : "";
 	const active = activeDesignAgent(cacheDir);
 	if (active && agentId && agentId !== active) return null;
 	const id = active || agentId;
 	if (!id) return null;
-	const state = loadDesignState(cacheDir, id);
-	if (!state) return null;
+	let state = loadDesignState(cacheDir, id);
+	if (!state) {
+		if (!active) return null;
+		const dsExists = findDesignSystem(cwd) !== "";
+		state = initDesignState(id, dsExists ? "page" : "full", dsExists);
+		saveDesignState(cacheDir, state);
+	}
 	if (event.phase === "post") {
 		recordPost(event, cacheDir, state);
 		if ((event.tool === "Write" || event.tool === "Edit") && /\.(tsx|jsx|css)$/.test(event.filePath ?? "")) {
@@ -1129,23 +1361,24 @@ function recordHistory(home, agentId, agentType, ts) {
 function trackAgentMemory(data, home = homedir(), now = Date.now()) {
 	mkdirSync(sessionsDir(home), { recursive: true });
 	const agentType = String(data.agent_type ?? data.subagent_type ?? "unknown");
-	const sessionId = String(data.session_id ?? "unknown");
+	const sessionId = sanitizeSessionId(data.session_id) ?? "unknown";
 	const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
 	recordHistory(home, String(data.agent_id ?? "unknown"), agentType, ts);
 	if (SKIP_AGENTS.test(agentType)) return JSON.stringify({ message: `Agent ${agentType} completed` });
-	const stateFile = join(sessionsDir(home), `session-${sessionId}-changes.json`);
-	if (existsSync(stateFile)) try {
-		const state = JSON.parse(readFileSync(stateFile, "utf-8"));
-		const count = state.cumulativeCodeFiles ?? 0;
-		if (count > 0) {
-			const files = (state.modifiedFiles ?? []).join(", ");
-			writeFileSync(stateFile, JSON.stringify({
-				...state,
+	const state = loadSessionState(sessionId, home);
+	const changes = state.changes;
+	const count = changes?.cumulativeCodeFiles ?? 0;
+	if (count > 0) {
+		const files = (changes?.modifiedFiles ?? []).join(", ");
+		saveSessionState(sessionId, {
+			...state,
+			changes: {
+				...changes,
 				cumulativeCodeFiles: 0
-			}), "utf-8");
-			return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${count} code file(s): ${files}. Run sniper agent now.`);
-		}
-	} catch {}
+			}
+		}, home);
+		return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${count} code file(s): ${files}. Run sniper agent now.`);
+	}
 	return JSON.stringify({ message: `Agent ${agentType} completed (no code changes)` });
 }
 //#endregion
@@ -1160,14 +1393,9 @@ function trackAgentMemory(data, home = homedir(), now = Date.now()) {
 */
 function validateTeammateOutput(data, home = homedir()) {
 	const teammate = String(data.teammate_name ?? "unknown");
-	const sessionId = String(data.session_id ?? "unknown");
-	const stateFile = join(sessionsDir(home), `session-${sessionId}-changes.json`);
-	if (!existsSync(stateFile)) return "";
-	try {
-		const state = JSON.parse(readFileSync(stateFile, "utf-8"));
-		const count = state.cumulativeCodeFiles ?? 0;
-		if (count > 0) return contextResponse("TeammateIdle", `Teammate '${teammate}' going idle after modifying ${count} code file(s): ${(state.modifiedFiles ?? []).slice(0, 5).join(", ")}. Consider running sniper validation.`);
-	} catch {}
+	const changes = loadSessionState(sanitizeSessionId(data.session_id) ?? "unknown", home).changes;
+	const count = changes?.cumulativeCodeFiles ?? 0;
+	if (count > 0) return contextResponse("TeammateIdle", `Teammate '${teammate}' going idle after modifying ${count} code file(s): ${(changes?.modifiedFiles ?? []).slice(0, 5).join(", ")}. Consider running sniper validation.`);
 	return "";
 }
 //#endregion
@@ -1260,7 +1488,7 @@ function validateRulesLoaded(data, home = homedir()) {
 //#endregion
 //#region src/runtime/lifecycle/track-changes.ts
 /** Code-file extensions tracked for sniper (mirrors track-session-changes.py). */
-const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
+const CODE_EXT$1 = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
 /**
 * Handle PostToolUse Write/Edit: track the cumulative set of modified code
 * files per session and emit the mandatory "SNIPER VALIDATION REQUIRED"
@@ -1272,7 +1500,7 @@ const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelt
 * @returns The native hook stdout (possibly empty when not a code file).
 */
 function trackSessionChanges(sessionIdRaw, filePath, home = homedir(), now = Date.now()) {
-	if (!filePath || !CODE_EXT.test(filePath)) return "";
+	if (!filePath || !CODE_EXT$1.test(filePath)) return "";
 	const sid = sanitizeSessionId(sessionIdRaw) ?? "unknown";
 	const state = loadSessionState(sid, home);
 	const prev = state.changes ?? {
@@ -1354,6 +1582,66 @@ function postEditTypescript(filePath) {
 	return contextResponse("PostToolUse", `Lint issues in ${basename(filePath)}: ${issues.join(" | ")}`);
 }
 //#endregion
+//#region src/runtime/lifecycle/task-completed.ts
+/** Code-file extensions audited on task completion (mirrors validate-task-solid.py). */
+const CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".py",
+	".go",
+	".rs",
+	".java",
+	".php",
+	".cpp",
+	".c",
+	".rb",
+	".swift",
+	".kt",
+	".dart",
+	".vue",
+	".svelte",
+	".astro"
+]);
+/**
+* Re-count physical lines of every modified code file and collect SOLID
+* violations (`<basename>: <n> lines (max <max>)`) for those exceeding `max`.
+* @param files - Candidate modified file paths.
+* @param max - The SOLID line ceiling.
+* @returns The list of violation strings (empty when all files comply).
+*/
+function collectViolations(files, max) {
+	const violations = [];
+	for (const fp of files) {
+		if (!CODE_EXTENSIONS.has(extname(fp)) || !existsSync(fp)) continue;
+		try {
+			const lines = countLines(readFileSync(fp, "utf-8"));
+			if (lines > max) violations.push(`${basename(fp)}: ${lines} lines (max ${max})`);
+		} catch {}
+	}
+	return violations;
+}
+/**
+* Handle TaskCompleted: re-measure the session's modified code files and emit a
+* `SOLID VIOLATION` additionalContext listing any file over the line ceiling.
+* Ports `task-completed/validate-task-solid.py`.
+* @param payload - The TaskCompleted hook payload (`task_id`, `task_subject`, `session_id`).
+* @param home - Home dir (defaults to `~`).
+* @returns The native hook stdout, or `""` when there are no violations.
+*/
+function validateTaskSolid(payload, home = homedir()) {
+	const sid = sanitizeSessionId(payload.session_id ?? "unknown");
+	if (!sid) return "";
+	const files = loadSessionState(sid, home).changes?.modifiedFiles ?? [];
+	if (files.length === 0) return "";
+	const max = resolveMaxLines();
+	const violations = collectViolations(files, max);
+	if (violations.length === 0) return "";
+	const taskId = String(payload.task_id ?? "");
+	return contextResponse("TaskCompleted", `SOLID VIOLATION in task '${String(payload.task_subject ?? "")}' (${taskId}): ${violations.length} file(s) exceed ${max} lines: ` + violations.slice(0, 5).join("; "));
+}
+//#endregion
 //#region src/runtime/lifecycle/cartographer/fs-util.ts
 /**
 * Filesystem helpers for the cartographer tree walk. Ports the fs parts of
@@ -1575,18 +1863,63 @@ function readPluginMeta(pluginPath) {
 /**
 * Auto-detect the marketplace `plugins` dir that contains `cartographer`,
 * falling back to the first marketplace with a `plugins` dir, else `cwd`.
-* Ports `find_marketplace_plugins`.
+* Ports `find_marketplace_plugins`, but harness-agnostic: the config dir is
+* derived from the detected harness (`.claude`, `.codex`, `.cursor`, …) via the
+* shared `HOME_DIR` mapping instead of a hardcoded `.claude`.
 * @param home - Home directory (defaults to `~`).
+* @param id - Detected harness id (defaults to runtime detection).
 * @returns The resolved plugins directory.
 */
-function findMarketplacePlugins(home = homedir()) {
-	const mp = join(home, ".claude", "plugins", "marketplaces");
+function findMarketplacePlugins(home = homedir(), id = detectHarness().id) {
+	const mp = join(home, HOME_DIR[id] ?? ".claude", "plugins", "marketplaces");
 	const markets = sortedNames$1(mp);
 	for (const m of markets) if (existsSync(join(mp, m, "plugins", "cartographer"))) return join(mp, m, "plugins");
 	for (const m of markets) if (existsSync(join(mp, m, "plugins"))) return join(mp, m, "plugins");
 	return process.cwd();
 }
 //#endregion
+//#region src/runtime/lifecycle/cartographer/scan-hooks.ts
+/**
+* Hook scanning (fs). Ports `_scan_hooks` from `scan_plugins.py`: reads a
+* plugin's `hooks/hooks.json` and reduces it to a single `("hooks", "<events>", "")`
+* row. The `hooks` value (or the whole document) is either a MAP of event →
+* entries (keys are the events) or a LIST of entries each carrying an `event`.
+*/
+/** True for a non-null plain object (excludes arrays), mirroring Python `isinstance(x, dict)`. */
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Sort unique non-empty strings alpha (byte-order). */
+function sortedEvents(events) {
+	return [...new Set([...events].filter((e) => e))].sort((a, b) => a.localeCompare(b, "en"));
+}
+/** Derive hook event names from the `hooks.json` data (map keys, or list `event` fields). */
+function hookEvents(hooksData) {
+	if (isPlainObject(hooksData)) return sortedEvents(Object.keys(hooksData).filter((k) => !k.startsWith("_")));
+	if (Array.isArray(hooksData)) return sortedEvents(hooksData.map((h) => isPlainObject(h) ? String(h.event ?? "") : ""));
+	return [];
+}
+/**
+* Scan `hooks/hooks.json` into a single `("hooks", "<events>", "")` row.
+* @param root - Absolute plugin directory.
+* @returns The single hooks row, or `[]` when absent/empty/unreadable.
+*/
+function scanHooks(root) {
+	const file = join(root, "hooks", "hooks.json");
+	if (!existsSync(file)) return [];
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf-8"));
+		const events = hookEvents(isPlainObject(raw) ? raw.hooks ?? raw : {});
+		return events.length ? [[
+			"hooks",
+			events.join(", "),
+			""
+		]] : [];
+	} catch {
+		return [];
+	}
+}
+//#endregion
 //#region src/runtime/lifecycle/cartographer/scan.ts
 /**
 * Plugin scanning (fs). Ports `scan_plugins.py`: turns a plugin's
@@ -1655,24 +1988,6 @@ function scanCommands(root) {
 		fileField(join(dir, n), "description").slice(0, 50)
 	]);
 }
-/** Scan `hooks/hooks.json` → a single `("hooks", "<events>", "")` row, or none. */
-function scanHooks(root) {
-	const file = join(root, "hooks", "hooks.json");
-	if (!existsSync(file)) return [];
-	try {
-		const raw = JSON.parse(readFileSync(file, "utf-8"));
-		const data = raw && typeof raw === "object" ? raw : {};
-		const hooks = data.hooks && typeof data.hooks === "object" ? data.hooks : data;
-		const events = Object.keys(hooks).filter((k) => !k.startsWith("_")).sort((a, b) => a.localeCompare(b, "en"));
-		return events.length ? [[
-			"hooks",
-			events.join(", "),
-			""
-		]] : [];
-	} catch {
-		return [];
-	}
-}
 /**
 * Scan a single plugin directory into ordered `[type, name, desc]` rows.
 * @param pluginDir - Absolute plugin directory.
@@ -1853,6 +2168,15 @@ function generateEcosystemMap(now, pluginsDirOverride) {
 * navigation context from the latter as additionalContext.
 */
 /**
+* Resolve the marketplace plugins dir from `CLAUDE_PLUGIN_ROOT`, mirroring the
+* Python hook which passes `${CLAUDE_PLUGIN_ROOT}/..` to `generate_map.py`.
+* @returns The plugins dir (env `/..`), or `undefined` to fall back to auto-detect.
+*/
+function pluginsDirFromEnv() {
+	const root = process.env.CLAUDE_PLUGIN_ROOT;
+	return root ? resolve(root, "..") : void 0;
+}
+/**
 * Regenerate the project map + plugin ecosystem map for `cwd` on SessionStart.
 * Emits the ecosystem navigation context as additionalContext (or "").
 * @param cwd - The working directory.
@@ -1861,7 +2185,7 @@ function generateEcosystemMap(now, pluginsDirOverride) {
 */
 function cartoSessionStart(cwd, now = Date.now()) {
 	generateProjectMap(cwd);
-	const ctx = generateEcosystemMap(now);
+	const ctx = generateEcosystemMap(now, pluginsDirFromEnv());
 	return ctx ? contextResponse("SessionStart", ctx) : "";
 }
 //#endregion
@@ -2658,12 +2982,101 @@ async function cacheDocFromTranscript(transcript, cwd, home = homedir()) {
 	await writeJsonFile(indexFile, index, true);
 }
 //#endregion
+//#region src/runtime/lifecycle/aipilot/promote-global-lessons.ts
+/**
+* Promote high-frequency project lessons (occurrence count >= 3) to the global,
+* stack-scoped cache (`fusengine-cache/lessons/_global/<stack>.json`, cap 25).
+* Ports the ai-pilot `promote-global-lessons.ts` (a spawned subprocess) as an
+* in-process call from `cacheSniperLessons`. Pure side-effect.
+*/
+const MIN_COUNT = 3;
+const MAX_GLOBAL = 25;
+/** Group lessons by `error_type:pattern`. */
+function groupByKey(lessons) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const l of lessons) {
+		const key = `${l.error_type}:${l.pattern}`;
+		(groups.get(key) ?? groups.set(key, []).get(key)).push(l);
+	}
+	return [...groups.values()];
+}
+/** Read every project lesson file's `errors` into one flat (un-deduped) list. */
+async function aggregateErrors(cacheDir) {
+	let files;
+	try {
+		files = readdirSync(cacheDir).filter((f) => f.endsWith(".json"));
+	} catch {
+		return [];
+	}
+	const all = [];
+	for (const f of files) {
+		const data = await readJsonFile(join(cacheDir, f));
+		if (data?.errors) all.push(...data.errors);
+	}
+	return all;
+}
+/** Keep groups seen >= MIN_COUNT times, collapsed to a single lesson each. */
+function filterFrequent(lessons) {
+	return groupByKey(lessons).filter((e) => e.length >= MIN_COUNT).map((entries) => {
+		const first = entries[0];
+		return {
+			error_type: first.error_type,
+			pattern: first.pattern,
+			fix: first.fix,
+			last_seen: first.last_seen,
+			count: entries.length,
+			files: [...new Set(entries.flatMap((e) => e.files))],
+			code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) }
+		};
+	});
+}
+/** Merge tagged candidates into existing global lessons; dedup, sum, sort, cap. */
+function mergeGlobal(existing, candidates, projHash) {
+	const tagged = candidates.map((c) => ({
+		...c,
+		source_projects: [projHash]
+	}));
+	return groupByKey([...existing, ...tagged]).map((entries) => {
+		const first = entries[0];
+		return {
+			error_type: first.error_type,
+			pattern: first.pattern,
+			fix: first.fix,
+			last_seen: first.last_seen,
+			count: entries.reduce((sum, e) => sum + e.count, 0),
+			files: [...new Set(entries.flatMap((e) => e.files))],
+			code: { line: [...new Set(entries.flatMap((e) => e.code?.line ?? []))].slice(0, 5) },
+			source_projects: [...new Set(entries.flatMap((e) => e.source_projects ?? []))]
+		};
+	}).sort((a, b) => b.count - a.count).slice(0, MAX_GLOBAL);
+}
+/**
+* Promote high-frequency lessons from `cacheDir` to the global stack file.
+* @param cacheDir - Per-project lessons cache dir to scan.
+* @param stack - Detected project stack (`nextjs`, `laravel`, …, `universal`).
+* @param projHash - Source project hash (tags promoted entries).
+* @param home - Home dir (defaults to `~`).
+*/
+async function promoteGlobalLessons(cacheDir, stack, projHash, home = homedir()) {
+	const candidates = filterFrequent(await aggregateErrors(cacheDir));
+	if (candidates.length === 0) return;
+	const globalDir = join(cacheBaseDir(home), "lessons", "_global");
+	mkdirSync(globalDir, { recursive: true });
+	const globalFile = join(globalDir, `${stack}.json`);
+	const merged = mergeGlobal(await readJsonFile(globalFile) ?? [], candidates, projHash);
+	await writeJsonFile(globalFile, merged, true);
+	logCacheEvent("lessons", "promoted", projHash, {
+		count: merged.length,
+		stack
+	}, home);
+}
+//#endregion
 //#region src/runtime/lifecycle/aipilot/cache-lessons.ts
 /**
 * SubagentStop (matcher "sniper") for the ai-pilot scope: capture error
 * patterns + corrected code from the sniper transcript as lessons. Ports
-* `cache-sniper-lessons.ts` (the dead `promote-global-lessons.ts` spawn is
-* dropped — that helper no longer exists). Pure side-effect.
+* `cache-sniper-lessons.ts`, including the high-frequency promotion to the
+* global stack cache (`promoteGlobalLessons`). Pure side-effect.
 */
 /**
 * SubagentStop sniper: extract lessons from the transcript and persist them.
@@ -2700,6 +3113,7 @@ async function cacheSniperLessons(transcript, cwd, home = homedir()) {
 		timestamp,
 		errors
 	}, true);
+	await promoteGlobalLessons(cacheDir, detectStack(projectPath), pHash, home);
 	logCacheEvent("lessons", "hit", pHash, { count: edits.length }, home);
 }
 //#endregion
@@ -2924,12 +3338,12 @@ function contextTextOf(response) {
 	}
 }
 /**
-* Combine two SubagentStart responses into one (Claude concatenates multiple
-* hooks' additionalContext; collapsing two matcher-"" scripts into one dispatch
-* call must do that join itself). Returns "" when both are empty.
+* Combine N SubagentStart responses into one (Claude concatenates every hook's
+* additionalContext; collapsing the matcher-"" + type-specific scripts into one
+* dispatch call must do that join itself). Returns "" when all are empty.
 */
-function combineContext(a, b) {
-	const parts = [contextTextOf(a), contextTextOf(b)].filter(Boolean);
+function combineContext(...responses) {
+	const parts = responses.map(contextTextOf).filter(Boolean);
 	return parts.length ? contextResponse("SubagentStart", parts.join("\n\n")) : "";
 }
 /** The transcript path a SubagentStop payload reports (Stop-only field). */
@@ -2937,13 +3351,22 @@ function transcriptOf(payload) {
 	const t = payload.agent_transcript_path;
 	return typeof t === "string" ? t : void 0;
 }
-/** SubagentStart routing: cache injectors keyed on agent_type. */
-async function onSubagentStart(payload, cwd, now) {
-	const agent = agentTypeOf(payload);
+/** Type-specific SubagentStart cache for an agent, or "" when none applies. */
+async function typeSpecificCache(agent, cwd, now) {
 	if (agent.includes("explore-codebase")) return injectExploreCache(cwd, void 0, now);
 	if (agent.includes("research-expert")) return injectDocCache(cwd, void 0, now);
 	if (agent.includes("sniper")) return injectTestCache(cwd, void 0, now);
-	return combineContext(await injectApexSubagentContext(cwd), await injectLessonsCache(cwd, void 0, now));
+	return "";
+}
+/**
+* SubagentStart routing. Parity with the Python ai-pilot hooks: the two
+* matcher-"" entries (APEX context + lessons "known issues") fire for EVERY
+* sub-agent, then the type-specific cache (explore/doc/test) is concatenated on
+* top. Sniper must still receive the lessons block — hence no early return.
+*/
+async function onSubagentStart(payload, cwd, now) {
+	const agent = agentTypeOf(payload);
+	return combineContext(await injectApexSubagentContext(cwd), await injectLessonsCache(cwd, void 0, now), await typeSpecificCache(agent, cwd, now));
 }
 /** SubagentStop routing: transcript-driven cache writers (side-effects). */
 async function onSubagentStop(payload, cwd) {
@@ -3014,6 +3437,7 @@ function dispatchLifecycle(input) {
 		case "InstructionsLoaded":
 			validateRulesLoaded(input.payload);
 			return "";
+		case "TaskCompleted": return validateTaskSolid(input.payload);
 		default: return null;
 	}
 }
@@ -3465,11 +3889,11 @@ async function dispatchMemory(event, payload, cwd, now) {
 * missing. Opt-in only — silent when no marker / non-HTML / file unreadable.
 */
 /**
-* Validate the edited file's SEO completeness. Returns a deny message (for a
-* `permissionDecision: deny` response) when HTML-like, opted-in, and missing
+* Validate the edited file's SEO completeness. Returns a block message (for a
+* top-level `decision: block` response) when HTML-like, opted-in, and missing
 * elements; otherwise `null` (allow).
 * @param payload - The raw PostToolUse payload.
-* @returns The deny reason string, or `null` to allow.
+* @returns The block reason string, or `null` to allow.
 */
 function seoPostToolUse(payload) {
 	const path = payload.tool_input?.file_path;
@@ -3484,14 +3908,16 @@ function seoPostToolUse(payload) {
 	}
 }
 /**
-* SEO PostToolUse as a ready native response: a `permissionDecision: deny`
+* SEO PostToolUse as a ready native response: a top-level `decision: block`
 * string when the edited file is missing SEO elements, else `null` (allow).
+* PostToolUse ignores `permissionDecision` (PreToolUse-only), so this must use
+* the `decision`/`reason` keys to actually feed the failure back to Claude.
 * @param payload - The raw PostToolUse payload.
-* @returns The deny response string, or `null` to allow.
+* @returns The block response string, or `null` to allow.
 */
 function seoPostToolUseResponse(payload) {
-	const deny = seoPostToolUse(payload);
-	return deny ? denyResponse("PostToolUse", deny) : null;
+	const block = seoPostToolUse(payload);
+	return block ? blockResponse(block) : null;
 }
 //#endregion
 //#region src/runtime/lifecycle-bridge.ts
@@ -3535,6 +3961,26 @@ function postEditContext(scope, event, now) {
 }
 //#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)$/;
+/** Paths exempt from the APEX gates even when they are code (parity: require-apex-agents.py EXEMPT_PATTERNS). */
+const EXEMPT_PATTERNS = [
+	/\.claude-plugin\//,
+	/CHANGELOG\.md$/,
+	/marketplace\.json$/,
+	/\/\.claude\/(apex|memory|logs|fusengine-cache)\//
+];
+/**
+* True when `filePath` is a code file the APEX freshness/doc/SOLID gates should
+* police — i.e. it matches a tracked source extension AND no exempt pattern.
+* Mirrors require-apex-agents.py so non-code (and exempt) paths skip those gates.
+* @param filePath - Absolute path of the edit target (or undefined).
+* @returns Whether the APEX gates apply to this path.
+*/
+function isApexScoped(filePath) {
+	if (!filePath || !CODE_EXT.test(filePath)) return false;
+	return !EXEMPT_PATTERNS.some((p) => p.test(filePath));
+}
 /**
 * Code-only line count of the existing on-disk file (undefined if
 * absent/unreadable). Uses {@link countLines} (skips blank/comment lines) so a
@@ -3556,7 +4002,7 @@ function existingLineCount(path) {
 //#region src/freshness/agent-evidence.ts
 /**
 * Platform-authored transcript evidence for APEX agent freshness.
-* Parses the Claude Code session JSONL transcript to find genuine Task
+* Parses the Claude Code session JSONL transcript to find genuine `Task`/`Agent`
 * tool_use entries — forging this requires writing into the transcript file
 * which the Claude Code platform controls, unlike the self-recorded track.
 */
@@ -3569,9 +4015,9 @@ function parseTs(raw) {
 }
 /**
 * Return `true` ONLY when, for EVERY name in `names`, the Claude Code
-* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task`
-* tool whose `subagent_type` (or `name`) input field matches, with the entry
-* timestamp within `windowMs` of `now`.
+* transcript at `transcriptPath` contains a genuine `tool_use` of the `Task` or
+* `Agent` tool whose `subagent_type` (or `name`) input field matches — after
+* stripping any plugin prefix — with the entry timestamp within `windowMs` of `now`.
 *
 * **Timestamp note:** when a transcript entry carries no `timestamp` field it
 * is counted as within-window (we cannot prove staleness). This is
@@ -3609,9 +4055,10 @@ function agentsRanFromTranscript(transcriptPath, names, windowMs, now) {
 		const content = entry.message?.content;
 		if (!Array.isArray(content)) continue;
 		for (const block of content) {
-			if (block?.type !== "tool_use" || block.name !== "Task") continue;
-			const agent = block.input?.subagent_type ?? block.input?.name;
-			if (typeof agent === "string" && names.includes(agent)) found.add(agent);
+			if (block?.type !== "tool_use" || block.name !== "Task" && block.name !== "Agent") continue;
+			const raw = block.input?.subagent_type ?? block.input?.name;
+			const agent = typeof raw === "string" ? raw.split(":").pop() ?? raw : void 0;
+			if (agent !== void 0 && names.includes(agent)) found.add(agent);
 		}
 		if (found.size === names.length) return true;
 	}
@@ -3958,6 +4405,8 @@ const TRIVIAL_BUDGET = 4;
 * track. Returns the first blocking prompt, or null to allow.
 */
 async function gate(input) {
+	const precommit = preCommitGate(input.tool, input.command, input.cwd);
+	if (precommit) return precommit;
 	const existingLines = existingLineCount(input.filePath);
 	let quick;
 	try {
@@ -3973,8 +4422,6 @@ async function gate(input) {
 		return FAIL_CLOSED;
 	}
 	if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
-	const precommit = preCommitGate(input.tool, input.command, input.cwd);
-	if (precommit) return precommit;
 	const modular = modularGate(input.tool, input.filePath, input.content, input.cwd);
 	if (modular) return modular;
 	if (!input.filePath) return null;
@@ -3982,29 +4429,31 @@ async function gate(input) {
 	const track = await loadTrack(input.trackFile);
 	const solidOrSkill = frameworkSkillGate(input, track.refsRead, existingLines);
 	if (solidOrSkill) return solidOrSkill;
-	const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
-	if (!input.isReplaceAll && lineCount < 5 && trivialCount(track, window, input.now) < 4) {
-		await saveTrack(input.trackFile, recordTrivialEdit(track, input.now, window, input.now));
-		return null;
-	}
-	const freshnessFor = (names) => input.transcriptPath ? agentsRanFromTranscript(input.transcriptPath, names, window, input.now) : agentsFresh(track, names, window, input.now);
-	const ctx = {
-		sessionId: input.sessionId,
-		framework: input.framework,
-		filePath: input.filePath,
-		content: input.content ?? "",
-		authorizations: track.authorizations,
-		refs: input.refs,
-		refsRead: track.refsRead,
-		agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
-		brainstormRequired: track.brainstormRequired,
-		brainstormFresh: freshnessFor(["brainstorming"])
-	};
-	try {
-		const apex = evaluateApex(ctx);
-		if (apex) return apex;
-	} catch {
-		return FAIL_CLOSED;
+	if (isApexScoped(input.filePath)) {
+		const lineCount = input.content === void 0 ? Number.POSITIVE_INFINITY : input.content.split("\n").length;
+		if (!input.isReplaceAll && lineCount < 5 && 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 ctx = {
+			sessionId: input.sessionId,
+			framework: input.framework,
+			filePath: input.filePath,
+			content: input.content ?? "",
+			authorizations: track.authorizations,
+			refs: input.refs,
+			refsRead: track.refsRead,
+			agentsFresh: freshnessFor([...REQUIRED_AGENTS]),
+			brainstormRequired: track.brainstormRequired,
+			brainstormFresh: freshnessFor(["brainstorming"], Number.MAX_SAFE_INTEGER)
+		};
+		try {
+			const apex = evaluateApex(ctx);
+			if (apex) return apex;
+		} catch {
+			return FAIL_CLOSED;
+		}
 	}
 	return dryGate(input.tool, input.filePath, input.content, input.cwd);
 }
@@ -4137,7 +4586,7 @@ async function handleHook(id, payload, opts) {
 		const response = payload.tool_response ?? payload.tool_output;
 		mcpPostStore(event.tool, event.input, response, mcpDir);
 		const designWarn = designGate(payload, event, mcpDir, opts.cwd);
-		const activity = activityFor({
+		const activities = activityFor({
 			tool: event.tool,
 			input: event.input,
 			sessionId: event.sessionId,
@@ -4145,7 +4594,7 @@ async function handleHook(id, payload, opts) {
 			now: opts.now,
 			responseLength: extractText(response).length
 		});
-		if (activity) await recordActivity(file, activity);
+		for (const activity of activities) await recordActivity(file, activity);
 		postTrackingSideEffects(opts.scope ?? "core", event, event.input, opts.now, payload, opts.cwd);
 		const seoDeny = opts.scope === "seo" ? seoPostToolUseResponse(payload) : null;
 		if (seoDeny) return {
@@ -4176,4 +4625,4 @@ async function handleHook(id, payload, opts) {
 	});
 }
 //#endregion
-export { sessionStartCore as $, writePluginMap as A, sanitizeSessionId as At, trackSessionChanges as B, aipilotPostToolUse as C, saveSecurityState as Ct, lessonsStateFileFor as D, claudeHome as Dt, lessonsFileFor as E, todayUtc as Et, mergeLines as F, validateTeammateOutput as G, cleanupSession as H, countFiles as I, detectSolidProfile as J, trackAgentMemory as K, getFileDesc as L, isProject as M, sessionStatePath as Mt, writeTree as N, sessionsDir as Nt, cartoSessionStart as O, fusengineCache as Ot, loadEnriched as P, runSessionStartCleanups as Q, listChildren as R, dispatchLifecycle as S, loadSecurityState as St, dispatchLessons as T, securityStatePath as Tt, saveApexState as U, validateRulesLoaded as V, logToolFailure as W, injectRules as X, solidDetectStart as Y, readRules as Z, postTrackingSideEffects as _, mcpPostStore as _t, TRIVIAL_BUDGET as a, gitContext as at, trackSkillRead as b, activityFor as bt, detectDuplication as c, taskContext as ct, lifecycleStdout as d, defaultStateDir as dt, pruneEmptyDirs as et, postEditContext as f, projectHash$1 as ft, securityAdvisory as g, isMcpTool as gt, dispatchMemory as h, MCP_TTL_MS as ht, REQUIRED_AGENTS as i, devContext as it, generateProjectMap as j, saveSessionState as jt, generateEcosystemMap as k, loadSessionState as kt, dryGate as l, respond as lt, seoPostToolUseResponse as m, normalizeEvent as mt, handlePre as n, removeOldFiles as nt, gate as o, projectContext as ot, seoPostToolUse as p, trackFile as pt, subagentCacheContext as q, DEFAULT_WINDOW_MS as r, trimLogFile as rt, preCommitGate as s, promptSubmitContext as st, handleHook as t, purgeTtlTree as tt, extractSymbols as u, recordActivity as ut, trackWatchResearch as v, mcpPreIntercept as vt, dispatchAipilot as w, securityStateDir as wt, trackEnrichment as x, isoUtc as xt, trackMcpResearch as y, queryOf as yt, postEditTypescript as z };
+export { sessionStartCore as $, writePluginMap as A, fusengineCache as At, trackSessionChanges as B, aipilotPostToolUse as C, isoUtc as Ct, lessonsStateFileFor as D, securityStatePath as Dt, lessonsFileFor as E, securityStateDir as Et, mergeLines as F, sessionsDir as Ft, validateTeammateOutput as G, cleanupSession as H, countFiles as I, detectSolidProfile as J, trackAgentMemory as K, getFileDesc as L, isProject as M, sanitizeSessionId as Mt, writeTree as N, saveSessionState as Nt, cartoSessionStart as O, todayUtc as Ot, loadEnriched as P, sessionStatePath as Pt, runSessionStartCleanups as Q, listChildren as R, dispatchLifecycle as S, activityFor as St, dispatchLessons as T, saveSecurityState as Tt, saveApexState as U, validateRulesLoaded as V, logToolFailure as W, injectRules as X, solidDetectStart as Y, readRules as Z, postTrackingSideEffects as _, MCP_TTL_MS as _t, TRIVIAL_BUDGET as a, gitContext as at, trackSkillRead as b, isMcpTool as bt, detectDuplication as c, taskContext as ct, lifecycleStdout as d, defaultStateDir as dt, pruneEmptyDirs as et, postEditContext as f, projectHash$1 as ft, securityAdvisory as g, mcpPreIntercept as gt, dispatchMemory as h, mcpPostStore as ht, REQUIRED_AGENTS as i, devContext as it, generateProjectMap as j, loadSessionState as jt, generateEcosystemMap as k, claudeHome as kt, dryGate as l, respond as lt, seoPostToolUseResponse as m, normalizeEvent as mt, handlePre as n, removeOldFiles as nt, gate as o, projectContext as ot, seoPostToolUse as p, trackFile as pt, subagentCacheContext as q, DEFAULT_WINDOW_MS as r, trimLogFile as rt, preCommitGate as s, promptSubmitContext as st, handleHook as t, purgeTtlTree as tt, extractSymbols as u, recordActivity as ut, trackWatchResearch as v, WEBFETCH_TTL_MS as vt, dispatchAipilot as w, loadSecurityState as wt, trackEnrichment as x, queryOf as xt, trackMcpResearch as y, cacheQueryOf as yt, postEditTypescript as z };