@goodfoot/agent-hooks 1.0.9 → 1.0.11

package/CHANGELOG.md

@@ -1,9 +1,12 @@
 # @goodfoot/agent-hooks npm package changelog
 
-## 1.0.9
-- Added support for Antigravity hooks, including event handling, output formatting, and transport
-- Added scaffolding for Antigravity hook projects via the CLI
-- Documented the Antigravity hook contract in the README
+## 1.0.11
+
+Moves generated-file tracking out of `hooks.json` into a sibling `hooks.meta.json`, because Claude Code rejects a hooks manifest carrying any key besides `hooks`. The manifest is now a pure function of its inputs, so a rebuild that changes nothing writes identical bytes and leaves the host's hook-trust hash intact. A missing or unreadable sidecar is treated as "nothing tracked as generated", which preserves the entries already in the manifest rather than pruning them.
+
+## 1.0.10
+
+Makes compiled bundles portable across ordinary hoisted workspace layouts by anchoring esbuild's module-boundary comments and sourcemap source paths at the directory that owns the resolved `node_modules`. Inline sourcemaps are now disabled by default for smaller, reviewable build artifacts and remain available with the explicit `--sourcemap` flag.
 
 ## 1.0.9
 

package/README.md

@@ -2,6 +2,8 @@
 
 **Build AI coding agent hooks in TypeScript — one package, any supported agent.**
 
+Compiled bundles omit inline sourcemaps by default. Pass `--sourcemap` when original TypeScript locations are needed in runtime stack traces.
+
 `@goodfoot/agent-hooks` is the unified successor to `@goodfoot/claude-code-hooks` and
 `@goodfoot/codex-hooks`: a shared agent-neutral core (hook factory primitive, transport
 driver, `Logger`, env/stdin utilities) with a per-agent entry point on top. Write

package/dist/agents/antigravity/cli-support.js

@@ -22,7 +22,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as esbuild from "esbuild";
 import ts from "typescript";
-import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
+import { buildEsbuildLoaderMap, discoverHookSourceFiles, moduleWorkingDir, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
 import { DEFAULT_TIMEOUT_SECONDS, GROUPED_EVENTS, HOOK_FACTORY_TO_EVENT } from "./constants.js";
 import { HOOK_EVENT_NAMES } from "./events.js";
 /** The matcher emitted when a grouped event's config names none. `"*"` matches every tool. */
@@ -82,9 +82,10 @@ export function analyzeAntigravityHookFile(sourcePath) {
  * Bundles one hook source into a self-contained ESM executable whose entry
  * wrapper calls this agent's `execute`.
  */
-export async function compileAntigravityHook(sourcePath, loaders, sourcemap = true) {
+export async function compileAntigravityHook(sourcePath, loaders, sourcemap = false) {
     const resolveDir = path.dirname(sourcePath);
     const runtimeAbsolute = symlinkVisiblePath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "./transport.js"), resolveDir);
+    const absWorkingDir = moduleWorkingDir(runtimeAbsolute, resolveDir);
     const runtimeRelative = path.relative(resolveDir, runtimeAbsolute).replace(/\\/g, "/");
     const runtimeSpecifier = runtimeRelative.startsWith(".") ? runtimeRelative : `./${runtimeRelative}`;
     const entry = [
@@ -94,6 +95,7 @@ export async function compileAntigravityHook(sourcePath, loaders, sourcemap = tr
         ``,
     ].join("\n");
     const built = await esbuild.build({
+        absWorkingDir,
         stdin: {
             contents: entry,
             resolveDir,

package/dist/agents/antigravity/scaffold.js

@@ -50,7 +50,7 @@ function packageJson(projectName, outputPath) {
             lint: "biome check .",
             typecheck: "tsc --noEmit",
         },
-        dependencies: { [PACKAGE_NAME]: "^1.0.9" },
+        dependencies: { [PACKAGE_NAME]: "^1.0.11" },
         devDependencies: {
             "@biomejs/biome": "2.4.9",
             "@types/node": "^24.0.0",

package/dist/agents/codex/cli-support.js

@@ -15,7 +15,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as esbuild from "esbuild";
 import ts from "typescript";
-import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
+import { buildEsbuildLoaderMap, discoverHookSourceFiles, moduleWorkingDir, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
 import { EVENTS_WITH_MATCHER, HOOK_FACTORY_TO_EVENT } from "./constants.js";
 /**
  * Extracts Codex hook metadata (event name, matcher, timeout in
@@ -88,9 +88,10 @@ export function analyzeCodexHookFile(sourcePath) {
  * Compiles one Codex hook to a self-contained ESM executable whose entry
  * wrapper imports this package's Codex runtime module (`execute`).
  */
-export async function compileCodexHook(sourcePath, loaders, sourcemap = true) {
+export async function compileCodexHook(sourcePath, loaders, sourcemap = false) {
     const resolveDir = path.dirname(sourcePath);
     const runtimePathAbsolute = symlinkVisiblePath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "./transport.js"), resolveDir);
+    const absWorkingDir = moduleWorkingDir(runtimePathAbsolute, resolveDir);
     let relativeRuntimePath = path.relative(resolveDir, runtimePathAbsolute).replace(/\\/g, "/");
     if (!relativeRuntimePath.startsWith(".")) {
         relativeRuntimePath = `./${relativeRuntimePath}`;
@@ -102,6 +103,7 @@ execute(hook);
 `;
     const baseName = path.basename(sourcePath, path.extname(sourcePath));
     const result = await esbuild.build({
+        absWorkingDir,
         stdin: {
             contents: wrapperContent,
             resolveDir,

package/dist/agents/codex/scaffold.js

@@ -55,7 +55,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            [PACKAGE_NAME]: "^1.0.9",
+            [PACKAGE_NAME]: "^1.0.11",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.9",

package/dist/agents/opencode/cli-support.js

@@ -23,7 +23,7 @@ import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag
  * Bundles one OpenCode plugin entry to a self-contained ESM artifact. The
  * source file's own default export is preserved unchanged — no wrapper.
  */
-export async function compileOpenCodePlugin(sourcePath, loaders, sourcemap = true) {
+export async function compileOpenCodePlugin(sourcePath, loaders, sourcemap = false) {
     const result = await esbuild.build({
         entryPoints: [sourcePath],
         loader: loaders,

package/dist/cli.js

@@ -26,7 +26,9 @@ import { scaffoldProject } from "./scaffold.js";
 // ============================================================================
 // Constants
 // ============================================================================
-const VERSION = "1.0.9";
+const VERSION = "1.0.11";
+/** Filename of the tracking sidecar written beside hooks.json. */
+const HOOKS_META_FILENAME = "hooks.meta.json";
 const DEFAULT_ESBUILD_LOADERS = {
     ".md": "text",
 };
@@ -142,13 +144,13 @@ Optional Arguments:
   --no-stable-names
       Restore the pre-1.7 behavior: hashed compiled bundles (<name>.<hash>.mjs).
 
-  --sourcemap (default)
+  --sourcemap
       Embed an inline sourcemap in each compiled bundle so stack traces show
       original TypeScript source locations.
 
-  --no-sourcemap
-      Emit bundles without the inline sourcemap, shrinking compiled output by
-      roughly 85-90%. The content hash is unaffected.
+  --no-sourcemap (default)
+      Emit bundles without the inline sourcemap, shrinking compiled output.
+      The content hash is unaffected.
 
   -h, --help
       Show this help message.
@@ -257,7 +259,7 @@ function parseArgs(argv) {
         // as true, while the Codex branch defaults by command context
         // (plugin mode → stable, otherwise hashed).
         stableNames: undefined,
-        sourcemap: true,
+        sourcemap: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -584,8 +586,12 @@ function symlinkVisiblePath(realPath, resolveDir) {
                     pkgRel = path.relative(dir, realPath);
                 }
             }
-            catch {
-                // Not a readable package.json — the realpath is not under a package.
+            catch (error) {
+                // An unreadable or malformed manifest is the same case as no manifest
+                // at all: identity stays undefined and the caller falls back below.
+                log("debug", `Could not read package manifest: ${pkgJsonPath}`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
             }
             break;
         }
@@ -642,6 +648,28 @@ function symlinkVisiblePath(realPath, resolveDir) {
         dir = parent;
     }
 }
+/**
+ * Returns the stable project anchor for a module reached through node_modules.
+ *
+ * esbuild otherwise uses process.cwd() when rendering module-boundary comments
+ * and sourcemap source paths. A workspace script normally runs from the
+ * consuming package, while its dependencies may be hoisted several directories
+ * higher, making those emitted paths depend on the consumer's nesting depth.
+ * Anchoring at the directory which owns the visible node_modules keeps the
+ * canonical `node_modules/...` form in every such layout.
+ */
+function moduleWorkingDir(modulePath, fallback) {
+    for (let dir = path.dirname(modulePath);;) {
+        if (path.basename(dir) === "node_modules") {
+            return path.dirname(dir);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return fallback;
+        }
+        dir = parent;
+    }
+}
 /**
  * Compiles a TypeScript hook file to a self-contained ESM executable.
  *
@@ -672,6 +700,7 @@ async function compileHook(options) {
     // nesting depth.
     const resolveDir = path.dirname(sourcePath);
     const runtimePathAbsolute = symlinkVisiblePath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "./agents/claude-code/transport.js"), resolveDir);
+    const absWorkingDir = moduleWorkingDir(runtimePathAbsolute, resolveDir);
     // Compute relative paths from resolveDir to avoid absolute paths in source maps.
     // This ensures reproducible builds regardless of checkout directory.
     const relativeSourcePath = `./${path.basename(sourcePath)}`;
@@ -731,6 +760,7 @@ execute(hook);
     ].join("\n");
     // Common esbuild options
     const commonOptions = {
+        absWorkingDir,
         stdin: stdinOptions,
         loader: loaders,
         format: "esm",
@@ -784,7 +814,7 @@ execute(hook);
     // output minus the trailing sourceMappingURL comment (verified on esbuild
     // 0.24.2), so the sourcemap-free content is emitted directly. The content
     // hash is always derived from pass-1 output, so it is unchanged by the flag.
-    if (sourcemap === false) {
+    if (sourcemap !== true) {
         return { content: contentForHash, contentHash };
     }
     const resultWithSourcemap = await esbuild.build({
@@ -1025,13 +1055,7 @@ function generateHooksJson(compiledHooks, buildDir, contextInfo, executable = "n
         }
         hooks[eventName] = entries;
     }
-    return {
-        hooks,
-        __generated: {
-            files: compiledHooks.map((h) => h.outputFilename),
-            timestamp: new Date().toISOString(),
-        },
-    };
+    return { hooks };
 }
 /**
  * Reads an existing hooks.json file if it exists.
@@ -1054,14 +1078,66 @@ function readExistingHooksJson(outputPath) {
     }
 }
 /**
- * Removes previously generated hook files from disk.
- * Only removes files that were tracked in __generated.files.
- * @param existingHooksJson - The existing hooks.json content
+ * Absolute path of the tracking sidecar that sits beside hooks.json.
+ * @param outputPath - Path to hooks.json
+ * @returns Path to hooks.meta.json
+ */
+function hooksMetaPath(outputPath) {
+    return path.join(path.dirname(outputPath), HOOKS_META_FILENAME);
+}
+/**
+ * Reads the tracking sidecar beside hooks.json if it exists.
+ *
+ * A missing or unreadable sidecar is not fatal: it only means no generated
+ * filenames are known, so every existing entry is treated as externally
+ * authored and preserved.
+ * @param outputPath - Path to the hooks.json the sidecar describes
+ * @returns Parsed HooksMeta or undefined if absent or unusable
+ */
+function readHooksMeta(outputPath) {
+    const metaPath = hooksMetaPath(outputPath);
+    if (!fs.existsSync(metaPath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+        const rawFiles = parsed.files;
+        if (!Array.isArray(rawFiles)) {
+            log("warn", "hooks.meta.json has no files array, treating generated hooks as untracked", { path: metaPath });
+            return undefined;
+        }
+        const files = rawFiles.filter((entry) => typeof entry === "string");
+        if (files.length !== rawFiles.length) {
+            log("warn", "hooks.meta.json lists non-string filenames, treating generated hooks as untracked", {
+                path: metaPath,
+            });
+            return undefined;
+        }
+        return { files };
+    }
+    catch (error) {
+        log("warn", "Failed to parse hooks.meta.json, treating generated hooks as untracked", {
+            path: metaPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/**
+ * Removes bundles a previous build generated that this build did not. Only
+ * filenames tracked in the sidecar are ever removed, and callers must run this
+ * after the new hooks.json is on disk so no reachable state loses a file it
+ * references.
+ * @param previousMeta - Tracking sidecar from the previous build, if any
  * @param outputDir - Directory containing the generated files
+ * @param keepFilenames - Filenames written by the current build
  */
-function removeOldGeneratedFiles(existingHooksJson, outputDir) {
-    const filesToRemove = existingHooksJson.__generated?.files ?? [];
+function removeStaleGeneratedFiles(previousMeta, outputDir, keepFilenames) {
+    const filesToRemove = previousMeta?.files ?? [];
     for (const filename of filesToRemove) {
+        if (keepFilenames.has(filename)) {
+            continue;
+        }
         const filePath = path.join(outputDir, filename);
         if (fs.existsSync(filePath)) {
             try {
@@ -1077,13 +1153,15 @@ function removeOldGeneratedFiles(existingHooksJson, outputDir) {
     }
 }
 /**
- * Extracts hooks from an existing hooks.json that were NOT generated by this package.
- * Identifies generated hooks by checking if their command path matches the generated file pattern.
+ * Extracts hooks from an existing hooks.json that were NOT generated by this
+ * package. Generated hooks are identified by the filenames tracked in the
+ * sidecar, so entries authored anywhere else survive a rebuild untouched.
  * @param existingHooksJson - The existing hooks.json content
+ * @param meta - Tracking sidecar from the previous build, if any
  * @returns Object containing preserved hooks (keyed by event type)
  */
-function extractPreservedHooks(existingHooksJson) {
-    const generatedFiles = new Set(existingHooksJson.__generated?.files ?? []);
+function extractPreservedHooks(existingHooksJson, meta) {
+    const generatedFiles = new Set(meta?.files ?? []);
     const preserved = {};
     for (const [eventType, entries] of Object.entries(existingHooksJson.hooks)) {
         if (!entries)
@@ -1131,28 +1209,24 @@ function mergeHooksJson(newHooksJson, preservedHooks) {
         // Combine preserved and generated entries
         mergedHooks[eventType] = [...preserved, ...generated];
     }
-    return {
-        hooks: mergedHooks,
-        __generated: newHooksJson.__generated,
-    };
+    return { hooks: mergedHooks };
 }
 /**
- * Writes hooks.json to the specified path atomically.
- * Uses write-to-temp-then-rename pattern for atomicity.
- * @param hooksJson - The hooks.json content
- * @param outputPath - Path to write hooks.json
+ * Writes a JSON document atomically, using write-to-temp-then-rename.
+ * @param value - Value to serialize
+ * @param filePath - Destination path
  */
-function writeHooksJson(hooksJson, outputPath) {
-    const dir = path.dirname(outputPath);
+function writeJsonAtomic(value, filePath) {
+    const dir = path.dirname(filePath);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
     // Write to a temporary file first, then rename for atomicity
-    const tempPath = `${outputPath}.tmp.${process.pid}`;
-    const content = `${JSON.stringify(hooksJson, null, 2)}\n`;
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    const content = `${JSON.stringify(value, null, 2)}\n`;
     try {
         fs.writeFileSync(tempPath, content, "utf-8");
-        fs.renameSync(tempPath, outputPath);
+        fs.renameSync(tempPath, filePath);
     }
     catch (error) {
         // Clean up temp file if rename failed
@@ -1167,6 +1241,22 @@ function writeHooksJson(hooksJson, outputPath) {
         throw error;
     }
 }
+/**
+ * Writes hooks.json to the specified path atomically.
+ * @param hooksJson - The hooks.json content
+ * @param outputPath - Path to write hooks.json
+ */
+function writeHooksJson(hooksJson, outputPath) {
+    writeJsonAtomic(hooksJson, outputPath);
+}
+/**
+ * Writes the tracking sidecar beside hooks.json atomically.
+ * @param meta - Tracking metadata for this build
+ * @param outputPath - Path to the hooks.json the sidecar describes
+ */
+function writeHooksMeta(meta, outputPath) {
+    writeJsonAtomic(meta, hooksMetaPath(outputPath));
+}
 // ============================================================================
 // Main Entry Point
 // ============================================================================
@@ -1352,15 +1442,14 @@ async function main() {
             process.stderr.write(`Error: No hook files found matching pattern: ${args.input}\n`);
             process.exit(1);
         }
-        // Read existing hooks.json to preserve non-generated hooks
+        // Read existing hooks.json and its tracking sidecar to preserve non-generated hooks
         const existingHooksJson = readExistingHooksJson(outputPath);
+        const existingMeta = readHooksMeta(outputPath);
         let preservedHooks = {};
         if (existingHooksJson !== undefined) {
             log("info", "Found existing hooks.json, will preserve non-generated hooks");
             // Extract hooks that were NOT generated by this package
-            preservedHooks = extractPreservedHooks(existingHooksJson);
-            // Remove old generated files from disk
-            removeOldGeneratedFiles(existingHooksJson, buildDir);
+            preservedHooks = extractPreservedHooks(existingHooksJson, existingMeta);
             const preservedCount = Object.values(preservedHooks).reduce((sum, entries) => sum + (entries?.reduce((s, e) => s + e.hooks.length, 0) ?? 0), 0);
             log("info", `Preserved ${preservedCount} hooks from other sources`);
         }
@@ -1384,19 +1473,16 @@ async function main() {
         // Generate hooks.json for newly compiled hooks
         const executable = args.executable !== undefined && args.executable !== "" ? args.executable : "node";
         const newHooksJson = generateHooksJson(compiledHooks, buildDir, hookContext, executable);
-        // Preserve timestamp if generated files haven't changed
-        if (existingHooksJson !== undefined) {
-            const existingFiles = [...(existingHooksJson.__generated?.files ?? [])].sort();
-            const newFiles = [...newHooksJson.__generated.files].sort();
-            const filesUnchanged = existingFiles.length === newFiles.length && existingFiles.every((f, i) => f === newFiles[i]);
-            if (filesUnchanged && existingHooksJson.__generated?.timestamp) {
-                newHooksJson.__generated.timestamp = existingHooksJson.__generated.timestamp;
-                log("info", "Files unchanged, preserving existing timestamp");
-            }
-        }
         // Merge with preserved hooks
         const finalHooksJson = mergeHooksJson(newHooksJson, preservedHooks);
         writeHooksJson(finalHooksJson, outputPath);
+        // Drop the bundles the previous build produced that this one did not, then
+        // record what this build wrote. Stale files go only after the hooks.json
+        // that references the current set is on disk, so every state on disk
+        // between the two writes stays runnable.
+        const writtenFilenames = new Set(compiledHooks.map((hook) => hook.outputFilename));
+        removeStaleGeneratedFiles(existingMeta, buildDir, writtenFilenames);
+        writeHooksMeta({ files: [...writtenFilenames].sort() }, outputPath);
         log("info", "Compilation complete", {
             hooksCompiled: compiledHooks.length,
             outputPath,
@@ -1447,4 +1533,4 @@ if (isDirectExecution) {
 // Shared build primitives reused by the per-agent CLI branches (single
 // source for driver logic — the duplication check forbids re-deriving these
 // inside agents/*).
-export { analyzeHookFile, buildLoaderMap, buildLoaderMap as buildEsbuildLoaderMap, compileHook, detectHookContext, discoverHookFiles, discoverHookFiles as discoverHookSourceFiles, extractPreservedHooks, generateCommandPath, generateContentHash, generateContentHash as sha256Prefix8, generateHooksJson, groupHooksByEventAndMatcher, HOOK_FACTORY_TO_EVENT, mergeHooksJson, parseArgs, parseLoaderFlag, parseLoaderFlag as parseEsbuildLoaderFlag, pruneStaleHashedBundles, readExistingHooksJson, removeOldGeneratedFiles, symlinkVisiblePath, validateArgs, };
+export { analyzeHookFile, buildLoaderMap, buildLoaderMap as buildEsbuildLoaderMap, compileHook, detectHookContext, discoverHookFiles, discoverHookFiles as discoverHookSourceFiles, extractPreservedHooks, generateCommandPath, generateContentHash, generateContentHash as sha256Prefix8, generateHooksJson, groupHooksByEventAndMatcher, HOOK_FACTORY_TO_EVENT, hooksMetaPath, mergeHooksJson, moduleWorkingDir, parseArgs, parseLoaderFlag, parseLoaderFlag as parseEsbuildLoaderFlag, pruneStaleHashedBundles, readExistingHooksJson, readHooksMeta, removeStaleGeneratedFiles, symlinkVisiblePath, validateArgs, };

package/dist/scaffold.js

@@ -131,7 +131,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            "@goodfoot/agent-hooks": "^1.0.9",
+            "@goodfoot/agent-hooks": "^1.0.11",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/agent-hooks",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Unified agent hooks library: shared core runtime with per-agent entry points for Claude Code, Codex, and Antigravity",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/agent-hooks",
   "repository": {

package/types/cli.d.ts

@@ -54,7 +54,7 @@ interface CliArgs {
     pluginRoot?: boolean;
     /** Emit hash-free `<name>.mjs` bundles. Defaults to true; set false with --no-stable-names. */
     stableNames?: boolean;
-    /** Embed an inline sourcemap in compiled bundles. Defaults to true; set false with --no-sourcemap. */
+    /** Embed an inline sourcemap in compiled bundles. Defaults to false; enable with --sourcemap. */
     sourcemap?: boolean;
 }
 type HookLoaderMap = Record<string, esbuild.Loader>;
@@ -106,17 +106,22 @@ interface MatcherEntry {
  * The complete hooks.json structure expected by Claude Code.
  *
  * Format: { hooks: { EventType: [ { matcher?, hooks: [...] } ] } }
+ *
+ * `hooks` is the only key that may appear here: the host validates hooks.json
+ * against its own schema and rejects files carrying unknown keys, so build
+ * tracking lives in the sidecar instead (see HooksMeta).
  */
 interface HooksJson {
     /** Object keyed by event type (PreToolUse, SessionStart, etc.). */
     hooks: Partial<Record<HookEventName, MatcherEntry[]>>;
-    /** Generated file tracking metadata. */
-    __generated: {
-        /** Array of generated filenames. */
-        files: string[];
-        /** ISO timestamp of generation. */
-        timestamp: string;
-    };
+}
+/**
+ * Build tracking metadata for a generated hooks.json, written to a sidecar
+ * file beside it (hooks.meta.json) rather than inside hooks.json itself.
+ */
+interface HooksMeta {
+    /** Bundle filenames this package generated, relative to the bin/ directory. */
+    files: string[];
 }
 /**
  * Parses command-line arguments.
@@ -173,14 +178,14 @@ interface CompileHookOptions {
     logEnvVar?: string;
     /** Explicit esbuild loaders for non-code imports. */
     loaders: HookLoaderMap;
-    /** Embed an inline sourcemap in the compiled content. Defaults to true; set false with --no-sourcemap. */
+    /** Embed an inline sourcemap in the compiled content. Defaults to false; enable with --sourcemap. */
     sourcemap?: boolean;
 }
 /**
  * Result of compiling a hook.
  */
 interface CompileHookResult {
-    /** Compiled content, with inline sourcemaps unless disabled. */
+    /** Compiled content, with inline sourcemaps when enabled. */
     content: string;
     /** Stable content hash generated from sourcemap-free output. */
     contentHash: string;
@@ -203,6 +208,17 @@ interface CompileHookResult {
  * checkout-local.
  */
 declare function symlinkVisiblePath(realPath: string, resolveDir: string): string;
+/**
+ * Returns the stable project anchor for a module reached through node_modules.
+ *
+ * esbuild otherwise uses process.cwd() when rendering module-boundary comments
+ * and sourcemap source paths. A workspace script normally runs from the
+ * consuming package, while its dependencies may be hoisted several directories
+ * higher, making those emitted paths depend on the consumer's nesting depth.
+ * Anchoring at the directory which owns the visible node_modules keeps the
+ * canonical `node_modules/...` form in every such layout.
+ */
+declare function moduleWorkingDir(modulePath: string, fallback: string): string;
 /**
  * Compiles a TypeScript hook file to a self-contained ESM executable.
  *
@@ -290,19 +306,40 @@ declare function generateHooksJson(compiledHooks: CompiledHook[], buildDir: stri
  */
 declare function readExistingHooksJson(outputPath: string): HooksJson | undefined;
 /**
- * Removes previously generated hook files from disk.
- * Only removes files that were tracked in __generated.files.
- * @param existingHooksJson - The existing hooks.json content
+ * Absolute path of the tracking sidecar that sits beside hooks.json.
+ * @param outputPath - Path to hooks.json
+ * @returns Path to hooks.meta.json
+ */
+declare function hooksMetaPath(outputPath: string): string;
+/**
+ * Reads the tracking sidecar beside hooks.json if it exists.
+ *
+ * A missing or unreadable sidecar is not fatal: it only means no generated
+ * filenames are known, so every existing entry is treated as externally
+ * authored and preserved.
+ * @param outputPath - Path to the hooks.json the sidecar describes
+ * @returns Parsed HooksMeta or undefined if absent or unusable
+ */
+declare function readHooksMeta(outputPath: string): HooksMeta | undefined;
+/**
+ * Removes bundles a previous build generated that this build did not. Only
+ * filenames tracked in the sidecar are ever removed, and callers must run this
+ * after the new hooks.json is on disk so no reachable state loses a file it
+ * references.
+ * @param previousMeta - Tracking sidecar from the previous build, if any
  * @param outputDir - Directory containing the generated files
+ * @param keepFilenames - Filenames written by the current build
  */
-declare function removeOldGeneratedFiles(existingHooksJson: HooksJson, outputDir: string): void;
+declare function removeStaleGeneratedFiles(previousMeta: HooksMeta | undefined, outputDir: string, keepFilenames: Set<string>): void;
 /**
- * Extracts hooks from an existing hooks.json that were NOT generated by this package.
- * Identifies generated hooks by checking if their command path matches the generated file pattern.
+ * Extracts hooks from an existing hooks.json that were NOT generated by this
+ * package. Generated hooks are identified by the filenames tracked in the
+ * sidecar, so entries authored anywhere else survive a rebuild untouched.
  * @param existingHooksJson - The existing hooks.json content
+ * @param meta - Tracking sidecar from the previous build, if any
  * @returns Object containing preserved hooks (keyed by event type)
  */
-declare function extractPreservedHooks(existingHooksJson: HooksJson): Partial<Record<HookEventName, MatcherEntry[]>>;
+declare function extractPreservedHooks(existingHooksJson: HooksJson, meta: HooksMeta | undefined): Partial<Record<HookEventName, MatcherEntry[]>>;
 /**
  * Merges preserved hooks with newly generated hooks.
  * Preserved hooks are added first, then new hooks are appended.
@@ -312,4 +349,4 @@ declare function extractPreservedHooks(existingHooksJson: HooksJson): Partial<Re
  */
 declare function mergeHooksJson(newHooksJson: HooksJson, preservedHooks: Partial<Record<HookEventName, MatcherEntry[]>>): HooksJson;
 export type { CliArgs, CompiledHook, HookConfig, HookLoaderMap, HookMetadata, HooksJson, MatcherEntry };
-export { analyzeHookFile, buildLoaderMap, buildLoaderMap as buildEsbuildLoaderMap, compileHook, detectHookContext, discoverHookFiles, discoverHookFiles as discoverHookSourceFiles, extractPreservedHooks, generateCommandPath, generateContentHash, generateContentHash as sha256Prefix8, generateHooksJson, groupHooksByEventAndMatcher, HOOK_FACTORY_TO_EVENT, mergeHooksJson, parseArgs, parseLoaderFlag, parseLoaderFlag as parseEsbuildLoaderFlag, pruneStaleHashedBundles, readExistingHooksJson, removeOldGeneratedFiles, symlinkVisiblePath, validateArgs, };
+export { analyzeHookFile, buildLoaderMap, buildLoaderMap as buildEsbuildLoaderMap, compileHook, detectHookContext, discoverHookFiles, discoverHookFiles as discoverHookSourceFiles, extractPreservedHooks, generateCommandPath, generateContentHash, generateContentHash as sha256Prefix8, generateHooksJson, groupHooksByEventAndMatcher, HOOK_FACTORY_TO_EVENT, hooksMetaPath, mergeHooksJson, moduleWorkingDir, parseArgs, parseLoaderFlag, parseLoaderFlag as parseEsbuildLoaderFlag, pruneStaleHashedBundles, readExistingHooksJson, readHooksMeta, removeStaleGeneratedFiles, symlinkVisiblePath, validateArgs, };