aiwcli 0.15.5 → 0.15.7

package/dist/lib/hooks/hook-utils.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Common utilities for hook scripts.
+ * Standardized boilerplate for JSON parsing, validation, error handling.
+ * See SPEC.md §5
+ */
+import type { ContextState, HookInput } from "../types.js";
+export declare const CONTEXT_BASELINE_TOKENS = 22600;
+export declare const DEFAULT_CONTEXT_WINDOW_SIZE = 200000;
+export interface BoundSessionContext {
+    payload: HookInput;
+    projectRoot: string;
+    sessionId: string;
+    state: ContextState;
+}
+export interface PersistenceContext extends BoundSessionContext {
+    toolInput: Record<string, unknown>;
+}
+export interface ToolInputContext {
+    payload: HookInput;
+    toolInput: Record<string, unknown>;
+}
+/**
+ * Load the current payload, resolve its project root, and require an already-bound session.
+ * Returns null when the hook should quietly no-op.
+ */
+export declare function requireBoundSession(hookName: string, prefetchedPayload?: HookInput | null): BoundSessionContext | null;
+/**
+ * Require a bound session plus tool_input for PostToolUse task persistence hooks.
+ */
+export declare function requirePersistenceContext(expectedTool: string, hookName: string): PersistenceContext | null;
+/**
+ * Require a tool_input payload for tool-oriented hooks without needing a bound session.
+ */
+export declare function requireToolInput(hookName: string): ToolInputContext | null;
+/**
+ * Best-effort wrapper around maybeActivate. Hooks should never fail closed on activation.
+ */
+export declare function safeMaybeActivate(contextId: string, permissionMode: string, projectRoot?: string, hookName?: string): boolean;
+/**
+ * Load and parse JSON from stdin (or return prefetched input if set).
+ * Returns null if stdin is empty or invalid JSON.
+ * See SPEC.md §5.1
+ */
+export declare function loadHookInput(): HookInput | null;
+/**
+ * Validate hook event type and optional tool name.
+ * See SPEC.md §5.2
+ */
+export declare function validateHookEvent(payload: HookInput, expectedEvent: string, expectedTool?: string): boolean;
+/**
+ * Extract and validate tool_input from payload.
+ * See SPEC.md §5.3
+ */
+export declare function getToolInput(payload: HookInput): Record<string, unknown> | null;
+/**
+ * Check if persistence should be skipped based on metadata flags.
+ * See SPEC.md §5.4
+ */
+export declare function checkSkipPersistence(payload: HookInput, hookName?: string): boolean;
+/**
+ * Emit hookSpecificOutput with additionalContext to stdout.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ *
+ * SubagentStop and Stop events use top-level systemMessage field instead of hookSpecificOutput.
+ * See SPEC.md §5.5
+ */
+export declare function emitContext(additionalContext: string): void;
+/**
+ * Emit hookSpecificOutput that denies the tool call with context and reason.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ * See SPEC.md §5.6
+ */
+export declare function emitContextAndBlock(additionalContext: string, reason: string): void;
+/**
+ * Block a user prompt submission with a reason.
+ * Only works for UserPromptSubmit hooks.
+ * Output: top-level { decision: "block", reason } + optional hookSpecificOutput.additionalContext
+ */
+export declare function emitBlockPrompt(reason: string, context?: string): void;
+/**
+ * Block via exit code 2 + stderr feedback.
+ * Works for PostToolUse, PostToolUseFailure.
+ * The reason becomes the stderr message (fed to Claude as system-reminder).
+ * If context is provided, it's prepended to the stderr message for richer feedback.
+ * NOTE: Exit 2 causes Claude Code to ignore all JSON stdout — only stderr matters.
+ */
+export declare function emitBlockViaExit(reason: string, context?: string): void;
+/**
+ * Block via top-level { decision: "block", reason }.
+ * Works for Stop and SubagentStop events.
+ * These events do NOT support additionalContext — only reason is available.
+ */
+export declare function emitBlockTopLevel(reason: string): void;
+/**
+ * Respond to a PermissionRequest with allow/deny.
+ * Only works for PermissionRequest hooks.
+ */
+export declare function emitPermissionDecision(behavior: "allow" | "deny", opts?: {
+    message?: string;
+    updatedInput?: Record<string, unknown>;
+    updatedPermissions?: Record<string, unknown>;
+}): void;
+/**
+ * Unified block dispatcher — auto-detects the correct blocking mechanism
+ * based on the current hook event type.
+ *
+ * PreToolUse → permissionDecision: "deny" (via emitContextAndBlock)
+ * UserPromptSubmit → top-level decision: "block" (via emitBlockPrompt)
+ * PostToolUse/PostToolUseFailure → exit(2) + stderr (via emitBlockViaExit)
+ * Stop/SubagentStop → top-level { decision: "block", reason } (via emitBlockTopLevel)
+ * PermissionRequest → decision: { behavior: "deny" } (via emitPermissionDecision)
+ * SessionStart/Notification/SubagentStart/SessionEnd/etc. → warn and no-op
+ *
+ * This is the RECOMMENDED universal blocking API. Hook authors should use
+ * emitBlock() and let the library handle event-specific dispatch.
+ */
+export declare function emitBlock(reason: string, context?: string): void;
+/**
+ * Parse context window from hook input.
+ * Returns [tokensUsed, maxTokens] or [null, null].
+ * See SPEC.md §5.9
+ */
+export declare function parseContextWindow(hookInput: HookInput): [number | null, number | null];
+/**
+ * Get context percentage remaining with fallback.
+ * Returns [percentRemaining, tokensUsed, maxTokens] or [null, null, null].
+ * See SPEC.md §5.9
+ */
+export declare function getContextPercentRemaining(hookInput: HookInput): [number | null, number | null, number | null];
+/**
+ * Standard hook entry point with lifecycle logging.
+ * See SPEC.md §5.7
+ */
+export declare function runHook(mainFunc: () => number | void, hookName?: string, prefetchedInput?: Record<string, unknown>): never;
+/**
+ * Async variant of runHook for hooks that need await (e.g., AI inference).
+ * Provides identical structured JSONL lifecycle logging as runHook.
+ * See SPEC.md §5.7
+ */
+export declare function runHookAsync(mainFunc: () => Promise<number | void>, hookName?: string, prefetchedInput?: Record<string, unknown>): void;
+export { hookLog, logBlocking, logDebug, logDiagnostic, logError, logHookError, logInfo, logWarn, setContextPath, setSessionId } from "../runtime/logger.js";