praxis-agent 0.30.0 → 0.32.0

package/dist/hooks/claude-file-change-watcher.js

@@ -0,0 +1,185 @@
+import { existsSync, watch } from 'node:fs';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+function defaultWatchDirectory(directory, listener) {
+    return watch(directory, (_event, filename) => {
+        listener(filename);
+    });
+}
+export class ClaudeFileChangeWatcher {
+    options;
+    cwd;
+    staticPaths;
+    dynamicPaths = [];
+    watchers = new Map();
+    knownExistence = new Map();
+    pending = new Map();
+    inFlight = new Map();
+    debounceMs;
+    pathExists;
+    watchDirectory;
+    generation = 0;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.cwd = options.cwd;
+        this.staticPaths = options.staticPaths;
+        this.debounceMs = options.debounceMs ?? 500;
+        this.pathExists = options.pathExists ?? existsSync;
+        this.watchDirectory = options.watchDirectory ?? defaultWatchDirectory;
+        this.rebuild();
+    }
+    updateForCwd(cwd, staticPaths, dynamicPaths) {
+        if (this.closed)
+            return;
+        this.cwd = cwd;
+        this.staticPaths = staticPaths;
+        this.dynamicPaths = this.validDynamicPaths(dynamicPaths);
+        this.rebuild();
+    }
+    updateDynamicPaths(paths) {
+        if (this.closed)
+            return;
+        const next = this.validDynamicPaths(paths);
+        if (next.length === this.dynamicPaths.length &&
+            next.every((path, index) => path === this.dynamicPaths[index])) {
+            return;
+        }
+        this.dynamicPaths = next;
+        this.rebuild();
+    }
+    async close(timeoutMs = 5_000) {
+        if (this.closed)
+            return;
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new Error('FileChanged watcher close timeout must be non-negative');
+        }
+        this.closed = true;
+        this.generation += 1;
+        this.clearResources();
+        const pending = [...this.inFlight.keys()];
+        if (pending.length === 0)
+            return;
+        let timer;
+        try {
+            if ((await Promise.race([
+                Promise.allSettled(pending).then(() => 'settled'),
+                new Promise((resolveTimeout) => {
+                    timer = setTimeout(() => resolveTimeout('timeout'), timeoutMs);
+                }),
+            ])) === 'timeout') {
+                for (const controller of this.inFlight.values())
+                    controller.abort();
+                this.inFlight.clear();
+                await Promise.resolve();
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    validDynamicPaths(paths) {
+        const valid = [];
+        for (const path of paths) {
+            if (!isAbsolute(path)) {
+                this.options.warn(`FileChanged hook ignored non-absolute watch path: ${path}`);
+                continue;
+            }
+            valid.push(resolve(path));
+        }
+        return [...new Set(valid)];
+    }
+    targetPaths() {
+        return [
+            ...new Set([
+                ...this.staticPaths.map((path) => isAbsolute(path) ? resolve(path) : resolve(this.cwd, path)),
+                ...this.dynamicPaths,
+            ]),
+        ];
+    }
+    rebuild() {
+        this.generation += 1;
+        this.clearResources();
+        const targets = this.targetPaths();
+        const byDirectory = new Map();
+        for (const target of targets) {
+            this.knownExistence.set(target, this.pathExists(target));
+            const directory = dirname(target);
+            const names = byDirectory.get(directory) ?? new Set();
+            names.add(basename(target));
+            byDirectory.set(directory, names);
+        }
+        for (const [directory, names] of byDirectory) {
+            try {
+                const watcher = this.watchDirectory(directory, (filename) => {
+                    if (filename === null) {
+                        for (const name of names)
+                            this.schedule(resolve(directory, name));
+                        return;
+                    }
+                    if (names.has(filename))
+                        this.schedule(resolve(directory, filename));
+                });
+                watcher.on('error', (error) => {
+                    this.options.warn(`FileChanged watcher failed for ${directory}: ${error.message}`);
+                });
+                watcher.unref?.();
+                this.watchers.set(directory, watcher);
+            }
+            catch (error) {
+                this.options.warn(`FileChanged watcher could not watch ${directory}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    schedule(path) {
+        const previous = this.pending.get(path);
+        if (previous)
+            clearTimeout(previous);
+        const generation = this.generation;
+        const timer = setTimeout(() => {
+            this.pending.delete(path);
+            if (this.closed || generation !== this.generation)
+                return;
+            const controller = new AbortController();
+            const dispatch = this.dispatch(path, generation, controller.signal);
+            this.inFlight.set(dispatch, controller);
+            void dispatch.finally(() => this.inFlight.delete(dispatch));
+        }, this.debounceMs);
+        timer.unref?.();
+        this.pending.set(path, timer);
+    }
+    async dispatch(path, generation, signal) {
+        const existed = this.knownExistence.get(path) ?? false;
+        const exists = this.pathExists(path);
+        this.knownExistence.set(path, exists);
+        if (!existed && !exists)
+            return;
+        const event = !existed
+            ? 'add'
+            : !exists
+                ? 'unlink'
+                : 'change';
+        try {
+            const watchPaths = await this.options.onFileChanged(path, event, signal);
+            if (!this.closed &&
+                generation === this.generation &&
+                watchPaths &&
+                watchPaths.length > 0) {
+                this.updateDynamicPaths(watchPaths);
+            }
+        }
+        catch (error) {
+            this.options.warn(`FileChanged hook failed for ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    clearResources() {
+        for (const timer of this.pending.values())
+            clearTimeout(timer);
+        this.pending.clear();
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+        this.knownExistence.clear();
+    }
+}
+//# sourceMappingURL=claude-file-change-watcher.js.map

package/dist/hooks/claude-hook-tools.d.ts

@@ -12,6 +12,7 @@ export interface ClaudeHookToolCoordinatorOptions {
     hooks: ClaudeHookRunner;
     session: ClaudeHookSessionInput;
     recordOutcome(outcome: ClaudeHookOutcome, deferUntilApproval?: boolean): Promise<void>;
+    warn?(message: string): void;
     deferPreToolUseOutcome?(call: ModelToolCall): boolean;
 }
 export declare class ClaudeHookToolCoordinator implements ToolRegistry, PermissionResolver {
@@ -25,6 +26,7 @@ export declare class ClaudeHookToolCoordinator implements ToolRegistry, Permissi
     };
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     resolve(call: ModelToolCall, context?: PermissionResolutionContext): Promise<PermissionDecision>;
+    private withPermissionDeniedHook;
     execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
 }
 //# sourceMappingURL=claude-hook-tools.d.ts.map

package/dist/hooks/claude-hook-tools.js

@@ -1,3 +1,4 @@
+import { permissionDecisionSource } from '../core/runtime.js';
 export class ClaudeHookToolCoordinator {
     options;
     prepared = new Map();
@@ -57,11 +58,13 @@ export class ClaudeHookToolCoordinator {
     }
     async resolve(call, context) {
         const prepared = this.prepared.get(call.id);
-        if (prepared?.permissionDecision)
-            return prepared.permissionDecision;
+        if (prepared?.permissionDecision) {
+            return this.withPermissionDeniedHook(call, prepared.permissionDecision, prepared.signal);
+        }
         const decision = await this.options.permissions.resolve(call, context);
-        if (decision.behavior !== 'ask')
-            return decision;
+        if (decision.behavior !== 'ask') {
+            return this.withPermissionDeniedHook(call, decision, prepared?.signal);
+        }
         const outcome = await this.options.hooks.run({
             ...this.options.session,
             hook_event_name: 'PermissionRequest',
@@ -72,17 +75,53 @@ export class ClaudeHookToolCoordinator {
         }, call.name, prepared?.signal);
         await this.options.recordOutcome(outcome);
         if (outcome.blockedReason || outcome.permissionDecision === 'deny') {
-            return {
+            return this.withPermissionDeniedHook(call, {
                 behavior: 'deny',
                 reason: outcome.blockedReason ??
                     outcome.permissionDecisionReason ??
                     `PermissionRequest:${call.name} hook denied tool`,
-            };
+            }, prepared?.signal);
         }
         if (outcome.permissionDecision === 'allow')
             return { behavior: 'allow' };
         return decision;
     }
+    async withPermissionDeniedHook(call, decision, signal) {
+        const decisionSource = permissionDecisionSource(decision);
+        if (decision.behavior !== 'deny' || decisionSource !== 'auto-classifier') {
+            return decision;
+        }
+        const prepared = this.prepared.get(call.id);
+        try {
+            const outcome = await this.options.hooks.run({
+                ...this.options.session,
+                hook_event_name: 'PermissionDenied',
+                tool_name: call.name,
+                tool_input: prepared?.hookInput ?? call.input,
+                tool_use_id: call.id,
+                reason: decision.reason,
+            }, call.name, signal);
+            await this.options.recordOutcome(outcome);
+            if (outcome.retry) {
+                return {
+                    ...decision,
+                    followUpUserMessages: [
+                        ...(decision.followUpUserMessages ?? []),
+                        'The PermissionDenied hook indicated this command is now approved. You may retry it if you would like.',
+                    ],
+                    source: decisionSource,
+                };
+            }
+        }
+        catch (error) {
+            if (signal?.aborted ||
+                (error instanceof Error && error.name === 'AbortError')) {
+                throw error;
+            }
+            this.options.warn?.(`PermissionDenied:${call.name} hook failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return decision;
+    }
     async execute(call, context) {
         const prepared = this.prepared.get(call.id);
         try {

package/dist/hooks/claude-hooks.d.ts

@@ -1,6 +1,7 @@
 import type { ClaudeJsonResource } from '../compatibility/claude/shared-resources.js';
 import type { PermissionBehavior } from '../core/runtime.js';
-export type ClaudeHookEventName = 'Setup' | 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PostToolUse' | 'PostToolUseFailure' | 'Stop' | 'SubagentStop' | 'SessionEnd';
+import type { ClaudeSessionEnvironment } from './claude-session-environment.js';
+export type ClaudeHookEventName = 'Setup' | 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PermissionDenied' | 'PostToolUse' | 'PostToolUseFailure' | 'Notification' | 'Stop' | 'StopFailure' | 'SubagentStop' | 'PreCompact' | 'PostCompact' | 'TaskCreated' | 'TaskCompleted' | 'ConfigChange' | 'InstructionsLoaded' | 'WorktreeCreate' | 'WorktreeRemove' | 'CwdChanged' | 'FileChanged' | 'SessionEnd';
 export interface ClaudeHookInput extends Record<string, unknown> {
     session_id: string;
     transcript_path: string;
@@ -53,6 +54,9 @@ export interface ClaudeHookOutcome {
     updatedInput?: Record<string, unknown>;
     permissionDecision?: PermissionBehavior;
     permissionDecisionReason?: string;
+    retry?: boolean;
+    watchPaths?: readonly string[];
+    systemMessages?: readonly string[];
     blockedReason?: string;
 }
 interface ProcessResult {
@@ -71,6 +75,7 @@ export interface ClaudeHookRunnerOptions {
     maxTimeoutMs?: number;
     executeCommand?: ClaudeHookCommandExecutor;
     onEvent?: (event: ClaudeHookStreamEvent) => void;
+    sessionEnvironment?: ClaudeSessionEnvironment;
 }
 export declare const HOOK_EVENTS: readonly ClaudeHookEventName[];
 export declare function validateClaudeHooks(settings: readonly ClaudeJsonResource[], maxTimeoutMs?: number): void;
@@ -81,9 +86,16 @@ export declare class ClaudeHookRunner {
     private readonly executeCommand;
     private readonly onEvent;
     private readonly cwd;
-    constructor(options: ClaudeHookRunnerOptions);
+    private readonly sessionEnvironment;
+    private readonly asynchronousHooks;
+    constructor(options: ClaudeHookRunnerOptions, asynchronousHooks?: Map<Promise<void>, AbortController>);
     withAdditionalSettings(settings: readonly ClaudeJsonResource[]): ClaudeHookRunner;
+    fileChangedWatchPaths(cwd?: string): readonly string[];
     run(input: ClaudeHookInput, matcherValue?: string, signal?: AbortSignal): Promise<ClaudeHookOutcome>;
+    drainAsync(timeoutMs: number): Promise<void>;
+    clearCwdEnvironment(sessionId: string): Promise<void>;
+    private executionEnvironment;
+    private invalidateSessionEnvironment;
     private runCommand;
 }
 export {};

package/dist/hooks/claude-hooks.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { basename, isAbsolute, resolve } from 'node:path';
 import { commandShell, commandShellArguments, } from '../platform/command-shell.js';
 import { redactSensitiveText, sanitizeChildEnvironment, sensitiveEnvironmentValues, } from '../platform/sensitive-data.js';
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
@@ -11,12 +12,23 @@ export const HOOK_EVENTS = [
     'UserPromptSubmit',
     'PreToolUse',
     'PermissionRequest',
+    'PermissionDenied',
     'PostToolUse',
     'PostToolUseFailure',
+    'Notification',
     'Stop',
+    'StopFailure',
     'SubagentStop',
+    'PreCompact',
+    'PostCompact',
+    'TaskCreated',
+    'TaskCompleted',
+    'InstructionsLoaded',
+    'CwdChanged',
+    'FileChanged',
     'SessionEnd',
 ];
+const EXECUTABLE_HOOK_EVENTS = new Set(HOOK_EVENTS);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -33,6 +45,7 @@ function combinedSensitiveValues(...groups) {
 }
 function eventSettings(settings, event, maxTimeoutMs) {
     const matchers = [];
+    let hookIndex = 0;
     for (const resource of settings) {
         if (!isRecord(resource.value) || !isRecord(resource.value.hooks))
             continue;
@@ -64,6 +77,8 @@ function eventSettings(settings, event, maxTimeoutMs) {
                 }
             }
             const hooks = group.hooks.flatMap((hook) => {
+                const currentHookIndex = hookIndex;
+                hookIndex += 1;
                 if (!isRecord(hook) || hook.type !== 'command')
                     return [];
                 const command = nonEmptyString(hook.command, `Claude ${event} hook command`);
@@ -73,10 +88,15 @@ function eventSettings(settings, event, maxTimeoutMs) {
                     timeoutSeconds <= 0) {
                     throw new Error(`Invalid Claude ${event} hook timeout: ${resource.path}`);
                 }
+                if (hook.async !== undefined && typeof hook.async !== 'boolean') {
+                    throw new Error(`Invalid Claude ${event} hook async: ${resource.path}`);
+                }
                 return [
                     {
                         command,
                         timeoutMs: Math.min(timeoutSeconds * 1000, maxTimeoutMs),
+                        asynchronous: hook.async === true,
+                        hookIndex: currentHookIndex,
                         ...(resource.environment === undefined
                             ? {}
                             : { environment: resource.environment }),
@@ -93,6 +113,32 @@ function eventSettings(settings, event, maxTimeoutMs) {
     }
     return matchers;
 }
+function fileChangedMatcherPaths(settings, cwd) {
+    const paths = [];
+    for (const resource of settings) {
+        if (!isRecord(resource.value) || !isRecord(resource.value.hooks))
+            continue;
+        const groups = resource.value.hooks.FileChanged;
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isRecord(group) || !Array.isArray(group.hooks))
+                continue;
+            if (!group.hooks.some((hook) => isRecord(hook) && hook.type === 'command')) {
+                continue;
+            }
+            if (typeof group.matcher !== 'string')
+                continue;
+            for (const candidate of group.matcher.split('|')) {
+                const path = candidate.trim();
+                if (!path)
+                    continue;
+                paths.push(isAbsolute(path) ? path : resolve(cwd, path));
+            }
+        }
+    }
+    return [...new Set(paths)];
+}
 export function validateClaudeHooks(settings, maxTimeoutMs = DEFAULT_TIMEOUT_MS) {
     if (!Number.isFinite(maxTimeoutMs) ||
         maxTimeoutMs <= 0 ||
@@ -130,6 +176,38 @@ function permissionBehavior(value) {
         ? value
         : undefined;
 }
+function hookMatcherValue(input) {
+    switch (input.hook_event_name) {
+        case 'Setup':
+            return optionalString(input.trigger) ?? '';
+        case 'SessionStart':
+            return optionalString(input.source) ?? '';
+        case 'SubagentStart':
+        case 'SubagentStop':
+            return optionalString(input.agent_type) ?? '';
+        case 'PreToolUse':
+        case 'PermissionRequest':
+        case 'PermissionDenied':
+        case 'PostToolUse':
+        case 'PostToolUseFailure':
+            return optionalString(input.tool_name) ?? '';
+        case 'Notification':
+            return optionalString(input.notification_type) ?? '';
+        case 'StopFailure':
+            return optionalString(input.error) ?? '';
+        case 'PreCompact':
+        case 'PostCompact':
+            return optionalString(input.trigger) ?? '';
+        case 'InstructionsLoaded':
+            return optionalString(input.load_reason) ?? '';
+        case 'FileChanged':
+            return basename(optionalString(input.file_path) ?? '');
+        case 'SessionEnd':
+            return optionalString(input.reason) ?? '';
+        default:
+            return '';
+    }
+}
 function abortError() {
     return new DOMException('Hook execution aborted', 'AbortError');
 }
@@ -140,13 +218,17 @@ export class ClaudeHookRunner {
     executeCommand;
     onEvent;
     cwd;
-    constructor(options) {
+    sessionEnvironment;
+    asynchronousHooks;
+    constructor(options, asynchronousHooks = new Map()) {
         this.settings = options.settings;
         this.maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
         this.maxTimeoutMs = options.maxTimeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.executeCommand = options.executeCommand ?? this.runCommand.bind(this);
         this.onEvent = options.onEvent;
         this.cwd = options.cwd;
+        this.sessionEnvironment = options.sessionEnvironment;
+        this.asynchronousHooks = asynchronousHooks;
     }
     withAdditionalSettings(settings) {
         return new ClaudeHookRunner({
@@ -155,25 +237,40 @@ export class ClaudeHookRunner {
             maxTimeoutMs: this.maxTimeoutMs,
             executeCommand: this.executeCommand,
             ...(this.onEvent ? { onEvent: this.onEvent } : {}),
+            ...(this.sessionEnvironment
+                ? { sessionEnvironment: this.sessionEnvironment }
+                : {}),
             cwd: this.cwd,
-        });
+        }, this.asynchronousHooks);
+    }
+    fileChangedWatchPaths(cwd = this.cwd) {
+        return fileChangedMatcherPaths(this.settings, cwd);
     }
     async run(input, matcherValue, signal) {
         if (signal?.aborted)
             throw abortError();
+        if (!EXECUTABLE_HOOK_EVENTS.has(input.hook_event_name)) {
+            return { executions: [], additionalContext: [] };
+        }
+        const matchQuery = matcherValue ?? hookMatcherValue(input);
         const ambientSensitiveValues = sensitiveEnvironmentValues(process.env);
-        const groups = eventSettings(this.settings, input.hook_event_name, this.maxTimeoutMs).filter((group) => !group.matcher || group.matcher.test(matcherValue ?? ''));
+        const groups = eventSettings(this.settings, input.hook_event_name, this.maxTimeoutMs).filter((group) => input.hook_event_name === 'CwdChanged' ||
+            !group.matcher ||
+            group.matcher.test(matchQuery));
         const executions = [];
         const additionalContext = [];
         let updatedInput;
         let permissionDecision;
         let permissionDecisionReason;
+        let retry = false;
+        const watchPaths = [];
+        const systemMessages = [];
         let blockedReason;
         for (const group of groups) {
             for (const hook of group.hooks) {
                 const sensitiveValues = combinedSensitiveValues(ambientSensitiveValues, hook.sensitiveValues);
                 const hookId = crypto.randomUUID();
-                const hookName = `${input.hook_event_name}${matcherValue ? `:${matcherValue}` : ''}`;
+                const hookName = `${input.hook_event_name}${matchQuery ? `:${matchQuery}` : ''}`;
                 this.onEvent?.({
                     type: 'started',
                     hookId,
@@ -199,8 +296,57 @@ export class ClaudeHookRunner {
                         output,
                     });
                 };
+                const executionEnvironment = await this.executionEnvironment(input, hook);
+                if (hook.asynchronous) {
+                    const controller = new AbortController();
+                    const pending = this.executeCommand(hook.command, input, hook.timeoutMs, controller.signal, reportProgress, executionEnvironment)
+                        .finally(() => this.invalidateSessionEnvironment(input))
+                        .then((result) => {
+                        const stdout = redactSensitiveText(result.stdout, sensitiveValues);
+                        const stderr = redactSensitiveText(result.stderr, sensitiveValues);
+                        const output = redactSensitiveText(result.output ?? `${result.stdout}${result.stderr}`, sensitiveValues);
+                        const outputExceeded = Buffer.byteLength(stdout) + Buffer.byteLength(stderr) >
+                            this.maxOutputBytes;
+                        this.onEvent?.({
+                            type: 'response',
+                            hookId,
+                            hookName,
+                            hookEvent: input.hook_event_name,
+                            stdout: outputExceeded ? '' : stdout,
+                            stderr: outputExceeded
+                                ? 'Hook output exceeded byte limit'
+                                : stderr,
+                            output: outputExceeded
+                                ? 'Hook output exceeded byte limit'
+                                : output,
+                            exitCode: outputExceeded ? 1 : result.exitCode,
+                            outcome: outputExceeded || result.exitCode !== 0 ? 'error' : 'success',
+                        });
+                    })
+                        .catch((error) => {
+                        const message = redactSensitiveText(hookErrorMessage(error), sensitiveValues);
+                        this.onEvent?.({
+                            type: 'response',
+                            hookId,
+                            hookName,
+                            hookEvent: input.hook_event_name,
+                            output: message,
+                            stdout: '',
+                            stderr: message,
+                            ...(hookWasCancelled(error, controller.signal)
+                                ? {}
+                                : { exitCode: 1 }),
+                            outcome: hookWasCancelled(error, controller.signal)
+                                ? 'cancelled'
+                                : 'error',
+                        });
+                    });
+                    this.asynchronousHooks.set(pending, controller);
+                    void pending.finally(() => this.asynchronousHooks.delete(pending));
+                    continue;
+                }
                 try {
-                    result = await this.executeCommand(hook.command, input, hook.timeoutMs, signal, reportProgress, hook.environment);
+                    result = await this.executeCommand(hook.command, input, hook.timeoutMs, signal, reportProgress, executionEnvironment);
                 }
                 catch (error) {
                     const message = redactSensitiveText(hookErrorMessage(error), sensitiveValues);
@@ -218,6 +364,9 @@ export class ClaudeHookRunner {
                     });
                     throw error;
                 }
+                finally {
+                    this.invalidateSessionEnvironment(input);
+                }
                 const toolUseId = optionalString(input.tool_use_id) ?? crypto.randomUUID();
                 const stdout = redactSensitiveText(result.stdout, sensitiveValues);
                 const stderr = redactSensitiveText(result.stderr, sensitiveValues);
@@ -288,6 +437,22 @@ export class ClaudeHookRunner {
                 permissionDecisionReason = nextPermissionReason
                     ? redactSensitiveText(nextPermissionReason, sensitiveValues)
                     : permissionDecisionReason;
+                if (input.hook_event_name === 'PermissionDenied' &&
+                    specific?.hookEventName === 'PermissionDenied' &&
+                    specific.retry === true) {
+                    retry = true;
+                }
+                if ((input.hook_event_name === 'CwdChanged' ||
+                    input.hook_event_name === 'FileChanged') &&
+                    specific?.hookEventName === input.hook_event_name &&
+                    Array.isArray(specific.watchPaths) &&
+                    specific.watchPaths.every((path) => typeof path === 'string')) {
+                    watchPaths.push(...specific.watchPaths);
+                }
+                const systemMessage = optionalString(parsedOutput?.systemMessage);
+                if (systemMessage) {
+                    systemMessages.push(redactSensitiveText(systemMessage, sensitiveValues));
+                }
                 if (parsedOutput?.continue === false ||
                     parsedOutput?.decision === 'block') {
                     blockedReason = redactSensitiveText(optionalString(parsedOutput.stopReason) ??
@@ -305,9 +470,69 @@ export class ClaudeHookRunner {
             ...(updatedInput ? { updatedInput } : {}),
             ...(permissionDecision ? { permissionDecision } : {}),
             ...(permissionDecisionReason ? { permissionDecisionReason } : {}),
+            ...(retry ? { retry } : {}),
+            ...(watchPaths.length > 0 ? { watchPaths } : {}),
+            ...(systemMessages.length > 0 ? { systemMessages } : {}),
             ...(blockedReason ? { blockedReason } : {}),
         };
     }
+    async drainAsync(timeoutMs) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new Error('Hook async drain timeout must be non-negative');
+        }
+        const pending = [...this.asynchronousHooks.keys()];
+        if (pending.length === 0)
+            return;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), timeoutMs);
+        });
+        try {
+            if ((await Promise.race([
+                Promise.allSettled(pending).then(() => 'settled'),
+                timeout,
+            ])) === 'timeout') {
+                for (const controller of this.asynchronousHooks.values()) {
+                    controller.abort();
+                }
+                // Give cooperative executors one event-loop turn to publish their
+                // cancelled response. Keep the wait bounded because custom executors
+                // are allowed to ignore AbortSignal entirely.
+                await Promise.race([
+                    Promise.allSettled(pending),
+                    new Promise((resolve) => setTimeout(resolve, 0)),
+                ]);
+                // Executors normally terminate their child process on abort. A custom
+                // executor may ignore cancellation, so shutdown abandons tracking
+                // after the deadline instead of turning a bounded drain into an
+                // unbounded wait.
+                this.asynchronousHooks.clear();
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async clearCwdEnvironment(sessionId) {
+        await this.sessionEnvironment?.clearCwdFiles(sessionId);
+    }
+    async executionEnvironment(input, hook) {
+        if (!this.sessionEnvironment ||
+            !['Setup', 'SessionStart', 'CwdChanged', 'FileChanged'].includes(input.hook_event_name)) {
+            return hook.environment;
+        }
+        const environmentFile = await this.sessionEnvironment.hookFile(input.session_id, input.hook_event_name, hook.hookIndex);
+        return {
+            ...hook.environment,
+            ...(environmentFile ? { CLAUDE_ENV_FILE: environmentFile } : {}),
+        };
+    }
+    invalidateSessionEnvironment(input) {
+        if (['Setup', 'SessionStart', 'CwdChanged', 'FileChanged'].includes(input.hook_event_name)) {
+            this.sessionEnvironment?.invalidate(input.session_id);
+        }
+    }
     runCommand(command, input, timeoutMs, signal, onProgress, environment) {
         return new Promise((resolve, reject) => {
             const startedAt = Date.now();