@goodfoot/claude-code-hooks 1.2.3 → 1.2.7

package/README.md

@@ -107,25 +107,27 @@ npm test        # Run tests
 
 ### Available Hook Types
 
-The `--hooks` argument accepts a comma-separated list of any of these 15 event types:
-
-| Hook Type            | Description                                |
-| -------------------- | ------------------------------------------ |
-| `PreToolUse`         | Before a tool executes (allow/deny/modify) |
-| `PostToolUse`        | After a tool completes successfully        |
-| `PostToolUseFailure` | After a tool fails                         |
-| `Notification`       | When Claude requests permissions           |
-| `UserPromptSubmit`   | When user submits a prompt                 |
-| `SessionStart`       | When session begins                        |
-| `SessionEnd`         | When session terminates                    |
-| `Stop`               | After main agent finishes                  |
-| `StopFailure`        | When session stops due to an error         |
-| `SubagentStart`      | When an Agent tool starts                   |
-| `SubagentStop`       | When an Agent tool completes                |
-| `PreCompact`         | Before context compaction                  |
-| `PostCompact`        | After context compaction completes         |
-| `PermissionRequest`  | When permission is requested               |
-| `Setup`              | On init, install, or update events         |
+The `--hooks` argument accepts a comma-separated list of any of these 17 event types:
+
+| Hook Type            | Description                                                              |
+| -------------------- | ------------------------------------------------------------------------ |
+| `PreToolUse`         | Before a tool executes (allow/deny/modify)                               |
+| `PostToolUse`        | After a tool completes successfully                                      |
+| `PostToolUseFailure` | After a tool fails                                                       |
+| `Notification`       | When Claude requests permissions                                         |
+| `UserPromptSubmit`   | When user submits a prompt                                               |
+| `SessionStart`       | When session begins                                                      |
+| `SessionEnd`         | When session terminates                                                  |
+| `Stop`               | After main agent finishes                                                |
+| `StopFailure`        | When session stops due to an error                                       |
+| `SubagentStart`      | When an Agent tool starts                                                |
+| `SubagentStop`       | When an Agent tool completes                                             |
+| `PreCompact`         | Before context compaction                                                |
+| `PostCompact`        | After context compaction completes                                       |
+| `PermissionRequest`  | When permission is requested                                             |
+| `Setup`              | On init, install, or update events                                       |
+| `CwdChanged`         | When Claude Code's working directory changes; return `watchPaths` to register paths for `FileChanged` |
+| `FileChanged`        | When a watched file changes on disk (`change`, `add`, or `unlink`); return `watchPaths` to update the watched set |
 
 Hook names are case-insensitive: `stop`, `Stop`, and `STOP` all work.
 
@@ -211,8 +213,11 @@ The Logger is **silent by default** — no output to stdout, stderr, or files un
 # Option A: Environment Variable
 export CLAUDE_CODE_HOOKS_LOG_FILE=/tmp/claude-hooks.log
 
-# Option B: CLI Argument (during build)
+# Option B: CLI Argument — hardcodes path into bundle (runtime CLAUDE_CODE_HOOKS_LOG_FILE overrides)
 npx -y @goodfoot/claude-code-hooks ... --log /tmp/claude-hooks.log
+
+# Option C: CLI Argument — embed the env var name instead of a hardcoded path (good for worktrees)
+npx -y @goodfoot/claude-code-hooks ... --log-env-var CLAUDE_CODE_HOOKS_LOG_FILE
 ```
 
 **View logs:**
@@ -231,9 +236,12 @@ import { Logger } from '@goodfoot/claude-code-hooks';
 // Silent by default — perfect for unit tests
 const logger = new Logger();
 
-// With file output
+// With file output (hardcoded path)
 const fileLogger = new Logger({ logFilePath: '/tmp/my-hooks.log' });
 
+// With dynamic path via env var
+const envLogger = new Logger({ logEnvVar: 'MY_PLUGIN_LOG_FILE' });
+
 // Subscribe to events programmatically
 const unsubscribe = logger.on('error', (event) => {
   sendToMonitoring(event);

package/dist/cli.js

@@ -68,11 +68,19 @@ Scaffold Mode (create new hook project):
 
 Optional Arguments:
   --log <path>
-      Path to a log file for runtime hook logging.
-      If provided, all context.logger calls within your hooks will write to this file.
-      This is equivalent to setting the CLAUDE_CODE_HOOKS_LOG_FILE environment variable.
+      Hardcode a log file path into the compiled bundle.
+      All context.logger calls within your hooks will write to this file.
+      A runtime CLAUDE_CODE_HOOKS_LOG_FILE env var overrides this hardcoded path.
+      Cannot be combined with --log-env-var.
       Example: "/tmp/claude-hooks.log"
 
+  --log-env-var <var>
+      Name of the environment variable that will supply the log file path at runtime.
+      The Logger reads process.env[VAR_NAME] at startup instead of a hardcoded path.
+      Use this when the log path must be determined dynamically (e.g. across worktrees).
+      Cannot be combined with --log.
+      Example: --log-env-var MY_PLUGIN_LOG_FILE
+
   --executable <path>
       Node executable path to use in generated commands (default: "node").
       Use this to specify a custom node path in the generated hooks.json commands.
@@ -88,9 +96,12 @@ Examples:
   1. Basic Compilation:
      npx -y @goodfoot/claude-code-hooks -i "hooks/**/*.ts" -o "dist/hooks.json"
 
-  2. With Runtime Logging:
+  2. With Hardcoded Log Path:
      npx -y @goodfoot/claude-code-hooks -i "src/hooks/*.ts" -o "bin/hooks.json" --log /tmp/claude-hooks.log
 
+  2b. With Dynamic Log Path (env var set at runtime):
+     npx -y @goodfoot/claude-code-hooks -i "src/hooks/*.ts" -o "bin/hooks.json" --log-env-var CLAUDE_CODE_HOOKS_LOG_FILE
+
   3. Scaffold a New Hook Project:
      npx -y @goodfoot/claude-code-hooks --scaffold ./my-hooks --hooks Stop,SubagentStop -o dist/hooks.json
 
@@ -106,7 +117,7 @@ Examples:
 Troubleshooting:
   - Ensure your hook files use 'export default'.
   - Use absolute paths in your glob patterns if relative paths aren't finding files.
-  - Check the log file specified by --log if hooks don't seem to run.
+  - Check the log file specified by --log (or the env var named by --log-env-var) if hooks don't seem to run.
 `;
 // ============================================================================
 // Logging
@@ -182,6 +193,9 @@ function parseArgs(argv) {
             case "--log":
                 args.log = argv[++i];
                 break;
+            case "--log-env-var":
+                args.logEnvVar = argv[++i];
+                break;
             case "-h":
             case "--help":
                 args.help = true;
@@ -227,6 +241,9 @@ function validateArgs(args) {
         return undefined;
     }
     // Normal build mode validation
+    if (args.log !== undefined && args.logEnvVar !== undefined) {
+        return "Cannot use --log and --log-env-var together: choose one method to configure log output";
+    }
     if (args.input === "") {
         return "Missing required argument: -i/--input <glob>";
     }
@@ -386,13 +403,9 @@ async function discoverHookFiles(pattern, cwd) {
  * @returns Compiled content and stable content hash
  */
 async function compileHook(options) {
-    const { sourcePath, logFilePath } = options;
+    const { sourcePath, logFilePath, logEnvVar } = options;
     // Get the path to the runtime module (absolute, then converted to relative)
     const runtimePathAbsolute = path.resolve(path.dirname(new URL(import.meta.url).pathname), "./runtime.js");
-    // Build log file injection code if specified
-    const logFileInjection = logFilePath !== undefined
-        ? `process.env['CLAUDE_CODE_HOOKS_CLI_LOG_FILE'] = ${JSON.stringify(logFilePath)};\n`
-        : "";
     // Compute relative paths from resolveDir to avoid absolute paths in source maps.
     // This ensures reproducible builds regardless of checkout directory.
     const resolveDir = path.dirname(sourcePath);
@@ -400,8 +413,7 @@ async function compileHook(options) {
     const relativeRuntimePath = path.relative(resolveDir, runtimePathAbsolute);
     // Create wrapper content that imports the hook and calls execute
     // Uses relative paths to produce reproducible builds
-    const wrapperContent = `${logFileInjection}
-import hook from '${relativeSourcePath.replace(/\\/g, "/")}';
+    const wrapperContent = `import hook from '${relativeSourcePath.replace(/\\/g, "/")}';
 import { execute } from '${relativeRuntimePath.replace(/\\/g, "/")}';
 
 execute(hook);
@@ -419,6 +431,22 @@ execute(hook);
     // Banner to polyfill CJS globals for dependencies bundled into ESM.
     // Some packages (e.g. typescript) use require(), __filename, and __dirname
     // internally, which are unavailable in ESM scope.
+    //
+    // Log configuration is also embedded here (before all bundled code) so the
+    // Logger singleton reads it at construction time.
+    //
+    // --log PATH:         sets CLAUDE_CODE_HOOKS_LOG_FILE if not already present
+    //                     (runtime env var wins over the hardcoded path)
+    // --log-env-var NAME: unconditionally sets CLAUDE_CODE_HOOKS_LOG_ENV_VAR
+    //                     (the var name is fixed at build time, no runtime override)
+    const logFileLines = logFilePath !== undefined
+        ? [
+            `if (!process.env['CLAUDE_CODE_HOOKS_LOG_FILE']) {`,
+            `  process.env['CLAUDE_CODE_HOOKS_LOG_FILE'] = ${JSON.stringify(logFilePath)};`,
+            `}`,
+        ]
+        : [];
+    const logEnvVarLines = logEnvVar !== undefined ? [`process.env['CLAUDE_CODE_HOOKS_LOG_ENV_VAR'] = ${JSON.stringify(logEnvVar)};`] : [];
     const esmRequireBanner = [
         `import { createRequire as __createRequire } from "node:module";`,
         `import { fileURLToPath as __fileURLToPath } from "node:url";`,
@@ -426,6 +454,8 @@ execute(hook);
         `const require = __createRequire(import.meta.url);`,
         `const __filename = __fileURLToPath(import.meta.url);`,
         `const __dirname = __pathDirname(__filename);`,
+        ...logFileLines,
+        ...logEnvVarLines,
     ].join("\n");
     // Common esbuild options
     const commonOptions = {
@@ -435,6 +465,7 @@ execute(hook);
         target: "node20",
         bundle: true,
         minify: false,
+        minifyWhitespace: true,
         treeShaking: true,
         write: false, // Return content directly via outputFiles
         banner: { js: esmRequireBanner },
@@ -498,7 +529,7 @@ function generateContentHash(content) {
  * @returns Array of compiled hook information
  */
 async function compileAllHooks(options) {
-    const { hookFiles, outputDir, logFilePath } = options;
+    const { hookFiles, outputDir, logFilePath, logEnvVar } = options;
     const compiledHooks = [];
     // Ensure output directory exists
     if (!fs.existsSync(outputDir)) {
@@ -518,7 +549,7 @@ async function compileAllHooks(options) {
         });
         // Compile the hook (two-step process for stable content hash)
         log("info", `Compiling: ${sourcePath}`);
-        const { content, contentHash } = await compileHook({ sourcePath, outputDir, logFilePath });
+        const { content, contentHash } = await compileHook({ sourcePath, outputDir, logFilePath, logEnvVar });
         // Determine output filename using the stable content hash
         const baseName = path.basename(sourcePath, path.extname(sourcePath));
         const outputFilename = `${baseName}.${contentHash}.mjs`;
@@ -803,8 +834,8 @@ function writeHooksJson(hooksJson, outputPath) {
             try {
                 fs.unlinkSync(tempPath);
             }
-            catch {
-                // Ignore cleanup errors
+            catch (cleanupError) {
+                log("warn", "Failed to clean up temp file", { path: tempPath, error: cleanupError });
             }
         }
         throw error;
@@ -852,12 +883,16 @@ async function main() {
         const hooksJsonDir = path.dirname(outputPath);
         // Compiled hooks go in a 'bin' subdirectory relative to hooks.json
         const buildDir = path.join(hooksJsonDir, "bin");
-        // Resolve log file path to absolute if provided
-        const logFilePath = args.log !== undefined ? path.resolve(cwd, args.log) : undefined;
+        // Resolve log file path: --log flag takes priority, then CLAUDE_CODE_HOOKS_LOG_FILE env var
+        const logFileRaw = args.log ?? process.env.CLAUDE_CODE_HOOKS_LOG_FILE;
+        const logFilePath = logFileRaw !== undefined ? path.resolve(cwd, logFileRaw) : undefined;
+        // --log-env-var names the env var the Logger should read at runtime
+        const logEnvVar = args.logEnvVar;
         log("info", "Starting hook compilation", {
             input: args.input,
             output: args.output,
             logFilePath,
+            logEnvVar,
             cwd,
         });
         // Discover hook files
@@ -880,7 +915,7 @@ async function main() {
             log("info", `Preserved ${preservedCount} hooks from other sources`);
         }
         // Compile all hooks
-        const compiledHooks = await compileAllHooks({ hookFiles, outputDir: buildDir, logFilePath });
+        const compiledHooks = await compileAllHooks({ hookFiles, outputDir: buildDir, logFilePath, logEnvVar });
         if (compiledHooks.length === 0 && hookFiles.length > 0) {
             process.stderr.write("Error: No valid hooks found in discovered files.\n");
             process.exit(1);

package/dist/constants.js

@@ -29,4 +29,6 @@ export const HOOK_FACTORY_TO_EVENT = {
     instructionsLoadedHook: "InstructionsLoaded",
     worktreeCreateHook: "WorktreeCreate",
     worktreeRemoveHook: "WorktreeRemove",
+    cwdChangedHook: "CwdChanged",
+    fileChangedHook: "FileChanged",
 };

package/dist/hooks.js

@@ -741,3 +741,67 @@ export function worktreeCreateHook(config, handler) {
 export function worktreeRemoveHook(config, handler) {
     return createHookFunction("WorktreeRemove", config, handler);
 }
+// ============================================================================
+// CwdChanged Hook Factory
+// ============================================================================
+/**
+ * Creates a CwdChanged hook handler.
+ *
+ * CwdChanged hooks fire when Claude Code's current working directory changes,
+ * allowing you to:
+ * - React to directory changes within a session
+ * - Update file watchers or environment state
+ * - Return `watchPaths` via `hookSpecificOutput` to register paths for FileChanged events
+ *
+ * **Matcher**: No matcher support - fires on all cwd change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { cwdChangedHook, cwdChangedOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * export default cwdChangedHook({}, async (input, { logger }) => {
+ *   logger.info('Working directory changed', { from: input.old_cwd, to: input.new_cwd });
+ *   return cwdChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#cwdchanged
+ */
+export function cwdChangedHook(config, handler) {
+    return createHookFunction("CwdChanged", config, handler);
+}
+// ============================================================================
+// FileChanged Hook Factory
+// ============================================================================
+/**
+ * Creates a FileChanged hook handler.
+ *
+ * FileChanged hooks fire when a watched file changes on disk, allowing you to:
+ * - React to file system changes during a session
+ * - Invalidate caches or reload configuration
+ * - Return `watchPaths` via `hookSpecificOutput` to update the set of watched paths
+ *
+ * The input `event` field indicates the type of change:
+ * - `'change'` - File contents changed
+ * - `'add'` - File was created
+ * - `'unlink'` - File was deleted
+ *
+ * **Matcher**: No matcher support - fires on all file change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { fileChangedHook, fileChangedOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * export default fileChangedHook({}, async (input, { logger }) => {
+ *   logger.info('File changed', { path: input.file_path, event: input.event });
+ *   return fileChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#filechanged
+ */
+export function fileChangedHook(config, handler) {
+    return createHookFunction("FileChanged", config, handler);
+}

package/dist/index.js

@@ -11,15 +11,15 @@ export {
 CLAUDE_ENV_VARS, getEnvFilePath, 
 // Getters
 getProjectDir, isRemoteEnvironment, } from "./env.js";
-// Hook factory functions - all 23 hook types
-export { configChangeHook, elicitationHook, elicitationResultHook, instructionsLoadedHook, notificationHook, permissionRequestHook, postCompactHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopFailureHook, stopHook, subagentStartHook, subagentStopHook, taskCompletedHook, teammateIdleHook, userPromptSubmitHook, worktreeCreateHook, worktreeRemoveHook, } from "./hooks.js";
+// Hook factory functions - all 25 hook types
+export { configChangeHook, cwdChangedHook, elicitationHook, elicitationResultHook, fileChangedHook, instructionsLoadedHook, notificationHook, permissionRequestHook, postCompactHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopFailureHook, stopHook, subagentStartHook, subagentStopHook, taskCompletedHook, teammateIdleHook, userPromptSubmitHook, worktreeCreateHook, worktreeRemoveHook, } from "./hooks.js";
 // Logger exports
 export { LOG_LEVELS, Logger, logger } from "./logger.js";
 // Output builder functions
-export { configChangeOutput, 
+export { configChangeOutput, cwdChangedOutput, 
 // Exit codes
-EXIT_CODES, elicitationOutput, elicitationResultOutput, instructionsLoadedOutput, notificationOutput, permissionRequestOutput, postCompactOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, 
-// All 23 output builder functions
+EXIT_CODES, elicitationOutput, elicitationResultOutput, fileChangedOutput, instructionsLoadedOutput, notificationOutput, permissionRequestOutput, postCompactOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, 
+// All 25 output builder functions
 preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopFailureOutput, stopOutput, subagentStartOutput, subagentStopOutput, taskCompletedOutput, teammateIdleOutput, userPromptSubmitOutput, worktreeCreateOutput, worktreeRemoveOutput, } from "./outputs.js";
 // Runtime exports - execute function
 export { 

package/dist/logger.js

@@ -108,8 +108,8 @@ export class Logger {
         for (const level of LOG_LEVELS) {
             this.handlers.set(level, new Set());
         }
-        // Set log file path from config or environment
-        this.logFilePath = config.logFilePath ?? process.env.CLAUDE_CODE_HOOKS_LOG_FILE ?? null;
+        // Set log file path from explicit config, or by reading the configured env var
+        this.logFilePath = config.logFilePath ?? (config.logEnvVar ? process.env[config.logEnvVar] : undefined) ?? null;
     }
     /**
      * Logs a debug message.
@@ -290,8 +290,8 @@ export class Logger {
             try {
                 closeSync(this.logFileFd);
             }
-            catch {
-                // Ignore errors on close
+            catch (closeError) {
+                process.stderr.write(`[claude-code-hooks] Failed to close log file: ${String(closeError)}\n`);
             }
             this.logFileFd = null;
         }
@@ -314,8 +314,8 @@ export class Logger {
             try {
                 closeSync(this.logFileFd);
             }
-            catch {
-                // Ignore errors on close
+            catch (closeError) {
+                process.stderr.write(`[claude-code-hooks] Failed to close log file: ${String(closeError)}\n`);
             }
             this.logFileFd = null;
         }
@@ -366,8 +366,8 @@ export class Logger {
                 try {
                     handler(event);
                 }
-                catch {
-                    // Silently ignore handler errors to not disrupt hook execution
+                catch (handlerError) {
+                    process.stderr.write(`[claude-code-hooks] Log handler error: ${String(handlerError)}\n`);
                 }
             }
         }
@@ -391,10 +391,11 @@ export class Logger {
             const line = `${JSON.stringify(event)}\n`;
             writeSync(this.logFileFd, line);
         }
-        catch {
-            // Silently ignore file write errors to not disrupt hook execution
-            // This follows the risk mitigation: "Graceful degradation - log write
-            // failures are silently ignored to not disrupt hook execution"
+        catch (writeError) {
+            // Disable file logging after a write failure to avoid repeated errors
+            this.logFileFd = null;
+            this.fileInitialized = false;
+            process.stderr.write(`[claude-code-hooks] Log file write failed: ${String(writeError)}\n`);
         }
     }
     /**
@@ -500,4 +501,8 @@ export class Logger {
  * }
  * ```
  */
-export const logger = new Logger();
+// CLAUDE_CODE_HOOKS_LOG_ENV_VAR is set unconditionally by the --log-env-var banner
+// before this module initialises. If absent, fall back to the default env var name.
+export const logger = new Logger({
+    logEnvVar: process.env.CLAUDE_CODE_HOOKS_LOG_ENV_VAR ?? "CLAUDE_CODE_HOOKS_LOG_FILE",
+});

package/dist/outputs.js

@@ -431,3 +431,39 @@ export const worktreeCreateOutput = /* @__PURE__ */ createSimpleOutputBuilder("W
  * ```
  */
 export const worktreeRemoveOutput = /* @__PURE__ */ createSimpleOutputBuilder("WorktreeRemove");
+/**
+ * Creates an output for CwdChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A CwdChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Return additional paths to watch after the cwd change
+ * cwdChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/new/path/to/watch']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * cwdChangedOutput({});
+ * ```
+ */
+export const cwdChangedOutput = /* @__PURE__ */ createHookSpecificOutputBuilder("CwdChanged");
+/**
+ * Creates an output for FileChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A FileChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Update the set of watched paths
+ * fileChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/path/to/watch', '/another/path']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * fileChangedOutput({});
+ * ```
+ */
+export const fileChangedOutput = /* @__PURE__ */ createHookSpecificOutputBuilder("FileChanged");

package/dist/runtime.js

@@ -161,21 +161,6 @@ export function convertToHookOutput(specificOutput) {
 export async function execute(hookFn) {
     let output;
     try {
-        // Check for log file configuration conflicts
-        // CLAUDE_CODE_HOOKS_CLI_LOG_FILE is injected by the CLI --log parameter
-        // CLAUDE_CODE_HOOKS_LOG_FILE is the user's environment variable
-        const cliLogFile = process.env.CLAUDE_CODE_HOOKS_CLI_LOG_FILE;
-        const envLogFile = process.env.CLAUDE_CODE_HOOKS_LOG_FILE;
-        if (cliLogFile !== undefined && envLogFile !== undefined && cliLogFile !== envLogFile) {
-            // Write error to stderr and exit with error code
-            process.stderr.write(`Log file configuration conflict: CLI --log="${cliLogFile}" vs CLAUDE_CODE_HOOKS_LOG_FILE="${envLogFile}". ` +
-                "Use only one method to configure hook logging.\n");
-            process.exit(EXIT_CODES.ERROR);
-        }
-        // If CLI log file is set, configure the logger
-        if (cliLogFile !== undefined) {
-            logger.setLogFile(cliLogFile);
-        }
         // Read and parse stdin
         let stdinContent;
         try {

package/dist/scaffold.js

@@ -60,6 +60,8 @@ const EVENT_TO_OUTPUT_FUNCTION = {
     InstructionsLoaded: "instructionsLoadedOutput",
     WorktreeCreate: "worktreeCreateOutput",
     WorktreeRemove: "worktreeRemoveOutput",
+    CwdChanged: "cwdChangedOutput",
+    FileChanged: "fileChangedOutput",
 };
 // ============================================================================
 // Validation
@@ -127,7 +129,7 @@ function generatePackageJson(projectName, outputPath) {
             "@goodfoot/claude-code-hooks": "^1.0.9",
         },
         devDependencies: {
-            "@biomejs/biome": "2.4.8",
+            "@biomejs/biome": "2.4.9",
             "@types/node": "^22.0.0",
             typescript: "^5.9.3",
             vitest: "^4.0.16",
@@ -170,7 +172,7 @@ function generateTsConfig() {
  */
 function generateBiomeConfig() {
     return `{
-  "$schema": "https://biomejs.dev/schemas/2.4.8/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.9/schema.json",
   "formatter": {
     "enabled": true,
     "indentStyle": "space",

package/dist/types.js

@@ -43,4 +43,6 @@ export const HOOK_EVENT_NAMES = [
     "InstructionsLoaded",
     "WorktreeCreate",
     "WorktreeRemove",
+    "CwdChanged",
+    "FileChanged",
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/claude-code-hooks",
-  "version": "1.2.3",
+  "version": "1.2.7",
   "description": "Type-safe Claude Code hooks library with camelCase types and output builders",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/claude-code-hooks",
   "repository": {
@@ -27,9 +27,7 @@
     "release": "bash ../../scripts/release-package.sh claude-code-hooks",
     "release:dry-run": "bash ../../scripts/release-package.sh claude-code-hooks --dry-run",
     "snapshot:sdk-types": "tsx scripts/snapshot-sdk-types.ts",
-    "upgrade:deps": "./scripts/upgrade-deps.sh",
-    "update:docs": "./scripts/update-docs.sh",
-    "update:docs:dry-run": "./scripts/update-docs.sh --dry-run"
+    "upgrade:deps": "./scripts/upgrade-deps.sh"
   },
   "exports": {
     ".": {
@@ -53,8 +51,8 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.80",
-    "@biomejs/biome": "2.4.8",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.83",
+    "@biomejs/biome": "2.4.9",
     "@types/node": "^24",
     "ts-morph": "^25.0.0",
     "tsx": "^4.20.3",

package/types/cli.d.ts

@@ -31,8 +31,10 @@ interface CliArgs {
     input: string;
     /** Path for hooks.json output file. */
     output: string;
-    /** Optional log file path. */
+    /** Optional log file path (hardcoded into bundle). */
     log?: string;
+    /** Optional env var name whose value supplies the log file path at runtime. */
+    logEnvVar?: string;
     /** Show help. */
     help: boolean;
     /** Show version. */
@@ -148,8 +150,10 @@ interface CompileHookOptions {
     sourcePath: string;
     /** Directory for compiled output. */
     outputDir: string;
-    /** Optional log file path to inject into compiled hook. */
+    /** Optional log file path to hardcode into the bundle via the banner. */
     logFilePath?: string;
+    /** Optional env var name the Logger should read for the log file path at runtime. */
+    logEnvVar?: string;
 }
 /**
  * Result of compiling a hook.

package/types/hooks.d.ts

@@ -22,8 +22,8 @@
  * @see https://code.claude.com/docs/en/hooks
  */
 import type { Logger } from "./logger.js";
-import type { ConfigChangeOutput, ElicitationOutput, ElicitationResultOutput, InstructionsLoadedOutput, NotificationOutput, PermissionRequestOutput, PostCompactOutput, PostToolUseFailureOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionEndOutput, SessionStartOutput, SetupOutput, SpecificHookOutput, StopFailureOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, TaskCompletedOutput, TeammateIdleOutput, UserPromptSubmitOutput, WorktreeCreateOutput, WorktreeRemoveOutput } from "./outputs.js";
-import type { ConfigChangeInput, ElicitationInput, ElicitationResultInput, HookEventName, InstructionsLoadedInput, KnownToolName, NotificationInput, PermissionRequestInput, PostCompactInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionEndInput, SessionStartInput, SetupInput, StopFailureInput, StopInput, SubagentStartInput, SubagentStopInput, TaskCompletedInput, TeammateIdleInput, ToolInputMap, UserPromptSubmitInput, WorktreeCreateInput, WorktreeRemoveInput } from "./types.js";
+import type { ConfigChangeOutput, CwdChangedOutput, ElicitationOutput, ElicitationResultOutput, FileChangedOutput, InstructionsLoadedOutput, NotificationOutput, PermissionRequestOutput, PostCompactOutput, PostToolUseFailureOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionEndOutput, SessionStartOutput, SetupOutput, SpecificHookOutput, StopFailureOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, TaskCompletedOutput, TeammateIdleOutput, UserPromptSubmitOutput, WorktreeCreateOutput, WorktreeRemoveOutput } from "./outputs.js";
+import type { ConfigChangeInput, CwdChangedInput, ElicitationInput, ElicitationResultInput, FileChangedInput, HookEventName, InstructionsLoadedInput, KnownToolName, NotificationInput, PermissionRequestInput, PostCompactInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionEndInput, SessionStartInput, SetupInput, StopFailureInput, StopInput, SubagentStartInput, SubagentStopInput, TaskCompletedInput, TeammateIdleInput, ToolInputMap, UserPromptSubmitInput, WorktreeCreateInput, WorktreeRemoveInput } from "./types.js";
 /**
  * Configuration options for hook factories.
  *
@@ -1072,4 +1072,58 @@ export declare function worktreeCreateHook(config: HookConfig, handler: HookHand
  * @see https://code.claude.com/docs/en/hooks#worktreeremove
  */
 export declare function worktreeRemoveHook(config: HookConfig, handler: HookHandler<WorktreeRemoveInput, WorktreeRemoveOutput>): HookFunction<WorktreeRemoveInput, WorktreeRemoveOutput>;
+/**
+ * Creates a CwdChanged hook handler.
+ *
+ * CwdChanged hooks fire when Claude Code's current working directory changes,
+ * allowing you to:
+ * - React to directory changes within a session
+ * - Update file watchers or environment state
+ * - Return `watchPaths` via `hookSpecificOutput` to register paths for FileChanged events
+ *
+ * **Matcher**: No matcher support - fires on all cwd change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { cwdChangedHook, cwdChangedOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * export default cwdChangedHook({}, async (input, { logger }) => {
+ *   logger.info('Working directory changed', { from: input.old_cwd, to: input.new_cwd });
+ *   return cwdChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#cwdchanged
+ */
+export declare function cwdChangedHook(config: HookConfig, handler: HookHandler<CwdChangedInput, CwdChangedOutput>): HookFunction<CwdChangedInput, CwdChangedOutput>;
+/**
+ * Creates a FileChanged hook handler.
+ *
+ * FileChanged hooks fire when a watched file changes on disk, allowing you to:
+ * - React to file system changes during a session
+ * - Invalidate caches or reload configuration
+ * - Return `watchPaths` via `hookSpecificOutput` to update the set of watched paths
+ *
+ * The input `event` field indicates the type of change:
+ * - `'change'` - File contents changed
+ * - `'add'` - File was created
+ * - `'unlink'` - File was deleted
+ *
+ * **Matcher**: No matcher support - fires on all file change events
+ * @param config - Hook configuration with optional timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { fileChangedHook, fileChangedOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * export default fileChangedHook({}, async (input, { logger }) => {
+ *   logger.info('File changed', { path: input.file_path, event: input.event });
+ *   return fileChangedOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#filechanged
+ */
+export declare function fileChangedHook(config: HookConfig, handler: HookHandler<FileChangedInput, FileChangedOutput>): HookFunction<FileChangedInput, FileChangedOutput>;
 export {};

package/types/index.d.ts

@@ -8,15 +8,15 @@
 export type * from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 export { CLAUDE_ENV_VARS, getEnvFilePath, getProjectDir, isRemoteEnvironment, } from "./env.js";
 export type { HookConfig, HookContext, HookFunction, HookHandler, SessionStartContext, TypedHookConfig, TypedPermissionRequestInput, TypedPostToolUseFailureHookInput, TypedPostToolUseHookInput, TypedPreToolUseHookInput, } from "./hooks.js";
-export { configChangeHook, elicitationHook, elicitationResultHook, instructionsLoadedHook, notificationHook, permissionRequestHook, postCompactHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopFailureHook, stopHook, subagentStartHook, subagentStopHook, taskCompletedHook, teammateIdleHook, userPromptSubmitHook, worktreeCreateHook, worktreeRemoveHook, } from "./hooks.js";
+export { configChangeHook, cwdChangedHook, elicitationHook, elicitationResultHook, fileChangedHook, instructionsLoadedHook, notificationHook, permissionRequestHook, postCompactHook, postToolUseFailureHook, postToolUseHook, preCompactHook, preToolUseHook, sessionEndHook, sessionStartHook, setupHook, stopFailureHook, stopHook, subagentStartHook, subagentStopHook, taskCompletedHook, teammateIdleHook, userPromptSubmitHook, worktreeCreateHook, worktreeRemoveHook, } from "./hooks.js";
 export type { LogEvent, LogEventError, LogEventHandler, LoggerConfig, LogLevel, Unsubscribe } from "./logger.js";
 export { LOG_LEVELS, Logger, logger } from "./logger.js";
 export type { 
 /** @deprecated Use CommonOptions instead */
-BaseOptions, CommonOptions, ConfigChangeOptions, ElicitationHookSpecificOutput, ElicitationOptions, ElicitationResultHookSpecificOutput, ElicitationResultOptions, ExitCode, ExitCodeOptions, HookOutput, HookSpecificOutput, InstructionsLoadedOptions, NotificationHookSpecificOutput, NotificationOptions, PermissionRequestAllowDecision, PermissionRequestDecision, PermissionRequestDenyDecision, PermissionRequestHookSpecificOutput, PermissionRequestOptions, PostCompactOptions, PostToolUseFailureHookSpecificOutput, PostToolUseFailureOptions, PostToolUseHookSpecificOutput, PostToolUseOptions, PreCompactOptions, PreToolUseHookSpecificOutput, PreToolUseOptions, SessionEndOptions, SessionStartHookSpecificOutput, SessionStartOptions, SetupHookSpecificOutput, SetupOptions, StopFailureOptions, StopOptions, SubagentStartHookSpecificOutput, SubagentStartOptions, SubagentStopOptions, SyncHookJSONOutput, TaskCompletedOptions, TeammateIdleOptions, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, WorktreeCreateOptions, WorktreeRemoveOptions, } from "./outputs.js";
-export { configChangeOutput, EXIT_CODES, elicitationOutput, elicitationResultOutput, instructionsLoadedOutput, notificationOutput, permissionRequestOutput, postCompactOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopFailureOutput, stopOutput, subagentStartOutput, subagentStopOutput, taskCompletedOutput, teammateIdleOutput, userPromptSubmitOutput, worktreeCreateOutput, worktreeRemoveOutput, } from "./outputs.js";
+BaseOptions, CommonOptions, ConfigChangeOptions, CwdChangedHookSpecificOutput, CwdChangedOptions, ElicitationHookSpecificOutput, ElicitationOptions, ElicitationResultHookSpecificOutput, ElicitationResultOptions, ExitCode, ExitCodeOptions, FileChangedHookSpecificOutput, FileChangedOptions, HookOutput, HookSpecificOutput, InstructionsLoadedOptions, NotificationHookSpecificOutput, NotificationOptions, PermissionRequestAllowDecision, PermissionRequestDecision, PermissionRequestDenyDecision, PermissionRequestHookSpecificOutput, PermissionRequestOptions, PostCompactOptions, PostToolUseFailureHookSpecificOutput, PostToolUseFailureOptions, PostToolUseHookSpecificOutput, PostToolUseOptions, PreCompactOptions, PreToolUseHookSpecificOutput, PreToolUseOptions, SessionEndOptions, SessionStartHookSpecificOutput, SessionStartOptions, SetupHookSpecificOutput, SetupOptions, StopFailureOptions, StopOptions, SubagentStartHookSpecificOutput, SubagentStartOptions, SubagentStopOptions, SyncHookJSONOutput, TaskCompletedOptions, TeammateIdleOptions, UserPromptSubmitHookSpecificOutput, UserPromptSubmitOptions, WorktreeCreateOptions, WorktreeRemoveOptions, } from "./outputs.js";
+export { configChangeOutput, cwdChangedOutput, EXIT_CODES, elicitationOutput, elicitationResultOutput, fileChangedOutput, instructionsLoadedOutput, notificationOutput, permissionRequestOutput, postCompactOutput, postToolUseFailureOutput, postToolUseOutput, preCompactOutput, preToolUseOutput, sessionEndOutput, sessionStartOutput, setupOutput, stopFailureOutput, stopOutput, subagentStartOutput, subagentStopOutput, taskCompletedOutput, teammateIdleOutput, userPromptSubmitOutput, worktreeCreateOutput, worktreeRemoveOutput, } from "./outputs.js";
 export { execute, } from "./runtime.js";
 export type { ContentContext, PatternCheckResult, ToolUseInput } from "./tool-helpers.js";
 export { checkContentForPattern, forEachContent, getFilePath, isAskUserQuestionTool, isBashTool, isConfigTool, isEditTool, isExitPlanModeTool, isFileModifyingTool, isGlobTool, isGrepTool, isJsTsFile, isKillShellTool, isListMcpResourcesTool, isMcpTool, isMultiEditTool, isNotebookEditTool, isReadMcpResourceTool, isReadTool, isTaskOutputTool, isTaskTool, isTodoWriteTool, isTsFile, isWebFetchTool, isWebSearchTool, isWriteTool, } from "./tool-helpers.js";
-export type { BaseHookInput, ConfigChangeInput, ConfigInput, ElicitationInput, ElicitationResultInput, FileModifyingToolInput, FileModifyingToolName, HookEventName, HookInput, InstructionsLoadedInput, KnownToolInput, KnownToolName, ListMcpResourcesInput, McpInput, MultiEditEntry, MultiEditToolInput, NotificationInput, PermissionMode, PermissionRequestInput, PermissionUpdate, PostCompactInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreCompactTrigger, PreToolUseInput, ReadMcpResourceInput, SessionEndInput, SessionEndReason, SessionStartInput, SessionStartSource, SetupInput, SetupTrigger, StopFailureInput, StopInput, SubagentStartInput, SubagentStopInput, TaskCompletedInput, TeammateIdleInput, ToolInputMap, UserPromptSubmitInput, WorktreeCreateInput, WorktreeRemoveInput, } from "./types.js";
+export type { BaseHookInput, ConfigChangeInput, ConfigInput, CwdChangedInput, ElicitationInput, ElicitationResultInput, FileChangedInput, FileModifyingToolInput, FileModifyingToolName, HookEventName, HookInput, InstructionsLoadedInput, KnownToolInput, KnownToolName, ListMcpResourcesInput, McpInput, MultiEditEntry, MultiEditToolInput, NotificationInput, PermissionMode, PermissionRequestInput, PermissionUpdate, PostCompactInput, PostToolUseFailureInput, PostToolUseInput, PreCompactInput, PreCompactTrigger, PreToolUseInput, ReadMcpResourceInput, SessionEndInput, SessionEndReason, SessionStartInput, SessionStartSource, SetupInput, SetupTrigger, StopFailureInput, StopInput, SubagentStartInput, SubagentStopInput, TaskCompletedInput, TeammateIdleInput, ToolInputMap, UserPromptSubmitInput, WorktreeCreateInput, WorktreeRemoveInput, } from "./types.js";
 export { HOOK_EVENT_NAMES } from "./types.js";

package/types/logger.d.ts

@@ -147,9 +147,15 @@ export interface LoggerConfig {
     /**
      * Path to the log file for file output.
      * If not set, file logging is disabled.
-     * Can also be set via `CLAUDE_CODE_HOOKS_LOG_FILE` environment variable.
      */
     logFilePath?: string;
+    /**
+     * Name of the environment variable to read for the log file path.
+     * When set, the Logger reads `process.env[logEnvVar]` at construction time.
+     * Ignored if `logFilePath` is also provided.
+     * Defaults to `'CLAUDE_CODE_HOOKS_LOG_FILE'` for the exported singleton.
+     */
+    logEnvVar?: string;
 }
 /**
  * Logger for Claude Code hooks with event subscription and file output.

package/types/outputs.d.ts

@@ -7,7 +7,7 @@
  * @see https://code.claude.com/docs/en/hooks
  * @module
  */
-import type { ElicitationHookSpecificOutput as SDKElicitationHookSpecificOutput, ElicitationResultHookSpecificOutput as SDKElicitationResultHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk";
+import type { CwdChangedHookSpecificOutput as SDKCwdChangedHookSpecificOutput, ElicitationHookSpecificOutput as SDKElicitationHookSpecificOutput, ElicitationResultHookSpecificOutput as SDKElicitationResultHookSpecificOutput, FileChangedHookSpecificOutput as SDKFileChangedHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk";
 import type { NotificationHookSpecificOutput as SDKNotificationHookSpecificOutput, PermissionRequestHookSpecificOutput as SDKPermissionRequestHookSpecificOutput, PostToolUseFailureHookSpecificOutput as SDKPostToolUseFailureHookSpecificOutput, PostToolUseHookSpecificOutput as SDKPostToolUseHookSpecificOutput, PreToolUseHookSpecificOutput as SDKPreToolUseHookSpecificOutput, SessionStartHookSpecificOutput as SDKSessionStartHookSpecificOutput, SetupHookSpecificOutput as SDKSetupHookSpecificOutput, SubagentStartHookSpecificOutput as SDKSubagentStartHookSpecificOutput, SyncHookJSONOutput as SDKSyncHookJSONOutput, UserPromptSubmitHookSpecificOutput as SDKUserPromptSubmitHookSpecificOutput } from "@anthropic-ai/claude-agent-sdk/sdk.js";
 /**
  * Exit codes used by Claude Code hooks.
@@ -36,7 +36,7 @@ export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
 /**
  * Re-export SDK hook-specific output types (includes hookEventName discriminator).
  */
-export type { SDKElicitationHookSpecificOutput, SDKElicitationResultHookSpecificOutput, SDKNotificationHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPreToolUseHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKSyncHookJSONOutput, SDKUserPromptSubmitHookSpecificOutput, };
+export type { SDKCwdChangedHookSpecificOutput, SDKElicitationHookSpecificOutput, SDKElicitationResultHookSpecificOutput, SDKFileChangedHookSpecificOutput, SDKNotificationHookSpecificOutput, SDKPermissionRequestHookSpecificOutput, SDKPostToolUseFailureHookSpecificOutput, SDKPostToolUseHookSpecificOutput, SDKPreToolUseHookSpecificOutput, SDKSessionStartHookSpecificOutput, SDKSetupHookSpecificOutput, SDKSubagentStartHookSpecificOutput, SDKSyncHookJSONOutput, SDKUserPromptSubmitHookSpecificOutput, };
 /**
  * PreToolUse hook-specific output fields.
  * Omits `hookEventName` which is added automatically by the builder.
@@ -111,10 +111,20 @@ export type PermissionRequestDecision = SDKPermissionRequestHookSpecificOutput["
  * Omits `hookEventName` which is added automatically by the builder.
  */
 export type NotificationHookSpecificOutput = Omit<SDKNotificationHookSpecificOutput, "hookEventName">;
+/**
+ * CwdChanged hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type CwdChangedHookSpecificOutput = Omit<SDKCwdChangedHookSpecificOutput, "hookEventName">;
+/**
+ * FileChanged hook-specific output fields.
+ * Omits `hookEventName` which is added automatically by the builder.
+ */
+export type FileChangedHookSpecificOutput = Omit<SDKFileChangedHookSpecificOutput, "hookEventName">;
 /**
  * Full hook-specific output with hookEventName discriminator.
  */
-export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | SDKNotificationHookSpecificOutput | SDKElicitationHookSpecificOutput | SDKElicitationResultHookSpecificOutput;
+export type HookSpecificOutput = SDKPreToolUseHookSpecificOutput | SDKPostToolUseHookSpecificOutput | SDKPostToolUseFailureHookSpecificOutput | SDKUserPromptSubmitHookSpecificOutput | SDKSessionStartHookSpecificOutput | SDKSetupHookSpecificOutput | SDKSubagentStartHookSpecificOutput | SDKPermissionRequestHookSpecificOutput | SDKNotificationHookSpecificOutput | SDKElicitationHookSpecificOutput | SDKElicitationResultHookSpecificOutput | SDKCwdChangedHookSpecificOutput | SDKFileChangedHookSpecificOutput;
 /**
  * The JSON output format expected by Claude Code (sync hooks only).
  * Extends SDK's SyncHookJSONOutput to include Notification hook support.
@@ -270,10 +280,18 @@ export type WorktreeCreateOutput = BaseSpecificOutput<"WorktreeCreate">;
  *
  */
 export type WorktreeRemoveOutput = BaseSpecificOutput<"WorktreeRemove">;
+/**
+ *
+ */
+export type CwdChangedOutput = BaseSpecificOutput<"CwdChanged">;
+/**
+ *
+ */
+export type FileChangedOutput = BaseSpecificOutput<"FileChanged">;
 /**
  * Union of all specific output types.
  */
-export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PostToolUseFailureOutput | NotificationOutput | UserPromptSubmitOutput | SessionStartOutput | SessionEndOutput | StopOutput | StopFailureOutput | SubagentStartOutput | SubagentStopOutput | PreCompactOutput | PostCompactOutput | PermissionRequestOutput | SetupOutput | TeammateIdleOutput | TaskCompletedOutput | ElicitationOutput | ElicitationResultOutput | ConfigChangeOutput | InstructionsLoadedOutput | WorktreeCreateOutput | WorktreeRemoveOutput;
+export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PostToolUseFailureOutput | NotificationOutput | UserPromptSubmitOutput | SessionStartOutput | SessionEndOutput | StopOutput | StopFailureOutput | SubagentStartOutput | SubagentStopOutput | PreCompactOutput | PostCompactOutput | PermissionRequestOutput | SetupOutput | TeammateIdleOutput | TaskCompletedOutput | ElicitationOutput | ElicitationResultOutput | ConfigChangeOutput | InstructionsLoadedOutput | WorktreeCreateOutput | WorktreeRemoveOutput | CwdChangedOutput | FileChangedOutput;
 /**
  * Options for decision-based hooks (Stop, SubagentStop).
  */
@@ -866,6 +884,66 @@ export declare const worktreeRemoveOutput: (options?: CommonOptions) => {
     readonly _type: "WorktreeRemove";
     stdout: SyncHookJSONOutput;
 };
+/**
+ * Options for the CwdChanged output builder.
+ */
+export type CwdChangedOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: CwdChangedHookSpecificOutput;
+};
+/**
+ * Creates an output for CwdChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A CwdChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Return additional paths to watch after the cwd change
+ * cwdChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/new/path/to/watch']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * cwdChangedOutput({});
+ * ```
+ */
+export declare const cwdChangedOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: CwdChangedHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "CwdChanged";
+    stdout: SyncHookJSONOutput;
+};
+/**
+ * Options for the FileChanged output builder.
+ */
+export type FileChangedOptions = CommonOptions & {
+    /** Hook-specific output matching the wire format. */
+    hookSpecificOutput?: FileChangedHookSpecificOutput;
+};
+/**
+ * Creates an output for FileChanged hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A FileChangedOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Update the set of watched paths
+ * fileChangedOutput({
+ *   hookSpecificOutput: {
+ *     watchPaths: ['/path/to/watch', '/another/path']
+ *   }
+ * });
+ *
+ * // Simple passthrough
+ * fileChangedOutput({});
+ * ```
+ */
+export declare const fileChangedOutput: (options?: CommonOptions & {
+    hookSpecificOutput?: FileChangedHookSpecificOutput | undefined;
+}) => {
+    readonly _type: "FileChanged";
+    stdout: SyncHookJSONOutput;
+};
 /**
  * @deprecated Use CommonOptions instead
  */

package/types/types.d.ts

@@ -12,8 +12,8 @@
  * Re-exports types from @anthropic-ai/claude-agent-sdk with "SDK" prefix.
  * These are used as base types for extension, ensuring synchronization with the SDK.
  */
-export type { BaseHookInput as SDKBaseHookInput, ConfigChangeHookInput as SDKConfigChangeHookInput, ElicitationHookInput as SDKElicitationHookInput, ElicitationResultHookInput as SDKElicitationResultHookInput, HookEvent as SDKHookEvent, HookInput as SDKHookInput, InstructionsLoadedHookInput as SDKInstructionsLoadedHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostCompactHookInput as SDKPostCompactHookInput, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopFailureHookInput as SDKStopFailureHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, TaskCompletedHookInput as SDKTaskCompletedHookInput, TeammateIdleHookInput as SDKTeammateIdleHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, WorktreeCreateHookInput as SDKWorktreeCreateHookInput, WorktreeRemoveHookInput as SDKWorktreeRemoveHookInput, } from "@anthropic-ai/claude-agent-sdk";
-import type { BaseHookInput as SDKBaseHookInput, ConfigChangeHookInput as SDKConfigChangeHookInput, ElicitationHookInput as SDKElicitationHookInput, ElicitationResultHookInput as SDKElicitationResultHookInput, InstructionsLoadedHookInput as SDKInstructionsLoadedHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostCompactHookInput as SDKPostCompactHookInput, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopFailureHookInput as SDKStopFailureHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, TaskCompletedHookInput as SDKTaskCompletedHookInput, TeammateIdleHookInput as SDKTeammateIdleHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, WorktreeCreateHookInput as SDKWorktreeCreateHookInput, WorktreeRemoveHookInput as SDKWorktreeRemoveHookInput } from "@anthropic-ai/claude-agent-sdk";
+export type { BaseHookInput as SDKBaseHookInput, ConfigChangeHookInput as SDKConfigChangeHookInput, CwdChangedHookInput as SDKCwdChangedHookInput, ElicitationHookInput as SDKElicitationHookInput, ElicitationResultHookInput as SDKElicitationResultHookInput, FileChangedHookInput as SDKFileChangedHookInput, HookEvent as SDKHookEvent, HookInput as SDKHookInput, InstructionsLoadedHookInput as SDKInstructionsLoadedHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostCompactHookInput as SDKPostCompactHookInput, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopFailureHookInput as SDKStopFailureHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, TaskCompletedHookInput as SDKTaskCompletedHookInput, TeammateIdleHookInput as SDKTeammateIdleHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, WorktreeCreateHookInput as SDKWorktreeCreateHookInput, WorktreeRemoveHookInput as SDKWorktreeRemoveHookInput, } from "@anthropic-ai/claude-agent-sdk";
+import type { BaseHookInput as SDKBaseHookInput, ConfigChangeHookInput as SDKConfigChangeHookInput, CwdChangedHookInput as SDKCwdChangedHookInput, ElicitationHookInput as SDKElicitationHookInput, ElicitationResultHookInput as SDKElicitationResultHookInput, FileChangedHookInput as SDKFileChangedHookInput, InstructionsLoadedHookInput as SDKInstructionsLoadedHookInput, NotificationHookInput as SDKNotificationHookInput, PermissionMode as SDKPermissionMode, PermissionRequestHookInput as SDKPermissionRequestHookInput, PermissionUpdate as SDKPermissionUpdate, PostCompactHookInput as SDKPostCompactHookInput, PostToolUseFailureHookInput as SDKPostToolUseFailureHookInput, PostToolUseHookInput as SDKPostToolUseHookInput, PreCompactHookInput as SDKPreCompactHookInput, PreToolUseHookInput as SDKPreToolUseHookInput, SessionEndHookInput as SDKSessionEndHookInput, SessionStartHookInput as SDKSessionStartHookInput, SetupHookInput as SDKSetupHookInput, StopFailureHookInput as SDKStopFailureHookInput, StopHookInput as SDKStopHookInput, SubagentStartHookInput as SDKSubagentStartHookInput, SubagentStopHookInput as SDKSubagentStopHookInput, TaskCompletedHookInput as SDKTaskCompletedHookInput, TeammateIdleHookInput as SDKTeammateIdleHookInput, UserPromptSubmitHookInput as SDKUserPromptSubmitHookInput, WorktreeCreateHookInput as SDKWorktreeCreateHookInput, WorktreeRemoveHookInput as SDKWorktreeRemoveHookInput } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentInput, AskUserQuestionInput, BashInput, ConfigInput, ExitPlanModeInput, FileEditInput, FileReadInput, FileWriteInput, GlobInput, GrepInput, TaskStopInput as KillShellInput, ListMcpResourcesInput, McpInput, NotebookEditInput, ReadMcpResourceInput, TaskOutputInput, TodoWriteInput, WebFetchInput, WebSearchInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 /**
  * Permission mode for controlling how tool executions are handled.
@@ -258,6 +258,35 @@ export type WorktreeCreateInput = {
 export type WorktreeRemoveInput = {
     [K in keyof SDKWorktreeRemoveHookInput]: SDKWorktreeRemoveHookInput[K];
 } & {};
+/**
+ * Input for CwdChanged hooks.
+ *
+ * Fires when Claude Code's current working directory changes, allowing you to:
+ * - React to directory changes within a session
+ * - Update file watchers or environment state
+ * - Return `watchPaths` to register paths for FileChanged events
+ * @see https://code.claude.com/docs/en/hooks#cwdchanged
+ */
+export type CwdChangedInput = {
+    [K in keyof SDKCwdChangedHookInput]: SDKCwdChangedHookInput[K];
+} & {};
+/**
+ * Input for FileChanged hooks.
+ *
+ * Fires when a watched file changes on disk, allowing you to:
+ * - React to file system changes during a session
+ * - Invalidate caches or reload configuration
+ * - Return `watchPaths` to update the set of watched paths
+ *
+ * The `event` field indicates the type of change:
+ * - `'change'` - File contents changed
+ * - `'add'` - File was created
+ * - `'unlink'` - File was deleted
+ * @see https://code.claude.com/docs/en/hooks#filechanged
+ */
+export type FileChangedInput = {
+    [K in keyof SDKFileChangedHookInput]: SDKFileChangedHookInput[K];
+} & {};
 /**
  * Input for SessionEnd hooks.
  *
@@ -352,7 +381,7 @@ export type SetupTrigger = "init" | "maintenance";
  * ```
  * @see https://code.claude.com/docs/en/hooks
  */
-export type HookInput = PreToolUseInput | PostToolUseInput | PostToolUseFailureInput | NotificationInput | UserPromptSubmitInput | SessionStartInput | SessionEndInput | StopInput | StopFailureInput | SubagentStartInput | SubagentStopInput | PreCompactInput | PostCompactInput | PermissionRequestInput | SetupInput | TeammateIdleInput | TaskCompletedInput | ElicitationInput | ElicitationResultInput | ConfigChangeInput | InstructionsLoadedInput | WorktreeCreateInput | WorktreeRemoveInput;
+export type HookInput = PreToolUseInput | PostToolUseInput | PostToolUseFailureInput | NotificationInput | UserPromptSubmitInput | SessionStartInput | SessionEndInput | StopInput | StopFailureInput | SubagentStartInput | SubagentStopInput | PreCompactInput | PostCompactInput | PermissionRequestInput | SetupInput | TeammateIdleInput | TaskCompletedInput | ElicitationInput | ElicitationResultInput | ConfigChangeInput | InstructionsLoadedInput | WorktreeCreateInput | WorktreeRemoveInput | CwdChangedInput | FileChangedInput;
 /**
  * Hook event name literal union.
  *
@@ -370,7 +399,7 @@ export type HookEventName = HookInput["hook_event_name"];
  * }
  * ```
  */
-export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "Setup", "TeammateIdle", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "InstructionsLoaded", "WorktreeCreate", "WorktreeRemove"];
+export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "Setup", "TeammateIdle", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "InstructionsLoaded", "WorktreeCreate", "WorktreeRemove", "CwdChanged", "FileChanged"];
 export type { SDKPermissionUpdate as PermissionUpdate };
 /**
  * Re-export all tool input types from the official Claude Agent SDK.