@fusengine/harness 0.1.89 → 0.1.91

package/src/runtime/inject-budget-recap.ts

@@ -0,0 +1,47 @@
+/**
+ * @module inject-budget-recap
+ * ONE event-level recap of every {@link module:inject-budget.capFragment}
+ * -tracked fragment injected for a SessionStart/SubagentStart event — the
+ * aggregated view the per-fragment caps never gave: each injection point
+ * (dev-context, snapshot sections, lessons, apex-subagent, ...) caps and
+ * reports itself in ISOLATION, with no total across the whole event.
+ *
+ * Rides the user-visible `systemMessage` channel, Claude-Code-only (gate at
+ * the call site — mirrors the existing `id === "claude-code"` pattern for
+ * `designLifecycle` in handle.ts): other adapters do not all re-export
+ * `attachSystemMessage`, and stamping a Claude-shaped envelope onto another
+ * harness's stdout shape would be silently wrong there.
+ *
+ * Deduped via {@link module:inject-dedup.onceExclusive}, not the JSON
+ * `oncePerWindow`: SessionStart/SubagentStart fan out across every installed
+ * plugin exactly like PostToolUse does (see burst-window.ts) — a shared-JSON
+ * read-modify-write here would risk the same lost-update race already fixed
+ * for the sniper reminder (lesson 2026-07-05 16:00).
+ * @packageDocumentation
+ */
+import { attachSystemMessage } from "../adapters/claude";
+import { budgetReport } from "./inject-budget";
+import { fragmentRegistry } from "./fragment-registry";
+import { onceExclusive } from "./inject-dedup";
+import { BURST_DEDUP_MS } from "./burst-window";
+import { defaultStateDir } from "./paths";
+
+/**
+ * Attach the aggregated recap onto `stdout` when 2+ fragments were recorded
+ * for `rawEvent`. A lone fragment already carries its own visibility (its
+ * producer's own per-fragment report, when it has one) — no recap is added
+ * for that case, so the common single-fragment event stays noise-free.
+ * @param stdout - The already-rendered hook stdout for this event.
+ * @param rawEvent - The raw hook event name (only SessionStart/SubagentStart qualify; others pass through unchanged).
+ * @param sessionId - Current session id (dedup scope).
+ * @param cwd - Project root (state-dir scope for the dedup marker).
+ * @param now - Clock.
+ * @returns `stdout` with a `systemMessage` recap attached, or `stdout` unchanged.
+ */
+export function attachBudgetRecap(stdout: string, rawEvent: string, sessionId: string, cwd: string, now: number): string {
+  if (rawEvent !== "SessionStart" && rawEvent !== "SubagentStart") return stdout;
+  const fragments = fragmentRegistry();
+  if (fragments.length <= 1) return stdout;
+  if (!onceExclusive(`budget:${sessionId}:${rawEvent}`, BURST_DEDUP_MS, { now, dir: defaultStateDir(cwd) })) return stdout;
+  return attachSystemMessage(stdout, budgetReport(fragments));
+}

package/src/runtime/inject-budget.ts

@@ -0,0 +1,81 @@
+/**
+ * @module inject-budget
+ * Hard per-fragment ceiling for harness-PRODUCED context injections (lessons,
+ * snapshot sections, APEX task context, cartographer/dev-context blocks) —
+ * inspired by Codex's "ContextualUserFragment, no item > 10K tokens" pattern.
+ * NEVER apply this to owner-authored content (CLAUDE.md/rules): that path is
+ * a locked invariant (see the "owner invariant" tests in
+ * test/dedup-inject.test.ts) and must always ship uncapped and in full.
+ *
+ * A real regression motivated this: MEMORY/LESSON.md's SessionStart injection
+ * had grown to ~44k tokens with no per-fragment or total alarm, silently
+ * bloating every SessionStart/SubagentStart turn.
+ * @packageDocumentation
+ */
+import { recordFragment } from "./fragment-registry";
+
+/**
+ * Hard cap per fragment, in characters. ~8000 chars ≈ 2000 tokens at the
+ * conservative ~4 chars/token ratio for mixed FR/EN prose — the accepted
+ * approximation absent a real tokenizer (cf. LangChain's `trim_messages`
+ * fallback token_counter). Chosen because a SINGLE SessionStart already
+ * stacks several harness fragments (lessons, snapshot, dev-context,
+ * cartographer) on top of the uncapped CLAUDE.md block, and the known 11x
+ * multi-plugin hook fan-out can multiply whatever ships — 2k tokens/fragment
+ * keeps the harness-produced share bounded even under that fan-out, while
+ * still leaving room for a few dozen useful lines of content.
+ */
+export const FRAGMENT_CHAR_CAP = 8000;
+
+/**
+ * Cap `text` at {@link FRAGMENT_CHAR_CAP} characters, cutting at the last
+ * newline within budget so no line is chopped mid-sentence. Text at or under
+ * the cap is returned byte-identical (no-op). Over the cap, a single English
+ * truncation line is appended so the reader knows content was dropped and
+ * that the SOURCE FILE itself is untouched (only this injected view is cut).
+ * @param label - Short identifier of the fragment (e.g. "lessons", "Git").
+ * @param text - The candidate fragment body.
+ * @returns `text` unchanged, or a truncated copy ending in the cut notice — always ≤ the cap.
+ */
+export function capFragment(label: string, text: string): string {
+  if (text.length <= FRAGMENT_CHAR_CAP) {
+    recordFragment(label, text.length);
+    return text;
+  }
+  const totalLen = text.length;
+  // Bound the label so a pathological (very long) label can never, by itself,
+  // push the suffix — and thus the output — past the cap. Real labels are short
+  // internal constants, so this is byte-identical for every actual caller.
+  const safeLabel = label.length <= 80 ? label : `${label.slice(0, 77)}...`;
+  const suffixFor = (keptLen: number): string =>
+    `\n[truncated ${safeLabel}: kept ${keptLen} of ${totalLen} chars — source file unchanged]`;
+  // Reserve worst-case suffix size using totalLen's digit count: kept length
+  // can only be <= totalLen, so its digit count never exceeds this reserve.
+  const reserve = suffixFor(totalLen).length;
+  const budget = Math.max(0, FRAGMENT_CHAR_CAP - reserve);
+  const slice = text.slice(0, budget);
+  const lastNl = slice.lastIndexOf("\n");
+  const kept = (lastNl > 0 ? slice.slice(0, lastNl) : slice).trimEnd();
+  const result = kept + suffixFor(kept.length);
+  recordFragment(label, result.length);
+  return result;
+}
+
+/** One named fragment's injected size, for {@link budgetReport}. */
+export interface FragmentSize {
+  label: string;
+  chars: number;
+}
+
+/**
+ * One-line numeric recap of what a batch of fragments actually injected —
+ * the owner-requested visibility so a silent blowup (like the 44k-token
+ * lessons block) shows up as a number instead of going unnoticed.
+ * @param fragments - The injected fragments (post-cap sizes).
+ * @returns e.g. `"injected 5 fragments, 14.2k chars"`, or `"injected 0 fragments"` when empty.
+ */
+export function budgetReport(fragments: FragmentSize[]): string {
+  if (fragments.length === 0) return "injected 0 fragments";
+  const total = fragments.reduce((sum, f) => sum + f.chars, 0);
+  return `injected ${fragments.length} fragments, ${(total / 1000).toFixed(1)}k chars`;
+}

package/src/runtime/inject-context.ts

@@ -0,0 +1,85 @@
+import { attachSystemMessage, contextResponse } from "../adapters/claude";
+import { renderInform } from "./inform";
+import { buildClaudeMdContext } from "../policy/claude-md-context";
+import { buildApexTaskInjection } from "../policy/apex-task-context";
+import { apexDocName } from "../policy/apex-target";
+import { hashText } from "../util/json-io";
+import { oncePerWindow, DEDUP_WINDOW_MS } from "./inject-dedup";
+import { capFragment } from "./inject-budget";
+
+/**
+ * Build the {@link oncePerWindow} key for the CLAUDE.md preamble gate. The
+ * prompt hash keeps two distinct legitimate turns from colliding — even non-dev
+ * prompts, whose block is prompt-independent (just CLAUDE.md) and would
+ * otherwise hash-collide within the window — while the content hash still lets a
+ * same-turn double-fire of an identical block be suppressed. Single source of
+ * truth so the owner invariant test guards the real production key.
+ * @param prompt - The raw user prompt.
+ * @param ctx - The rendered CLAUDE.md (+ optional APEX) block.
+ * @returns The namespaced dedup key.
+ */
+export function claudeMdKey(prompt: string, ctx: string): string {
+  return `claude-md:${hashText(prompt)}:${hashText(ctx)}`;
+}
+
+/**
+ * Extract the APEX preamble portion of a `buildClaudeMdContext` result, i.e.
+ * everything BEFORE the `# <docName>\n` root-doc block it prepends on dev
+ * prompts. Returns "" when `ctx` has no preamble (plain prompt: `ctx` starts
+ * directly with the root-doc heading).
+ * @param ctx - The full `buildClaudeMdContext` return value.
+ * @param docName - Root doc file name (e.g. "AGENTS.md").
+ * @returns The preamble text, or "" when absent.
+ */
+function extractApexPreamble(ctx: string, docName: string): string {
+  const heading = `# ${docName}\n`;
+  if (ctx.startsWith(heading)) return "";
+  const sep = `\n\n${heading}`;
+  const idx = ctx.indexOf(sep);
+  return idx === -1 ? "" : ctx.slice(0, idx);
+}
+
+/**
+ * UserPromptSubmit context injection: render the CLAUDE.md (+ optional APEX)
+ * preamble as a Claude `additionalContext` response, or "" when nothing to emit.
+ * Guarded by {@link oncePerWindow} via {@link claudeMdKey}: only a
+ * near-simultaneous double-fire of the SAME turn (identical prompt AND identical
+ * block, within {@link DEDUP_WINDOW_MS}) is suppressed. The invariant "CLAUDE.md
+ * is emitted on EVERY message" is thus preserved.
+ *
+ * On kimi specifically, the root doc body is dropped from the emitted text:
+ * Kimi loads `<kimiHome>/AGENTS.md` natively at session start (`apex-target.ts`),
+ * so re-injecting its full body on every prompt is redundant terminal noise
+ * (kimi has no model-only hook channel — `runtime/inform.ts`). The APEX
+ * preamble, which is NOT part of `AGENTS.md`, is still emitted in full when the
+ * prompt is dev-shaped; a plain prompt leaves only the notice.
+ * @param prompt - The raw user prompt.
+ * @param cwd - Project root (for project-type detection).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function promptSubmitContext(prompt: string, cwd: string, id: string = "claude-code"): string {
+  const ctx = buildClaudeMdContext(prompt, cwd, id);
+  if (!ctx) return "";
+  if (!oncePerWindow(claudeMdKey(prompt, ctx), DEDUP_WINDOW_MS)) return "";
+  const notice = `${apexDocName(id)} injected`;
+  if (id === "kimi") {
+    const preamble = extractApexPreamble(ctx, apexDocName(id));
+    return preamble ? renderInform(id, "UserPromptSubmit", preamble, notice) : notice;
+  }
+  return renderInform(id, "UserPromptSubmit", ctx, notice);
+}
+
+/**
+ * PreToolUse Task context injection: render the APEX sub-agent context as a
+ * Claude `additionalContext` response when `.claude/apex/` exists, else "".
+ * Harness-produced (not owner CLAUDE.md content), so it is subject to the
+ * per-fragment {@link capFragment} budget — unlike {@link promptSubmitContext}.
+ * @param cwd - Fallback project root when `CLAUDE_PROJECT_DIR` is unset.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function taskContext(cwd: string, id: string = "claude-code"): string {
+  const ctx = buildApexTaskInjection(process.env.CLAUDE_PROJECT_DIR ?? cwd, id);
+  return ctx ? contextResponse("PreToolUse", capFragment("apex-task", ctx)) : "";
+}

package/src/runtime/inject-dedup-exclusive.ts

@@ -0,0 +1,98 @@
+/**
+ * @module inject-dedup-exclusive
+ * Cross-process-exact-once cooldown gate, via EXCLUSIVE file creation.
+ *
+ * {@link module:inject-dedup.oncePerWindow}'s shared-JSON read-modify-write is
+ * best-effort under true concurrency: the ~11-process plugin hook fan-out for
+ * one Claude event can lose an update and let 2-3 siblings all observe "not
+ * seen yet" (lesson 2026-07-05 16:00 — the `saveTrack` lost-update race, same
+ * shape). `writeFileSync(path, data, { flag: "wx" })` sidesteps this: the OS
+ * guarantees exclusive creation is atomic, so of N concurrent siblings calling
+ * this for the SAME key, exactly one observes success and the rest get
+ * `EEXIST` — never a double-win, with no lock file or retry loop needed.
+ *
+ * One marker file per key (not a shared map) is the tradeoff for that
+ * guarantee. A bounded sweep on every call deletes markers older than
+ * `windowMs` so the directory never grows unbounded under many distinct keys.
+ *
+ * Reserve this for HIGH-CONCURRENCY callers on a short burst window (same
+ * tool-use/lifecycle event fanned out to every installed plugin) — e.g. the
+ * sniper reminder ({@link module:lifecycle/track-changes}) and compliance
+ * notices ({@link module:notices}). Low-frequency, long-window callers (e.g.
+ * the 30-min lessons Stop-reminder cooldown) are fine on the JSON mode: a
+ * single real Stop event per session is not concurrent with itself the way
+ * one PostToolUse's ~11 sibling hooks are within the same 2s burst.
+ * @packageDocumentation
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { defaultStateDir } from "./paths";
+import type { OnceOpts } from "./inject-dedup";
+
+/** Subdirectory (under the state dir) holding one marker file per dedup key. */
+const EXCLUSIVE_SUBDIR = "inject-dedup-locks";
+
+/**
+ * Filesystem-safe, collision-resistant basename for `key`. Full MD5 hex
+ * (unlike {@link module:util/json-io.hashText}'s 8-char truncation) — a
+ * collision here would silently merge two unrelated keys' exclusivity.
+ */
+function lockFileName(key: string): string {
+  return `${createHash("md5").update(key).digest("hex")}.lock`;
+}
+
+/**
+ * Delete marker files older than `windowMs` in `dir` — O(n) per call, bounds
+ * directory growth. Compares against the creation timestamp STORED IN the
+ * marker's content (written by {@link onceExclusive} below), not the file's
+ * fs `mtime`: callers may pass a fake logical `now` (tests), which would never
+ * agree with the real OS clock backing `mtime`.
+ */
+function sweepExclusiveDir(dir: string, now: number, windowMs: number): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    try {
+      const createdAt = Number(readFileSync(path, "utf8"));
+      if (!Number.isFinite(createdAt) || now - createdAt >= windowMs) unlinkSync(path);
+    } catch {
+      /* a sibling process already swept/removed it, or a transient read race — ignore */
+    }
+  }
+}
+
+/**
+ * Cooldown gate via exclusive marker-file creation. Returns `true` exactly
+ * once per `key` within `windowMs` across ALL concurrent processes sharing
+ * `opts.dir` (the caller MAY emit), `false` for every other concurrent or
+ * subsequent call inside the same window (the caller SHOULD suppress).
+ *
+ * Fails open on any unwritable state dir or unexpected fs error: the emission
+ * is allowed rather than silently dropped.
+ * @param key - Stable identity of the block (same semantics as {@link module:inject-dedup.oncePerWindow}).
+ * @param windowMs - Suppression window in ms (also the sweep threshold).
+ * @param opts - Optional clock + state-dir overrides (for tests).
+ * @returns `true` to proceed/emit, `false` to suppress.
+ */
+export function onceExclusive(key: string, windowMs: number, opts: OnceOpts = {}): boolean {
+  const now = opts.now ?? Date.now();
+  const dir = join(opts.dir ?? defaultStateDir(), EXCLUSIVE_SUBDIR);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return true;
+  }
+  sweepExclusiveDir(dir, now, windowMs);
+  try {
+    writeFileSync(join(dir, lockFileName(key)), String(now), { flag: "wx" });
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code !== "EEXIST";
+  }
+}

package/src/runtime/inject-dedup.ts

@@ -0,0 +1,89 @@
+/**
+ * @module inject-dedup
+ * Generic "once per window" guard for hook context injection.
+ *
+ * Persists a tiny sidecar map `{ key -> lastEmittedEpochMs }` in the existing
+ * per-project state dir (`~/.fuse-harness/state/<projectHash>/inject-dedup.json`,
+ * the same dir as the session track — see {@link defaultStateDir}). Lets a caller
+ * suppress a block it has already emitted within a short window, defending
+ * against the "same content emitted by two near-simultaneous hooks" family
+ * (cf. the 0.1.48 SubagentStart double-inject). Also reused as a cooldown gate.
+ *
+ * Best-effort under true process-level concurrency (the read-modify-write is not
+ * locked); reliable for the sequential single-process callers that use it.
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { defaultStateDir } from "./paths";
+
+/** Default suppression window (ms): catches same-turn double-fire, not next-turn re-emits. */
+export const DEDUP_WINDOW_MS = 3000;
+
+/** Sidecar basename under the per-project state dir. */
+const SIDECAR = "inject-dedup.json";
+
+/** Optional overrides — tests inject a clock + a scratch dir; production omits both. */
+export interface OnceOpts {
+  /** Clock in epoch-ms (default `Date.now()`). */
+  now?: number;
+  /** State-dir override (default {@link defaultStateDir}). */
+  dir?: string;
+}
+
+/** Load the `{ key -> epochMs }` map, or `{}` when missing/corrupt. */
+function loadMap(path: string): Record<string, number> {
+  try {
+    if (!existsSync(path)) return {};
+    const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, number>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Keep only entries newer than `windowMs` before `now` (bounds sidecar size). */
+function prune(map: Record<string, number>, now: number, windowMs: number): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const [k, t] of Object.entries(map)) {
+    if (typeof t === "number" && now - t < windowMs) out[k] = t;
+  }
+  return out;
+}
+
+/**
+ * Cooldown gate. Returns `true` when `key` has NOT been recorded within the last
+ * `windowMs` (the caller MAY emit — and the emission is recorded now), or `false`
+ * when it was (the caller SHOULD suppress). The first call in a window wins;
+ * subsequent identical keys are throttled until the window elapses.
+ *
+ * Fails open: if the sidecar is unwritable, the emission is allowed rather than
+ * silently dropping context.
+ * @param key - Stable identity of the block (e.g. a content hash, or `lesson:<id>`).
+ * @param windowMs - Suppression window in ms.
+ * @param opts - Optional clock + state-dir overrides (for tests).
+ * @returns `true` to proceed/emit, `false` to suppress.
+ */
+export function oncePerWindow(key: string, windowMs: number, opts: OnceOpts = {}): boolean {
+  const now = opts.now ?? Date.now();
+  const path = join(opts.dir ?? defaultStateDir(), SIDECAR);
+  const map = prune(loadMap(path), now, windowMs);
+  const last = map[key];
+  if (typeof last === "number" && now - last < windowMs) return false;
+  map[key] = now;
+  try {
+    atomicWrite(path, JSON.stringify(map));
+  } catch {
+    /* sidecar unwritable → fail-open: allow the emission rather than lose context */
+  }
+  return true;
+}
+
+/**
+ * Cross-process-exact-once variant (exclusive file creation, not the shared
+ * JSON above) for high-concurrency callers — split out to
+ * {@link module:inject-dedup-exclusive} to keep this file under the SOLID
+ * line budget; re-exported here so both modes share one import surface.
+ */
+export { onceExclusive } from "./inject-dedup-exclusive";

package/src/runtime/is-agent-tool.ts

@@ -0,0 +1,19 @@
+/**
+ * Sub-agent dispatch tool detection — the single source of truth for "this
+ * tool call spawns a sub-agent". Claude Code and Codex dispatch via `Task`;
+ * Kimi Code CLI dispatches via `Agent` (and `AgentSwarm` for parallel fan-out).
+ * Centralized so the APEX task-context injection, the activity tracking and
+ * the PostToolUse evidence credit stop drifting on inline `"Task" | "Agent"`
+ * unions: every consumer imports from HERE, never re-declares the list.
+ */
+
+/** Canonical set of sub-agent dispatch tool names (the ONLY definition). */
+export const AGENT_TOOLS: ReadonlySet<string> = new Set(["Task", "Agent", "AgentSwarm"]);
+
+/**
+ * True when the tool is a sub-agent dispatch primitive on any harness.
+ * @param tool - The normalized tool name from the hook payload.
+ */
+export function isAgentTool(tool: string): boolean {
+  return AGENT_TOOLS.has(tool);
+}

package/src/runtime/lifecycle/agent-files.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-agent file attribution for SubagentStop. Uses the shared transcript parser
+ * ({@link readAgentToolUses}) to recover the exact set of files a sub-agent wrote
+ * via Write/Edit/MultiEdit/NotebookEdit, so the sniper reminder attributes only
+ * the files THIS agent touched instead of every file changed in the whole session
+ * (which cross-attributes other teammates' work — the bug this fixes).
+ */
+import { basename } from "node:path";
+import { readAgentToolUses } from "./agent-transcript";
+
+/** Tools whose `input.file_path`/`notebook_path` names a file the agent authored. */
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/**
+ * Return the distinct file paths written by the sub-agent whose own transcript is
+ * at `transcriptPath` (Write/Edit/MultiEdit/NotebookEdit). `null` when unreadable
+ * (caller MUST fall back to the session-wide list — no regression); a possibly-
+ * empty array when parsed (empty = authored nothing, so it should NOT be told to
+ * validate files other agents changed).
+ * @param transcriptPath - Absolute path to the sub-agent's own `.jsonl` transcript.
+ * @returns Distinct written paths (order-preserving), or `null` when unreadable.
+ */
+export function filesWrittenByAgent(transcriptPath: string | undefined): string[] | null {
+  const uses = readAgentToolUses(transcriptPath);
+  if (uses === null) return null;
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const u of uses) {
+    if (!WRITE_TOOLS.has(u.name)) continue;
+    const fp = u.input?.file_path ?? u.input?.notebook_path;
+    if (typeof fp === "string" && fp && !seen.has(fp)) { seen.add(fp); out.push(fp); }
+  }
+  return out;
+}
+
+/**
+ * Filter `sessionFiles` down to the ones this agent actually wrote. Matches the
+ * exact recorded string first, then tolerantly on `basename` so a relative-vs-
+ * absolute drift between the PostToolUse record and the transcript input never
+ * loses an owned file.
+ * @param sessionFiles - Session-wide modified files.
+ * @param written - Paths the agent wrote (from {@link filesWrittenByAgent}).
+ * @returns The subset of `sessionFiles` attributable to this agent.
+ */
+export function attributeFiles(sessionFiles: readonly string[], written: readonly string[]): string[] {
+  const exact = new Set(written);
+  const bases = new Set(written.map((f) => basename(f)));
+  return sessionFiles.filter((f) => exact.has(f) || bases.has(basename(f)));
+}

package/src/runtime/lifecycle/agent-memory.ts

@@ -0,0 +1,82 @@
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { contextResponse } from "../../adapters/claude";
+import { resolveTtlSec } from "../../config/ttl";
+import { loadSessionState, sanitizeSessionId, saveSessionState, sessionsDir } from "../home-state";
+import { defaultStateDir, trackFile } from "../paths";
+import { freshReceiptFromFile } from "../../tracking/receipts";
+import { attributeFiles, filesWrittenByAgent } from "./agent-files";
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes {
+  cumulativeCodeFiles?: number;
+  modifiedFiles?: string[];
+}
+
+/** `~/.claude/memory/agents` — agent completion history dir. */
+function memoryDir(home: string): string {
+  return join(home, ".claude", "memory", "agents");
+}
+
+const SKIP_AGENTS = /(sniper|sniper-faster|explore-codebase|research-expert|claude-code-guide|Explore|Plan)/;
+
+/** Append the agent completion record to `agent-history.jsonl` (best effort). */
+function recordHistory(home: string, agentId: string, agentType: string, ts: string): void {
+  const dir = memoryDir(home);
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "agent-history.jsonl"), JSON.stringify({ agentId, agentType, completedAt: ts }) + "\n", "utf-8");
+  } catch { /* best effort */ }
+}
+
+/**
+ * Handle SubagentStop: append the completion to agent-history.jsonl and, for a
+ * non-skipped agent that touched code, emit the sniper reminder + reset the
+ * counter. Ports `subagent-stop/track-agent-memory.py`.
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (always a JSON message).
+ */
+export function trackAgentMemory(data: Record<string, unknown>, home: string = homedir(), now: number = Date.now()): string {
+  mkdirSync(sessionsDir(home), { recursive: true });
+  const agentType = String(data.agent_type ?? data.subagent_type ?? "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 state = loadSessionState(sessionId, home);
+  const changes = state.changes as Changes | undefined;
+  const count = changes?.cumulativeCodeFiles ?? 0;
+  if (count > 0) {
+    // Attribute only the files THIS agent actually wrote, parsed from its own
+    // transcript (SubagentStop `agent_transcript_path`, CLI v2.0.42+). When the
+    // field is absent or the transcript is unreadable, `filesWrittenByAgent`
+    // returns null → fall back to the session-wide list (no regression).
+    const written = filesWrittenByAgent(typeof data.agent_transcript_path === "string" ? data.agent_transcript_path : undefined);
+    const owned = written === null ? (changes?.modifiedFiles ?? []) : attributeFiles(changes?.modifiedFiles ?? [], written);
+    // Only reset the session counter when this agent owns changes — so an agent
+    // that touched none of the tracked files never clears them for the real
+    // author, and never gets told to validate another teammate's work.
+    if (owned.length > 0) {
+      saveSessionState(sessionId, { ...state, changes: { ...changes, cumulativeCodeFiles: 0 } }, home);
+      // Never demand sniper on a file the agent deleted before stopping (e.g. a
+      // scratch probe rm -rf'd): the tracked list records writes, never removals,
+      // so re-check the disk (a relative path resolves against the hook cwd) and
+      // keep only files still present. All gone → nothing to validate → "no changes".
+      const hookCwd = typeof data.cwd === "string" ? data.cwd : process.cwd();
+      const present = owned.filter((f) => existsSync(resolve(hookCwd, f)));
+      if (present.length > 0) {
+        // Advisory (no hard block here — the TaskCompleted gate enforces): flag the
+        // missing proof when the agent owns code but posted no fresh passing receipt.
+        // Window = TTL×5, matching the TaskCompleted receipt gate.
+        const windowMs = resolveTtlSec(process.env) * 1000 * 5;
+        const noReceipt = freshReceiptFromFile(trackFile(sessionId, defaultStateDir(process.cwd())), windowMs, now) === null;
+        const note = noReceipt ? " NO VERIFICATION RECEIPT — run tsc + tests before reporting done." : "";
+        return contextResponse("SubagentStop", `SNIPER VALIDATION REQUIRED: Agent '${agentType}' modified ${present.length} code file(s): ${present.join(", ")}. Run sniper agent now.${note}`);
+      }
+    }
+  }
+  return JSON.stringify({ message: `Agent ${agentType} completed (no code changes)` });
+}

package/src/runtime/lifecycle/agent-transcript.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared low-level parser for a sub-agent's OWN transcript (`agent_transcript_path`
+ * — the clean JSONL the Claude Code platform writes per sub-agent, CLI v2.0.42+).
+ * Per LESSON.md this is the RELIABLE anchor for evidence: sidechain PostToolUse
+ * hooks are not guaranteed (issues #43612/#27655/#34692). One parser, reused by
+ * file-attribution (`agent-files.ts`) and retroactive evidence harvesting
+ * (`src/freshness/evidence-harvest.ts`) — no duplication.
+ */
+import { readText } from "../../util/runtime-io";
+
+/** A tool_use content block inside a transcript message. */
+interface ToolUseBlock {
+  type: string;
+  /** Tool name, e.g. "Write", "Edit", "WebSearch", "Grep". */
+  name?: string;
+  /** Raw tool input — shape varies per tool; narrowed at the call-site. */
+  input?: Record<string, unknown>;
+}
+
+/** One JSONL line of a Claude Code transcript. */
+interface TranscriptLine {
+  /** ISO-8601 or epoch-ms timestamp written by the platform (may be absent). */
+  timestamp?: string | number;
+  message?: { content?: unknown[] };
+}
+
+/** A parsed `tool_use`, carrying its message timestamp when the platform stamped one. */
+export interface TranscriptToolUse {
+  /** Tool name, e.g. "Write", "WebSearch", "Read". */
+  name: string;
+  /** Raw tool input payload (shape varies per tool). */
+  input: Record<string, unknown> | undefined;
+  /** Epoch-ms of the enclosing message, or `undefined` when unstamped. */
+  ts?: number;
+}
+
+/** Parse a raw `timestamp` field to epoch ms; `undefined` when absent or invalid. */
+function parseTs(raw: string | number | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw === "number") return raw;
+  const ms = Date.parse(raw);
+  return Number.isFinite(ms) ? ms : undefined;
+}
+
+/**
+ * Scan a sub-agent transcript into its ordered `tool_use` blocks (each with the
+ * enclosing message timestamp). Distinguishes "no tool use" from "cannot read":
+ * returns `null` when the path is absent or the transcript is unreadable (callers
+ * fail-open), or a possibly-empty array when parsed. Malformed lines/blocks are
+ * tolerated and skipped.
+ * @param transcriptPath - Absolute path to the sub-agent's own `.jsonl` transcript.
+ * @returns Ordered tool uses, or `null` when unreadable.
+ */
+export function readAgentToolUses(transcriptPath: string | undefined): TranscriptToolUse[] | null {
+  if (!transcriptPath) return null;
+  let text: string;
+  try {
+    text = readText(transcriptPath);
+  } catch {
+    return null; // fail-open: caller keeps its pre-harvest state
+  }
+  const out: TranscriptToolUse[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry: TranscriptLine;
+    try {
+      entry = JSON.parse(line) as TranscriptLine;
+    } catch {
+      continue; // tolerate malformed lines
+    }
+    const content = entry.message?.content;
+    if (!Array.isArray(content)) continue;
+    const ts = parseTs(entry.timestamp);
+    for (const block of content as ToolUseBlock[]) {
+      if (block?.type !== "tool_use" || !block.name) continue;
+      out.push({ name: block.name, input: block.input, ts });
+    }
+  }
+  return out;
+}