@nexrall/code-core 1.4.66 → 1.4.67

package/dist/agent/hooks.js

@@ -0,0 +1,1228 @@
+"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.withAgentHooks = withAgentHooks;
+exports.loadHooks = loadHooks;
+exports.setHookWakeListener = setHookWakeListener;
+exports.setHookStatusListener = setHookStatusListener;
+exports.drainHookDeliveries = drainHookDeliveries;
+exports.takeHookWakes = takeHookWakes;
+exports.hasPendingHookWake = hasPendingHookWake;
+exports.formatHookDeliveries = formatHookDeliveries;
+exports.resetHookOnceState = resetHookOnceState;
+exports.setHookMcpCaller = setHookMcpCaller;
+exports.setHookEventListener = setHookEventListener;
+exports.hasHookEventListener = hasHookEventListener;
+exports.parsePromptHookReply = parsePromptHookReply;
+exports.hookRunOptsFor = hookRunOptsFor;
+exports.classifyStopFailure = classifyStopFailure;
+exports.apiFailureForStopReason = apiFailureForStopReason;
+exports.runToolHooks = runToolHooks;
+exports.runSimpleHooks = runSimpleHooks;
+exports.runLifecycleHooks = runLifecycleHooks;
+exports.runPermissionRequestHooks = runPermissionRequestHooks;
+exports.runElicitationHooks = runElicitationHooks;
+exports.runElicitationResultHooks = runElicitationResultHooks;
+exports.fireObserverHook = fireObserverHook;
+exports.fireNotificationHooks = fireNotificationHooks;
+exports.fireManualPostCompactHook = fireManualPostCompactHook;
+exports.fireManualPreCompactHook = fireManualPreCompactHook;
+const client_1 = require("../api/client");
+const executor_1 = require("../tools/executor");
+const agentTypes_1 = require("./agentTypes");
+const rules_1 = require("../permissions/rules");
+const index_1 = require("../plugins/index");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+function withAgentHooks(base, agent) {
+    if (!agent)
+        return base;
+    return {
+        ...base,
+        PreToolUse: [...(base.PreToolUse ?? []), ...(agent.PreToolUse ?? [])],
+        PostToolUse: [...(base.PostToolUse ?? []), ...(agent.PostToolUse ?? [])],
+        SubagentStop: [...(base.SubagentStop ?? []), ...(agent.Stop ?? [])],
+    };
+}
+function loadHooks(workDir) {
+    let fromSettings = {};
+    try {
+        const p = path.join(workDir, '.nexrall', 'settings.json');
+        if (fs.existsSync(p))
+            fromSettings = JSON.parse(fs.readFileSync(p, 'utf-8')).hooks ?? {};
+    }
+    catch { /* ignore */ }
+    // `--settings`: hooks from the run's own settings object run after the project's.
+    const sess = (0, rules_1.getSessionSettings)()?.hooks;
+    if (sess && typeof sess === 'object') {
+        const base = { ...fromSettings };
+        for (const [phase, list] of Object.entries(sess)) {
+            if (Array.isArray(list))
+                base[phase] = [...(base[phase] ?? []), ...list];
+        }
+        fromSettings = base;
+    }
+    // Merge plugin-provided hooks AFTER the project's own (project hooks run first).
+    const fromPlugins = (0, index_1.pluginHooks)(workDir);
+    const merged = { ...fromSettings };
+    for (const phase of Object.keys(fromPlugins)) {
+        const extra = fromPlugins[phase];
+        if (!Array.isArray(extra) || !extra.length)
+            continue;
+        merged[phase] = [
+            ...((merged[phase]) ?? []),
+            ...extra,
+        ];
+    }
+    // One normalising pass over every entry-list phase, whatever source it came from.
+    for (const phase of ENTRY_LIST_PHASES) {
+        const list = merged[phase];
+        if (Array.isArray(list) && list.length) {
+            merged[phase] = toHookEntries(list);
+        }
+    }
+    return merged;
+}
+/** The phases whose value is an array of ENTRIES (each carrying a matcher + handlers). */
+const ENTRY_LIST_PHASES = [
+    'PreToolUse', 'PostToolUse', 'SessionStart', 'UserPromptSubmit', 'PreCompact',
+    'PermissionRequest', 'Notification', 'PostToolUseFailure', 'SubagentStart',
+    'PostCompact', 'SessionEnd', 'FileChanged', 'InstructionsLoaded', 'StopFailure',
+    'PermissionDenied', 'PreModelSwitch', 'PostModelSwitch', 'CwdChanged', 'DirectoryAdded',
+    'ConfigChange', 'WorktreeCreate', 'WorktreeRemove', 'Setup',
+    'PostToolBatch', 'TaskCreated', 'TaskCompleted',
+    'Elicitation', 'ElicitationResult',
+];
+/**
+ * Accept BOTH config shapes for the same list, so a hook can never be silently dropped:
+ *
+ *   • Claude Code's nested form — `[{ "matcher": "Edit|Write", "hooks": [{ "type": "command", … }] }]`
+ *   • the FLAT/short form our docs show — `[{ "matcher": "Edit|Write", "command": "…" }]`
+ *
+ * A short-form entry used to satisfy neither parser: the entry-lists walk `entry.hooks`
+ * (absent → skipped) and the flat lists require a known `type` (absent → skipped). So a
+ * gate written exactly as documented — the lint-on-write script in hooks.md — never ran,
+ * and nothing said so. Normalise once, here, where every consumer reads its config from.
+ */
+function toHookEntries(list) {
+    return list.map((it) => {
+        const e = it;
+        if (Array.isArray(e.hooks))
+            return { matcher: e.matcher, hooks: e.hooks };
+        // The flat form: the entry IS the handler. No `type` means a command — the only
+        // transport that needs no extra field, and the one the short form documents.
+        const { matcher, ...rest } = e;
+        const hook = { ...rest };
+        // No `type`: a command — unless the entry names a server AND a tool and has no
+        // command of its own, which is unambiguously an mcp_tool handler.
+        if (!isKnownHandlerType(hook.type)) {
+            hook.type = !hook.command && !hook.url && !hook.prompt && hook.server && hook.tool ? 'mcp_tool' : 'command';
+        }
+        return { matcher, hooks: [hook] };
+    });
+}
+const _hookDeliveries = [];
+let _hookWakeListener = null;
+let _hookStatusListener = null;
+/** Called (if set) the moment a wake lands, so an idle host can react at once. */
+function setHookWakeListener(fn) { _hookWakeListener = fn; }
+/** Where `statusMessage` goes. The message is null when no hook is running. */
+function setHookStatusListener(fn) { _hookStatusListener = fn; }
+/** Everything queued so far — the loop calls this before each request. */
+function drainHookDeliveries() { return _hookDeliveries.splice(0); }
+/** Only the wakes — an idle host must not start a turn just for async context. */
+function takeHookWakes() {
+    const out = _hookDeliveries.filter((d) => d.kind === 'wake');
+    for (let i = _hookDeliveries.length - 1; i >= 0; i--)
+        if (_hookDeliveries[i].kind === 'wake')
+            _hookDeliveries.splice(i, 1);
+    return out;
+}
+function hasPendingHookWake() { return _hookDeliveries.some((d) => d.kind === 'wake'); }
+/** The text a delivery batch becomes in the conversation — the same envelope sync hooks use. */
+function formatHookDeliveries(list) {
+    return list.map((d) => `<hook-context source="${d.source}">\n${d.text}\n</hook-context>`).join('\n\n');
+}
+// `once`: which hooks have already run successfully, keyed by STABLE identity — the
+// definition itself, not the object (loadHooks rebuilds the objects every call).
+const _hookOnceDone = new Set();
+function hookIdentity(event, hook, matcher, dir) {
+    const body = hook.command ?? hook.url ?? hook.prompt ?? `${hook.server ?? ''}__${hook.tool ?? ''}`;
+    // `dir` is part of it: ONE process can serve several projects (worktrees, /add-dir), and
+    // "once" must not leak from one project into another.
+    return `${dir ?? ''}|${event}|${matcher ?? ''}|${body}`;
+}
+/** Forget which `once` hooks have run (a new session: /clear, a fresh run). */
+function resetHookOnceState() { _hookOnceDone.clear(); }
+// While any hook with a statusMessage is running the UI shows the NEWEST of those
+// messages — null once they all finish. Ref-counted because parallel sub-agents run
+// hooks concurrently, and "the first hook to finish" must not clear the label of one
+// still running.
+const _activeStatuses = new Map();
+let _statusSeq = 0;
+function hookStatusBegin(message) {
+    const id = ++_statusSeq;
+    _activeStatuses.set(id, message);
+    _hookStatusListener?.(message);
+    return id;
+}
+function hookStatusEnd(id) {
+    if (!_activeStatuses.delete(id))
+        return;
+    if (!_activeStatuses.size) {
+        _hookStatusListener?.(null);
+        return;
+    }
+    _hookStatusListener?.([..._activeStatuses.values()].pop() ?? null);
+}
+let _hookMcpCaller = null;
+/** Hosts with connected MCP servers register their caller once; null = mcp_tool hooks report "no MCP client". */
+function setHookMcpCaller(fn) { _hookMcpCaller = fn; }
+let _hookEventListener = null;
+/**
+ * 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.
+ */
+function setHookEventListener(fn) { _hookEventListener = fn; }
+/** True when a sink is installed, for hosts skipping work that would only feed the stream. */
+function hasHookEventListener() { return _hookEventListener !== null; }
+let _hookIdSeq = 0;
+function emitHookLifecycle(evt) {
+    try {
+        _hookEventListener?.(evt);
+    }
+    catch { /* the host's listener must not break the hook */ }
+}
+/** The stream's hook_name: what the handler IS, in the config author's terms. */
+function hookDisplayName(hook) {
+    if (hook.type === 'http')
+        return String(hook.url ?? 'http');
+    if (hook.type === 'mcp_tool')
+        return `${String(hook.server ?? '')}:${String(hook.tool ?? '')}`;
+    if (hook.type === 'prompt' || hook.type === 'agent')
+        return hook.type;
+    return String(hook.command ?? 'command');
+}
+/**
+ * Output produced before this much runtime never becomes progress — a fast hook
+ * stays a started/response pair, matching Claude Code's rule that progress is for
+ * command hooks running longer than a second.
+ */
+const HOOK_PROGRESS_AFTER_MS = 1000;
+/** At most one progress record per hook per window, so a chatty hook cannot flood the stream. */
+const HOOK_PROGRESS_FLUSH_MS = 250;
+/**
+ * Run one hook with lifecycle records around it. With no listener installed this is
+ * a straight pass-through — no ids, no timers, no bookkeeping.
+ *
+ * Progress covers output produced after the hook has run ≥1 s, flushed at most
+ * every 250 ms; the final unflushed chunk is DROPPED rather than emitted late,
+ * because `response` already carries the complete output and a progress record
+ * must never follow it.
+ */
+async function runWithHookEvents(hook, event, run) {
+    if (!_hookEventListener)
+        return run(undefined);
+    const hookId = `hook_${Date.now().toString(36)}_${(++_hookIdSeq).toString(36)}`;
+    const hookName = hookDisplayName(hook);
+    const startedAt = Date.now();
+    emitHookLifecycle({ kind: 'started', hookId, hookName, hookEvent: event });
+    let pendingOut = '';
+    let pendingErr = '';
+    let lastFlush = 0;
+    let flushTimer = null;
+    const flush = () => {
+        flushTimer = null;
+        if (!pendingOut && !pendingErr)
+            return;
+        const stdout = pendingOut, stderr = pendingErr;
+        pendingOut = '';
+        pendingErr = '';
+        lastFlush = Date.now();
+        emitHookLifecycle({ kind: 'progress', hookId, hookName, hookEvent: event, stdout, stderr, output: stdout + stderr });
+    };
+    const onData = (d) => {
+        if (Date.now() - startedAt < HOOK_PROGRESS_AFTER_MS)
+            return;
+        if (d.stdout)
+            pendingOut += d.stdout;
+        if (d.stderr)
+            pendingErr += d.stderr;
+        if (!pendingOut && !pendingErr)
+            return;
+        const since = Date.now() - lastFlush;
+        if (since >= HOOK_PROGRESS_FLUSH_MS)
+            flush();
+        else if (!flushTimer)
+            flushTimer = setTimeout(flush, HOOK_PROGRESS_FLUSH_MS - since);
+    };
+    let r;
+    try {
+        r = await run(onData);
+    }
+    catch (err) {
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        const message = err?.message ?? String(err);
+        emitHookLifecycle({ kind: 'response', hookId, hookName, hookEvent: event, stdout: '', stderr: message, output: message, outcome: 'error' });
+        throw err;
+    }
+    if (flushTimer)
+        clearTimeout(flushTimer);
+    const stdout = r.stdout ?? '';
+    const stderr = r.stderr ?? '';
+    emitHookLifecycle({
+        kind: 'response',
+        hookId,
+        hookName,
+        hookEvent: event,
+        stdout,
+        stderr,
+        output: [stdout.trim(), stderr.trim()].filter(Boolean).join('\n'),
+        // status null = killed / never exited (spawnHook's timeout path) — there is no exit code to report.
+        ...(r.status === null ? {} : { exitCode: r.status }),
+        outcome: r.status === 0 ? 'success' : r.status === null ? 'cancelled' : 'error',
+    });
+    return r;
+}
+/** async / asyncRewake are command-only (Claude Code: "only available on type:command hooks"). */
+function isBackgroundHook(hook) {
+    return hook.type === 'command' && (hook.async === true || hook.asyncRewake === true);
+}
+function hookGate(hook, event, matcher, dir) {
+    const key = hook.once ? hookIdentity(event, hook, matcher, dir) : undefined;
+    if (key && _hookOnceDone.has(key))
+        return { skip: true };
+    if (isBackgroundHook(hook))
+        return { background: true, key };
+    return { key, statusId: hook.statusMessage ? hookStatusBegin(hook.statusMessage) : undefined };
+}
+/**
+ * Start a background hook. Its result goes to the delivery queue; the caller does not
+ * wait. `timeoutMs: null` = no timeout enforced (plain `async`, like Claude Code);
+ * `asyncRewake` passes a real timeout so a stuck hook cannot strand the wake.
+ */
+function startBackgroundHook(hook, payload, opts) {
+    const statusId = hook.statusMessage ? hookStatusBegin(hook.statusMessage) : undefined;
+    const done = (r) => {
+        if (statusId !== undefined)
+            hookStatusEnd(statusId);
+        if (r.status === 0 && opts.key)
+            _hookOnceDone.add(opts.key);
+        const out = (r.stdout ?? '').toString().trim();
+        if (hook.asyncRewake && r.status === 2) {
+            const text = (r.stderr ?? '').toString().trim() || out;
+            _hookDeliveries.push({ kind: 'wake', text: text || 'Hook asked the session to wake (exit 2).', source: opts.eventLabel });
+            try {
+                _hookWakeListener?.();
+            }
+            catch { /* the host's listener must not break the hook */ }
+            return;
+        }
+        const context = directiveContext(out);
+        if (context)
+            _hookDeliveries.push({ kind: 'context', text: context, source: opts.eventLabel });
+    };
+    // Through runHookHandler, not spawnHook directly: background runs get the same
+    // start/finish lifecycle records, and command dispatch stays in one place.
+    void runHookHandler(hook, payload, { cwd: opts.cwd, timeoutMs: opts.timeoutMs, env: opts.env, event: opts.event })
+        .then(done, () => done({ status: null, stdout: '', stderr: '' }));
+}
+/** additionalContext + systemMessage from a background hook's JSON stdout — both go to the model. */
+function directiveContext(out) {
+    if (!out.startsWith('{'))
+        return '';
+    try {
+        const j = JSON.parse(out);
+        const parts = [];
+        if (typeof j.additionalContext === 'string' && j.additionalContext)
+            parts.push(j.additionalContext);
+        if (typeof j.systemMessage === 'string' && j.systemMessage)
+            parts.push(j.systemMessage);
+        return parts.join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+// Run PreToolUse / PostToolUse hooks with a Claude-Code-style control protocol.
+//
+// Each hook command receives a JSON payload on stdin and NEXRALL_TOOL_* env vars.
+// It controls the agent via:
+//   • exit code 2          → BLOCK the tool; stderr becomes the reason
+//   • stdout JSON object    → { "decision": "block"|"allow", "reason": "...",
+//                              "additionalContext": "text to feed the model" }
+//   • any other exit code   → non-blocking (stderr logged, tool proceeds)
+/**
+ * Run one hook command WITHOUT blocking the event loop. spawnSync froze everything in
+ * the process for up to the hook's timeout — parallel sub-agents' streams, the UI, the
+ * stall watchdogs — which a 60 s PostToolUse test hook turned into a visible hang.
+ */
+function spawnHook(command, opts) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const done = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ status, stdout, stderr });
+        };
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(command, { shell: true, cwd: opts.cwd, env: opts.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            resolve({ status: null, stdout: '', stderr: '' });
+            return;
+        }
+        // timeout === null = no timer at all: plain `async` hooks are not bounded
+        // (Claude Code enforces no timeout on them), and a clamped setTimeout would
+        // fire immediately and kill the hook instead of never firing.
+        const timer = opts.timeout === null ? null : setTimeout(() => { try {
+            child.kill('SIGTERM');
+        }
+        catch { /* gone */ } done(null); }, opts.timeout);
+        const cap = 16 * 1024 * 1024;
+        // `onData` is how `--include-hook-events` sees a long hook's output as it
+        // arrives; without such a listener it is undefined and costs one check.
+        child.stdout?.on('data', (d) => {
+            const s = d.toString('utf-8');
+            if (stdout.length < cap)
+                stdout += s;
+            opts.onData?.({ stdout: s });
+        });
+        child.stderr?.on('data', (d) => {
+            const s = d.toString('utf-8');
+            if (stderr.length < cap)
+                stderr += s;
+            opts.onData?.({ stderr: s });
+        });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(opts.input ?? '');
+    });
+}
+/**
+ * Run one `type:"http"` hook: POST the payload as JSON, read the answer with the
+ * SAME protocol as a command hook's stdout (Claude Code's HTTP-hook contract).
+ *
+ *   • 2xx + empty body      → success (exit 0, no output)
+ *   • 2xx + JSON object     → parsed as the { decision, reason, additionalContext } directive
+ *   • 2xx + other body      → non-blocking error
+ *   • non-2xx / failure     → non-blocking error (never blocks the tool)
+ * There is no HTTP equivalent of exit code 2: to block, return 2xx with a directive.
+ */
+async function httpHook(hook, payload, timeoutMs) {
+    const url = String(hook.url ?? '');
+    if (!/^https?:\/\//i.test(url))
+        return { status: 1, stdout: '', stderr: `hook url must be http(s): ${url}` };
+    const headers = { 'content-type': 'application/json' };
+    const allowed = new Set(hook.allowedEnvVars ?? []);
+    for (const [k, v] of Object.entries(hook.headers ?? {})) {
+        // Unlisted variables expand to nothing rather than leaking the whole environment
+        // into a request header.
+        headers[k] = String(v).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_m, a1, a2) => (allowed.has(a1 ?? a2) ? (process.env[a1 ?? a2] ?? '') : ''));
+    }
+    try {
+        const res = await fetch(url, { method: 'POST', headers, body: payload, signal: AbortSignal.timeout(timeoutMs) });
+        const text = (await res.text()).trim();
+        if (res.status < 200 || res.status >= 300) {
+            return { status: 1, stdout: '', stderr: `hook returned HTTP ${res.status}` };
+        }
+        if (!text)
+            return { status: 0, stdout: '', stderr: '' };
+        if (text.startsWith('{'))
+            return { status: 0, stdout: text, stderr: '' };
+        return { status: 1, stdout: '', stderr: 'hook returned a non-JSON body' };
+    }
+    catch (err) {
+        return { status: 1, stdout: '', stderr: `hook request failed: ${err.message}` };
+    }
+}
+/**
+ * `type:"mcp_tool"` (Nexrall extension, same spirit as Claude Code's MCP-tool handlers):
+ * call a tool on a CONNECTED MCP server and treat its text like a command hook's stdout —
+ * so every caller's directive/blocking logic works unchanged.
+ *
+ *   • tool text starts with "{"  → parsed as the { decision, reason, additionalContext } directive
+ *   • any other text             → wrapped as additionalContext (context for the model)
+ *   • no caller / server error   → non-blocking error (never blocks the tool)
+ * There is no exit-2 equivalent: to block, return the JSON directive.
+ */
+async function mcpToolHook(hook, payload) {
+    const caller = _hookMcpCaller;
+    const server = String(hook.server ?? '');
+    const tool = String(hook.tool ?? '');
+    if (!caller) {
+        return { status: 1, stdout: '', stderr: `mcp_tool hook "${server}:${tool}" needs a connected MCP client` };
+    }
+    try {
+        const res = await caller(server, tool, mcpHookInput(hook.input, payload));
+        if ('error' in res)
+            return { status: 1, stdout: '', stderr: res.error };
+        const text = (res.text ?? '').trim();
+        if (!text)
+            return { status: 0, stdout: '', stderr: '' };
+        return { status: 0, stdout: text.startsWith('{') ? text : JSON.stringify({ additionalContext: text }), stderr: '' };
+    }
+    catch (err) {
+        return { status: 1, stdout: '', stderr: `mcp_tool hook ${server}:${tool} failed: ${err.message}` };
+    }
+}
+/**
+ * Resolve `${path.to.value}` placeholders in an mcp_tool hook's `input` against the
+ * hook's input JSON. Claude Code spells the tool arguments `${tool_input.file_path}`;
+ * plain `${input.file_path}` and a bare `${file_path}` resolve the same way. A value
+ * that is EXACTLY one `${…}` keeps its original type (number, boolean, object…).
+ */
+function mcpHookInput(input, payload) {
+    if (!input)
+        return {};
+    let root = {};
+    try {
+        const j = JSON.parse(payload);
+        if (j && typeof j === 'object' && !Array.isArray(j))
+            root = j;
+    }
+    catch { /* non-JSON payload: nothing to substitute from */ }
+    const nav = (parts) => {
+        let cur = root;
+        for (const p of parts) {
+            if (cur === null || typeof cur !== 'object')
+                return undefined;
+            cur = cur[p];
+        }
+        return cur;
+    };
+    const lookup = (path) => {
+        const parts = path.split('.').map((s) => s.trim()).filter(Boolean);
+        if (!parts.length)
+            return undefined;
+        const candidates = [parts];
+        if (parts[0] === 'tool_input' || parts[0] === 'input') {
+            const rest = parts.slice(1);
+            // Both payload layouts: ours nests the args under `input`, Claude Code's under `tool_input`.
+            candidates.unshift(rest, ['input', ...rest], ['tool_input', ...rest]);
+        }
+        for (const c of candidates) {
+            const v = nav(c);
+            if (v !== undefined)
+                return v;
+        }
+        return undefined;
+    };
+    const subst = (v) => {
+        if (typeof v !== 'string')
+            return v;
+        const whole = v.match(/^\$\{([^}]+)\}$/);
+        if (whole) {
+            const hit = lookup(whole[1]);
+            return hit === undefined ? '' : hit;
+        }
+        return v.replace(/\$\{([^}]+)\}/g, (_m, p) => {
+            const hit = lookup(p);
+            if (hit === undefined)
+                return '';
+            return typeof hit === 'string' ? hit : JSON.stringify(hit);
+        });
+    };
+    const out = {};
+    for (const [k, val] of Object.entries(input))
+        out[k] = subst(val);
+    return out;
+}
+/** One handler, whichever transport it declares. `event` labels its lifecycle records. */
+async function runHookHandler(hook, payload, opts) {
+    return runWithHookEvents(hook, opts.event ?? 'hook', (onData) => {
+        if (hook.type === 'http')
+            return httpHook(hook, payload, opts.timeoutMs ?? 60000);
+        if (hook.type === 'mcp_tool')
+            return mcpToolHook(hook, payload);
+        if (hook.type === 'prompt' || hook.type === 'agent') {
+            return promptHook(hook, payload, { ...opts, timeoutMs: opts.timeoutMs ?? 60000, envCtx: opts.hookEnv });
+        }
+        return spawnHook(String(hook.command ?? ''), { cwd: opts.cwd, timeout: opts.timeoutMs, input: payload, env: opts.env, onData });
+    });
+}
+// ─── Prompt / agent hooks ──────────────────────────────────────────────────────
+//
+// Claude Code's `type:"prompt"` hooks ask a MODEL to decide. We map the model's answer
+// onto the SAME {status, stdout, stderr} contract the process hooks already use, so
+// every caller's blocking logic works unchanged:
+//
+//   {"ok":true}                 → status 0        (allow / pass)
+//   {"ok":false,"reason":"…"}   → status 2        (exactly the exit-code-2 protocol:
+//                                                  blocks where blocking is possible,
+//                                                  the reason is what the model/user sees)
+//   {"additionalContext":"…"}   → passed through as stdout JSON at status 0
+//   no/invalid JSON, crash       → status 1        (non-blocking error — never a veto)
+//
+// `type:"agent"` is the same thing plus the four READ-ONLY project tools, so the model
+// can look at the repo before deciding. Both call the session's model (or the hook's
+// own `model:`), so they BILL the account — the config docs say so.
+/** The only tools an agent hook may use — read-only, no writes, no bash, no network. */
+const HOOK_AGENT_TOOLS = [
+    {
+        name: 'read_file',
+        description: 'Read a file from the working directory.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path, relative to the working directory.' },
+                offset: { type: 'number', description: '0-based line to start from.' },
+                limit: { type: 'number', description: 'Maximum number of lines.' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'search_files',
+        description: 'Search file contents (regex) or find files by name in the working directory.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Regex or literal string to search for.' },
+                path: { type: 'string', description: 'Directory to search in.' },
+                type: { type: 'string', description: 'files (paths only) | content (matching lines) | filename.' },
+            },
+            required: ['pattern'],
+        },
+    },
+    {
+        name: 'list_directory',
+        description: 'List the files and directories at a path.',
+        input_schema: { type: 'object', properties: { path: { type: 'string' } } },
+    },
+    {
+        name: 'glob',
+        description: 'Find files matching a glob pattern, e.g. "**/*.ts".',
+        input_schema: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' } }, required: ['pattern'] },
+    },
+];
+/** A model name that cannot exist — the allowlist filter then sends NO tools at all. */
+const NO_TOOLS_MARKER = '\u0000hook-no-tools';
+/** Pull the decision object out of a model reply: first {...} block, fences tolerated. */
+function parsePromptHookReply(reply) {
+    const text = String(reply ?? '');
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const j = JSON.parse(text.slice(start, end + 1));
+        if (typeof j.ok !== 'boolean' && typeof j.decision !== 'string')
+            return null;
+        return {
+            ok: typeof j.ok === 'boolean' ? j.ok : undefined,
+            reason: typeof j.reason === 'string' ? j.reason : undefined,
+            additionalContext: typeof j.additionalContext === 'string' ? j.additionalContext : undefined,
+            decision: typeof j.decision === 'string' ? j.decision : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const PROMPT_HOOK_RULES = 'You are a hook evaluator for a coding agent. The hook input JSON is given below, followed by ' +
+    'the hook\'s own instruction. Decide whether the agent action described in the input should ' +
+    'proceed. Reply with ONLY one JSON object and nothing else: {"ok":true} to allow, or ' +
+    '{"ok":false,"reason":"short explanation"} to block.';
+async function promptHook(hook, payload, opts) {
+    const instruction = String(hook.prompt ?? '');
+    if (!instruction)
+        return { status: 1, stdout: '', stderr: 'prompt hook has no "prompt"' };
+    // `\$ARGUMENTS` escapes the substitution (Claude Code's own rule).
+    const body = instruction.replace(/\\\$ARGUMENTS/g, '\u0001').replace(/\$ARGUMENTS/g, payload).replace(/\u0001/g, '$ARGUMENTS');
+    // Abort bridge: streamChat polls a plain {aborted} object, and a hook must never hang
+    // the turn — the timer flips it at the hook's own timeout, the outer signal aborts too.
+    const ctl = { aborted: false };
+    const timer = setTimeout(() => { ctl.aborted = true; }, Math.max(1000, opts.timeoutMs));
+    const outerPoll = opts.abortSignal
+        ? setInterval(() => { if (opts.abortSignal?.aborted)
+            ctl.aborted = true; }, 100)
+        : undefined;
+    if (opts.abortSignal?.aborted) {
+        clearTimeout(timer);
+        if (outerPoll)
+            clearInterval(outerPoll);
+        return { status: 1, stdout: '', stderr: 'aborted' };
+    }
+    try {
+        return await runModel();
+    }
+    finally {
+        clearTimeout(timer);
+        if (outerPoll)
+            clearInterval(outerPoll);
+    }
+    async function runModel() {
+        const messages = [{
+                role: 'user',
+                content: [{ type: 'text', text: `${PROMPT_HOOK_RULES}\n\nHook input:\n${payload}\n\nHook instruction:\n${body}` }],
+            }];
+        const isAgent = hook.type === 'agent';
+        try {
+            let replyText = '';
+            for (let round = 0; round < (isAgent ? 6 : 1); round++) {
+                const msg = await (0, client_1.streamChat)(messages, {
+                    model: hook.model ?? opts.model ?? 'turbo',
+                    env: opts.envCtx ?? { cwd: opts.cwd },
+                    abortSignal: ctl,
+                    // Wire the tools by allowlist rather than a separate channel: the backend
+                    // filters builtins+extra against it, so an agent hook sees ONLY the four
+                    // read-only tools and a prompt hook sees none (the marker matches nothing).
+                    toolAllowlist: isAgent ? HOOK_AGENT_TOOLS.map((t) => t.name) : [NO_TOOLS_MARKER],
+                    extraTools: isAgent ? HOOK_AGENT_TOOLS : undefined,
+                }, () => { });
+                const blocks = Array.isArray(msg.content) ? msg.content : [];
+                const toolUses = blocks.filter((b) => b.type === 'tool_use');
+                if (!toolUses.length || !isAgent) {
+                    replyText = blocks.filter((b) => b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+                    break;
+                }
+                // Run the read-only tool round and feed the results back.
+                messages.push({ role: 'assistant', content: msg.content });
+                const results = [];
+                for (const tu of toolUses) {
+                    let out;
+                    try {
+                        out = getHookToolExecutors().includes(String(tu.name))
+                            ? await (0, executor_1.executeTool)(String(tu.name), tu.input ?? {}, ctl, undefined, opts.cwd)
+                            : { error: `Tool ${String(tu.name)} is not available to a hook — only ${getHookToolExecutors().join(', ')}.` };
+                    }
+                    catch (err) {
+                        out = { error: err.message || 'tool failed' };
+                    }
+                    results.push({
+                        type: 'tool_result',
+                        tool_use_id: String(tu.id),
+                        content: out.error ? (out.output ? `Error: ${out.error}\n\n${out.output}` : `Error: ${out.error}`) : (out.output ?? ''),
+                        is_error: out.error !== undefined,
+                    });
+                }
+                messages.push({ role: 'user', content: results });
+            }
+            const parsed = parsePromptHookReply(replyText);
+            if (!parsed) {
+                // No decision = non-blocking error. A hook that cannot answer must never veto,
+                // and it must not silently pass as "allowed" either — the caller logs stderr.
+                return { status: 1, stdout: '', stderr: 'prompt hook returned no decision' };
+            }
+            const decided = parsed.ok === false || parsed.decision === 'block' || parsed.decision === 'deny';
+            if (decided)
+                return { status: 2, stdout: '', stderr: parsed.reason || `Blocked by ${hook.type} hook` };
+            // Allow — carry additionalContext through the same JSON channel callers parse.
+            const passthrough = parsed.additionalContext ? JSON.stringify({ additionalContext: parsed.additionalContext }) : '';
+            return { status: 0, stdout: passthrough, stderr: '' };
+        }
+        catch (err) {
+            if (ctl.aborted)
+                return { status: 1, stdout: '', stderr: 'prompt hook timed out' };
+            return { status: 1, stdout: '', stderr: `prompt hook failed: ${err.message}` };
+        }
+    }
+}
+/** Names executeTool is allowed to run on behalf of an agent hook. */
+function getHookToolExecutors() {
+    return ['read_file', 'search_files', 'list_directory', 'glob'];
+}
+/** Model / env / abort for prompt+agent hooks, taken from the run that fires them. */
+function hookRunOptsFor(options) {
+    return { model: options.model ?? 'turbo', abortSignal: options.abortSignal, hookEnv: options.env };
+}
+/**
+ * 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.
+ */
+function classifyStopFailure(err) {
+    const status = err?.status;
+    const code = err?.code;
+    const details = [status ? `HTTP ${status}` : '', code ? String(code) : ''].filter(Boolean).join(' ') || undefined;
+    if (status === 429)
+        return { error: 'rate_limit', error_details: details };
+    if (status === 529)
+        return { error: 'overloaded', error_details: details };
+    if (status === 401)
+        return { error: 'authentication_failed', error_details: details };
+    if (status === 402)
+        return { error: 'billing_error', error_details: details };
+    if (status === 403)
+        return { error: 'authentication_failed', error_details: details };
+    if (status === 400 || status === 422)
+        return { error: 'invalid_request', error_details: details };
+    if (status === 404)
+        return { error: 'model_not_found', error_details: details };
+    if (typeof status === 'number' && status >= 500)
+        return { error: 'server_error', error_details: details };
+    return { error: 'unknown', error_details: details };
+}
+/** The same mapping for stops that ended the loop WITHOUT a throw. */
+function apiFailureForStopReason(stopReason) {
+    if (stopReason === 'output-limit')
+        return { error: 'max_output_tokens' }; // cut off at the ceiling
+    if (stopReason === 'no-balance')
+        return { error: 'billing_error', error_details: 'wallet empty (402)' };
+    if (stopReason === 'no-team-budget')
+        return { error: 'billing_error', error_details: 'team pool empty (402)' };
+    if (stopReason === 'reported-elsewhere')
+        return { error: 'billing_error', error_details: 'pre-flight 402' };
+    if (stopReason === 'team-unavailable')
+        return { error: 'account_on_hold', error_details: 'team billing unusable (403)' };
+    return null;
+}
+/** `timeout_ms` (Nexrall) or `timeout` seconds (Claude Code), capped at 10 minutes. */
+function hookTimeoutMs(hook, fallbackMs = 60000) {
+    if (typeof hook.timeout_ms === 'number' && hook.timeout_ms > 0)
+        return Math.min(hook.timeout_ms, 600000);
+    if (typeof hook.timeout === 'number' && hook.timeout > 0)
+        return Math.min(hook.timeout * 1000, 600000);
+    return fallbackMs;
+}
+/**
+ * Does a hook's matcher select this tool? Empty / "*" = every tool. "A|B" = either.
+ * Each alternative may be a Claude Code tool name ("Bash", "Edit") or a Nexrall one, and
+ * a Nexrall-name alternative keeps the old substring behaviour ("file" matches read_file).
+ */
+function hookMatches(matcher, toolName) {
+    if (!matcher || matcher === '*')
+        return true;
+    return matcher.split('|').map((m) => m.trim()).filter(Boolean).some((alt) => {
+        const norm = (0, agentTypes_1.normaliseToolName)(alt);
+        return norm === toolName || (norm === alt && toolName.includes(alt));
+    });
+}
+async function runToolHooks(entries, phase, toolName, input, workDir, result, hookOpts) {
+    const outcome = { block: false };
+    if (!entries?.length)
+        return outcome;
+    const payload = JSON.stringify({
+        phase,
+        tool: toolName,
+        input,
+        ...(result ? { result: { output: result.output, error: result.error } } : {}),
+    });
+    const eventLabel = `${phase} (${toolName})`;
+    const hookEnv = {
+        ...process.env,
+        NEXRALL_TOOL_NAME: toolName,
+        NEXRALL_TOOL_INPUT: JSON.stringify(input),
+        NEXRALL_HOOK_PHASE: phase,
+    };
+    for (const entry of entries) {
+        if (!hookMatches(entry.matcher, toolName))
+            continue;
+        for (const hook of entry.hooks ?? []) {
+            // `type:"command"` runs a shell command; `type:"http"` POSTs the same payload
+            // to a URL; `type:"prompt"|"agent"` asks the model to decide; `type:"mcp_tool"`
+            // calls a tool on a connected MCP server. Anything else is skipped rather than
+            // guessed at.
+            if (!isRunnableHook(hook))
+                continue;
+            const gate = hookGate(hook, phase, entry.matcher, workDir);
+            if (gate.skip)
+                continue;
+            // async / asyncRewake: started and NOT awaited — a background hook can never
+            // block this tool; its directive output is delivered ahead of the next request.
+            // asyncRewake keeps a timeout so a stuck hook cannot strand the wake.
+            if (gate.background) {
+                startBackgroundHook(hook, payload, {
+                    cwd: workDir,
+                    env: hookEnv,
+                    eventLabel,
+                    event: phase,
+                    timeoutMs: hook.asyncRewake ? hookTimeoutMs(hook, 60000) : null,
+                    key: gate.key,
+                });
+                continue;
+            }
+            // Per-hook timeout. Default 60s (was a hard 10s that made the canonical
+            // "auto-run tests on PostToolUse" use-case useless — any real suite is
+            // slower). Configurable via `timeout_ms` on the hook, capped at 10min.
+            const r = await runHookHandler(hook, payload, {
+                cwd: workDir,
+                timeoutMs: hookTimeoutMs(hook, 60000),
+                env: hookEnv,
+                event: phase,
+                ...hookOpts,
+            });
+            // Optional JSON directive on stdout
+            const out = (r.stdout ?? '').toString().trim();
+            if (out.startsWith('{')) {
+                try {
+                    const j = JSON.parse(out);
+                    if (j.decision === 'block') {
+                        outcome.block = true;
+                        outcome.reason = j.reason ?? outcome.reason ?? 'Blocked by hook';
+                    }
+                    if (typeof j.additionalContext === 'string' && j.additionalContext) {
+                        outcome.context = (outcome.context ? outcome.context + '\n' : '') + j.additionalContext;
+                    }
+                }
+                catch { /* not a directive — ignore */ }
+            }
+            // Exit code 2 → hard block; stderr is the reason fed back to the model
+            if (r.status === 2) {
+                outcome.block = true;
+                const err = (r.stderr ?? '').toString().trim();
+                outcome.reason = err || outcome.reason || `Blocked by ${phase} hook`;
+            }
+            if (gate.statusId !== undefined)
+                hookStatusEnd(gate.statusId);
+            if (r.status === 0 && gate.key)
+                _hookOnceDone.add(gate.key);
+        }
+    }
+    return outcome;
+}
+async function runSimpleHooks(defs, workDir, extraEnv, hookOpts, event = 'hook') {
+    if (!defs?.length)
+        return;
+    const env = extraEnv ? { ...process.env, ...extraEnv } : undefined;
+    for (const hook of defs) {
+        if (!isRunnableHook(hook))
+            continue;
+        const gate = hookGate(hook, event, undefined, workDir);
+        if (gate.skip)
+            continue;
+        if (gate.background) {
+            startBackgroundHook(hook, '', { cwd: workDir, env, eventLabel: event, event, timeoutMs: hook.asyncRewake ? hookTimeoutMs(hook, 10000) : null, key: gate.key });
+            continue;
+        }
+        const r = await runHookHandler(hook, '', { cwd: workDir, timeoutMs: hookTimeoutMs(hook, 10000), env, event, ...hookOpts });
+        if (gate.statusId !== undefined)
+            hookStatusEnd(gate.statusId);
+        if (r.status === 0 && gate.key)
+            _hookOnceDone.add(gate.key);
+    }
+}
+// ─── Lifecycle hooks (SessionStart / UserPromptSubmit / PreCompact / Notification) ───
+//
+// Same stdin-JSON + exit-code-2 protocol as the tool hooks. `event` is passed as
+// `hook_event_name`; the payload also carries session_id/cwd, plus whatever the event adds.
+// Config accepts Claude Code's `[{ "matcher": "…", "hooks": [{type:"command",…}] }]` and the
+// flat `[{type:"command",…}]` the older Nexrall events use.
+function flattenHookDefs(items, matchValue) {
+    const out = [];
+    for (const it of items ?? []) {
+        if (it && Array.isArray(it.hooks)) {
+            const m = it.matcher;
+            // For these events the matcher (if any) selects on a plain value (e.g. the compact
+            // trigger "auto"/"manual"); empty or "*" matches all.
+            if (m && m !== '*' && matchValue !== undefined && !m.split('|').map((x) => x.trim()).includes(matchValue))
+                continue;
+            out.push(...it.hooks);
+        }
+        else if (it && isKnownHandlerType(it.type))
+            out.push(it);
+    }
+    return out;
+}
+/** Every handler transport this file knows how to run. */
+function isKnownHandlerType(t) {
+    return t === 'command' || t === 'http' || t === 'prompt' || t === 'agent' || t === 'mcp_tool';
+}
+/** A handler whose required field is present (prompt hooks need `prompt`, http need `url`…). */
+function isRunnableHook(hook) {
+    if (!isKnownHandlerType(hook.type))
+        return false;
+    if (hook.type === 'command')
+        return !!hook.command;
+    if (hook.type === 'http')
+        return !!hook.url;
+    if (hook.type === 'mcp_tool')
+        return !!hook.server && !!hook.tool;
+    return !!hook.prompt;
+}
+async function runLifecycleHooks(items, event, workDir, payload, matchValue, hookOpts) {
+    const outcome = { block: false };
+    const defs = flattenHookDefs(items, matchValue);
+    if (!defs.length)
+        return outcome;
+    const input = JSON.stringify({ hook_event_name: event, cwd: workDir, ...payload });
+    for (const hook of defs) {
+        if (!isRunnableHook(hook))
+            continue;
+        const gate = hookGate(hook, event, matchValue, workDir);
+        if (gate.skip)
+            continue;
+        if (gate.background) {
+            startBackgroundHook(hook, input, {
+                cwd: workDir,
+                env: { ...process.env, NEXRALL_HOOK_PHASE: event },
+                eventLabel: event,
+                event,
+                timeoutMs: hook.asyncRewake ? hookTimeoutMs(hook, 60000) : null,
+                key: gate.key,
+            });
+            continue;
+        }
+        const timeout = hookTimeoutMs(hook, hook.type === 'agent' ? 60000 : hook.type === 'prompt' ? 30000 : 30000);
+        const r = await runHookHandler(hook, input, { cwd: workDir, timeoutMs: timeout, env: { ...process.env, NEXRALL_HOOK_PHASE: event }, event, ...hookOpts });
+        const out = (r.stdout ?? '').toString().trim();
+        if (out.startsWith('{')) {
+            try {
+                const j = JSON.parse(out);
+                // PermissionRequest answers, in nex's flat form or Claude Code's hookSpecificOutput form.
+                if (event === 'PermissionRequest') {
+                    const d = j.hookSpecificOutput?.decision?.behavior ?? (typeof j.decision === 'string' ? j.decision : j.decision?.behavior);
+                    if (d === 'allow' || d === 'approve')
+                        outcome.allow = true;
+                    else if (d === 'deny' || d === 'block') {
+                        outcome.block = true;
+                        outcome.reason = j.reason ?? j.hookSpecificOutput?.decision?.message ?? outcome.reason ?? 'Denied by PermissionRequest hook';
+                    }
+                }
+                if (j.decision === 'block') {
+                    outcome.block = true;
+                    outcome.reason = j.reason ?? outcome.reason ?? `Blocked by ${event} hook`;
+                }
+                if (typeof j.additionalContext === 'string' && j.additionalContext)
+                    outcome.context = (outcome.context ? outcome.context + '\n' : '') + j.additionalContext;
+                // FileChanged: watchPaths is the event's one data-carrying field; systemMessage is shown.
+                if (event === 'FileChanged' && Array.isArray(j.watchPaths))
+                    outcome.watchPaths = j.watchPaths.filter((p) => typeof p === 'string');
+                if (typeof j.systemMessage === 'string' && j.systemMessage)
+                    outcome.systemMessage = j.systemMessage;
+            }
+            catch { /* not a directive */ }
+        }
+        else if (out && (event === 'SessionStart' || event === 'UserPromptSubmit') && r.status === 0) {
+            // Claude Code parity: plain stdout from these two events is added as context.
+            outcome.context = (outcome.context ? outcome.context + '\n' : '') + out;
+        }
+        if (r.status === 2) {
+            outcome.block = true;
+            outcome.reason = (r.stderr ?? '').toString().trim() || outcome.reason || `Blocked by ${event} hook`;
+        }
+        if (gate.statusId !== undefined)
+            hookStatusEnd(gate.statusId);
+        if (r.status === 0 && gate.key)
+            _hookOnceDone.add(gate.key);
+    }
+    return outcome;
+}
+/**
+ * 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.
+ */
+async function runPermissionRequestHooks(workDir, tool, input, sessionId = '') {
+    try {
+        const items = loadHooks(workDir).PermissionRequest;
+        if (!items?.length)
+            return { answer: null };
+        const o = await runLifecycleHooks(items, 'PermissionRequest', workDir, { session_id: sessionId, tool_name: tool, tool_input: input }, tool);
+        if (o.block)
+            return { answer: 'deny', reason: o.reason };
+        if (o.allow)
+            return { answer: 'allow' };
+    }
+    catch { /* a hook must never break the prompt */ }
+    return { answer: null };
+}
+/** `hookSpecificOutput:{action,content}` (Claude Code's shape) or the flat form; null = no answer. */
+function parseElicitationAnswer(stdout) {
+    const out = stdout.trim();
+    if (!out.startsWith('{'))
+        return null;
+    try {
+        const j = JSON.parse(out);
+        const src = j.hookSpecificOutput ?? j;
+        if (src.action !== 'accept' && src.action !== 'decline' && src.action !== 'cancel')
+            return null;
+        const content = src.content && typeof src.content === 'object' && !Array.isArray(src.content)
+            ? src.content
+            : undefined;
+        return content ? { action: src.action, content } : { action: src.action };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+async function runElicitationHooks(workDir, server, input, sessionId = '') {
+    try {
+        const items = loadHooks(workDir).Elicitation;
+        if (!items?.length)
+            return null;
+        const defs = flattenHookDefs(items, server);
+        if (!defs.length)
+            return null;
+        const payload = JSON.stringify({ session_id: sessionId, cwd: workDir, hook_event_name: 'Elicitation', mcp_server_name: server, ...input });
+        for (const hook of defs) {
+            if (!isRunnableHook(hook))
+                continue;
+            const gate = hookGate(hook, 'Elicitation', server, workDir);
+            if (gate.skip)
+                continue;
+            if (gate.background) {
+                startBackgroundHook(hook, payload, { cwd: workDir, env: { ...process.env, NEXRALL_HOOK_PHASE: 'Elicitation' }, eventLabel: 'Elicitation', event: 'Elicitation', timeoutMs: hook.asyncRewake ? hookTimeoutMs(hook, 60000) : null, key: gate.key });
+                continue;
+            }
+            const r = await runHookHandler(hook, payload, { cwd: workDir, timeoutMs: hookTimeoutMs(hook, 30000), env: { ...process.env, NEXRALL_HOOK_PHASE: 'Elicitation' }, event: 'Elicitation' });
+            if (gate.statusId !== undefined)
+                hookStatusEnd(gate.statusId);
+            if (r.status === 0 && gate.key)
+                _hookOnceDone.add(gate.key);
+            if (r.status === 2)
+                return { action: 'decline' };
+            const answer = parseElicitationAnswer((r.stdout ?? '').toString());
+            if (answer)
+                return answer;
+        }
+    }
+    catch { /* a hook must never break elicitation */ }
+    return 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.
+ */
+async function runElicitationResultHooks(workDir, server, answer, meta = {}) {
+    try {
+        const items = loadHooks(workDir).ElicitationResult;
+        if (!items?.length)
+            return answer;
+        const defs = flattenHookDefs(items, server);
+        if (!defs.length)
+            return answer;
+        let current = answer;
+        for (const hook of defs) {
+            if (!isRunnableHook(hook))
+                continue;
+            const gate = hookGate(hook, 'ElicitationResult', server, workDir);
+            if (gate.skip)
+                continue;
+            const payload = JSON.stringify({
+                session_id: meta.sessionId ?? '', cwd: workDir, hook_event_name: 'ElicitationResult', mcp_server_name: server,
+                action: current.action, content: current.content, mode: meta.mode, elicitation_id: meta.elicitationId,
+            });
+            if (gate.background) {
+                startBackgroundHook(hook, payload, { cwd: workDir, env: { ...process.env, NEXRALL_HOOK_PHASE: 'ElicitationResult' }, eventLabel: 'ElicitationResult', event: 'ElicitationResult', timeoutMs: hook.asyncRewake ? hookTimeoutMs(hook, 60000) : null, key: gate.key });
+                continue;
+            }
+            const r = await runHookHandler(hook, payload, { cwd: workDir, timeoutMs: hookTimeoutMs(hook, 30000), env: { ...process.env, NEXRALL_HOOK_PHASE: 'ElicitationResult' }, event: 'ElicitationResult' });
+            if (gate.statusId !== undefined)
+                hookStatusEnd(gate.statusId);
+            if (r.status === 0 && gate.key)
+                _hookOnceDone.add(gate.key);
+            if (r.status === 2)
+                return { action: 'decline' };
+            const override = parseElicitationAnswer((r.stdout ?? '').toString());
+            if (override) {
+                if (override.action === 'accept') {
+                    const content = override.content ?? (current.action === 'accept' ? current.content : undefined);
+                    current = content ? { action: 'accept', content } : { action: 'accept' };
+                }
+                else {
+                    current = { action: override.action };
+                }
+            }
+        }
+        return current;
+    }
+    catch {
+        return answer;
+    }
+}
+/**
+ * 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".
+ */
+async function fireObserverHook(workDir, event, payload, matchValue) {
+    try {
+        const items = loadHooks(workDir)[event];
+        if (!items?.length)
+            return 0;
+        await runLifecycleHooks(items, event, workDir, payload, matchValue);
+        return items.length;
+    }
+    catch {
+        return 0; /* a hook must never break the host */
+    }
+}
+/** For hosts (the CLI) that show the prompt themselves: run Notification hooks, never blocking. */
+function fireNotificationHooks(workDir, message, type = 'permission_prompt') {
+    try {
+        const items = loadHooks(workDir).Notification;
+        if (!items?.length)
+            return;
+        void runLifecycleHooks(items, 'Notification', workDir, { message, notification_type: type }).catch(() => { });
+    }
+    catch { /* ignore */ }
+}
+/** 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"). */
+async function fireManualPostCompactHook(workDir, sessionId, messagesSummarized) {
+    try {
+        const items = loadHooks(workDir).PostCompact;
+        if (!items?.length)
+            return;
+        await runLifecycleHooks(items, 'PostCompact', workDir, { trigger: 'manual', session_id: sessionId, messages_summarized: messagesSummarized }, 'manual');
+    }
+    catch { /* a hook must never break compaction */ }
+}
+async function fireManualPreCompactHook(workDir, sessionId, messagesToSummarize) {
+    try {
+        const items = loadHooks(workDir).PreCompact;
+        if (!items?.length)
+            return;
+        await runLifecycleHooks(items, 'PreCompact', workDir, { trigger: 'manual', session_id: sessionId, messages_to_summarize: messagesToSummarize }, 'manual');
+    }
+    catch { /* a hook must never break compaction */ }
+}
+//# sourceMappingURL=hooks.js.map