@goodfoot/agent-hooks 1.0.0

package/types/core/logger.d.ts

@@ -0,0 +1,476 @@
+/**
+ * Logger system for agent hooks.
+ *
+ * Provides structured logging with event subscription and optional file output.
+ * The logger is **silent by default** to avoid interfering with hook protocol
+ * (stdout is reserved for JSON responses, stderr may conflict with the host
+ * CLI).
+ * @module
+ * @example
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * // Subscribe to log events
+ * const unsubscribe = logger.on('error', (event) => {
+ *   console.error(`Error in ${event.hookType}: ${event.message}`);
+ * });
+ *
+ * // Later, clean up
+ * unsubscribe();
+ * ```
+ */
+/**
+ * Available log levels.
+ *
+ * | Level | Severity | Use Case |
+ * |-------|----------|----------|
+ * | `debug` | Lowest | Detailed debugging information |
+ * | `info` | Low | General operational events |
+ * | `warn` | Medium | Warning conditions that may indicate issues |
+ * | `error` | High | Error conditions requiring attention |
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * All log levels in order of severity (lowest to highest).
+ */
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+/**
+ * A structured log event emitted by the logger.
+ *
+ * Log events contain contextual information about what happened during hook
+ * execution, making them suitable for debugging, monitoring, and analytics.
+ * @example
+ * ```typescript
+ * // Example log event
+ * const event: LogEvent = {
+ *   timestamp: '2024-01-15T10:30:00.000Z',
+ *   level: 'warn',
+ *   hookType: 'PreToolUse',
+ *   message: 'Blocking dangerous command',
+ *   input: { tool_name: 'Bash', tool_input: { command: 'rm -rf /' } }
+ * };
+ * ```
+ */
+export interface LogEvent {
+    /**
+     * ISO 8601 timestamp of when the event occurred.
+     * @example '2024-01-15T10:30:00.000Z'
+     */
+    timestamp: string;
+    /**
+     * Severity level of the log event.
+     */
+    level: LogLevel;
+    /**
+     * Agent event name of the hook that generated this event.
+     * May be undefined for events outside hook context.
+     */
+    hookType?: string;
+    /**
+     * Human-readable description of what happened.
+     */
+    message: string;
+    /**
+     * Hook input data at the time of logging.
+     * Useful for debugging and reproducing issues.
+     */
+    input?: Record<string, unknown>;
+    /**
+     * Error information if this event represents an error.
+     * Contains structured error details for analysis.
+     */
+    error?: LogEventError;
+    /**
+     * Additional context data provided by the caller.
+     * Can contain arbitrary metadata relevant to the event.
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * Structured error information within a log event.
+ */
+export interface LogEventError {
+    /**
+     * Error name (e.g., 'TypeError', 'ValidationError').
+     */
+    name: string;
+    /**
+     * Error message describing what went wrong.
+     */
+    message: string;
+    /**
+     * Stack trace if available.
+     */
+    stack?: string;
+    /**
+     * Error cause chain if the error was wrapped.
+     */
+    cause?: LogEventError;
+}
+/**
+ * Handler function invoked when a log event is emitted.
+ *
+ * Handlers receive log events and can process them in any way - forwarding
+ * to external services, writing to custom formats, or aggregating metrics.
+ * @param event - The log event to handle
+ * @example
+ * ```typescript
+ * // Forward to external logging service
+ * const handler: LogEventHandler = (event) => {
+ *   externalLogger.log({
+ *     level: event.level,
+ *     message: event.message,
+ *     metadata: { hookType: event.hookType }
+ *   });
+ * };
+ * ```
+ */
+export type LogEventHandler = (event: LogEvent) => void;
+/**
+ * Function to unsubscribe a log event handler.
+ *
+ * Call this function to stop receiving log events. Always call unsubscribe
+ * when the handler is no longer needed to prevent memory leaks.
+ * @example
+ * ```typescript
+ * const unsubscribe = logger.on('error', handleError);
+ * // ... later
+ * unsubscribe(); // Stop receiving events
+ * ```
+ */
+export type Unsubscribe = () => void;
+/**
+ * Configuration options for the Logger.
+ */
+export interface LoggerConfig {
+    /**
+     * Path to the log file for file output.
+     * If not set, file logging is disabled.
+     */
+    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 `'AGENT_HOOKS_LOG_FILE'` for the exported singleton.
+     */
+    logEnvVar?: string;
+}
+/**
+ * Logger for agent hooks with event subscription and file output.
+ *
+ * ## Key Behaviors
+ *
+ * | Configuration | Behavior |
+ * |--------------|----------|
+ * | No config (default) | **Silent** - no output anywhere |
+ * | `AGENT_HOOKS_LOG_FILE` env var | Append JSON lines to file |
+ * | `.on(level, handler)` registered | Events delivered to handlers only |
+ * | Multiple destinations | All destinations receive events |
+ *
+ * ## Important Notes
+ *
+ * - **Never outputs to stdout** (reserved for JSON hook response)
+ * - **Never outputs to stderr** (may interfere with host CLI error handling)
+ * - File output uses JSON Lines format for easy parsing
+ * - `.on(level, handler)` returns an unsubscribe function
+ * @example
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * // Subscribe to events at specific level
+ * logger.on('warn', (event) => {
+ *   sendAlert(event.message);
+ * });
+ *
+ * // Log within a hook handler
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.warn('About to validate Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ */
+export declare class Logger {
+    /**
+     * Registered event handlers by log level.
+     */
+    private handlers;
+    /**
+     * File descriptor for log file output.
+     * Lazily initialized on first write.
+     */
+    private logFileFd;
+    /**
+     * Path to the log file, if configured.
+     */
+    private logFilePath;
+    /**
+     * Whether file initialization has been attempted.
+     */
+    private fileInitialized;
+    /**
+     * Current hook context for enriching log events.
+     */
+    private currentHookType;
+    /**
+     * Current hook input for enriching log events.
+     */
+    private currentInput;
+    /**
+     * Creates a new Logger instance.
+     *
+     * Typically you should use the exported `logger` singleton rather than
+     * creating new instances.
+     * @param config - Optional configuration
+     * @example
+     * ```typescript
+     * // Use singleton (recommended)
+     * import { logger } from '@goodfoot/agent-hooks';
+     *
+     * // Or create custom instance
+     * const customLogger = new Logger({ logFilePath: '/var/log/hooks.log' });
+     * ```
+     */
+    constructor(config?: LoggerConfig);
+    /**
+     * Logs a debug message.
+     *
+     * Use for detailed debugging information that is typically only useful
+     * during development or troubleshooting.
+     * @param message - The debug message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.debug('Processing tool input', { toolName: 'Bash', inputSize: 256 });
+     * ```
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs an info message.
+     *
+     * Use for general operational events like hook invocations, successful
+     * completions, or state changes.
+     * @param message - The info message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.info('Session started', { source: 'startup', sessionId: 'abc123' });
+     * ```
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs a warning message.
+     *
+     * Use for conditions that may indicate issues but don't prevent
+     * operation, such as deprecated patterns or performance concerns.
+     * @param message - The warning message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.warn('Deprecated hook pattern detected', { pattern: 'legacyMatcher' });
+     * ```
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs an error message.
+     *
+     * Use for error conditions that require attention but were handled
+     * gracefully. For exceptions, prefer {@link logError}.
+     * @param message - The error message
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * logger.error('Failed to validate tool input', { toolName: 'Bash', reason: 'empty command' });
+     * ```
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Logs a structured error with full error details.
+     *
+     * Use this method when logging caught exceptions to capture the full
+     * error context including name, message, stack trace, and cause chain.
+     * @param error - The error to log
+     * @param message - Human-readable description of what failed
+     * @param context - Optional additional context
+     * @example
+     * ```typescript
+     * try {
+     *   await dangerousOperation();
+     * } catch (err) {
+     *   logger.logError(err, 'Failed to execute dangerous operation', {
+     *     operation: 'delete',
+     *     target: '/important/file.txt'
+     *   });
+     * }
+     * ```
+     */
+    logError(error: unknown, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Subscribes a handler to log events at the specified level.
+     *
+     * The handler will be called for every log event at the specified level.
+     * Returns an unsubscribe function that should be called when the handler
+     * is no longer needed.
+     * @param level - The log level to subscribe to
+     * @param handler - The handler function to call for each event
+     * @returns A function to unsubscribe the handler
+     * @example
+     * ```typescript
+     * // Subscribe to error events
+     * const unsubscribe = logger.on('error', (event) => {
+     *   console.error(`[${event.hookType}] ${event.message}`);
+     *   if (event.error) {
+     *     console.error(event.error.stack);
+     *   }
+     * });
+     *
+     * // Later, clean up
+     * unsubscribe();
+     * ```
+     * @example
+     * ```typescript
+     * // Forward to external logging library
+     * import pino from 'pino';
+     * const pinoLogger = pino();
+     *
+     * logger.on('info', (event) => pinoLogger.info(event, event.message));
+     * logger.on('warn', (event) => pinoLogger.warn(event, event.message));
+     * logger.on('error', (event) => pinoLogger.error(event, event.message));
+     * ```
+     */
+    on(level: LogLevel, handler: LogEventHandler): Unsubscribe;
+    /**
+     * Sets the current hook context for enriching log events.
+     *
+     * This is called internally by the runtime before invoking hook handlers.
+     * You typically don't need to call this directly.
+     * @param hookType - The agent event name being executed
+     * @param input - The hook input data
+     * @internal
+     */
+    setContext(hookType: string | undefined, input: Record<string, unknown> | undefined): void;
+    /**
+     * Clears the current hook context.
+     *
+     * Called internally by the runtime after hook execution completes.
+     * @internal
+     */
+    clearContext(): void;
+    /**
+     * Configures the log file path at runtime.
+     *
+     * Call this to enable or change file logging. Setting to `null` disables
+     * file logging (but doesn't close existing file handle immediately).
+     * @param filePath - Path to the log file, or null to disable
+     * @example
+     * ```typescript
+     * // Enable file logging at runtime
+     * logger.setLogFile('/var/log/agent-hooks.log');
+     *
+     * // Disable file logging
+     * logger.setLogFile(null);
+     * ```
+     */
+    setLogFile(filePath: string | null): void;
+    /**
+     * Closes all resources held by the logger.
+     *
+     * Call this during graceful shutdown to ensure all log data is flushed.
+     * @example
+     * ```typescript
+     * process.on('exit', () => {
+     *   logger.close();
+     * });
+     * ```
+     */
+    close(): void;
+    /**
+     * Checks if there are any active handlers or destinations.
+     *
+     * Returns true if any handlers are registered or file logging is enabled.
+     * @returns Whether the logger has any active output destinations
+     */
+    hasDestinations(): boolean;
+    /**
+     * Emits a log event.
+     * @param level - The severity level of the event
+     * @param message - The log message
+     * @param context - Optional additional context data
+     */
+    private emit;
+    /**
+     * Delivers an event to all registered destinations.
+     * @param event - The log event to deliver
+     */
+    private deliverEvent;
+    /**
+     * Writes an event to the log file.
+     * @param event - The log event to write
+     */
+    private writeToFile;
+    /**
+     * Initializes the log file for writing.
+     */
+    private initializeFile;
+    /**
+     * Extracts structured error information from an unknown error.
+     * @param error - The error to extract information from
+     * @returns Structured error information
+     */
+    private extractErrorInfo;
+}
+/**
+ * Global logger instance for agent hooks.
+ *
+ * Use this singleton for all logging within hooks. The logger is configured
+ * via environment variables and supports event subscription for custom
+ * destinations.
+ *
+ * ## Configuration
+ *
+ * | Environment Variable | Description |
+ * |---------------------|-------------|
+ * | `AGENT_HOOKS_LOG_FILE` | Path to log file (JSON Lines format) |
+ *
+ * ## Usage in Hooks
+ *
+ * The logger is passed to hook handlers via context for convenience:
+ *
+ * ```typescript
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.warn('Validating Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ *
+ * ## External Integration
+ *
+ * Subscribe to events to forward logs to external systems:
+ *
+ * ```typescript
+ * import { logger } from '@goodfoot/agent-hooks';
+ * import pino from 'pino';
+ *
+ * const pinoLogger = pino({ level: 'debug' });
+ *
+ * logger.on('debug', (event) => pinoLogger.debug(event, event.message));
+ * logger.on('info', (event) => pinoLogger.info(event, event.message));
+ * logger.on('warn', (event) => pinoLogger.warn(event, event.message));
+ * logger.on('error', (event) => pinoLogger.error(event, event.message));
+ * ```
+ * @example
+ * ```typescript
+ * // Direct usage
+ * import { logger } from '@goodfoot/agent-hooks';
+ *
+ * logger.info('Starting operation');
+ * logger.warn('Resource limit approaching', { usage: 0.9 });
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   logger.logError(err, 'Risky operation failed');
+ * }
+ * ```
+ */
+export declare const logger: Logger;

package/types/core/stdin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Stdin acquisition and JSON parsing for agent hooks.
+ *
+ * Both source runtimes (`claude-code-hooks`, `codex-hooks`) read stdin and
+ * parse JSON identically; this module is that shared logic. Wire rules for
+ * what a parse failure *means* belong to each agent's transport — core only
+ * classifies the outcome.
+ * @module
+ */
+/**
+ * Reads all data from stdin.
+ * @returns Promise resolving to the complete stdin content
+ */
+export declare function readStdin(): Promise<string>;
+/**
+ * Parses stdin JSON input.
+ * @param stdinContent - Raw stdin content
+ * @returns Parsed input in the host CLI's wire format
+ * @throws SyntaxError if JSON is malformed
+ */
+export declare function parseStdinJson(stdinContent: string): unknown;

package/types/core/transport.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Transport abstraction and the shared driver.
+ *
+ * Core owns the try/catch skeleton — stdin read, JSON parse, handler
+ * invocation, outcome classification, buffered single-write emission, process
+ * exit — and has **no knowledge of exit codes or stdout policy**: every wire
+ * decision is delegated to the agent's {@link Transport.finalize}, a pure
+ * mapping from {@link HookOutcome} to `{ stdout?, stderr?, exitCode }`. Agent
+ * transports are data-heavy adapters; they must not re-implement driver logic.
+ * @module
+ * @example
+ * ```typescript
+ * const transport: Transport<MyOutput> = {
+ *   finalize: (outcome) => {
+ *     if (outcome.kind === "response") {
+ *       return { stdout: JSON.stringify(outcome.output ?? {}), exitCode: 0 };
+ *     }
+ *     return { stderr: "blocked", exitCode: 2 };
+ *   },
+ * };
+ *
+ * await drive(transport, myHook);
+ * ```
+ */
+import type { HookContext, HookErrorPhase, HookFunction } from "./types.js";
+/**
+ * Error thrown by a hook handler to signal an intentional block.
+ *
+ * `drive()` classifies a caught {@link HookBlockError} **before** consulting
+ * the `unexpectedError` policy: it always routes to the `block` outcome,
+ * under every policy value, so an advisory event's in-flight block decision
+ * survives a crash mid-computation. Any other throw is subject to policy as
+ * usual. Agents may subclass or re-export this class; each agent's transport
+ * owns the wire translation of the `block` outcome.
+ */
+export declare class HookBlockError extends Error {
+    /**
+     * Optional structured fields carried alongside the block reason (e.g.
+     * extra wire fields the agent's translation may forward).
+     */
+    readonly fields?: Record<string, unknown>;
+    /**
+     * @param message - The block reason; becomes the error `message`.
+     * @param fields - Optional additional structured fields.
+     */
+    constructor(message: string, fields?: Record<string, unknown>);
+}
+/**
+ * The classified result of one hook invocation, prior to wire mapping.
+ *
+ * Discriminated by `kind`; core produces exactly one outcome per invocation
+ * and hands it to {@link Transport.finalize} exactly once.
+ * @template TOutput - The agent's output type for the event.
+ */
+export type HookOutcome<TOutput> = 
+/** The handler returned normally (`output: undefined` = empty response). */
+{
+    kind: "response";
+    output: TOutput | undefined;
+}
+/** The handler threw a {@link HookBlockError}. */
+ | {
+    kind: "block";
+    error: HookBlockError;
+}
+/** The handler (or a pre-handler phase) failed unexpectedly. */
+ | {
+    kind: "handlerError";
+    error: unknown;
+    phase: HookErrorPhase;
+}
+/** The handler returned a plain-text-protocol payload, per the transport's predicate. */
+ | {
+    kind: "rawStdout";
+    stdout: string;
+};
+/**
+ * The wire-level result produced by a transport's finalize mapping.
+ */
+export interface FinalizedResult {
+    /** Text to write to stdout, or undefined to write nothing. */
+    stdout?: string;
+    /** Text to write to stderr, or undefined to write nothing. */
+    stderr?: string;
+    /** Process exit code. */
+    exitCode: number;
+}
+/**
+ * Per-agent wire adapter.
+ *
+ * Implementations own all exit-code and stdout/stderr policy decisions:
+ * `finalize` is a pure mapping from the classified outcome to the streams and
+ * exit code the host CLI should observe. It must not throw and must not
+ * perform I/O; `drive()` owns writing and exiting.
+ *
+ * The optional `rawStdout` predicate lets the transport declare which
+ * returned outputs carry a plain-text protocol payload (e.g. worktree events
+ * whose stdout is read verbatim by the host): when it returns a string for a
+ * normally-returned output, `drive()` classifies the invocation as
+ * `rawStdout` instead of `response`. The returned output is never modified.
+ *
+ * @template TOutput - The agent's output type for the event.
+ */
+export interface Transport<TOutput> {
+    /**
+     * Purely maps a classified outcome to wire text and an exit code.
+     * Called exactly once per invocation.
+     */
+    finalize(outcome: HookOutcome<TOutput>): FinalizedResult;
+    /**
+     * Optional plain-text-protocol detector. See {@link Transport}.
+     */
+    rawStdout?(output: TOutput): string | undefined;
+}
+/**
+ * Runs one hook invocation end to end: reads stdin, parses JSON, invokes the
+ * handler, classifies the outcome, maps it once through the transport, writes
+ * the resulting streams buffered (at most one write per stream), and exits
+ * with the transport's exit code.
+ *
+ * Malformed/unreadable stdin is classified at its phase (`read`/`parse`) like
+ * any other unexpected failure and logged identically to both source
+ * runtimes; each agent's transport decides the wire shape for that
+ * classification.
+ *
+ * @param transport - The agent's wire adapter.
+ * @param hookFn - The hook function to execute (from a factory built on
+ * {@link defineHook}).
+ * @returns Never resolves normally: the process exits inside this function.
+ */
+export declare function drive<TInput, TOutput>(transport: Transport<TOutput>, hookFn: HookFunction<TInput, TOutput, HookContext>): Promise<void>;