@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/aipilot/cache-base.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared cache-path + age helpers for the ai-pilot scope.
+ * Reuses the harness home-state (`fusengineCache`) so the ai-pilot caches live
+ * under the same `~/.fuse-harness/cache` tree as the core MCP cache — no
+ * second cache layer.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fusengineCache } from "../../home-state";
+import { readText } from "../../../util/runtime-io";
+
+/** Doc cache freshness window, in seconds (7 days) — shared by inject-doc.ts (serves the cache) and doc-cache-gate.ts (denies a redundant re-query). */
+export const DOC_CACHE_TTL_SECONDS = 604_800;
+
+/** 16-char hex SHA-256 of `text` (project hash / doc topic key). */
+export function hashText16(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/** 16-char project hash from its absolute path. */
+export function projectHash(projectPath: string): string {
+  return hashText16(projectPath);
+}
+
+/** `~/.fuse-harness/cache` base dir (shared with the core MCP cache). */
+export function cacheBaseDir(home: string = homedir()): string {
+  return fusengineCache(home);
+}
+
+/** Per-type, per-project cache dir: `cache/<type>/<projectHash>`. */
+export function cacheDirFor(type: string, projectPath: string, home: string = homedir()): string {
+  return join(cacheBaseDir(home), type, projectHash(projectPath));
+}
+
+/** Age in seconds from an ISO timestamp (now - ts). */
+export function cacheAge(ts: string, now: number = Date.now()): number {
+  return Math.floor((now - new Date(ts).getTime()) / 1000);
+}
+
+/** Full SHA-256 hex checksum of a file's text; "" when unreadable. */
+export async function fileChecksum(path: string): Promise<string> {
+  try {
+    return createHash("sha256").update(readText(path)).digest("hex");
+  } catch {
+    return "";
+  }
+}

package/src/runtime/lifecycle/aipilot/cache-doc.ts

@@ -0,0 +1,100 @@
+/**
+ * SubagentStop (matcher "research-expert") for the ai-pilot scope: extract the
+ * agent's synthesis text from the transcript and cache it as documentation.
+ * Ports `cache-doc-from-transcript.ts`. SubagentStop output here is a pure
+ * side-effect (no stdout needed).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { readText, writeText, pathExists, sleep } from "../../../util/runtime-io";
+import { hashText16, cacheDirFor } from "./cache-base";
+import { transcriptFilePaths, projectRootFromPaths } from "./transcript";
+import { canonicalizeMcpToolName } from "../../mcp-tool-name";
+import type { CacheEntry, CacheIndex } from "./types";
+
+const TOOL_PATTERN = /context7__query-docs|exa__get_code_context|exa__web_search/;
+const MAX_DOC_SIZE = 20480;
+const MIN_TEXT_SIZE = 200;
+const MAX_DOCS = 15;
+const RETRY_DELAYS = [500, 1000, 2000];
+
+/**
+ * Extract the longest assistant synthesis + queried library ids from a transcript.
+ * @param id - Harness adapter id, used to canonicalize `block.name` (Codex-mangled
+ *   underscore tool names) before the {@link TOOL_PATTERN} match — see
+ *   {@link cacheDocFromTranscript} for why this is a defensive, unconfirmed-case cover.
+ */
+async function extractSynthesis(path: string, id: string): Promise<{ text: string; libraries: string[] }> {
+  const lines = readText(path).split("\n").filter(Boolean);
+  const libraries: string[] = [];
+  let synthesis = "";
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line) as { type?: string; role?: string; message?: { content?: unknown } };
+      const role = entry?.type ?? entry?.role;
+      const contents = entry?.message?.content;
+      if (!Array.isArray(contents)) continue;
+      for (const block of contents) {
+        if (block.type === "tool_use" && TOOL_PATTERN.test(canonicalizeMcpToolName(id, block.name ?? ""))) {
+          const lib = block.input?.libraryId ?? block.input?.query ?? "";
+          if (lib && !libraries.includes(lib)) libraries.push(lib);
+        }
+        if (role === "assistant" && block.type === "text" && typeof block.text === "string" && block.text.length > synthesis.length) {
+          synthesis = block.text;
+        }
+      }
+    } catch { /* skip malformed */ }
+  }
+  return { text: synthesis, libraries };
+}
+
+/**
+ * SubagentStop research-expert: cache the synthesis text from the transcript.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ * @param id - Harness adapter id (defaults to "claude-code"). On `"codex"`,
+ *   every `tool_use.name` read from the transcript is canonicalized before the
+ *   {@link TOOL_PATTERN} match, defensively covering the SAME Codex-mangled
+ *   underscore form as `doc-cache-gate.ts`'s `docCacheGate`. UNLIKE that gate,
+ *   this is NOT a confirmed-reproduced bug: the proof that Codex emits the
+ *   underscore form (`sanitize_responses_api_tool_name()`, openai/codex#14605,
+ *   `SCENARIO_DASH_TOOL` in #18385) is about the live PreToolUse HOOK payload,
+ *   never observed here against transcript `tool_use.name` content. The
+ *   canonicalization is a no-op when the transcript already carries the dash
+ *   form (idempotence proven in `test/mcp-tool-name.test.ts`, test 2), so this
+ *   costs nothing if the hypothesis turns out false.
+ */
+export async function cacheDocFromTranscript(transcript: string | undefined, cwd: string, home: string = homedir(), id: string = "claude-code"): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const allPaths = await transcriptFilePaths(transcript);
+  const projPath = projectRootFromPaths(allPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const cacheDir = cacheDirFor("doc", projPath, home);
+  const docsDir = join(cacheDir, "docs");
+
+  let result = await extractSynthesis(transcript, id);
+  for (const delay of RETRY_DELAYS) {
+    if (result.text.length >= MIN_TEXT_SIZE && result.libraries.length > 0) break;
+    await sleep(delay);
+    result = await extractSynthesis(transcript, id);
+  }
+  const { text, libraries } = result;
+  if (text.length < MIN_TEXT_SIZE || libraries.length === 0) return;
+
+  const indexFile = join(cacheDir, "index.json");
+  const index = (await readJsonFile<CacheIndex>(indexFile)) ?? { project: projPath, docs: [] };
+  const timestamp = new Date().toISOString();
+  const content = text.slice(0, MAX_DOC_SIZE);
+  const topic = libraries.join(", ");
+  const docHash = hashText16(topic);
+  writeText(join(docsDir, `${docHash}.md`), content);
+
+  const sizeKb = Math.floor(content.length / 1024);
+  for (const lib of libraries) {
+    index.docs = index.docs.filter((d: CacheEntry) => d.library !== lib);
+    index.docs.push({ hash: docHash, library: lib, topic, timestamp, size_kb: sizeKb });
+  }
+  if (index.docs.length > MAX_DOCS) index.docs = index.docs.slice(-MAX_DOCS);
+  await writeJsonFile(indexFile, index, true);
+}

package/src/runtime/lifecycle/aipilot/cache-lessons.ts

@@ -0,0 +1,58 @@
+/**
+ * SubagentStop (matcher "sniper") for the ai-pilot scope: capture error
+ * patterns + corrected code from the sniper transcript as lessons. Ports
+ * `cache-sniper-lessons.ts`, including the high-frequency promotion to the
+ * global stack cache (`promoteGlobalLessons`). Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonFile } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { cacheDirFor, projectHash } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { transcriptEdits, transcriptReport, projectRootFromPaths } from "./transcript";
+import { categorizeEdit } from "./lessons";
+import { detectStack } from "./source-scan";
+import { promoteGlobalLessons } from "./promote-global-lessons";
+import type { LessonEntry } from "./types";
+
+/**
+ * SubagentStop sniper: extract lessons from the transcript and persist them.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function cacheSniperLessons(transcript: string | undefined, cwd: string, home: string = homedir()): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const edits = await transcriptEdits(transcript);
+  if (edits.length === 0) return;
+
+  const editPaths = edits.map((e) => e.file);
+  const projectPath = projectRootFromPaths(editPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projectPath);
+  const cacheDir = cacheDirFor("lessons", projectPath, home);
+  mkdirSync(cacheDir, { recursive: true });
+
+  const report = await transcriptReport(transcript);
+  const timestamp = new Date().toISOString();
+  const errors: LessonEntry[] = edits.map((edit) => {
+    const basename = edit.file.split("/").pop() ?? edit.file;
+    const descLine = report.split("\n").find((l) => l.toLowerCase().includes(basename.toLowerCase()));
+    const errorType = categorizeEdit(edit);
+    return {
+      error_type: errorType,
+      pattern: descLine ?? `Code correction in ${basename}`,
+      fix: `Fix ${errorType} in ${basename}`,
+      count: 1,
+      last_seen: timestamp,
+      files: [edit.file],
+      code: { line: (edit.newStr ?? "").split("\n").filter(Boolean).slice(0, 10) },
+    };
+  });
+
+  const safeName = timestamp.replace(/:/g, "-");
+  await writeJsonFile(join(cacheDir, `${safeName}.json`), { project: projectPath, timestamp, errors }, true);
+  await promoteGlobalLessons(cacheDir, detectStack(projectPath), pHash, home);
+  logCacheEvent("lessons", "hit", pHash, { count: edits.length }, home);
+}

package/src/runtime/lifecycle/aipilot/cache-test.ts

@@ -0,0 +1,70 @@
+/**
+ * SubagentStop (matcher "sniper") for the ai-pilot scope: extract linter
+ * results from the transcript and cache per-file checksums. Ports
+ * `cache-test-results.ts`. Pure side-effect.
+ */
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonFile, writeJsonFile } from "../../../util/json-io";
+import { readText, pathExists } from "../../../util/runtime-io";
+import { cacheDirFor, projectHash, fileChecksum } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { transcriptFilePaths, projectRootFromPaths } from "./transcript";
+import { scanSourceFiles } from "./source-scan";
+import type { TestCache, TestResult } from "./types";
+
+/** Extract linter-related command/output text from a JSONL transcript. */
+async function extractLinterOutput(path: string): Promise<string> {
+  const text = readText(path);
+  const outputs: string[] = [];
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const content = (JSON.parse(line) as { message?: { content?: unknown } })?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block.type === "tool_use" && block.name === "Bash") {
+          const cmd = block.input?.command ?? "";
+          if (/eslint|tsc|biome|npx.*lint/i.test(cmd)) outputs.push(cmd);
+        }
+        if (block.type === "tool_result" || block.type === "text") outputs.push(block.text ?? block.content ?? "");
+      }
+    } catch { /* skip malformed */ }
+  }
+  return outputs.join("\n");
+}
+
+/**
+ * SubagentStop sniper: cache linter results per-file with checksums.
+ * @param transcript - Path to the agent JSONL transcript.
+ * @param cwd - Fallback project root.
+ * @param home - Home dir (defaults to `~`).
+ */
+export async function cacheTestResults(transcript: string | undefined, cwd: string, home: string = homedir()): Promise<void> {
+  if (!transcript || !pathExists(transcript)) return;
+  const allPaths = await transcriptFilePaths(transcript);
+  const projectPath = projectRootFromPaths(allPaths) ?? process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const pHash = projectHash(projectPath);
+  const cacheDir = cacheDirFor("tests", projectPath, home);
+  mkdirSync(cacheDir, { recursive: true });
+  const resultsPath = join(cacheDir, "results.json");
+
+  const linterOutput = await extractLinterOutput(transcript);
+  if (!linterOutput) return;
+  const srcFiles = await scanSourceFiles(projectPath);
+  if (srcFiles.length === 0) return;
+
+  const existing = (await readJsonFile<TestCache>(resultsPath)) ?? { timestamp: "", files: {} };
+  const timestamp = new Date().toISOString();
+  const newFiles: Record<string, TestResult> = {};
+  for (const filepath of srcFiles) {
+    const relPath = filepath.replace(`${projectPath}/`, "");
+    const checksum = (await fileChecksum(filepath)).slice(0, 16);
+    if (!checksum) continue;
+    const basename = filepath.split("/").pop() ?? "";
+    const hasError = linterOutput.includes(basename) && linterOutput.includes("error");
+    newFiles[relPath] = { checksum, eslint: hasError ? "fail" : "pass", tsc: "pass", last_tested: timestamp };
+  }
+  await writeJsonFile(resultsPath, { timestamp, files: { ...existing.files, ...newFiles } }, true);
+  logCacheEvent("tests", "hit", pHash, { count: Object.keys(newFiles).length }, home);
+}

package/src/runtime/lifecycle/aipilot/curate-lessons.ts

@@ -0,0 +1,64 @@
+/**
+ * Stage-0 mechanical, LLM-free dedup of MEMORY/LESSON.md bullets + cap→archive
+ * orchestration. Strict-dedup near-identical bullets (keep newest, `[TRIGGERS …]`
+ * preserved), then hand the deduped set to lesson-archive's cap split. Returns the
+ * rewritten LESSON.md content, the archive block to move out, and a human report.
+ * Pure: all file I/O (archive-first, fail-safe) lives in the dispatch caller.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { CAP, DAY_MS, STALE_DAYS, TRIG, type Block, citedPaths, jaccard, parse } from "./lesson-parse";
+import { formatArchive, splitAtCap } from "./lesson-archive";
+
+const SIM_THRESHOLD = 0.8;
+const MIN_TOKENS = 4;
+
+/** Report lines for bullets older than STALE_DAYS whose only cited path is gone. */
+function staleReport(blocks: Block[], now: number, root: string): string[] {
+  const cutoff = now - STALE_DAYS * DAY_MS;
+  return blocks.flatMap((b) => {
+    if (!(b.ts <= cutoff)) return [];
+    const paths = citedPaths(b.raw.join(" "));
+    if (paths.length === 0 || paths.some((p) => existsSync(join(root, p)))) return [];
+    return [`[STALE?] ${(b.raw[0] ?? "").slice(0, 90)} — missing path(s): ${paths.join(", ")}`];
+  });
+}
+
+/** Strict-dedup: keep the newest of each near-identical pair (TRIGGERS carried over). Returns kept blocks + merge report lines. */
+function dedup(blocks: Block[]): { kept: Block[]; fused: string[] } {
+  const kept: Block[] = [];
+  const fused: string[] = [];
+  for (const b of blocks) {
+    const hit = b.tokens.size >= MIN_TOKENS ? kept.find((k) => k.tokens.size >= MIN_TOKENS && jaccard(k.tokens, b.tokens) >= SIM_THRESHOLD) : undefined;
+    if (!hit) { kept.push(b); continue; }
+    const [win, drop] = (b.ts > hit.ts || Number.isNaN(hit.ts)) ? [b, hit] : [hit, b];
+    if (win !== hit) kept[kept.indexOf(hit)] = win;
+    if (!win.raw.some((l) => TRIG.test(l.trim()))) { const t = drop.raw.find((l) => TRIG.test(l.trim())); if (t) win.raw.push(t); }
+    fused.push(`merged: kept ${(win.raw[0] ?? "").slice(0, 60)} · dropped ${(drop.raw[0] ?? "").slice(0, 60)}`);
+  }
+  return { kept, fused };
+}
+
+/** Result of a curation pass: rewritten LESSON.md, the block to archive out, a report. */
+export interface CurateResult { content: string; archive: string; report: string; }
+
+/**
+ * Dedup LESSON.md bullets, then archive the oldest excess over CAP (via
+ * lesson-archive). `content` is byte-identical to the input when nothing is
+ * deduped or archived. The `archive` block (possibly "") is what the caller must
+ * PREPEND to LESSON-archive.md, archive-first, before writing `content`.
+ * @param content - Raw LESSON.md text.
+ * @param now - Clock (ms) for stale/archival windows.
+ * @param root - Project root, for resolving cited paths in the stale report.
+ * @returns The rewritten content, the archive block, and the report.
+ */
+export function curateLessons(content: string, now: number, root: string = process.cwd()): CurateResult {
+  const { preamble, blocks } = parse(content);
+  const { kept, fused } = dedup(blocks);
+  const { keep, archive } = splitAtCap(kept, now);
+  const changed = fused.length > 0 || archive.length > 0;
+  const rebuilt = changed ? `${preamble}\n${keep.map((b) => b.raw.join("\n")).join("\n\n")}\n` : content;
+  const capReport = archive.length ? [`${kept.length} bullets (> ${CAP}) — ${archive.length} oldest archived → LESSON-archive.md`] : [];
+  const report = [...fused, ...capReport, ...staleReport(blocks, now, root)].join("\n");
+  return { content: rebuilt, archive: formatArchive(archive, now), report };
+}

package/src/runtime/lifecycle/aipilot/dispatch-aipilot.ts

@@ -0,0 +1,100 @@
+/**
+ * ai-pilot scope dispatcher: routes Claude lifecycle events to the ported
+ * cache/injection handlers by (event, agent_type matcher).
+ */
+import { homedir } from "node:os";
+import { injectApexSubagentContext } from "./inject-apex";
+import { injectExploreCache } from "./inject-explore";
+import { injectDocCache } from "./inject-doc";
+import { injectLessonsCache } from "./inject-lessons";
+import { injectTestCache } from "./inject-test";
+import { cacheDocFromTranscript } from "./cache-doc";
+import { cacheSniperLessons } from "./cache-lessons";
+import { cacheTestResults } from "./cache-test";
+import { cacheAnalyticsSave } from "./analytics";
+import { syncTaskTracking } from "./sync-task";
+import { docCacheGate } from "./doc-cache-gate";
+import { checkSolidCompliance } from "./solid-compliance";
+import { checkSolidFromTranscript } from "./solid-transcript";
+import { contextResponse } from "../../../adapters/claude";
+
+/** The agent_type a SubagentStart/Stop payload reports. */
+function agentTypeOf(payload: Record<string, unknown>): string {
+  return String(payload.agent_type ?? payload.subagent_type ?? "");
+}
+
+/** Extract the `additionalContext` text from a SubagentStart response, or "". */
+function contextTextOf(response: string): string {
+  if (!response) return "";
+  try {
+    const parsed = JSON.parse(response) as { hookSpecificOutput?: { additionalContext?: string } };
+    return parsed.hookSpecificOutput?.additionalContext ?? "";
+  } catch { return ""; }
+}
+
+/**
+ * Combine N SubagentStart responses into one (Claude concatenates every hook's
+ * additionalContext; this single dispatch call must do that join itself). "" when all empty.
+ */
+function combineContext(...responses: string[]): string {
+  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). */
+function transcriptOf(payload: Record<string, unknown>): string | undefined {
+  const t = payload.agent_transcript_path;
+  return typeof t === "string" ? t : undefined;
+}
+
+/** Type-specific SubagentStart cache for an agent, or "" when none applies. */
+async function typeSpecificCache(agent: string, cwd: string, now: number, home: string): Promise<string> {
+  if (agent.includes("explore-codebase")) return injectExploreCache(cwd, home, now);
+  if (agent.includes("research-expert")) return injectDocCache(cwd, home, now);
+  if (agent.includes("sniper")) return injectTestCache(cwd, home, now);
+  return "";
+}
+
+/**
+ * SubagentStart routing (parity with the Python ai-pilot hooks): the two matcher-""
+ * entries (APEX context + lessons) fire for EVERY sub-agent, then the type-specific
+ * cache is concatenated on top — sniper too, hence no early return.
+ */
+async function onSubagentStart(payload: Record<string, unknown>, cwd: string, now: number, home: string, id: string): Promise<string> {
+  const agent = agentTypeOf(payload);
+  const apex = await injectApexSubagentContext(cwd, home, id);
+  const lessons = await injectLessonsCache(cwd, home, now);
+  const typeSpecific = await typeSpecificCache(agent, cwd, now, home);
+  return combineContext(apex, lessons, typeSpecific);
+}
+
+/** SubagentStop routing: transcript-driven cache writers, then the universal SOLID check. `id` selects the harness target (defaults to "claude-code"), threaded into `cacheDocFromTranscript`. */
+async function onSubagentStop(payload: Record<string, unknown>, cwd: string, home: string, id: string): Promise<string> {
+  const agent = agentTypeOf(payload);
+  const transcript = transcriptOf(payload);
+  if (agent.includes("research-expert")) await cacheDocFromTranscript(transcript, cwd, home, id);
+  if (agent.includes("sniper")) {
+    await cacheSniperLessons(transcript, cwd, home);
+    await cacheTestResults(transcript, cwd, home);
+  }
+  return checkSolidFromTranscript(transcript, cwd);
+}
+
+/**
+ * Dispatch an ai-pilot-scope lifecycle event. Returns the native stdout, or
+ * `null` when unhandled (caller falls through to the default pipeline).
+ * @param home - Home dir for cache resolution (defaults to `~`; injectable for test isolation); `id` selects the harness target (defaults to "claude-code").
+ */
+export async function dispatchAipilot(event: string, payload: Record<string, unknown>, cwd: string, now: number, home: string = homedir(), id: string = "claude-code"): Promise<string | null> {
+  if (event === "SubagentStart") return onSubagentStart(payload, cwd, now, home, id);
+  if (event === "SubagentStop") return onSubagentStop(payload, cwd, home, id);
+  // Stop too: Codex emits no SessionEnd, so its ai-pilot hooks.json wires Stop here as the sole analytics-flush trigger — reusing the SessionEnd handler verbatim (codex-plugins/docs/reference/hooks.md).
+  if (event === "SessionEnd" || event === "Stop") { await cacheAnalyticsSave(home, now); return ""; }
+  if (event === "PreToolUse") return docCacheGate(payload, cwd, now, home, id);
+  return null;
+}
+
+/** PostToolUse (Write/Edit SOLID check, else TaskCreate/TaskUpdate sync) for the ai-pilot scope; `id` selects the harness target (defaults to "claude-code"). */
+export async function aipilotPostToolUse(payload: Record<string, unknown>, cwd: string, id: string = "claude-code"): Promise<string> {
+  return checkSolidCompliance(payload) || (await syncTaskTracking(payload, cwd, id));
+}

package/src/runtime/lifecycle/aipilot/doc-cache-gate.ts

@@ -0,0 +1,69 @@
+/**
+ * @module aipilot/doc-cache-gate
+ * PreToolUse gate for the ai-pilot scope: DENY a Context7/Exa doc call when the
+ * per-project doc cache already holds that library fresh (< 7d). Ports the
+ * source `doc-cache-gate.ts`. The inject side (`inject-doc.ts`) serves the same
+ * cache on SubagentStart; this side avoids the redundant live re-query.
+ * @packageDocumentation
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJsonFile } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { denyResponse } from "../../../adapters/claude";
+import { cacheDirFor, cacheAge, projectHash, DOC_CACHE_TTL_SECONDS } from "./cache-base";
+import { logCacheEvent } from "./analytics";
+import { canonicalizeMcpToolName } from "../../mcp-tool-name";
+import type { CacheIndex } from "./types";
+
+const GATED_TOOLS = /context7__query-docs|exa__get_code_context|exa__web_search/;
+
+/** The library key a gated tool call targets (Context7 libraryId / Exa query), or "". */
+function libraryOf(payload: Record<string, unknown>): string {
+  const tool = String(payload.tool_name ?? "");
+  const input = (payload.tool_input as Record<string, unknown> | undefined) ?? {};
+  if (tool.includes("context7")) {
+    // Real mcp__context7__query-docs input is {libraryId, query} — no "topic"
+    // field exists (confirmed against cache-doc.ts and mcp-key.ts's queryOf,
+    // which both key on `query`, never `topic`).
+    const libraryId = typeof input.libraryId === "string" ? input.libraryId : "";
+    const query = typeof input.query === "string" ? input.query : "";
+    return libraryId && query ? libraryId : "";
+  }
+  if (tool.includes("exa")) return typeof input.query === "string" ? input.query : "";
+  return "";
+}
+
+/**
+ * DENY a redundant doc call when the library is cached fresh, else `null`.
+ * @param payload - The raw PreToolUse hook payload.
+ * @param cwd - Fallback project root (uses `CLAUDE_PROJECT_DIR` first).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param home - Home dir (defaults to `~`).
+ * @param id - Harness adapter id (defaults to "claude-code"); on `"codex"`,
+ *   `payload.tool_name` is canonicalized before the {@link GATED_TOOLS} match
+ *   so the Codex-mangled underscore form (`mcp__context7__query_docs`) gates
+ *   exactly like the dash form does on every other harness.
+ * @returns A native deny response, or `null` to fall through to the live call.
+ */
+export async function docCacheGate(payload: Record<string, unknown>, cwd: string, now: number = Date.now(), home: string = homedir(), id: string = "claude-code"): Promise<string | null> {
+  const tool = canonicalizeMcpToolName(id, String(payload.tool_name ?? ""));
+  if (!GATED_TOOLS.test(tool)) return null;
+  const library = libraryOf(payload);
+  if (!library) return null;
+
+  const projPath = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const cacheDir = cacheDirFor("doc", projPath, home);
+  const index = await readJsonFile<CacheIndex>(join(cacheDir, "index.json"));
+  const entry = index?.docs?.find((d) => d.library === library);
+  if (!entry?.hash || !entry.timestamp) return null;
+
+  const docFile = join(cacheDir, "docs", `${entry.hash}.md`);
+  if (!pathExists(docFile)) return null;
+  const age = cacheAge(entry.timestamp, now);
+  if (age >= DOC_CACHE_TTL_SECONDS) return null;
+
+  logCacheEvent("doc", "blocked", projectHash(projPath), { library }, home);
+  const ageH = Math.floor(age / 3600);
+  return denyResponse("PreToolUse", `Doc already cached at ${docFile} (age: ${ageH}h). Use the Read tool to access it instead of re-querying.`);
+}

package/src/runtime/lifecycle/aipilot/inject-apex.ts

@@ -0,0 +1,98 @@
+/**
+ * SubagentStart (matcher "") for the ai-pilot scope: inject APEX AGENTS.md +
+ * task context + cartographer paths into every sub-agent. Ports
+ * `inject-subagent-context.ts`. The core-scope SubagentStart already surfaces
+ * the MCP cache table (`subagent-cache.ts`) in a separate hook entry — this
+ * handler only emits the APEX/cartographer block, so there is no double-emit.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { readJsonFile } from "../../../util/json-io";
+import { readText } from "../../../util/runtime-io";
+import { resolveMaxLines } from "../../../config/limits";
+import { contextResponse } from "../../../adapters/claude";
+import { capFragment } from "../../inject-budget";
+import { harnessHomeSegment } from "../../../policy/apex-target";
+import { apexAgentSteps } from "../../../policy/apex-target-steps";
+import type { ApexTaskFile } from "./types";
+
+type TaskMap = ApexTaskFile["tasks"];
+
+/** Last 3 completed task subjects (newest first), or "none". */
+function completedTasks(tasks: TaskMap): string {
+  const done = Object.entries(tasks)
+    .filter(([, t]) => t.status === "completed")
+    .sort((a, b) => (b[1].completed_at ?? "").localeCompare(a[1].completed_at ?? ""))
+    .slice(0, 3)
+    .map(([id, t]) => `#${id}: ${t.subject}`);
+  return done.length > 0 ? done.join(", ") : "none";
+}
+
+/** Pending task subjects, or "none". */
+function pendingTasks(tasks: TaskMap): string {
+  const pending = Object.entries(tasks)
+    .filter(([, t]) => t.status === "pending")
+    .map(([id, t]) => `#${id}: ${t.subject}`);
+  return pending.length > 0 ? pending.join(", ") : "none";
+}
+
+/** Cartographer navigation block, or "" when no plugin map is present. */
+function cartographerContext(): string {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!pluginRoot) return "";
+  const pluginsMap = resolve(pluginRoot, "..", ".cartographer", "index.md");
+  if (!existsSync(pluginsMap)) return "";
+  return `\n### 7. Cartographer Maps\nNavigate branches (index.md) -> leaves link to real files:\n- Plugin skills: ${pluginsMap}\n- Project files: .cartographer/project/index.md`;
+}
+
+/**
+ * Build the APEX sub-agent injection for SubagentStart, or "" when the project has no target apex dir (`.claude/apex/`, `.codex/apex/`, ...). Reads AGENTS.md (first 4KB) + task.json.
+ * @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
+ * @param home - Home dir (unused placeholder; kept for symmetry/testing).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export async function injectApexSubagentContext(cwd: string, home: string = homedir(), id: string = "claude-code"): Promise<string> {
+  void home;
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? cwd;
+  const seg = harnessHomeSegment(id);
+  const apexDir = join(projectRoot, seg, "apex");
+  if (!existsSync(apexDir)) return "";
+
+  const agentsPath = join(apexDir, "AGENTS.md");
+  const agents = existsSync(agentsPath) ? readText(agentsPath).slice(0, 4000) : "";
+  const taskData = await readJsonFile<ApexTaskFile>(join(apexDir, "task.json"));
+  const completed = taskData ? completedTasks(taskData.tasks) : "none";
+  const pending = taskData ? pendingTasks(taskData.tasks) : "none";
+  const { beforeStart, whenDone } = apexAgentSteps(id);
+
+  const context = `## APEX Sub-Agent Instructions
+
+You are a sub-agent in APEX workflow. Follow these rules:
+
+### 1. AGENTS.md Rules
+${agents}
+
+### 2. Task Context
+- Last completed: ${completed}
+- Pending: ${pending}
+
+### 3. Before Starting Work
+- ${beforeStart}
+
+### 4. SOLID Rules
+- Files < ${resolveMaxLines()} lines | Interfaces in src/interfaces/ | JSDoc/PHPDoc required
+
+### 5. Research Before Code
+- Use Context7/Exa for docs | Write notes to ${seg}/apex/docs/
+
+### 6. Before Done (NEVER skip)
+- eLicit: self-review with a NAMED elicitation technique; fix findings first
+- Verify: run/functional-check your changes (references⇔declarations)
+
+### 7. When Done
+- ${whenDone}${cartographerContext()}`;
+
+  return contextResponse("SubagentStart", capFragment("apex-subagent", context));
+}