@nexrall/code-core 1.4.66 → 1.4.68

package/dist/agent/fileLocks.d.ts

@@ -0,0 +1,34 @@
+export declare const _fileLocks: Map<string, Promise<void>>;
+/**
+ * Take several locks at once, always in a globally consistent order.
+ *
+ * Needed because move_file/copy_file touch TWO paths. Locking only one of them (the
+ * old behaviour locked `source` and left `dest` unprotected) leaves exactly the race
+ * the lock exists to prevent: a `move_file{dest:'shared.ts'}` running concurrently with
+ * an `edit_file{path:'shared.ts'}` had nothing serialising them.
+ *
+ * The sort is load-bearing, not tidiness: two callers acquiring {A,B} and {B,A} at the
+ * same time would deadlock, each holding what the other waits for. Sorting means every
+ * caller in the process takes them in the same order, which makes that impossible.
+ */
+export declare function withFileLocks<T>(absPaths: string[], fn: () => Promise<T>): Promise<T>;
+/**
+ * Shared lock key for bash commands that mutate repository-wide state.
+ *
+ * Not a path, because these commands do not declare one — `git commit` contends over
+ * `.git/index.lock`, `npm install` over `node_modules` and the lockfile. One key means
+ * they serialise against each other while everything else stays parallel.
+ */
+export declare const REPO_STATE_LOCK = "\0repo-state";
+/**
+ * Every path a tool call will touch, so all of them can be locked.
+ *
+ * `move_file`/`copy_file` carry `source` + `destination`, the rest carry `path`. Both
+ * `dest` and `destination` are accepted because the schema has used both spellings and
+ * silently missing the key would mean silently losing the lock — a failure that shows
+ * up as corrupted content rather than an error.
+ *
+ * Exported for tests: getting this wrong is invisible until two writes race.
+ */
+export declare function lockPathsFor(name: string, input: Record<string, unknown>, workDir?: string): string[];
+//# sourceMappingURL=fileLocks.d.ts.map

package/dist/agent/fileLocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileLocks.d.ts","sourceRoot":"","sources":["../../src/agent/fileLocks.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,UAAU,4BAAmC,CAAC;AAiB3D;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAK3F;AAQD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,iBAAqB,CAAC;AAElD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAQV"}

package/dist/agent/fileLocks.js

@@ -0,0 +1,114 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPO_STATE_LOCK = exports._fileLocks = void 0;
+exports.withFileLocks = withFileLocks;
+exports.lockPathsFor = lockPathsFor;
+const path = __importStar(require("path"));
+// ─── Per-file write lock ──────────────────────────────────────────────────────
+// When the model emits multiple tool_use blocks in one turn (executed via
+// Promise.all), two edits to the same file race: both read the original, both
+// write their version, and the second write silently discards the first edit.
+// This lock serialises writes per absolute path to prevent that.
+exports._fileLocks = new Map();
+async function withFileLock(absPath, fn) {
+    const prev = exports._fileLocks.get(absPath) ?? Promise.resolve();
+    let releaseLock;
+    const next = new Promise((res) => { releaseLock = res; });
+    exports._fileLocks.set(absPath, prev.then(() => next));
+    try {
+        await prev; // wait for any in-flight operation on this file
+        return await fn();
+    }
+    finally {
+        releaseLock();
+        // Cleanup: remove the entry once the chain is idle to avoid unbounded growth
+        if (exports._fileLocks.get(absPath) === next)
+            exports._fileLocks.delete(absPath);
+    }
+}
+/**
+ * Take several locks at once, always in a globally consistent order.
+ *
+ * Needed because move_file/copy_file touch TWO paths. Locking only one of them (the
+ * old behaviour locked `source` and left `dest` unprotected) leaves exactly the race
+ * the lock exists to prevent: a `move_file{dest:'shared.ts'}` running concurrently with
+ * an `edit_file{path:'shared.ts'}` had nothing serialising them.
+ *
+ * The sort is load-bearing, not tidiness: two callers acquiring {A,B} and {B,A} at the
+ * same time would deadlock, each holding what the other waits for. Sorting means every
+ * caller in the process takes them in the same order, which makes that impossible.
+ */
+async function withFileLocks(absPaths, fn) {
+    const unique = [...new Set(absPaths.filter(Boolean))].sort();
+    if (unique.length === 0)
+        return fn();
+    const [first, ...rest] = unique;
+    return withFileLock(first, () => (rest.length ? withFileLocks(rest, fn) : fn()));
+}
+/** Tools that mutate the filesystem and must be serialised per path. */
+const WRITE_TOOLS = new Set([
+    'write_file', 'write_docx', 'write_xlsx', 'write_pptx',
+    'edit_file', 'multi_edit', 'delete_file', 'move_file', 'copy_file', 'notebook_edit',
+]);
+/**
+ * Shared lock key for bash commands that mutate repository-wide state.
+ *
+ * Not a path, because these commands do not declare one — `git commit` contends over
+ * `.git/index.lock`, `npm install` over `node_modules` and the lockfile. One key means
+ * they serialise against each other while everything else stays parallel.
+ */
+exports.REPO_STATE_LOCK = '\u0000repo-state';
+/**
+ * Every path a tool call will touch, so all of them can be locked.
+ *
+ * `move_file`/`copy_file` carry `source` + `destination`, the rest carry `path`. Both
+ * `dest` and `destination` are accepted because the schema has used both spellings and
+ * silently missing the key would mean silently losing the lock — a failure that shows
+ * up as corrupted content rather than an error.
+ *
+ * Exported for tests: getting this wrong is invisible until two writes race.
+ */
+function lockPathsFor(name, input, workDir) {
+    if (!WRITE_TOOLS.has(name))
+        return [];
+    const raw = [input.path, input.source, input.destination, input.dest]
+        .filter((p) => typeof p === 'string' && p.length > 0);
+    const abs = raw.map((p) => (workDir ? path.resolve(workDir, p) : p));
+    // Fall back to the tool name so a malformed call still serialises against itself
+    // rather than escaping the lock entirely.
+    return abs.length ? abs : [name];
+}
+//# sourceMappingURL=fileLocks.js.map

package/dist/agent/hooks.d.ts

@@ -0,0 +1,331 @@
+import type { ToolResult, EnvContext, AgentLoopOptions } from '../types';
+import { type AgentHooks } from './agentTypes';
+export interface HookDef {
+    type: 'command' | 'http' | 'prompt' | 'agent' | 'mcp_tool';
+    command?: string;
+    /** `type:"http"`: POST the hook payload here (Claude Code's HTTP hooks). */
+    url?: string;
+    /** Extra request headers. `$VAR` / `${VAR}` are filled from allowedEnvVars only. */
+    headers?: Record<string, string>;
+    allowedEnvVars?: string[];
+    /**
+     * `type:"prompt"|"agent"`: instruction for a model that decides the outcome.
+     * `$ARGUMENTS` is replaced with the hook input JSON (`\$ARGUMENTS` escapes it).
+     * The model must answer `{"ok":true}` or `{"ok":false,"reason":"…"}`; "agent"
+     * additionally gets the read-only tools (read_file, search_files, list_directory,
+     * glob) so it can inspect the repo before deciding. A decisive `ok:false` behaves
+     * exactly like exit code 2. NOTE: this calls a model, so it BILLS the session.
+     */
+    prompt?: string;
+    /** `type:"prompt"|"agent"`: model override; defaults to the session's model. */
+    model?: string;
+    /** Seconds (Claude Code) — the loader converts it to timeout_ms. */
+    timeout?: number;
+    timeout_ms?: number;
+    /**
+     * `type:"command"`: start the hook and CONTINUE without waiting (Claude Code's
+     * `async`). No timeout is enforced, the hook cannot block or veto anything, and a
+     * JSON directive on stdout (`additionalContext` / `systemMessage`) is delivered to
+     * the model ahead of its next request.
+     */
+    async?: boolean;
+    /**
+     * `type:"command"`: like `async`, but exit code 2 WAKES the model with the hook's
+     * stderr (or stdout when stderr is empty) as a system reminder. Unlike plain `async`,
+     * the `timeout` IS enforced here.
+     */
+    asyncRewake?: boolean;
+    /**
+     * Run the hook once per session — after its first SUCCESSFUL run (exit 0) it is
+     * skipped; a failure, exit 2 or a timeout leaves it armed. Claude Code only honours
+     * this in skill frontmatter; Nexrall honours it wherever the hook is declared.
+     */
+    once?: boolean;
+    /** Spinner text shown in the UI while the hook runs (Claude Code's `statusMessage`). */
+    statusMessage?: string;
+    /** `type:"mcp_tool"`: the connected MCP server to call. */
+    server?: string;
+    /** `type:"mcp_tool"`: the tool on that server. Its text output is treated like stdout. */
+    tool?: string;
+    /**
+     * `type:"mcp_tool"`: the tool's arguments. String values may embed `${path.to.value}`
+     * from the hook's input JSON — `${tool_input.file_path}` (Claude Code spelling) and
+     * `${input.file_path}` both resolve; a value that is exactly one `${…}` keeps its
+     * original type.
+     */
+    input?: Record<string, unknown>;
+    /**
+     * Which plugin this handler came from (stamped by the loader when it merges a
+     * plugin's hooks.json — see pluginHooks in ../plugins/index). Its processes are
+     * then started with NEXRALL_PLUGIN_DATA pointing at that plugin's OWN persistent
+     * data directory, the one place it may keep files across plugin updates.
+     */
+    plugin?: string;
+}
+export interface HookEntry {
+    matcher?: string;
+    hooks: HookDef[];
+}
+export interface HooksConfig {
+    PreToolUse?: HookEntry[];
+    PostToolUse?: HookEntry[];
+    PostMessageComplete?: HookDef[];
+    OnError?: HookDef[];
+    OnStop?: HookDef[];
+    /** Runs when a SUB-AGENT finishes (Claude Code's SubagentStop). OnStop is main-agent only. */
+    SubagentStop?: HookDef[];
+    /** Once per session, before its first turn. May return additionalContext. */
+    SessionStart?: Array<HookEntry | HookDef>;
+    /** Before each user prompt is processed. Exit 2 / decision:"block" rejects it; additionalContext is appended to it. */
+    UserPromptSubmit?: Array<HookEntry | HookDef>;
+    /** Right before a conversation is auto-compacted (history is about to be summarised). */
+    PreCompact?: Array<HookEntry | HookDef>;
+    /** About to ask the user for permission. A hook may answer: {"decision":"allow"|"deny"} (exit 2 = deny). Matcher = tool name. */
+    PermissionRequest?: Array<HookEntry | HookDef>;
+    /** The agent is waiting on the user (a permission prompt). Fire-and-forget. */
+    Notification?: Array<HookEntry | HookDef>;
+    /** A tool call came back with an error. Matcher = tool name. Exit 2 / additionalContext feed the model. */
+    PostToolUseFailure?: Array<HookEntry | HookDef>;
+    /** A sub-agent is about to start. Matcher = agent type. Observer; additionalContext is added to its brief. */
+    SubagentStart?: Array<HookEntry | HookDef>;
+    /** Right after a conversation was compacted. Observer. */
+    PostCompact?: Array<HookEntry | HookDef>;
+    /** The main agent's turn run is ending (reason: completed | aborted | error | max_iterations …). Observer. */
+    SessionEnd?: Array<HookEntry | HookDef>;
+    /**
+     * A watched literal file in the working directory changed on disk (Claude Code's
+     * FileChanged). Matcher = filename(s), "a.txt|b.txt" — it both builds the watch list
+     * and selects which groups run for THAT file. Observer; a hook answering with
+     * {"watchPaths":[…]} replaces the dynamic watch list — a dynamic file had no matcher
+     * naming it, so it notifies EVERY FileChanged group — and {"systemMessage":"…"} is shown.
+     */
+    FileChanged?: Array<HookEntry | HookDef>;
+    /**
+     * Instruction files were loaded for this session (nexrall.md, memory). Matcher =
+     * load reason ("session_start"). Observer; output and exit code are ignored.
+     */
+    InstructionsLoaded?: Array<HookEntry | HookDef>;
+    /**
+     * The turn ended because of an API error (Claude Code's StopFailure — fires INSTEAD
+     * of a clean stop). Matcher = error type (rate_limit, overloaded, authentication_failed,
+     * billing_error, invalid_request, model_not_found, server_error, max_output_tokens,
+     * unknown). Observer: output and exit code are ignored.
+     */
+    StopFailure?: Array<HookEntry | HookDef>;
+    /** The permission gate REFUSED a tool call (rule, mode, plan lock, destructive guard, dontAsk). Matcher = tool name. Observer. */
+    PermissionDenied?: Array<HookEntry | HookDef>;
+    /** About to switch model (/model, picker, fallback). Matcher = new model id. Observer — it cannot veto the switch. */
+    PreModelSwitch?: Array<HookEntry | HookDef>;
+    /** The model was switched. Matcher = new model id. Observer. */
+    PostModelSwitch?: Array<HookEntry | HookDef>;
+    /** The session's working directory changed. Observer. */
+    CwdChanged?: Array<HookEntry | HookDef>;
+    /** An extra working directory was added (--add-dir, /add-dir). Observer. */
+    DirectoryAdded?: Array<HookEntry | HookDef>;
+    /** A setting changed in-session (/config, /theme, /output-style …). Matcher = the setting key. Observer. */
+    ConfigChange?: Array<HookEntry | HookDef>;
+    /** A git worktree was created for this session. Observer. */
+    WorktreeCreate?: Array<HookEntry | HookDef>;
+    /** A session worktree was removed. Observer. */
+    WorktreeRemove?: Array<HookEntry | HookDef>;
+    /** Once, on startup, when the CLI is run with --init / --maintenance style setup (matcher "init" | "maintenance"). Observer. */
+    Setup?: Array<HookEntry | HookDef>;
+    /**
+     * After EVERY tool call of a batch resolved, ONCE, before the next model call (Claude
+     * Code's PostToolBatch — PostToolUse fires per tool, this fires per batch). Payload:
+     * `tool_calls: [{tool_name, tool_input, tool_use_id, tool_response}]` where tool_response
+     * is the text the model receives. `additionalContext` is injected with the tool results;
+     * exit 2 / `decision:"block"` stops the turn before the next model call (the reason stays
+     * in the conversation). No matcher.
+     */
+    PostToolBatch?: Array<HookEntry | HookDef>;
+    /**
+     * A shared task was just created (`create_shared_task`). Payload: `task_id`,
+     * `task_subject`, `task_description?`, `teammate_name?`. Exit 2 / `decision:"block"`
+     * DELETES the task and returns the reason to the model as the tool's error — exactly
+     * Claude Code's contract, so a veto always leaves no task behind. No matcher.
+     */
+    TaskCreated?: Array<HookEntry | HookDef>;
+    /**
+     * A shared task is about to be marked completed (`update_shared_task_status`). Payload:
+     * `task_id`, `task_subject`, `task_description?`, `teammate_name?`. Exit 2 /
+     * `decision:"block"` refuses the completion and feeds the reason back to the model, so
+     * the task stays open. No matcher.
+     */
+    TaskCompleted?: Array<HookEntry | HookDef>;
+    /**
+     * An MCP server asked the user for input mid-tool-call (its `elicitation/create`
+     * request). Runs BEFORE the interactive dialog: a hook whose stdout carries
+     * `hookSpecificOutput:{action:"accept"|"decline"|"cancel", content:{…}}` answers
+     * outright, so a CI can fill a form nobody is there to type — the first hook that
+     * answers wins and the dialog is skipped. Exit 2 = decline. Matcher = MCP server
+     * name. Input includes `message`, `mode` ('form'|'url'), `requested_schema` (form),
+     * `url` + `elicitation_id` (url mode).
+     */
+    Elicitation?: Array<HookEntry | HookDef>;
+    /**
+     * After an elicitation was answered (by a hook or by the user), before the response
+     * is sent back to the server. Same `hookSpecificOutput` shape may OVERRIDE the
+     * answer — overrides apply in order, the last one wins; a hook that accepts without
+     * `content` keeps the existing values. Exit 2 blocks the response, which means
+     * 'decline' with the content dropped. Matcher = MCP server name. Input includes
+     * `action`, `content?`, `mode`, `elicitation_id?`.
+     */
+    ElicitationResult?: Array<HookEntry | HookDef>;
+}
+export declare function withAgentHooks(base: HooksConfig, agent?: AgentHooks): HooksConfig;
+export declare function loadHooks(workDir: string): HooksConfig;
+/** Events a host fires purely to tell hooks something happened. Their output and exit code are ignored. */
+export type ObserverEvent = 'PermissionDenied' | 'PreModelSwitch' | 'PostModelSwitch' | 'CwdChanged' | 'DirectoryAdded' | 'ConfigChange' | 'WorktreeCreate' | 'WorktreeRemove' | 'Setup';
+export interface HookOutcome {
+    /** PermissionRequest only: a hook answered "allow" (block = answered "deny"). */
+    allow?: boolean;
+    block: boolean;
+    reason?: string;
+    context?: string;
+    /** FileChanged only: replace the dynamic watch list (Claude Code's watchPaths). */
+    watchPaths?: string[];
+    /** FileChanged only: a one-line notice to show the user (systemMessage). */
+    systemMessage?: string;
+}
+export interface HookDelivery {
+    /** 'context' = feed the model before its next request; 'wake' = start a turn NOW. */
+    kind: 'context' | 'wake';
+    text: string;
+    /** Which hook produced it, e.g. `PostToolUse (Bash) · asyncRewake`. */
+    source: string;
+}
+/** Called (if set) the moment a wake lands, so an idle host can react at once. */
+export declare function setHookWakeListener(fn: (() => void) | null): void;
+/** Where `statusMessage` goes. The message is null when no hook is running. */
+export declare function setHookStatusListener(fn: ((message: string | null) => void) | null): void;
+/** Everything queued so far — the loop calls this before each request. */
+export declare function drainHookDeliveries(): HookDelivery[];
+/** Only the wakes — an idle host must not start a turn just for async context. */
+export declare function takeHookWakes(): HookDelivery[];
+export declare function hasPendingHookWake(): boolean;
+/** The text a delivery batch becomes in the conversation — the same envelope sync hooks use. */
+export declare function formatHookDeliveries(list: HookDelivery[]): string;
+/** Forget which `once` hooks have run (a new session: /clear, a fresh run). */
+export declare function resetHookOnceState(): void;
+/** What a `type:"mcp_tool"` handler calls — the host wires one from its MCP manager. */
+export type HookMcpCaller = (server: string, tool: string, input: Record<string, unknown>) => Promise<{
+    text: string;
+} | {
+    error: string;
+}>;
+/** Hosts with connected MCP servers register their caller once; null = mcp_tool hooks report "no MCP client". */
+export declare function setHookMcpCaller(fn: HookMcpCaller | null): void;
+/** One lifecycle record for a single hook run — hosts format/stream these. */
+export interface HookLifecycleEvent {
+    kind: 'started' | 'progress' | 'response';
+    /** Stable for one run: the same id on its started, progress and response records. */
+    hookId: string;
+    /** Display name of the handler — its command, url, `server:tool`, or handler type. */
+    hookName: string;
+    /** The event that fired it: 'PreToolUse', 'SessionStart', … */
+    hookEvent: string;
+    /** Progress: output since the previous progress record. Response: the full output. */
+    stdout?: string;
+    stderr?: string;
+    /** Response: stdout+stderr as one string; progress: this record's stdout+stderr. */
+    output?: string;
+    /** Response only, and only when the hook actually exited. */
+    exitCode?: number;
+    /** Response only: 0 → success; killed/never-exited → cancelled; anything else → error. */
+    outcome?: 'success' | 'error' | 'cancelled';
+}
+/**
+ * Install (or clear) the sink that receives every hook run's lifecycle records.
+ * One per process: hooks fire from the loop, the lifecycle host and the permission
+ * gate, but they all belong to the same session's stream.
+ */
+export declare function setHookEventListener(fn: ((evt: HookLifecycleEvent) => void) | null): void;
+/** True when a sink is installed, for hosts skipping work that would only feed the stream. */
+export declare function hasHookEventListener(): boolean;
+/** Pull the decision object out of a model reply: first {...} block, fences tolerated. */
+export declare function parsePromptHookReply(reply: string): {
+    ok?: boolean;
+    reason?: string;
+    additionalContext?: string;
+    decision?: string;
+} | null;
+/** Model / env / abort for prompt+agent hooks, taken from the run that fires them. */
+export declare function hookRunOptsFor(options: AgentLoopOptions): HookRunOpts;
+/**
+ * Map a stream/API error onto Claude Code's StopFailure error types, so a matcher
+ * written for one works here: rate_limit, overloaded, authentication_failed,
+ * billing_error, invalid_request, model_not_found, server_error, max_output_tokens,
+ * cloud_credential_error, account_on_hold, unknown.
+ *
+ * Only what the error actually carries is used (HTTP status, then code) — no guessing
+ * from message text, which would misfile e.g. a user-facing "rate limit" in a tool error.
+ */
+export declare function classifyStopFailure(err: unknown): {
+    error: string;
+    error_details?: string;
+};
+/** The same mapping for stops that ended the loop WITHOUT a throw. */
+export declare function apiFailureForStopReason(stopReason: string): {
+    error: string;
+    error_details?: string;
+} | null;
+export declare function runToolHooks(entries: HookEntry[] | undefined, phase: 'PreToolUse' | 'PostToolUse', toolName: string, input: Record<string, unknown>, workDir: string, result?: ToolResult, hookOpts?: HookRunOpts): Promise<HookOutcome>;
+export declare function runSimpleHooks(defs: HookDef[] | undefined, workDir: string, extraEnv?: Record<string, string>, hookOpts?: HookRunOpts, event?: string): Promise<void>;
+/** Model / env / abort threaded from the run so prompt+agent hooks can call a model. */
+interface HookRunOpts {
+    model?: string;
+    abortSignal?: {
+        aborted: boolean;
+    };
+    hookEnv?: EnvContext;
+}
+export declare function runLifecycleHooks(items: Array<HookEntry | HookDef> | undefined, event: string, workDir: string, payload: Record<string, unknown>, matchValue?: string, hookOpts?: HookRunOpts): Promise<HookOutcome>;
+/**
+ * For hosts that show their own permission prompt: ask PermissionRequest hooks first.
+ * 'allow' / 'deny' = a hook answered, so the human is not asked; null = nobody answered,
+ * ask as usual. A DENY wins over an allow (a stricter hook is never overruled by a looser one),
+ * and a hook that crashes or times out answers nothing — it can never silently approve.
+ */
+export declare function runPermissionRequestHooks(workDir: string, tool: string, input: Record<string, unknown>, sessionId?: string): Promise<{
+    answer: 'allow' | 'deny' | null;
+    reason?: string;
+}>;
+export type ElicitationAction = 'accept' | 'decline' | 'cancel';
+export interface ElicitationAnswer {
+    action: ElicitationAction;
+    content?: Record<string, unknown>;
+}
+/**
+ * Ask Elicitation hooks before the user sees the dialog. Returns the answer a hook
+ * supplied, or null when none did (the caller then asks the human). Exit 2 = decline.
+ * The FIRST hook that answers wins — later hooks are not consulted, so two hooks can
+ * never fight over one dialog. A background (`async`) hook cannot answer by design.
+ */
+export declare function runElicitationHooks(workDir: string, server: string, input: Record<string, unknown>, sessionId?: string): Promise<ElicitationAnswer | null>;
+/**
+ * Run ElicitationResult hooks after an elicitation was answered and override the answer
+ * with whatever they return (exit 2 = decline, content dropped). Always returns an answer
+ * safe to send to the server, so a throw inside a hook can never turn one into none.
+ */
+export declare function runElicitationResultHooks(workDir: string, server: string, answer: ElicitationAnswer, meta?: {
+    sessionId?: string;
+    mode?: string;
+    elicitationId?: string;
+}): Promise<ElicitationAnswer>;
+/**
+ * Tell hooks that something happened. Awaitable, but it can NEVER block, throw or change the
+ * outcome: an observer event is a notification, so a hook that exits 2, prints a decision or
+ * crashes is ignored. `matchValue` is the event's selector (tool name, model id, setting key).
+ * Returns how many handler groups were configured, so a caller/test can tell "nothing
+ * listening" from "ran".
+ */
+export declare function fireObserverHook(workDir: string, event: ObserverEvent, payload: Record<string, unknown>, matchValue?: string): Promise<number>;
+/** For hosts (the CLI) that show the prompt themselves: run Notification hooks, never blocking. */
+export declare function fireNotificationHooks(workDir: string, message: string, type?: string): void;
+/** For hosts that run their own manual /compact: fire PreCompact (trigger "manual"), awaited, never blocking. */
+/** The manual /compact counterpart of the auto PostCompact hook (trigger "manual"). */
+export declare function fireManualPostCompactHook(workDir: string, sessionId: string, messagesSummarized: number): Promise<void>;
+export declare function fireManualPreCompactHook(workDir: string, sessionId: string, messagesToSummarize: number): Promise<void>;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/agent/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/agent/hooks.ts"],"names":[],"mappings":"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"}