@leonardo-marziali/ad-lfl-kit 2.2.0 → 2.3.0

package/README.md

@@ -15,13 +15,18 @@ plugin can build the same loop without re-implementing it.
 
 ## The pattern
 
-1. A `PostToolUse` hook (matching `Edit`/`Write`) records every file the
-   current session touches that matches some predicate — only `.md` files,
-   say — into a session-scoped list.
-2. A `Stop`/`SubagentStop` hook reads that list, runs a check (optionally
-   preceded by an auto-fix pass), and:
+1. A tracking hook records every file the current session touches that
+   matches some predicate — only `.md` files, say — into a session-scoped
+   list. Edit-family tools name their file; for `Bash`, `PowerShell` and MCP
+   tools, which don't, the hook also runs on `PreToolUse` to snapshot the
+   workspace and tracks whatever changed by the time the call ends. Tool
+   calls made inside a subagent are tracked the same way, and additionally
+   into that subagent's own list.
+2. A `Stop`/`SubagentStop` hook reads that list — a `SubagentStop` reads only
+   its subagent's — runs a check (optionally preceded by an auto-fix pass),
+   and:
    - if it passes, cleans up the session state and lets the session end;
-   - if it fails, blocks the stop with `decision: "continue"` so Claude sees
+   - if it fails, blocks the stop with `decision: "block"` so Claude sees
      the failures and keeps working, up to a capped number of attempts;
    - at the cap, gives up — reporting what's left, optionally applying a
      caller-supplied fallback — rather than blocking forever.
@@ -40,9 +45,20 @@ npm install @leonardo-marziali/ad-lfl-kit
 ## Quick start
 
 Two hook scripts, wired up in the plugin's `hooks/hooks.json` the same way
-as [`plugins/markdown/hooks/hooks.json`](https://github.com/leonardo-marziali/agentic-development-kit/blob/main/plugins/markdown/hooks/hooks.json):
-a `PostToolUse` hook on `Edit|Write`, and `Stop`/`SubagentStop` hooks, both
-pointed at `${CLAUDE_PLUGIN_ROOT}`.
+as [`plugins/markdown/hooks/hooks.json`](https://github.com/leonardo-marziali/agentic-development-kit/blob/main/plugins/markdown/hooks/hooks.json),
+all pointed at `${CLAUDE_PLUGIN_ROOT}`:
+
+- `PreToolUse` and `PostToolUseFailure`, matching `Bash|PowerShell|mcp__.*`
+  → `track-touched.js`
+- `PostToolUse`, matching
+  `Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell|mcp__.*` →
+  `track-touched.js`
+- `Stop` and `SubagentStop` → `check-and-loop.js`
+
+`PostToolUseFailure` matters: a command that edits files and then exits
+non-zero (`./fix.py && pytest`) reports through it, not `PostToolUse`.
+Subagents need nothing extra — Claude Code fires plugin hooks for their tool
+calls too, with the parent's `session_id` and their own `agent_id`.
 
 **`scripts/hooks/track-touched.js`**
 
@@ -51,7 +67,7 @@ pointed at `${CLAUDE_PLUGIN_ROOT}`.
 'use strict';
 
 const path = require('node:path');
-const { readHookInput, stateDir, trackTouchedFile } = require('@leonardo-marziali/ad-lfl-kit');
+const { readHookInput, stateDir, trackSessionChanges } = require('@leonardo-marziali/ad-lfl-kit');
 
 const input = readHookInput();
 if (input) {
@@ -59,7 +75,7 @@ if (input) {
     sessionId: input.session_id,
     namespace: 'my-plugin-session-scope',
   });
-  trackTouchedFile({
+  trackSessionChanges({
     input,
     listFile: path.join(dir, 'touched-files.txt'),
     matches: (absPath) => /\.md$/i.test(absPath),
@@ -77,15 +93,20 @@ const path = require('node:path');
 const {
   readHookInput,
   stateDir,
+  loopStateDir,
   readTrackedFiles,
   runFixLoop,
   runBin,
 } = require('@leonardo-marziali/ad-lfl-kit');
 
 const input = readHookInput();
-const dir = stateDir({
-  sessionId: input?.session_id,
-  namespace: 'my-plugin-session-scope',
+// A SubagentStop gets its subagent's own directory; a Stop the session's.
+const dir = loopStateDir({
+  dir: stateDir({
+    sessionId: input?.session_id,
+    namespace: 'my-plugin-session-scope',
+  }),
+  input,
 });
 const stateFiles = ['touched-files.txt', 'attempts.json'];
 const files = readTrackedFiles(path.join(dir, 'touched-files.txt'));
@@ -182,6 +203,14 @@ excluded rather than drop it silently.
 - **`stateDir({ sessionId, namespace })`** — a directory scoped to one
   session and one namespace, under `${CLAUDE_PLUGIN_DATA}` when set (so it
   survives plugin updates) or the OS temp dir otherwise.
+- **`agentStateDir(dir, agentId)`** — one subagent's share of a session
+  directory, `<dir>/agents/<agentId>`. The tracking functions append a
+  subagent's files here as well as to the session's list.
+- **`loopStateDir({ dir, input })`** — the directory a `Stop`/`SubagentStop`
+  hook should run its loop in: `agentStateDir(dir, input.agent_id)` for a
+  `SubagentStop`, `dir` for anything else. A subagent is then held only to
+  the files it wrote, with its own attempt count, while the main `Stop`
+  still checks everything, subagents' files included.
 - **`readTrackedFiles(listFile)`** — the de-duplicated contents of a tracked
   file list, filtered to files that still exist on disk.
 - **`appendTrackedFile(listFile, absPath)`** — appends a path, skipping it
@@ -196,11 +225,49 @@ excluded rather than drop it silently.
 
 ### Tracking (`track.js`)
 
-- **`trackTouchedFile({ input, listFile, matches })`** — the `PostToolUse`
-  half. No-ops unless `input.tool_name` is `Edit` or `Write`, the tool's
-  `file_path` still exists on disk (resolved against `input.cwd`), and
-  `matches(absPath)` returns true (omit `matches` to track everything).
-  Returns the tracked absolute path, or `null`.
+- **`trackSessionChanges({ input, listFile, matches })`** — the tracking
+  half; wire it to `PreToolUse`, `PostToolUse` and `PostToolUseFailure`.
+  Tracks every file `toolChangedFiles` reports that `matches(absPath)`
+  accepts (omit `matches` to track everything), in `listFile` and — for a
+  subagent's call — in that subagent's list. Snapshots are kept beside
+  `listFile`. Returns the tracked paths.
+- **`toolChangedFiles({ input, stateDir })`** — the files one tool call
+  wrote, for hooks that act on them without tracking (a formatter). For
+  `Edit`, `Write`, `MultiEdit` and `NotebookEdit` that's the file the input
+  names, if it exists. For `Bash`, `PowerShell` and `mcp__*` tools,
+  `PreToolUse` writes a snapshot to `<stateDir>/pending/<tool_use_id>.json`
+  and the `Post*` event returns what changed since and consumes it, so only
+  one script per state dir should call this. Read-only tools return `[]`
+  without scanning anything.
+- **`trackTouchedFile({ input, listFile, matches })`** — the Edit-family
+  subset of `trackSessionChanges`: no-ops unless `input.tool_name` is
+  `Edit`, `Write`, `MultiEdit` or `NotebookEdit` and the file it names still
+  exists. Returns the tracked absolute path, or `null`.
+
+### Change detection (`changes.js`)
+
+How `toolChangedFiles` answers for tools that don't name their files.
+
+- **`snapshotWorkspace(cwd)`** — `{ startedAt, cwd, root, head }`: the time,
+  the cwd, and the git root and `HEAD` it sits in (both `null` outside a
+  repo).
+- **`filesChangedSince(snapshot, { cwd })`** — absolute paths written since
+  the snapshot. In a repo: the dirty and untracked files from `git status`,
+  plus the files of commits made during the call (so `edit && git commit`
+  isn't missed), keeping only those whose mtime falls after the snapshot.
+  Already-dirty files the call didn't touch are older than that, and a
+  `checkout` or `pull` leaves the tree clean and brings commits dated
+  before the call, so neither drags in unrelated files. Outside a repo: a
+  bounded walk of the cwd. Gitignored files and dependency directories
+  (`node_modules`, `.venv`, `__pycache__`…) are never reported. Unlike
+  `scope.js` this fails closed — an error means "nothing changed" — since
+  it decides which files a session becomes answerable for.
+- **`MTIME_SLACK_MS`** / **`PRUNED_DIR_NAMES`** — the mtime tolerance for
+  coarse filesystems, and the directories skipped.
+
+What it can't see: writes made after the call returns, such as by a
+`run_in_background` command, and writes outside both the snapshot's and
+the current cwd's repository.
 
 ### Execution (`exec.js`)
 
@@ -255,14 +322,20 @@ fix, check, onCap, buildMessage, write })`** — the `Stop`/`SubagentStop`
   given; `onCap({ files, outcome, maxAttempts })` is optional and runs
   once instead of blocking when the attempt cap is reached;
   `buildMessage({ attempt, maxAttempts, outcome, files })` returns
-  `{ stopReason?, systemMessage }` for the block payload. `maxAttempts`
+  `{ stopReason?, systemMessage }` for the block payload, which is printed
+  as `{ "decision": "block", "reason": systemMessage, "systemMessage":
+stopReason }`: `reason` is what Claude is told to fix (cut to
+  `MAX_REASON_CHARS`, since Claude Code would otherwise swap a longer one
+  for a short preview), `systemMessage` a notice shown only to the user. `maxAttempts`
   defaults to `DEFAULT_MAX_ATTEMPTS` (3). Returns
   `{ blocked, reason, ... }` so a caller or its tests can assert on which
   path was taken (`'no-input'`, `'no-files'`, `'clean'`, `'cap'`,
   `'blocked'`, or `'error'` if `fix`/`check` threw — in which case the
   session's state is left untouched so the next `Stop` retries, rather than
   either blocking on a broken toolchain or silently discarding progress).
-- **`DEFAULT_MAX_ATTEMPTS`** — `3`.
+- **`blockPayload({ stopReason, systemMessage })`** — that payload, for
+  hooks that block a stop outside `runFixLoop`.
+- **`DEFAULT_MAX_ATTEMPTS`** — `3`. **`MAX_REASON_CHARS`** — `9500`.
 
 ## Design notes
 
@@ -275,6 +348,10 @@ fix, check, onCap, buildMessage, write })`** — the `Stop`/`SubagentStop`
   the file names it's given; two hooks sharing a session's state directory
   (a tracking hook and, say, this repo's own test-verification hook) can't
   clobber each other.
+- **Block with top-level `decision: "block"`.** It is the only shape Claude
+  Code honours for `Stop`/`SubagentStop`. Versions of this kit before it
+  printed `hookSpecificOutput.decision: "continue"`, which Claude Code
+  ignores, so the stop went through and Claude never saw the report.
 - **A failing `check`/`fix` is not the same as a failing check.** If either
   throws, `runFixLoop` neither blocks the session nor discards its state —
   a broken toolchain shouldn't trap a session in a loop, and it shouldn't

package/changes.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/*
+ * Finds the files a tool call wrote when the tool doesn't say which ones.
+ *
+ * Edit and Write name their target in `tool_input.file_path`, but a Bash or
+ * PowerShell command (`sed -i`, a Python script, a code generator) or an MCP
+ * tool can write anywhere and reports nothing. So the PreToolUse hook takes a
+ * cheap snapshot — a timestamp, the cwd and each repo's HEAD — and the
+ * PostToolUse hook asks what changed since:
+ *
+ *   - in a git repo, the dirty and untracked files (`git status`), plus the
+ *     files of any commit made during the call, so `edit && git commit` in one
+ *     command isn't missed;
+ *   - outside a repo, a bounded walk of the cwd;
+ *
+ * and in both cases keeps only files whose mtime falls inside the call's
+ * window. Pre-existing dirty files the call didn't touch are older than the
+ * snapshot, and a `git checkout` / `git pull` leaves the tree clean and brings
+ * in commits made before the call, so neither drags unrelated files in.
+ *
+ * Everything here fails CLOSED, unlike scope.js: a snapshot or a git call
+ * that fails resolves to "nothing changed". This module decides which files
+ * a session becomes answerable for, and guessing wrong in the other
+ * direction would hand Claude somebody else's code.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { runBin } = require('./exec');
+
+/*
+ * Some filesystems store mtimes at a coarse resolution (FAT and SMB at 2s,
+ * some network mounts at 1s), which can round a write made just after the
+ * snapshot to just before it.
+ */
+const MTIME_SLACK_MS = 2000;
+
+/*
+ * Directories that are never a session's own source even when a command
+ * writes into them — and that a fresh project often hasn't gitignored yet,
+ * so `git status` would list every file in them after a `uv sync` or a
+ * `pnpm install`.
+ */
+const PRUNED_DIR_NAMES = new Set([
+  '.git',
+  'node_modules',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.tox',
+]);
+
+// Upper bound on entries visited by the no-git fallback walk.
+const MAX_WALK_ENTRIES = 20000;
+
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+function git(args, cwd) {
+  try {
+    const result = runBin('git', args, { cwd, encoding: 'utf8', maxBuffer: MAX_BUFFER });
+    return !result.error && result.status === 0 ? result.stdout : null;
+  } catch {
+    return null;
+  }
+}
+
+function repoRoot(dir) {
+  const out = git(['rev-parse', '--show-toplevel'], dir);
+  return out ? out.trim() || null : null;
+}
+
+function headOf(root) {
+  const out = git(['rev-parse', '--verify', '--quiet', 'HEAD'], root);
+  return out ? out.trim() || null : null;
+}
+
+function isPruned(absPath) {
+  return path
+    .dirname(absPath)
+    .split(path.sep)
+    .some((segment) => PRUNED_DIR_NAMES.has(segment));
+}
+
+function isDirectory(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/*
+ * Taken by the PreToolUse hook. JSON-serialisable on purpose: it is written
+ * to the session's state dir and read back by a different process.
+ */
+function snapshotWorkspace(cwd, { now = Date.now() } = {}) {
+  const dir = path.resolve(cwd || process.cwd());
+  const root = isDirectory(dir) ? repoRoot(dir) : null;
+  return { startedAt: now, cwd: dir, root, head: root ? headOf(root) : null };
+}
+
+/*
+ * `git status -z` entries are `XY <path>`; a rename or copy is followed by
+ * one more NUL-terminated entry holding the original path, which is skipped.
+ */
+function parseStatus(out, root) {
+  const paths = [];
+  const entries = out.split('\0');
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i];
+    if (entry.length < 4) continue;
+    if (/[RC]/.test(entry.slice(0, 2))) i += 1;
+    paths.push(path.resolve(root, entry.slice(3)));
+  }
+  return paths;
+}
+
+function dirtyFiles(root) {
+  const out = git(['status', '--porcelain=v1', '-z', '--untracked-files=all'], root);
+  return out === null ? [] : parseStatus(out, root);
+}
+
+/*
+ * Files touched by commits the call itself made. `--since` drops commits
+ * that merely arrived during the call (a pull, a checkout of another
+ * branch), which carry their original, older committer dates.
+ */
+function committedFiles(root, fromHead, startedAt) {
+  const head = headOf(root);
+  if (!head || head === fromHead) return [];
+
+  const range = fromHead ? [`${fromHead}..${head}`] : [head];
+  const since = new Date(startedAt - MTIME_SLACK_MS).toISOString();
+  const out = git(['log', '--format=', '--name-only', '-z', `--since=${since}`, ...range], root);
+  if (out === null) return [];
+  return out
+    .split(/[\0\n]/)
+    .filter(Boolean)
+    .map((rel) => path.resolve(root, rel));
+}
+
+function walkFiles(dir) {
+  const files = [];
+  const stack = [dir];
+  let visited = 0;
+
+  while (stack.length > 0 && visited < MAX_WALK_ENTRIES) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      visited += 1;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!PRUNED_DIR_NAMES.has(entry.name)) stack.push(full);
+      } else if (entry.isFile()) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+
+function modifiedSince(absPath, since) {
+  try {
+    const stat = fs.statSync(absPath);
+    return stat.isFile() && stat.mtimeMs >= since;
+  } catch {
+    return false;
+  }
+}
+
+/*
+ * The PostToolUse half: absolute paths of the files written between the
+ * snapshot and now. `cwd` is where the session is now, which a `cd` inside
+ * the command may have moved away from the snapshot's.
+ */
+function filesChangedSince(snapshot, { cwd } = {}) {
+  if (!snapshot || typeof snapshot.startedAt !== 'number') return [];
+  const since = snapshot.startedAt - MTIME_SLACK_MS;
+
+  const candidates = [];
+  const roots = new Map();
+  if (snapshot.root) roots.set(snapshot.root, snapshot.head);
+
+  const nowDir = cwd ? path.resolve(cwd) : null;
+  const nowRoot =
+    nowDir && nowDir !== snapshot.cwd && isDirectory(nowDir) ? repoRoot(nowDir) : null;
+  // A repo entered mid-command has no recorded HEAD, so its commits are skipped.
+  if (nowRoot && !roots.has(nowRoot)) roots.set(nowRoot, undefined);
+
+  for (const [root, head] of roots) {
+    candidates.push(...dirtyFiles(root));
+    if (head !== undefined) candidates.push(...committedFiles(root, head, snapshot.startedAt));
+  }
+  if (!snapshot.root && snapshot.cwd && isDirectory(snapshot.cwd)) {
+    candidates.push(...walkFiles(snapshot.cwd));
+  }
+
+  return [...new Set(candidates)].filter((file) => !isPruned(file) && modifiedSince(file, since));
+}
+
+module.exports = {
+  MTIME_SLACK_MS,
+  PRUNED_DIR_NAMES,
+  snapshotWorkspace,
+  filesChangedSince,
+};

package/index.js

@@ -10,6 +10,7 @@ module.exports = {
   ...require('./exec'),
   ...require('./hook-input'),
   ...require('./state'),
+  ...require('./changes'),
   ...require('./track'),
   ...require('./scope'),
   ...require('./loop'),

package/loop.js

@@ -5,9 +5,44 @@ const { readAttempts, writeAttempts, cleanup } = require('./state');
 
 const DEFAULT_MAX_ATTEMPTS = 3;
 
+/*
+ * Claude Code caps a hook's `reason` at 10,000 characters; past that it
+ * saves the text to a file and hands Claude only a 2,000-character preview,
+ * without asking it to read the rest. A long lint report is better cut here,
+ * with a note that it was, than silently swapped for a preview.
+ */
+const MAX_REASON_CHARS = 9500;
+
+function clampReason(text) {
+  if (text.length <= MAX_REASON_CHARS) return text;
+  const omitted = text.length - MAX_REASON_CHARS;
+  return (
+    `${text.slice(0, MAX_REASON_CHARS)}\n\n[… ${omitted} more characters omitted. ` +
+    'Fix the findings above, then stop again to see the rest.]'
+  );
+}
+
+/*
+ * The only shape Claude Code honours for blocking a Stop or SubagentStop is
+ * a top-level `decision: "block"` with a `reason`, which becomes Claude's
+ * next instruction. Anything nested under hookSpecificOutput (other than
+ * additionalContext) is ignored and the stop simply goes through, which is
+ * how earlier versions of this kit, emitting `decision: "continue"` there,
+ * never actually blocked. `systemMessage` is shown to the user only.
+ */
+function blockPayload({ stopReason, systemMessage }) {
+  return {
+    decision: 'block',
+    reason: clampReason(
+      systemMessage || stopReason || 'Checks failed on files this session touched.',
+    ),
+    ...(stopReason ? { systemMessage: stopReason } : {}),
+  };
+}
+
 /*
  * The Stop/SubagentStop half of the loop: check the files this session
- * touched, and if they don't pass, block the stop with decision:"continue" so
+ * touched, and if they don't pass, block the stop with decision:"block" so
  * Claude is handed the failures and keeps working.
  *
  * The loop is capped so it can't run forever. Hitting the cap is not success —
@@ -24,7 +59,9 @@ const DEFAULT_MAX_ATTEMPTS = 3;
  *   fix         — optional, mechanically fixes what it can before checking
  *   check       — returns { failed, report }
  *   onCap       — optional, called instead of blocking once attempts run out
- *   buildMessage— returns { stopReason?, systemMessage } for the block payload
+ *   buildMessage— returns { stopReason?, systemMessage } for the block payload:
+ *                 systemMessage is what Claude is told to fix, stopReason an
+ *                 optional one-line notice shown to the user
  *
  * Returns { blocked, reason } describing which path was taken, so hooks and
  * their tests can assert on the outcome rather than on stdout alone.
@@ -80,18 +117,9 @@ function runFixLoop({
 
   const { stopReason, systemMessage } = buildMessage({ attempt, maxAttempts, outcome, files });
 
-  write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: input.hook_event_name || 'Stop',
-        decision: 'continue',
-        ...(stopReason ? { stopReason } : {}),
-        systemMessage,
-      },
-    }),
-  );
+  write(JSON.stringify(blockPayload({ stopReason, systemMessage })));
 
   return { blocked: true, reason: 'blocked', attempt, outcome };
 }
 
-module.exports = { runFixLoop, DEFAULT_MAX_ATTEMPTS };
+module.exports = { runFixLoop, blockPayload, DEFAULT_MAX_ATTEMPTS, MAX_REASON_CHARS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leonardo-marziali/ad-lfl-kit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Agentic development lint-fix-loop kit: session-scoped file tracking and a capped Stop-hook fix loop for Claude Code plugins.",
   "keywords": [
     "claude-code",
@@ -27,6 +27,7 @@
     "exec.js",
     "hook-input.js",
     "state.js",
+    "changes.js",
     "track.js",
     "scope.js",
     "loop.js"

package/state.js

@@ -19,6 +19,32 @@ function stateDir({ sessionId, namespace }) {
   return path.join(base, sessionId || 'unknown-session');
 }
 
+/*
+ * Where one subagent's share of a session's state lives, inside the
+ * session's own directory. Subagent tool calls arrive with the parent's
+ * session_id plus their own agent_id, so a file a subagent writes is
+ * tracked twice: in the session's list, which the main Stop checks, and in
+ * this one, which that subagent's SubagentStop checks.
+ */
+function agentStateDir(dir, agentId) {
+  // agent_id is a hex token today; never let it name a path outside `dir`.
+  return path.join(dir, 'agents', String(agentId).replaceAll(/[^\w-]/g, '_'));
+}
+
+/*
+ * The directory a Stop/SubagentStop hook should run its loop in. A
+ * SubagentStop gets the subagent's own directory, so a subagent is only
+ * held to the files it wrote — not to whatever the main conversation or a
+ * sibling subagent left unfinished — and keeps an attempt count of its own.
+ * Every other event gets the session directory unchanged.
+ */
+function loopStateDir({ dir, input }) {
+  if (input?.hook_event_name === 'SubagentStop' && input.agent_id) {
+    return agentStateDir(dir, input.agent_id);
+  }
+  return dir;
+}
+
 /*
  * The tracked-file list is append-only newline-delimited text. Entries can go
  * stale within a session — a file gets tracked, then deleted or renamed — so
@@ -69,6 +95,8 @@ function cleanup(dir, ownStateFiles) {
   }
   try {
     fs.rmdirSync(dir);
+    // A subagent's dir (see agentStateDir) leaves an empty `agents` behind.
+    if (path.basename(path.dirname(dir)) === 'agents') fs.rmdirSync(path.dirname(dir));
   } catch {
     // not empty (another hook's state still pending) or already gone
   }
@@ -76,6 +104,8 @@ function cleanup(dir, ownStateFiles) {
 
 module.exports = {
   stateDir,
+  agentStateDir,
+  loopStateDir,
   readTrackedFiles,
   appendTrackedFile,
   readAttempts,

package/track.js

@@ -2,23 +2,33 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { appendTrackedFile } = require('./state');
+const { appendTrackedFile, agentStateDir } = require('./state');
+const { snapshotWorkspace, filesChangedSince } = require('./changes');
 
 /*
- * The PostToolUse half of the loop: records the file a tool just wrote, so the
- * Stop hook only ever inspects files this session actually touched — never
- * pre-existing content the user didn't ask us to police.
- *
- * `matches` decides what's in scope for the calling plugin and receives the
- * resolved absolute path. Returns the path that was tracked, or null when the
- * event wasn't one we care about — callers generally ignore the return and
- * just let the hook exit.
+ * The PostToolUse half of the loop: records the files a tool just wrote, so
+ * the Stop hook only ever inspects files this session actually touched —
+ * never pre-existing content the user didn't ask us to police.
  */
-function trackTouchedFile({ input, listFile, matches }) {
-  if (!input) return null;
-  if (!/^(Edit|Write)$/.test(input.tool_name || '')) return null;
 
-  const filePath = input.tool_input?.file_path;
+// Tools that name the one file they write in their input.
+const FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/*
+ * Tools that can write files without saying which: shells and MCP servers.
+ * Read-only built-ins (Read, Grep, Glob, WebFetch…) are left out so their
+ * hooks don't pay for a workspace scan on every call. A subagent's own tool
+ * calls fire these hooks themselves, so Agent/Task needs no entry.
+ */
+const SHELL_TOOL = /^(Bash|PowerShell|mcp__.+)$/;
+
+const PENDING_DIR = 'pending';
+
+// A Pre marker whose Post never came (a denied permission, a crash).
+const STALE_MARKER_MS = 24 * 60 * 60 * 1000;
+
+function resolveToolPath(input) {
+  const filePath = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
   if (!filePath) return null;
 
   /*
@@ -26,14 +36,136 @@ function trackTouchedFile({ input, listFile, matches }) {
    * cwd, not this hook process's, which can differ.
    */
   const cwd = input.cwd || process.cwd();
-  const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+  return path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+}
+
+/*
+ * Appends to the session's list and, for a subagent's tool call, to that
+ * subagent's own list as well (see agentStateDir).
+ */
+function record(listFile, absPath, input) {
+  const lists = [listFile];
+  if (input.agent_id) {
+    lists.push(
+      path.join(agentStateDir(path.dirname(listFile), input.agent_id), path.basename(listFile)),
+    );
+  }
+  for (const list of lists) {
+    fs.mkdirSync(path.dirname(list), { recursive: true });
+    appendTrackedFile(list, absPath);
+  }
+}
 
-  if (!fs.existsSync(absPath)) return null;
+/*
+ * Tracks the file an Edit, Write, MultiEdit or NotebookEdit call wrote.
+ *
+ * `matches` decides what's in scope for the calling plugin and receives the
+ * resolved absolute path. Returns the path that was tracked, or null when the
+ * event wasn't one we care about — callers generally ignore the return and
+ * just let the hook exit.
+ */
+function trackTouchedFile({ input, listFile, matches }) {
+  if (!input) return null;
+  if (!FILE_TOOLS.has(input.tool_name || '')) return null;
+
+  const absPath = resolveToolPath(input);
+  if (!absPath || !fs.existsSync(absPath)) return null;
   if (typeof matches === 'function' && !matches(absPath)) return null;
 
-  fs.mkdirSync(path.dirname(listFile), { recursive: true });
-  appendTrackedFile(listFile, absPath);
+  record(listFile, absPath, input);
   return absPath;
 }
 
-module.exports = { trackTouchedFile };
+function markerFile(stateDir, toolUseId) {
+  return path.join(stateDir, PENDING_DIR, `${String(toolUseId).replaceAll(/[^\w-]/g, '_')}.json`);
+}
+
+function pruneStaleMarkers(pendingDir, now) {
+  let names;
+  try {
+    names = fs.readdirSync(pendingDir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const full = path.join(pendingDir, name);
+    try {
+      if (now - fs.statSync(full).mtimeMs > STALE_MARKER_MS) fs.rmSync(full, { force: true });
+    } catch {
+      // best effort
+    }
+  }
+}
+
+function takeMarker(file) {
+  try {
+    const snapshot = JSON.parse(fs.readFileSync(file, 'utf8'));
+    fs.rmSync(file, { force: true });
+    try {
+      fs.rmdirSync(path.dirname(file));
+    } catch {
+      // other calls still pending
+    }
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+/*
+ * The files one tool call wrote, whatever the tool.
+ *
+ * Wire it to PreToolUse, PostToolUse and PostToolUseFailure — a shell
+ * command that edits files and then exits non-zero (`./fix.py && pytest`)
+ * reports through PostToolUseFailure, not PostToolUse:
+ *
+ *   - PreToolUse on a shell or MCP tool: records a snapshot under
+ *     `<stateDir>/pending/<tool_use_id>.json` and returns [].
+ *   - Post* on an Edit-family tool: the one file it names, if it exists.
+ *   - Post* on a shell or MCP tool: every file changed since the snapshot
+ *     (see changes.js), consuming the snapshot. No snapshot, no files —
+ *     the PreToolUse hook wasn't wired, or the call was never seen starting.
+ *
+ * Each snapshot is consumed by the first Post hook that reads it, so a
+ * plugin should have one script per state dir call this.
+ */
+function toolChangedFiles({ input, stateDir, now = Date.now() }) {
+  if (!input) return [];
+  const tool = input.tool_name || '';
+  const event = input.hook_event_name || 'PostToolUse';
+
+  if (FILE_TOOLS.has(tool)) {
+    if (event === 'PreToolUse') return [];
+    const absPath = resolveToolPath(input);
+    return absPath && fs.existsSync(absPath) ? [absPath] : [];
+  }
+
+  if (!SHELL_TOOL.test(tool) || !input.tool_use_id) return [];
+  const marker = markerFile(stateDir, input.tool_use_id);
+
+  if (event === 'PreToolUse') {
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    pruneStaleMarkers(path.dirname(marker), now);
+    fs.writeFileSync(marker, JSON.stringify(snapshotWorkspace(input.cwd, { now })));
+    return [];
+  }
+
+  const snapshot = takeMarker(marker);
+  return snapshot ? filesChangedSince(snapshot, { cwd: input.cwd }) : [];
+}
+
+/*
+ * toolChangedFiles + trackTouchedFile's bookkeeping: tracks every file the
+ * call wrote that `matches` accepts, in the session's list and (inside a
+ * subagent) the subagent's. Snapshots live beside `listFile`. Returns the
+ * paths tracked.
+ */
+function trackSessionChanges({ input, listFile, matches, now }) {
+  if (!input) return [];
+  const files = toolChangedFiles({ input, stateDir: path.dirname(listFile), now });
+  const tracked = files.filter((file) => typeof matches !== 'function' || matches(file));
+  for (const file of tracked) record(listFile, file, input);
+  return tracked;
+}
+
+module.exports = { trackTouchedFile, toolChangedFiles, trackSessionChanges };