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

package/README.md

@@ -19,8 +19,9 @@ plugin can build the same loop without re-implementing it.
    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
+   workspace and tracks whatever changed by the time the call ends — or, for
+   a command run in the background, keeps tracking its writes on later
+   events. 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),
@@ -95,19 +96,24 @@ const {
   stateDir,
   loopStateDir,
   readTrackedFiles,
+  trackSessionChanges,
   runFixLoop,
   runBin,
 } = require('@leonardo-marziali/ad-lfl-kit');
 
 const input = readHookInput();
-// 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',
-  }),
+const sessionDir = stateDir({
+  sessionId: input?.session_id,
+  namespace: 'my-plugin-session-scope',
+});
+// Collect what background commands wrote since the last tool call.
+trackSessionChanges({
   input,
+  listFile: path.join(sessionDir, 'touched-files.txt'),
+  matches: (absPath) => absPath.endsWith('.md'),
 });
+// A SubagentStop gets its subagent's own directory; a Stop the session's.
+const dir = loopStateDir({ dir: sessionDir, input });
 const stateFiles = ['touched-files.txt', 'attempts.json'];
 const files = readTrackedFiles(path.join(dir, 'touched-files.txt'));
 
@@ -226,11 +232,15 @@ excluded rather than drop it silently.
 ### Tracking (`track.js`)
 
 - **`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.
+  half; wire it to `PreToolUse`, `PostToolUse` and `PostToolUseFailure`,
+  and call it from the `Stop`/`SubagentStop` hook too, before reading
+  `listFile`, so background writes made after the last tool call are
+  collected. 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. A
+  background command's later writes reach its subagent's list only while
+  that subagent is the one calling; the session's list always gets them.
+  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
@@ -239,6 +249,18 @@ excluded rather than drop it silently.
   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.
+
+  A backgrounded command — `run_in_background: true`, or one the user sent
+  to the background, which Claude Code reports with a `backgroundTaskId` —
+  gets its `Post*` event as soon as it's backgrounded, while it keeps
+  writing. Its snapshot then moves to `<stateDir>/background/` instead of
+  being consumed, and every later `Post*`, `Stop` and `SubagentStop` event
+  also returns what it wrote since the previous such sweep. Hooks aren't
+  told when a background command exits, so its window closes
+  `BACKGROUND_WINDOW_MS` (2 hours) after it started, with one last sweep.
+  Within the window, anything written in the scanned repos counts —
+  including edits you make in an editor meanwhile.
+
 - **`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
@@ -251,6 +273,8 @@ 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).
+- **`advanceSnapshot(snapshot)`** — the same snapshot moved up to now (new
+  time and `HEAD`), for watching a window that stays open.
 - **`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`
@@ -265,9 +289,9 @@ How `toolChangedFiles` answers for tools that don't name their files.
 - **`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.
+What it can't see: writes outside both the snapshot's and the current
+cwd's repository, and a background command's writes more than
+`BACKGROUND_WINDOW_MS` after it started.
 
 ### Execution (`exec.js`)
 

package/changes.js

@@ -103,6 +103,16 @@ function snapshotWorkspace(cwd, { now = Date.now() } = {}) {
   return { startedAt: now, cwd: dir, root, head: root ? headOf(root) : null };
 }
 
+/*
+ * The snapshot that picks up where `snapshot` leaves off: same cwd and repo,
+ * with the clock and HEAD moved to now. Take it *before* reading what
+ * changed since `snapshot`, so a write landing in between falls into both
+ * windows rather than neither.
+ */
+function advanceSnapshot(snapshot, { now = Date.now() } = {}) {
+  return { ...snapshot, startedAt: now, head: snapshot.root ? headOf(snapshot.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.
@@ -212,5 +222,6 @@ module.exports = {
   MTIME_SLACK_MS,
   PRUNED_DIR_NAMES,
   snapshotWorkspace,
+  advanceSnapshot,
   filesChangedSince,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leonardo-marziali/ad-lfl-kit",
-  "version": "2.3.0",
+  "version": "2.5.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",

package/track.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { appendTrackedFile, agentStateDir } = require('./state');
-const { snapshotWorkspace, filesChangedSince } = require('./changes');
+const { snapshotWorkspace, advanceSnapshot, filesChangedSince } = require('./changes');
 
 /*
  * The PostToolUse half of the loop: records the files a tool just wrote, so
@@ -23,10 +23,23 @@ const FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 const SHELL_TOOL = /^(Bash|PowerShell|mcp__.+)$/;
 
 const PENDING_DIR = 'pending';
+const BACKGROUND_DIR = 'background';
 
 // A Pre marker whose Post never came (a denied permission, a crash).
 const STALE_MARKER_MS = 24 * 60 * 60 * 1000;
 
+/*
+ * How long a background command's writes keep being attributed to the
+ * session. Claude Code doesn't tell hooks when a background command exits,
+ * so its window closes on a clock instead: long enough for a build, a
+ * codegen run or a test suite, short enough that a dev server left running
+ * doesn't make the session answer for the rest of the day's edits.
+ */
+const BACKGROUND_WINDOW_MS = 2 * 60 * 60 * 1000;
+
+// Events that only collect what background commands wrote since last time.
+const STOP_EVENTS = new Set(['Stop', 'SubagentStop']);
+
 function resolveToolPath(input) {
   const filePath = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
   if (!filePath) return null;
@@ -40,15 +53,13 @@ function resolveToolPath(input) {
 }
 
 /*
- * Appends to the session's list and, for a subagent's tool call, to that
+ * Appends to the session's list and, for a file a subagent wrote, to that
  * subagent's own list as well (see agentStateDir).
  */
-function record(listFile, absPath, input) {
+function record(listFile, absPath, agentId) {
   const lists = [listFile];
-  if (input.agent_id) {
-    lists.push(
-      path.join(agentStateDir(path.dirname(listFile), input.agent_id), path.basename(listFile)),
-    );
+  if (agentId) {
+    lists.push(path.join(agentStateDir(path.dirname(listFile), agentId), path.basename(listFile)));
   }
   for (const list of lists) {
     fs.mkdirSync(path.dirname(list), { recursive: true });
@@ -72,12 +83,100 @@ function trackTouchedFile({ input, listFile, matches }) {
   if (!absPath || !fs.existsSync(absPath)) return null;
   if (typeof matches === 'function' && !matches(absPath)) return null;
 
-  record(listFile, absPath, input);
+  record(listFile, absPath, input.agent_id);
   return absPath;
 }
 
-function markerFile(stateDir, toolUseId) {
-  return path.join(stateDir, PENDING_DIR, `${String(toolUseId).replaceAll(/[^\w-]/g, '_')}.json`);
+function markerFile(stateDir, toolUseId, kind = PENDING_DIR) {
+  return path.join(stateDir, kind, `${String(toolUseId).replaceAll(/[^\w-]/g, '_')}.json`);
+}
+
+/*
+ * A `run_in_background: true` call, or one the user sent to the background
+ * mid-run: its Post event fires as soon as it's backgrounded, while the
+ * command itself keeps writing.
+ */
+function isBackgrounded(input) {
+  return (
+    input.tool_input?.run_in_background === true || Boolean(input.tool_response?.backgroundTaskId)
+  );
+}
+
+// Rename over the old file, so a concurrent reader never sees half of one.
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value));
+  fs.renameSync(tmp, file);
+}
+
+/*
+ * Keeps watching after a background command's Post event: its snapshot,
+ * moved up to now, is left under `<stateDir>/background/` for later events
+ * to sweep. `cwd` is where the call left the session, which filesChangedSince
+ * also scans.
+ */
+function openBackgroundWindow(stateDir, input, snapshot, now) {
+  writeJsonAtomic(markerFile(stateDir, input.tool_use_id, BACKGROUND_DIR), {
+    openedAt: now,
+    cwd: input.cwd,
+    agentId: input.agent_id,
+    snapshot,
+  });
+}
+
+// A window as openBackgroundWindow wrote it, or null.
+function readWindow(file) {
+  try {
+    const window = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return typeof window?.openedAt === 'number' && window.snapshot ? window : null;
+  } catch {
+    return null;
+  }
+}
+
+/*
+ * Everything open background commands wrote since the last sweep, each
+ * window then moved up to `now` — or, once BACKGROUND_WINDOW_MS has passed,
+ * closed after this last look.
+ */
+function sweepBackgroundWindows(stateDir, now) {
+  const dir = path.join(stateDir, BACKGROUND_DIR);
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const changes = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    const window = readWindow(file);
+    if (!window) {
+      // Swept and closed by a concurrent hook, or unreadable: fail closed.
+      fs.rmSync(file, { force: true });
+      continue;
+    }
+
+    const expired = now - window.openedAt >= BACKGROUND_WINDOW_MS;
+    const next = expired ? null : advanceSnapshot(window.snapshot, { now });
+    for (const changed of filesChangedSince(window.snapshot, { cwd: window.cwd })) {
+      changes.push({ file: changed, agentId: window.agentId });
+    }
+    try {
+      if (expired) fs.rmSync(file, { force: true });
+      else writeJsonAtomic(file, { ...window, snapshot: next });
+    } catch {
+      // best effort
+    }
+  }
+  try {
+    fs.rmdirSync(dir);
+  } catch {
+    // windows still open
+  }
+  return changes;
 }
 
 function pruneStaleMarkers(pendingDir, now) {
@@ -126,32 +225,51 @@ function takeMarker(file) {
  *     (see changes.js), consuming the snapshot. No snapshot, no files —
  *     the PreToolUse hook wasn't wired, or the call was never seen starting.
  *
+ * A backgrounded command's Post event fires when it's sent to the
+ * background, not when it exits, so its snapshot moves to
+ * `<stateDir>/background/` instead, and every later Post* — and a Stop or
+ * SubagentStop, which only does this — also returns what open background
+ * commands wrote since the last such sweep.
+ *
  * 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 [];
+function toolChangedEntries({ input, stateDir, now }) {
   const tool = input.tool_name || '';
   const event = input.hook_event_name || 'PostToolUse';
+  const own = (files) => files.map((file) => ({ file, agentId: input.agent_id }));
+
+  if (event === 'PreToolUse') {
+    if (SHELL_TOOL.test(tool) && input.tool_use_id) {
+      const marker = markerFile(stateDir, input.tool_use_id);
+      fs.mkdirSync(path.dirname(marker), { recursive: true });
+      pruneStaleMarkers(path.dirname(marker), now);
+      fs.writeFileSync(marker, JSON.stringify(snapshotWorkspace(input.cwd, { now })));
+    }
+    return [];
+  }
+
+  const changes = sweepBackgroundWindows(stateDir, now);
+  if (STOP_EVENTS.has(event)) return changes;
 
   if (FILE_TOOLS.has(tool)) {
-    if (event === 'PreToolUse') return [];
     const absPath = resolveToolPath(input);
-    return absPath && fs.existsSync(absPath) ? [absPath] : [];
+    return absPath && fs.existsSync(absPath) ? [...changes, ...own([absPath])] : changes;
   }
 
-  if (!SHELL_TOOL.test(tool) || !input.tool_use_id) return [];
-  const marker = markerFile(stateDir, input.tool_use_id);
+  if (!SHELL_TOOL.test(tool) || !input.tool_use_id) return changes;
+  const snapshot = takeMarker(markerFile(stateDir, input.tool_use_id));
+  if (!snapshot) return changes;
 
-  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 next = isBackgrounded(input) ? advanceSnapshot(snapshot, { now }) : null;
+  changes.push(...own(filesChangedSince(snapshot, { cwd: input.cwd })));
+  if (next) openBackgroundWindow(stateDir, input, next, now);
+  return changes;
+}
 
-  const snapshot = takeMarker(marker);
-  return snapshot ? filesChangedSince(snapshot, { cwd: input.cwd }) : [];
+function toolChangedFiles({ input, stateDir, now = Date.now() }) {
+  if (!input) return [];
+  return [...new Set(toolChangedEntries({ input, stateDir, now }).map(({ file }) => file))];
 }
 
 /*
@@ -159,13 +277,26 @@ function toolChangedFiles({ input, stateDir, now = Date.now() }) {
  * 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.
+ *
+ * Call it from the Stop/SubagentStop hook too, before reading `listFile`,
+ * to collect what background commands wrote after the last tool call. A
+ * background command's file goes in its subagent's list only when that
+ * subagent is the one sweeping: one that has already stopped has no loop
+ * left to read it, and the session's list still gets it.
  */
-function trackSessionChanges({ input, listFile, matches, now }) {
+function trackSessionChanges({ input, listFile, matches, now = Date.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);
+  const tracked = [];
+  for (const { file, agentId } of toolChangedEntries({
+    input,
+    stateDir: path.dirname(listFile),
+    now,
+  })) {
+    if (typeof matches === 'function' && !matches(file)) continue;
+    record(listFile, file, agentId && agentId === input.agent_id ? agentId : undefined);
+    if (!tracked.includes(file)) tracked.push(file);
+  }
   return tracked;
 }
 
-module.exports = { trackTouchedFile, toolChangedFiles, trackSessionChanges };
+module.exports = { BACKGROUND_WINDOW_MS, trackTouchedFile, toolChangedFiles, trackSessionChanges };