reasonix 0.4.22 → 0.4.23

package/dist/index.d.ts

@@ -253,6 +253,189 @@ declare function aggregateBranchUsage(samples: readonly BranchSample[]): {
     promptCacheMissTokens: number;
 };
 
+/**
+ * Hooks — user-defined automation that fires at well-known points in
+ * the agent loop. Mirrors the two-scope layout we use for memory and
+ * skills:
+ *
+ *   - `<project>/.reasonix/settings.json` — committable per-project
+ *   - `~/.reasonix/settings.json`         — every session
+ *
+ * A hook is a shell command. We invoke it with stdin = a JSON
+ * payload describing the event, and interpret the exit code:
+ *
+ *   - `0` — pass; loop continues normally
+ *   - `2` — block; for `PreToolUse` / `UserPromptSubmit` the
+ *     loop refuses to continue with that step and surfaces the
+ *     hook's stderr as the reason. For `PostToolUse` / `Stop` block
+ *     is meaningless (the action already happened) — treat as warn.
+ *   - anything else — warn; loop continues but stderr is rendered
+ *     to the user as an inline notice.
+ *
+ * stdin JSON shape (one envelope per event):
+ *
+ *   {
+ *     "event":    "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop",
+ *     "cwd":      "<absolute project root or process.cwd()>",
+ *     "toolName": "<string>",   // tool events only
+ *     "toolArgs": <unknown>,    // tool events only — already JSON-decoded
+ *     "toolResult": "<string>", // PostToolUse only — same body the model sees
+ *     "prompt":   "<string>",   // UserPromptSubmit only
+ *     "lastAssistantText": "<string>", // Stop only
+ *     "turn":     <number>,     // Stop only
+ *   }
+ *
+ * Hooks are executed in order: project scope first, then global.
+ * `Pre*` events stop dispatching at the first block; non-block
+ * outcomes accumulate into a single report so the UI can render
+ * each warning inline.
+ */
+type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop";
+/** All four events as a const array — drives slash listing + validation. */
+declare const HOOK_EVENTS: readonly HookEvent[];
+type HookScope = "project" | "global";
+interface HookConfig {
+    /**
+     * Tool-name pattern (PreToolUse / PostToolUse only). Anchored regex.
+     * Omitted or `"*"` matches every tool. Ignored for prompt / Stop
+     * events (they have no tool name to match against).
+     */
+    match?: string;
+    /** Shell command to run. Spawned through the platform shell. */
+    command: string;
+    /** Optional human description — surfaced in `/hooks`. */
+    description?: string;
+    /** Per-hook timeout override in ms. */
+    timeout?: number;
+    /**
+     * Working directory for the spawned process. Defaults to:
+     *   - project scope → the project root
+     *   - global scope  → process.cwd()
+     */
+    cwd?: string;
+}
+/** Shape of `<scope>/.reasonix/settings.json` — only `hooks` for now. */
+interface HookSettings {
+    hooks?: Partial<Record<HookEvent, HookConfig[]>>;
+}
+/** A loaded hook with its origin scope baked in (used for ordering and `/hooks`). */
+interface ResolvedHook extends HookConfig {
+    event: HookEvent;
+    scope: HookScope;
+    /** Absolute path to the settings.json the hook came from. */
+    source: string;
+}
+/** Outcome of a single hook invocation. */
+interface HookOutcome {
+    /** Which hook fired. */
+    hook: ResolvedHook;
+    /**
+     * Decision:
+     *   - `pass`    — exit 0
+     *   - `block`   — exit 2 on a blocking event (otherwise downgraded to `warn`)
+     *   - `warn`    — non-zero exit that is not a successful block
+     *   - `timeout` — the spawn was killed past `timeout`
+     *   - `error`   — could not spawn at all (missing command, etc.)
+     */
+    decision: "pass" | "block" | "warn" | "timeout" | "error";
+    exitCode: number | null;
+    /** Captured stdout (trimmed). May be empty. */
+    stdout: string;
+    /** Captured stderr (trimmed). The block / warn message comes from here. */
+    stderr: string;
+    durationMs: number;
+}
+/** Aggregate report for `runHooks`. */
+interface HookReport {
+    event: HookEvent;
+    outcomes: HookOutcome[];
+    /** True iff at least one outcome was a `block` — only meaningful for blocking events. */
+    blocked: boolean;
+}
+declare const HOOK_SETTINGS_FILENAME = "settings.json";
+declare const HOOK_SETTINGS_DIRNAME = ".reasonix";
+/** Where the global settings.json lives. Equivalent to `~/.reasonix/settings.json`. */
+declare function globalSettingsPath(homeDirOverride?: string): string;
+/** Where the project settings.json lives for a given root. */
+declare function projectSettingsPath(projectRoot: string): string;
+/**
+ * Pull every configured hook out of the project + global settings
+ * files, in the order they should fire (project first, global second,
+ * within each scope: array order from the file).
+ *
+ * Returns a flat list — the dispatcher filters by event + match
+ * pattern at run time. Loading is cheap (one or two JSON files), so
+ * we don't memoize across processes; re-load is allowed via
+ * `/hooks reload` and on every fresh App mount.
+ */
+interface LoadHookSettingsOptions {
+    /** Absolute project root, if any. Without it, only global hooks load. */
+    projectRoot?: string;
+    /** Override `~` for tests. */
+    homeDir?: string;
+}
+declare function loadHooks(opts?: LoadHookSettingsOptions): ResolvedHook[];
+/**
+ * True if `toolName` matches the hook's `match` field. `"*"` and
+ * undefined match everything. Otherwise we anchor the field as a
+ * regex — partial-name matches don't fire, so `"file"` would not
+ * trigger on `read_file` (use `".*file"` for that).
+ */
+declare function matchesTool(hook: ResolvedHook, toolName: string): boolean;
+/** Payload envelope passed to hook stdin. */
+interface HookPayload {
+    event: HookEvent;
+    cwd: string;
+    toolName?: string;
+    toolArgs?: unknown;
+    toolResult?: string;
+    prompt?: string;
+    lastAssistantText?: string;
+    turn?: number;
+}
+/** Test seam — same shape as Node's spawn but returns a Promise of the raw outcome bits. */
+interface HookSpawnInput {
+    command: string;
+    cwd: string;
+    stdin: string;
+    timeoutMs: number;
+}
+interface HookSpawnResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** True iff spawn() itself failed (ENOENT, EACCES, …). */
+    spawnError?: Error;
+}
+type HookSpawner = (input: HookSpawnInput) => Promise<HookSpawnResult>;
+/**
+ * Format a hook outcome as a single-line UI string. Used by both the
+ * loop (for `warning` events) and the App (for UserPromptSubmit /
+ * Stop outcomes). Centralizing keeps the language consistent across
+ * scopes.
+ */
+declare function formatHookOutcomeMessage(outcome: HookOutcome): string;
+/**
+ * Decide the hook's outcome decision from raw spawn results.
+ * Pulled out as a pure function so tests can pin the matrix.
+ */
+declare function decideOutcome(event: HookEvent, raw: HookSpawnResult): "pass" | "block" | "warn" | "timeout" | "error";
+interface RunHooksOptions {
+    payload: HookPayload;
+    hooks: ResolvedHook[];
+    /** Test seam — defaults to a real `spawn`. */
+    spawner?: HookSpawner;
+}
+/**
+ * Filter hooks down to the ones that match `payload.event` (and
+ * `payload.toolName`, for tool events), then run them in order.
+ * Stops at the first `block` outcome on a blocking event so a
+ * gating hook can prevent later hooks from incorrectly seeing a
+ * success that wasn't going to happen.
+ */
+declare function runHooks(opts: RunHooksOptions): Promise<HookReport>;
+
 interface ImmutablePrefixOptions {
     system: string;
     toolSpecs?: readonly ToolSpec[];
@@ -623,6 +806,21 @@ interface CacheFirstLoopOptions {
      * `~/.reasonix/sessions/<name>.jsonl` so the next run can resume.
      */
     session?: string;
+    /**
+     * Resolved hook list — loaded from `<project>/.reasonix/settings.json`
+     * + `~/.reasonix/settings.json` by the CLI before constructing the loop.
+     * The loop dispatches `PreToolUse` and `PostToolUse` events itself; the
+     * CLI handles `UserPromptSubmit` and `Stop` since they live at the App
+     * boundary. Empty / unset → no hooks fire (the runtime cost of an empty
+     * filter is one ms). See `src/hooks.ts` for the full contract.
+     */
+    hooks?: ResolvedHook[];
+    /**
+     * `cwd` reported to hooks via the stdin payload. Defaults to `process.cwd()`.
+     * `reasonix code` overrides this to the sandbox root so a hook that does
+     * `cd $REASONIX_CWD` lands in the project, not in the user's shell home.
+     */
+    hookCwd?: string;
 }
 /**
  * Pillar 1 — Cache-First Loop.
@@ -655,6 +853,14 @@ declare class CacheFirstLoop {
     branchEnabled: boolean;
     branchOptions: BranchOptions;
     sessionName: string | null;
+    /**
+     * Hook list, mutable so `/hooks reload` can swap it without
+     * reconstructing the loop. Default empty — the filter cost on a
+     * tool call is one array length check.
+     */
+    hooks: ResolvedHook[];
+    /** `cwd` reported to hook stdin. Resolved once at construction. */
+    readonly hookCwd: string;
     /** Number of messages that were pre-loaded from the session file. */
     readonly resumedMessageCount: number;
     private _turn;
@@ -2389,4 +2595,4 @@ declare function compareVersions(a: string, b: string): number;
  */
 declare function isNpxInstall(): boolean;
 
-export { AppendOnlyLog, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DEFAULT_MAX_RESULT_CHARS, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EditBlock, type EditSnapshot, type EventRole, type FilesystemToolsOptions, type FlattenDecision, type FlattenOptions, type GetLatestVersionOptions, type GetPromptResult, type HarvestOptions, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type InspectionReport, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, LATEST_CACHE_TTL_MS, LATEST_FETCH_TIMEOUT_MS, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoopEvent, MCP_PROTOCOL_VERSION, MEMORY_INDEX_FILE, MEMORY_INDEX_MAX_CHARS, McpClient, type McpClientOptions, type McpContentBlock, type McpProgressHandler, type McpProgressInfo, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type MemoryEntry, type MemoryScope, MemoryStore, type MemoryStoreOptions, type MemoryToolsOptions, type MemoryType, type WriteInput as MemoryWriteInput, NeedsConfirmationError, PROJECT_MEMORY_FILE, PROJECT_MEMORY_MAX_CHARS, type PageContent, PlanProposedError, type PlanToolOptions, type ProgressNotificationParams, type ProjectMemory, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type RetryInfo, type RetryOptions, type Role, type RunCommandResult, type ScavengeOptions, type ScavengeResult, type SearchResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type ShellToolsOptions, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, type ToolCallContext, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, USER_MEMORY_DIR, Usage, VERSION, VolatileScratch, type WebFetchOptions, type WebSearchOptions, type WebToolsOptions, aggregateBranchUsage, analyzeSchema, appendSessionMessage, applyEditBlock, applyEditBlocks, applyMemoryStack, applyProjectMemory, applyUserMemory, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, compareVersions, computeReplayStats, costUsd, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatCommandResult, formatLoopError, formatSearchResults, getLatestVersion, harvest, healLoadedMessages, htmlToText, inputCostUsd, inspectMcpServer, isAllowed, isJsonRpcError, isNpxInstall, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadSessionMessages, memoryEnabled, nestArguments, openTranscriptFile, outputCostUsd, parseEditBlocks, parseMcpSpec, parseMojeekResults, parseTranscript, prepareSpawn, projectHash, quoteForCmdExe, readConfig, readProjectMemory, readTranscript, recordFromLoopEvent, redactKey, registerFilesystemTools, registerMemoryTools, registerPlanTool, registerShellTools, registerWebTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, resolveExecutable, restoreSnapshots, runBranches, runCommand, sanitizeMemoryName, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, tokenizeCommand, truncateForModel, webFetch, webSearch, writeConfig, writeMeta, writeRecord };
+export { AppendOnlyLog, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DEFAULT_MAX_RESULT_CHARS, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EditBlock, type EditSnapshot, type EventRole, type FilesystemToolsOptions, type FlattenDecision, type FlattenOptions, type GetLatestVersionOptions, type GetPromptResult, HOOK_EVENTS, HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME, type HarvestOptions, type HookConfig, type HookEvent, type HookOutcome, type HookPayload, type HookReport, type HookScope, type HookSettings, type HookSpawnInput, type HookSpawnResult, type HookSpawner, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type InspectionReport, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, LATEST_CACHE_TTL_MS, LATEST_FETCH_TIMEOUT_MS, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoadHookSettingsOptions, type LoopEvent, MCP_PROTOCOL_VERSION, MEMORY_INDEX_FILE, MEMORY_INDEX_MAX_CHARS, McpClient, type McpClientOptions, type McpContentBlock, type McpProgressHandler, type McpProgressInfo, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type MemoryEntry, type MemoryScope, MemoryStore, type MemoryStoreOptions, type MemoryToolsOptions, type MemoryType, type WriteInput as MemoryWriteInput, NeedsConfirmationError, PROJECT_MEMORY_FILE, PROJECT_MEMORY_MAX_CHARS, type PageContent, PlanProposedError, type PlanToolOptions, type ProgressNotificationParams, type ProjectMemory, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type ResolvedHook, type RetryInfo, type RetryOptions, type Role, type RunCommandResult, type RunHooksOptions, type ScavengeOptions, type ScavengeResult, type SearchResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type ShellToolsOptions, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, type ToolCallContext, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, USER_MEMORY_DIR, Usage, VERSION, VolatileScratch, type WebFetchOptions, type WebSearchOptions, type WebToolsOptions, aggregateBranchUsage, analyzeSchema, appendSessionMessage, applyEditBlock, applyEditBlocks, applyMemoryStack, applyProjectMemory, applyUserMemory, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, compareVersions, computeReplayStats, costUsd, decideOutcome, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatCommandResult, formatHookOutcomeMessage, formatLoopError, formatSearchResults, getLatestVersion, globalSettingsPath, harvest, healLoadedMessages, htmlToText, inputCostUsd, inspectMcpServer, isAllowed, isJsonRpcError, isNpxInstall, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadHooks, loadSessionMessages, matchesTool, memoryEnabled, nestArguments, openTranscriptFile, outputCostUsd, parseEditBlocks, parseMcpSpec, parseMojeekResults, parseTranscript, prepareSpawn, projectHash, projectSettingsPath, quoteForCmdExe, readConfig, readProjectMemory, readTranscript, recordFromLoopEvent, redactKey, registerFilesystemTools, registerMemoryTools, registerPlanTool, registerShellTools, registerWebTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, resolveExecutable, restoreSnapshots, runBranches, runCommand, runHooks, sanitizeMemoryName, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, tokenizeCommand, truncateForModel, webFetch, webSearch, writeConfig, writeMeta, writeRecord };