@goodfoot/agent-hooks 1.0.0

package/types/agents/codex/types.d.ts

@@ -0,0 +1,131 @@
+export type HookEventName = "PreToolUse" | "PostToolUse" | "PermissionRequest" | "UserPromptSubmit" | "SessionStart" | "SubagentStart" | "Stop" | "SubagentStop" | "PreCompact" | "PostCompact";
+export type PermissionMode = "default" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions";
+export type SessionStartSource = "startup" | "resume" | "clear" | "compact";
+export type PreCompactTrigger = "manual" | "auto";
+export interface BaseHookInput {
+    cwd: string;
+    hook_event_name: HookEventName;
+    model: string;
+    session_id: string;
+    transcript_path: string | null;
+}
+export interface PreToolUseInput extends BaseHookInput {
+    hook_event_name: "PreToolUse";
+    permission_mode: PermissionMode;
+    tool_input: unknown;
+    tool_name: string;
+    tool_use_id: string;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface PostToolUseInput extends BaseHookInput {
+    hook_event_name: "PostToolUse";
+    permission_mode: PermissionMode;
+    tool_input: unknown;
+    tool_name: string;
+    tool_response: unknown;
+    tool_use_id: string;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface PermissionRequestInput extends BaseHookInput {
+    hook_event_name: "PermissionRequest";
+    permission_mode: PermissionMode;
+    tool_input: unknown;
+    tool_name: string;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface UserPromptSubmitInput extends BaseHookInput {
+    hook_event_name: "UserPromptSubmit";
+    permission_mode: PermissionMode;
+    prompt: string;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface SessionStartInput extends BaseHookInput {
+    hook_event_name: "SessionStart";
+    permission_mode: PermissionMode;
+    source: SessionStartSource;
+}
+export interface SubagentStartInput extends BaseHookInput {
+    hook_event_name: "SubagentStart";
+    permission_mode: PermissionMode;
+    agent_id: string;
+    agent_type: string;
+    turn_id: string;
+}
+export interface StopInput extends BaseHookInput {
+    hook_event_name: "Stop";
+    permission_mode: PermissionMode;
+    last_assistant_message: string | null;
+    stop_hook_active: boolean;
+    turn_id: string;
+}
+export interface SubagentStopInput extends BaseHookInput {
+    hook_event_name: "SubagentStop";
+    permission_mode: PermissionMode;
+    agent_id: string;
+    agent_transcript_path: string | null;
+    agent_type: string;
+    last_assistant_message: string | null;
+    stop_hook_active: boolean;
+    turn_id: string;
+}
+export interface PreCompactInput extends BaseHookInput {
+    hook_event_name: "PreCompact";
+    trigger: PreCompactTrigger;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface PostCompactInput extends BaseHookInput {
+    hook_event_name: "PostCompact";
+    trigger: PreCompactTrigger;
+    turn_id: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export type HookInput = PreToolUseInput | PostToolUseInput | PermissionRequestInput | UserPromptSubmitInput | SessionStartInput | SubagentStartInput | StopInput | SubagentStopInput | PreCompactInput | PostCompactInput;
+/**
+ * "error" (default) preserves existing behavior: an unhandled exception
+ * anywhere in the runtime (stdin read, parse, handler, serialize, write,
+ * cleanup) writes a stack trace to stderr and exits non-zero.
+ *
+ * "continue" is an opt-in fail-open policy for advisory hooks whose only
+ * purpose is to enrich context (e.g. UserPromptSubmit additionalContext).
+ * Under this policy, unexpected runtime failures are swallowed, the event's
+ * valid empty output (`{}`) is emitted if no response was already written,
+ * and the process exits 0 so Codex does not show a failed-hook banner.
+ * `BlockError` is unaffected: it always writes its reason and exits 2.
+ * Do not use "continue" for hooks that enforce permission, safety, or
+ * policy decisions — a swallowed failure there silently grants the
+ * decision the hook was supposed to make.
+ */
+export type UnexpectedErrorPolicy = "error" | "continue";
+/** The runtime phase in which an unexpected error occurred. */
+export type HookErrorPhase = "read" | "parse" | "handler" | "serialize" | "write" | "cleanup";
+/**
+ * Best-effort diagnostic sink for unexpected errors under the "continue"
+ * policy. Called in addition to (not instead of) the runtime's own logger.
+ * Errors thrown by this handler are swallowed — a broken diagnostic sink
+ * must never itself fail the invocation.
+ */
+export type UnexpectedErrorHandler = (error: unknown, phase: HookErrorPhase) => void;
+export interface MatcherHookConfig {
+    matcher?: string;
+    timeout?: number;
+    statusMessage?: string;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+}
+export interface NoMatcherHookConfig {
+    timeout?: number;
+    statusMessage?: string;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+}

package/types/cli.d.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for compiling Claude Code hooks using esbuild.
+ *
+ * Compiles TypeScript hooks to standalone ESM modules and generates hooks.json
+ * with correct command paths and matcher configurations.
+ * @example
+ * ```bash
+ * # Compile hooks and generate hooks.json
+ * agent-hooks --agent claude-code -i "hooks/**\/*.ts" -o "./dist/hooks.json"
+ *
+ * # With runtime logging (equivalent to AGENT_HOOKS_LOG_FILE)
+ * agent-hooks --agent claude-code -i "hooks/**\/*.ts" -o "./dist/hooks.json" --log /tmp/hooks.log
+ * ```
+ * @module
+ */
+import * as esbuild from "esbuild";
+import type { HookEventName } from "./agents/claude-code/types.js";
+import { HOOK_FACTORY_TO_EVENT } from "./constants.js";
+/**
+ * Hook context determines how paths are resolved in hooks.json.
+ *
+ * - `plugin`: Uses `$CLAUDE_PLUGIN_ROOT` for plugin hooks
+ * - `agent`: Uses `"$CLAUDE_PROJECT_DIR"` for agent hooks (.claude/hooks/)
+ */
+type HookContext = "plugin" | "agent";
+/**
+ * Command-line arguments parsed from process.argv.
+ */
+interface CliArgs {
+    /** Target agent runtime (required): "claude-code" | "codex" | "antigravity". */
+    agent: string;
+    /** Glob pattern for hook source files. */
+    input: string;
+    /** Path for hooks.json output file. */
+    output: string;
+    /** 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. */
+    version: boolean;
+    /** Directory path for scaffolding a new hook project. */
+    scaffold?: string;
+    /** Comma-separated list of hook types to generate when scaffolding. */
+    hooks?: string;
+    /** Node executable path to use in command output (default: "node"). */
+    executable?: string;
+    /** Repeated esbuild loader flags in EXT=TYPE form. */
+    loaderFlags: string[];
+    /** Force Codex plugin mode: ${PLUGIN_ROOT}-relative commands + stable names default. */
+    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. */
+    sourcemap?: boolean;
+}
+type HookLoaderMap = Record<string, esbuild.Loader>;
+/**
+ * Metadata extracted from a hook file via TypeScript AST analysis.
+ */
+interface HookMetadata {
+    /** The hook event type (PreToolUse, SessionStart, etc.). */
+    hookEventName: HookEventName;
+    /** Optional matcher pattern from hook config. */
+    matcher?: string;
+    /** Optional timeout in milliseconds from hook config. */
+    timeout?: number;
+}
+/**
+ * A compiled hook with its metadata and output path.
+ */
+interface CompiledHook {
+    /** Original source file path. */
+    sourcePath: string;
+    /** Compiled output file path. */
+    outputPath: string;
+    /** Output filename (e.g., "my-hook.abc123de.mjs"). */
+    outputFilename: string;
+    /** Extracted hook metadata. */
+    metadata: HookMetadata;
+}
+/**
+ * Individual hook configuration within a matcher group.
+ */
+interface HookConfig {
+    /** Hook type - always "command" for compiled hooks. */
+    type: "command";
+    /** Absolute path to compiled hook executable. */
+    command: string;
+    /** Optional timeout in seconds. */
+    timeout?: number;
+}
+/**
+ * Matcher group entry within an event type.
+ */
+interface MatcherEntry {
+    /** Matcher pattern (tool name, regex, etc.). Optional for some event types. */
+    matcher?: string;
+    /** Array of hook configurations in this matcher group. */
+    hooks: HookConfig[];
+}
+/**
+ * The complete hooks.json structure expected by Claude Code.
+ *
+ * Format: { hooks: { EventType: [ { matcher?, hooks: [...] } ] } }
+ */
+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;
+    };
+}
+/**
+ * Parses command-line arguments.
+ * @param argv - Process argv (usually process.argv.slice(2))
+ * @returns Parsed arguments
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Validates CLI arguments and returns error message if invalid.
+ * @param args - Parsed CLI arguments
+ * @returns Error message if invalid, undefined if valid
+ */
+declare function validateArgs(args: CliArgs): string | undefined;
+declare function parseLoaderFlag(spec: string): {
+    extension: string;
+    loader: esbuild.Loader;
+} | undefined;
+declare function buildLoaderMap(loaderFlags?: string[]): HookLoaderMap;
+/**
+ * Extracts hook metadata from a TypeScript source file using AST analysis.
+ *
+ * Looks for default exports that call hook factory functions (preToolUseHook, etc.)
+ * and extracts the hook type, matcher, and timeout from the config object.
+ * @param sourcePath - Absolute path to the TypeScript source file
+ * @returns Extracted hook metadata or undefined if not a valid hook file
+ * @example
+ * ```typescript
+ * // For a file containing:
+ * // export default preToolUseHook({ matcher: 'Bash', timeout: 5000 }, handler);
+ *
+ * const metadata = analyzeHookFile('/path/to/hook.ts');
+ * // { hookEventName: 'PreToolUse', matcher: 'Bash', timeout: 5000 }
+ * ```
+ */
+declare function analyzeHookFile(sourcePath: string): HookMetadata | undefined;
+/**
+ * Discovers hook files matching the glob pattern.
+ * @param pattern - Glob pattern for hook files
+ * @param cwd - Current working directory for relative patterns
+ * @returns Array of absolute paths to hook files
+ */
+declare function discoverHookFiles(pattern: string, cwd: string): Promise<string[]>;
+/**
+ * Options for compiling a hook.
+ */
+interface CompileHookOptions {
+    /** Absolute path to source file. */
+    sourcePath: string;
+    /** Directory for compiled output. */
+    outputDir: string;
+    /** 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;
+    /** 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. */
+    sourcemap?: boolean;
+}
+/**
+ * Result of compiling a hook.
+ */
+interface CompileHookResult {
+    /** Compiled content, with inline sourcemaps unless disabled. */
+    content: string;
+    /** Stable content hash generated from sourcemap-free output. */
+    contentHash: string;
+}
+/**
+ * Re-roots a realpath through the node_modules symlink chain visible from
+ * `resolveDir`, so relative paths computed against it do not depend on how
+ * deeply the checkout is nested below a shared install.
+ *
+ * Walks `resolveDir`'s ancestors for a `node_modules` directory whose
+ * realpath contains `realPath` (e.g. a checkout-level symlink to a shared
+ * install) and returns `realPath` as seen through that directory. Also
+ * recognizes the package directory itself being symlinked into that
+ * `node_modules` — whether the package lives in a store (pnpm-style store
+ * link, npx cache, external install) or in the checkout's own source tree
+ * (`packages/` with a `node_modules` entry symlinked back into it) — and
+ * re-roots through the symlink form, so esbuild records one module identity
+ * regardless of install topology. Falls back to the realpath when no such
+ * node_modules exists — with no symlink involved, the realpath is already
+ * checkout-local.
+ */
+declare function symlinkVisiblePath(realPath: string, resolveDir: string): string;
+/**
+ * Compiles a TypeScript hook file to a self-contained ESM executable.
+ *
+ * Uses esbuild's stdin option to avoid writing temporary wrapper files to disk.
+ * This produces stable, reproducible builds by:
+ * - Using a distinct sourcefile name to avoid import resolution conflicts
+ * - Eliminating environment-specific temp paths from source comments
+ *
+ * Uses a two-step process to generate stable content hashes:
+ * 1. Compile WITHOUT sourcemaps → generate stable content hash
+ * 2. Compile WITH sourcemaps → final output content
+ *
+ * @param options - Compilation options
+ * @returns Compiled content and stable content hash
+ */
+declare function compileHook(options: CompileHookOptions): Promise<CompileHookResult>;
+/**
+ * Generates a content hash (SHA-256, 8-char prefix) for a compiled hook.
+ * @param content - Compiled hook content
+ * @returns 8-character hex hash
+ */
+declare function generateContentHash(content: string): string;
+/**
+ * Removes hashed `<name>.<hash>.mjs` siblings of the stable bundles we just
+ * wrote, so re-running the build with --stable-names cleans up leftovers from
+ * previous --no-stable-names (or pre-1.7) runs.
+ */
+declare function pruneStaleHashedBundles(outputDir: string, keepFilenames: Set<string>): void;
+/**
+ * Groups compiled hooks by event type, then by matcher pattern.
+ * @param compiledHooks - Array of compiled hooks
+ * @returns Nested map: EventType -> Matcher -> Hooks
+ */
+declare function groupHooksByEventAndMatcher(compiledHooks: CompiledHook[]): Map<HookEventName, Map<string | undefined, CompiledHook[]>>;
+/**
+ * Result of detecting the hook context, including the root directory.
+ */
+interface HookContextInfo {
+    /** Hook context type. */
+    context: HookContext;
+    /** Absolute path to the root directory (plugin root or project root). */
+    rootDir: string;
+}
+/**
+ * Auto-detects the hook context and root directory based on directory structure.
+ *
+ * Detection logic:
+ * - If output path contains `.claude/` directory segment → agent context, root is parent of .claude/
+ * - If `.claude-plugin/` directory exists within 3 levels up → plugin context, root is that directory
+ * - Default: plugin context with hooks.json parent directory as root
+ * @param outputPath - Absolute path to the hooks.json output file
+ * @returns Detected hook context and root directory
+ */
+declare function detectHookContext(outputPath: string): HookContextInfo;
+/**
+ * Generates a command path based on the hook context.
+ *
+ * Calculates the relative path from the root directory to the bin directory.
+ * Prepends the node executable.
+ *
+ * - `plugin`: Uses `node "$CLAUDE_PLUGIN_ROOT"/hooks/bin/filename`
+ * - `agent`: Uses `node "$CLAUDE_PROJECT_DIR"/.claude/hooks/bin/filename`
+ * @param filename - The compiled hook filename
+ * @param buildDir - Absolute path to the bin directory
+ * @param contextInfo - Hook context info including root directory
+ * @param executable - Node executable path (default: "node")
+ * @returns The command path string
+ */
+declare function generateCommandPath(filename: string, buildDir: string, contextInfo: HookContextInfo, executable?: string): string;
+/**
+ * Generates the hooks.json content in Claude Code's expected format.
+ *
+ * Format: { hooks: { EventType: [ { matcher?, hooks: [...] } ] } }
+ * @param compiledHooks - Array of compiled hooks
+ * @param buildDir - Absolute path to the bin directory
+ * @param contextInfo - Hook context info for path resolution
+ * @param executable - Node executable path (default: "node")
+ * @returns The hooks.json structure
+ */
+declare function generateHooksJson(compiledHooks: CompiledHook[], buildDir: string, contextInfo: HookContextInfo, executable?: string): HooksJson;
+/**
+ * Reads an existing hooks.json file if it exists.
+ * @param outputPath - Path to the hooks.json file
+ * @returns Parsed HooksJson or undefined if file doesn't exist
+ */
+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
+ * @param outputDir - Directory containing the generated files
+ */
+declare function removeOldGeneratedFiles(existingHooksJson: HooksJson, outputDir: 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.
+ * @param existingHooksJson - The existing hooks.json content
+ * @returns Object containing preserved hooks (keyed by event type)
+ */
+declare function extractPreservedHooks(existingHooksJson: HooksJson): Partial<Record<HookEventName, MatcherEntry[]>>;
+/**
+ * Merges preserved hooks with newly generated hooks.
+ * Preserved hooks are added first, then new hooks are appended.
+ * @param newHooksJson - The newly generated hooks.json content
+ * @param preservedHooks - Hooks to preserve from the existing hooks.json
+ * @returns Merged HooksJson
+ */
+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, };

package/types/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared constants for the CLI and scaffold modules.
+ * @module
+ */
+import type { HookEventName } from "./agents/claude-code/types.js";
+/**
+ * Maps hook factory function names to their event names.
+ */
+export declare const HOOK_FACTORY_TO_EVENT: Record<string, HookEventName>;

package/types/core/define-hook.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic hook factory primitive.
+ *
+ * `defineHook` is the agent-neutral seam every agent's per-event factory
+ * builds on: the agent supplies its event name, its config shape, and an
+ * optional policy gate enforcing that event's advisory allow-list. Core never
+ * hardcodes an event list — validation is fully injected via
+ * {@link HookPolicyGate} and fails closed when a gate rejects.
+ * @module
+ * @example
+ * ```typescript
+ * const hook = defineHook(
+ *   "UserPromptSubmit",
+ *   { unexpectedError: "continue" },
+ *   async (input, { logger }) => {
+ *     logger.info("Enriching prompt");
+ *     return { additionalContext: "..." };
+ *   },
+ *   (eventName, policy) => policy === undefined || policy === "continue",
+ * );
+ * ```
+ */
+import type { HookConfig, HookContext, HookFunction, HookHandler, HookPolicyGate } from "./types.js";
+/**
+ * Creates a hook function for a specific agent event.
+ *
+ * @param eventName - The agent's event name (e.g. `"PreToolUse"`); attached
+ * to the returned {@link HookFunction} as `eventName` for runtime inspection.
+ * @param config - Hook configuration (matcher, timeout, unexpected-error
+ * policy and diagnostics, optional context factory).
+ * @param handler - The handler function to wrap.
+ * @param policyGate - Optional per-event policy-validation closure injected
+ * by the agent. Called with `(eventName, config.unexpectedError)`; returning
+ * `false` or throwing rejects the configuration, and this function throws
+ * (fail closed) instead of creating the hook.
+ * @returns A wrapped hook function carrying its metadata for the driver.
+ * @throws Error when `policyGate` rejects `(eventName, policy)`.
+ */
+export declare function defineHook<TInput, TOutput, TContext extends HookContext = HookContext>(eventName: string, config: HookConfig<TInput>, handler: HookHandler<TInput, TOutput, TContext>, policyGate?: HookPolicyGate): HookFunction<TInput, TOutput, TContext>;

package/types/core/env.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Environment variable utilities for Claude Code hooks.
+ *
+ * Provides typed access to Claude Code's environment variables and utilities
+ * for persisting environment variables in SessionStart hooks.
+ *
+ * ## Environment Variables
+ *
+ * Claude Code sets these environment variables when running hooks:
+ *
+ * | Variable | Description | Available In |
+ * |----------|-------------|--------------|
+ * | `CLAUDE_PROJECT_DIR` | Absolute path to project root | All hooks |
+ * | `CLAUDE_ENV_FILE` | Path to file for persisting env vars | SessionStart only |
+ * | `CLAUDE_CODE_REMOTE` | `"true"` if running remotely | All hooks |
+ * @module
+ * @example
+ * ```typescript
+ * import { getProjectDir, persistEnvVar, isRemoteEnvironment } from '@goodfoot/agent-hooks';
+ *
+ * // Get project directory
+ * const projectDir = getProjectDir();
+ *
+ * // Check if running remotely
+ * if (isRemoteEnvironment()) {
+ *   // Handle remote-specific logic
+ * }
+ *
+ * // In SessionStart hook: persist environment variables
+ * persistEnvVar('NODE_ENV', 'production');
+ * persistEnvVar('API_KEY', 'secret-key');
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#hook-execution-details
+ */
+/**
+ * Claude Code environment variable names.
+ *
+ * These are the environment variables that Claude Code sets when running hooks.
+ */
+export declare const CLAUDE_ENV_VARS: {
+    /**
+     * Absolute path to the project root directory where Claude Code was started.
+     * Available in all hooks.
+     */
+    readonly PROJECT_DIR: "CLAUDE_PROJECT_DIR";
+    /**
+     * Path to a file where SessionStart hooks can persist environment variables.
+     * Variables written to this file will be available in all subsequent bash commands.
+     * Only available in SessionStart hooks.
+     */
+    readonly ENV_FILE: "CLAUDE_ENV_FILE";
+    /**
+     * Set to "true" when running in a remote (web) environment.
+     * Not set or empty when running in local CLI environment.
+     */
+    readonly REMOTE: "CLAUDE_CODE_REMOTE";
+};
+/**
+ * Gets the Claude Code project directory.
+ *
+ * This is the absolute path to the project root where Claude Code was started.
+ * The value comes from the `CLAUDE_PROJECT_DIR` environment variable.
+ * @returns The project directory path, or undefined if not set
+ * @example
+ * ```typescript
+ * const projectDir = getProjectDir();
+ * if (projectDir) {
+ *   const configPath = `${projectDir}/.claude/config.json`;
+ * }
+ * ```
+ */
+export declare function getProjectDir(): string | undefined;
+/**
+ * Gets the Claude Code env file path for persisting environment variables.
+ *
+ * This is only available in SessionStart hooks. The path points to a file
+ * where you can write shell export statements to persist environment variables
+ * for all subsequent bash commands in the session.
+ * @returns The env file path, or undefined if not set (not a SessionStart hook)
+ * @example
+ * ```typescript
+ * const envFile = getEnvFilePath();
+ * if (envFile) {
+ *   // We're in a SessionStart hook and can persist env vars
+ *   persistEnvVar('MY_VAR', 'my-value');
+ * }
+ * ```
+ */
+export declare function getEnvFilePath(): string | undefined;
+/**
+ * Checks if the hook is running in a remote (web) environment.
+ *
+ * Remote environments may have different capabilities or restrictions
+ * compared to local CLI environments.
+ * @returns true if running remotely, false if running locally
+ * @example
+ * ```typescript
+ * if (isRemoteEnvironment()) {
+ *   // Use web-compatible approaches
+ * } else {
+ *   // Can use local CLI features
+ * }
+ * ```
+ */
+export declare function isRemoteEnvironment(): boolean;
+/**
+ * Persists an environment variable for use in subsequent bash commands.
+ *
+ * This function writes a shell export statement to the `CLAUDE_ENV_FILE`,
+ * which Claude Code sources before running bash commands. This allows
+ * SessionStart hooks to configure the environment for the entire session.
+ *
+ * **Important**: This function only works in SessionStart hooks where
+ * `CLAUDE_ENV_FILE` is set. In other hooks, it will throw an error.
+ * @param name - The environment variable name
+ * @param value - The environment variable value (will be shell-escaped)
+ * @throws Error if CLAUDE_ENV_FILE is not set (not in a SessionStart hook)
+ * @example
+ * ```typescript
+ * import { sessionStartHook, sessionStartOutput, persistEnvVar } from '@goodfoot/agent-hooks';
+ *
+ * export default sessionStartHook({}, async (input) => {
+ *   // Persist environment variables for the session
+ *   persistEnvVar('NODE_ENV', 'production');
+ *   persistEnvVar('API_KEY', process.env.MY_API_KEY ?? 'default');
+ *   persistEnvVar('PATH', `${process.env.PATH}:./node_modules/.bin`);
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#persisting-environment-variables
+ */
+export declare function persistEnvVar(name: string, value: string): void;
+/**
+ * Persists multiple environment variables at once.
+ *
+ * This is a convenience wrapper around `persistEnvVar` for setting
+ * multiple variables in a single call.
+ * @param vars - Object mapping variable names to values
+ * @throws Error if CLAUDE_ENV_FILE is not set (not in a SessionStart hook)
+ * @example
+ * ```typescript
+ * persistEnvVars({
+ *   NODE_ENV: 'production',
+ *   API_KEY: 'secret',
+ *   DEBUG: 'false'
+ * });
+ * ```
+ */
+export declare function persistEnvVars(vars: Record<string, string>): void;