@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/hooks/dispatch.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One hook round trip: write the request, wait bounded, write exactly one outcome
+ * (headless-threads-and-lifecycle-hooks section 2.4.8).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THREE NON-NEGOTIABLE PROPERTIES, each of which a naive implementation loses:
+ *
+ *   EVERY REQUEST GETS EXACTLY ONE `hook_resolved` (I-H5). Timeout, saturation, abort,
+ *   an illegal answer and a request for an unknown hook id all settle. A caller that
+ *   bookkeeps by id can therefore close its own table, which is the only reason the
+ *   channels are debuggable at all.
+ *
+ *   SATURATION REFUSES INSTEAD OF QUEUEING. A queued hook request makes the host wait
+ *   for an answer it already knows will time out; refusing is explainable now and the
+ *   model can route around it immediately.
+ *
+ *   THE TIMEOUT IS THE HOOK'S OWN. `timeoutMs` comes from the spec (clamped by the
+ *   validator and by `--hook-timeout` at dispatch), not from a global constant, because
+ *   two hooks on one tool may legitimately need different budgets.
+ */
+import type { BridgeHookAnswerFrame } from '../bridge/protocol.js';
+import { type HookOutcome, type HookPoint, type HookTimeoutPolicy } from './limits.js';
+import type { HookRegistry, HookSpec } from './registry.js';
+import { type HookAnswer } from './validate.js';
+export interface HookDispatchPorts {
+    /** One outbound frame through the sealed writer. */
+    write(event: Record<string, unknown>): void;
+    /** Stamped onto every event; the thread's session id. */
+    sessionId: string;
+    now?: () => number;
+    /** The effective ceiling for one round trip: `min(spec.timeoutMs, --hook-timeout)`. */
+    timeoutMs: () => number;
+    /** `--on-hook-timeout`; read per request so a signal change is not needed. */
+    policy: () => HookTimeoutPolicy;
+    onAudit?: (record: {
+        hookId: string;
+        point: HookPoint;
+        outcome: HookOutcome;
+    }) => void;
+}
+export interface HookRequestInput {
+    hook: HookSpec;
+    /** The request this hook fires for. Never empty: `prompt_pre` runs after `begin()`. */
+    requestId: string;
+    payload: Record<string, unknown>;
+    /** The tool call's abort signal, when the host has one. */
+    signal?: AbortSignal;
+}
+/** What one hook said, plus why it said nothing when it did not. */
+export interface HookReply {
+    outcome: HookOutcome;
+    /** Present only for `outcome: 'answered'`. */
+    answer?: HookAnswer;
+    /** The action string as the caller wrote it, for `hook_resolved.action`. */
+    action?: string;
+    /** A stable reason for a non-answer: `hook_timeout`, `hook_saturated`, ... */
+    code?: string;
+}
+export interface HookDispatcher {
+    /** One round trip. NEVER rejects; every failure is an outcome. */
+    request(input: HookRequestInput): Promise<HookReply>;
+    /** Route a `hook_answer` frame. `false` when it names no live request. */
+    answer(frame: BridgeHookAnswerFrame): boolean;
+    /** Settle every request in flight as `aborted` (cancel_request, thread close, interrupt). */
+    abortAll(code?: string): void;
+    inFlight(): number;
+    close(): void;
+}
+export interface HookDispatcherOptions {
+    registry: HookRegistry;
+    ports: HookDispatchPorts;
+}
+export declare function createHookDispatcher(options: HookDispatcherOptions): HookDispatcher;
+/** What a non-answer means, per `--on-hook-timeout` (section 2.4.8's table). */
+export declare function isFailClosed(reply: HookReply): boolean;

package/dist/exec/hooks/dispatch.js

@@ -0,0 +1,169 @@
+import { HOOK_LIMITS } from './limits.js';
+import { validateHookAnswer } from './validate.js';
+export function createHookDispatcher(options) {
+    const ports = options.ports;
+    const now = ports.now ?? Date.now;
+    const pending = new Map();
+    let sequence = 0;
+    let closed = false;
+    const resolved = (hook, requestId, outcome, extra = {}) => {
+        ports.write({
+            type: 'hook_resolved',
+            sessionId: ports.sessionId,
+            requestId,
+            ...(extra.hookRequestId !== undefined ? { hookRequestId: extra.hookRequestId } : {}),
+            hookId: hook.id,
+            point: hook.point,
+            outcome,
+            ...(extra.action !== undefined ? { action: extra.action } : {}),
+            ...(extra.code !== undefined ? { code: extra.code } : {}),
+        });
+        ports.onAudit?.({ hookId: hook.id, point: hook.point, outcome });
+    };
+    /** Remove the entry, clear its timer, drop the abort listener. Idempotent by id. */
+    const take = (id) => {
+        const entry = pending.get(id);
+        if (!entry)
+            return undefined;
+        pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        if (entry.signal && entry.onAbort)
+            entry.signal.removeEventListener('abort', entry.onAbort);
+        return entry;
+    };
+    return {
+        request(input) {
+            const { hook } = input;
+            if (closed) {
+                resolved(hook, input.requestId, 'aborted', { code: 'hook_closed' });
+                return Promise.resolve({ outcome: 'aborted', code: 'hook_closed' });
+            }
+            if (pending.size >= HOOK_LIMITS.maxConcurrentRequests) {
+                // NOT QUEUED: see the file header.
+                resolved(hook, input.requestId, 'saturated', { code: 'hook_saturated' });
+                return Promise.resolve({ outcome: 'saturated', code: 'hook_saturated' });
+            }
+            sequence += 1;
+            const id = `hx-${sequence}`;
+            const timeoutMs = Math.min(ports.timeoutMs(), hook.timeoutMs);
+            return new Promise((resolve) => {
+                // SETTLED ONCE, AND THE SETTLE DOES NOT RE-ENTER THE TABLE. The first draft routed
+                // the settle back through `take()`, which had already removed the entry - so the
+                // promise never resolved and every hook looked like it hung. One boolean, right here.
+                let settled = false;
+                const finish = (reply) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (entry.timer)
+                        clearTimeout(entry.timer);
+                    if (input.signal && entry.onAbort) {
+                        input.signal.removeEventListener('abort', entry.onAbort);
+                    }
+                    resolve(reply);
+                };
+                const entry = {
+                    hook,
+                    point: hook.point,
+                    requestId: input.requestId,
+                    timer: null,
+                    settle: finish,
+                    ...(input.signal ? { signal: input.signal } : {}),
+                };
+                if (input.signal) {
+                    const onAbort = () => {
+                        resolved(hook, input.requestId, 'aborted', { code: 'hook_aborted' });
+                        pending.delete(id);
+                        entry.settle({ outcome: 'aborted', code: 'hook_aborted' });
+                    };
+                    entry.onAbort = onAbort;
+                    if (input.signal.aborted) {
+                        resolved(hook, input.requestId, 'aborted', { code: 'hook_aborted' });
+                        resolve({ outcome: 'aborted', code: 'hook_aborted' });
+                        return;
+                    }
+                    input.signal.addEventListener('abort', onAbort, { once: true });
+                }
+                pending.set(id, entry);
+                entry.timer = setTimeout(() => {
+                    pending.delete(id);
+                    // `hookRequestId` IS CARRIED HERE TOO. A timeout is precisely the case where the
+                    // caller must be able to close its own bookkeeping entry, and an outcome without
+                    // the round-trip id would leave that entry open forever.
+                    resolved(hook, input.requestId, 'timeout', {
+                        code: 'hook_timeout',
+                        hookRequestId: id,
+                    });
+                    entry.settle({ outcome: 'timeout', code: 'hook_timeout' });
+                }, timeoutMs);
+                entry.timer.unref?.();
+                ports.write({
+                    type: 'hook_request',
+                    sessionId: ports.sessionId,
+                    requestId: input.requestId,
+                    hookRequestId: id,
+                    hookId: hook.id,
+                    point: hook.point,
+                    payload: input.payload,
+                    createdAt: now(),
+                    timeoutMs,
+                });
+            });
+        },
+        answer(frame) {
+            const entry = take(frame.respondsTo);
+            if (!entry)
+                return false;
+            // AN ILLEGAL ANSWER IS `invalid`, AND THE REQUEST STILL SETTLES (I-H7). The caller
+            // is told the exact reason so it can fix its own hook, and the policy table then
+            // decides what the host does - never a third, undocumented behaviour.
+            const validated = validateHookAnswer(entry.point, frame);
+            if (!validated.ok) {
+                resolved(entry.hook, entry.requestId, 'invalid', {
+                    code: validated.code,
+                    hookRequestId: frame.respondsTo,
+                });
+                entry.settle({ outcome: 'invalid', code: validated.code });
+                return true;
+            }
+            resolved(entry.hook, entry.requestId, 'answered', {
+                action: validated.answer.action,
+                hookRequestId: frame.respondsTo,
+            });
+            entry.settle({
+                outcome: 'answered',
+                answer: validated.answer,
+                action: validated.answer.action,
+            });
+            return true;
+        },
+        abortAll(code = 'hook_aborted') {
+            for (const id of [...pending.keys()]) {
+                const entry = take(id);
+                if (!entry)
+                    continue;
+                resolved(entry.hook, entry.requestId, 'aborted', { code, hookRequestId: id });
+                entry.settle({ outcome: 'aborted', code });
+            }
+        },
+        inFlight: () => pending.size,
+        close() {
+            closed = true;
+            for (const id of [...pending.keys()]) {
+                const entry = take(id);
+                if (!entry)
+                    continue;
+                resolved(entry.hook, entry.requestId, 'aborted', {
+                    code: 'hook_closed',
+                    hookRequestId: id,
+                });
+                entry.settle({ outcome: 'aborted', code: 'hook_closed' });
+            }
+        },
+    };
+}
+/** What a non-answer means, per `--on-hook-timeout` (section 2.4.8's table). */
+export function isFailClosed(reply) {
+    return reply.outcome !== 'answered';
+}

package/dist/exec/hooks/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The hook channel's one public surface
+ * (headless-threads-and-lifecycle-hooks section 2.6 rows 22-27).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THREE PORTS, ONE OBJECT, AND THEY ARE THE ONLY THINGS THE REST OF THE RUN SEES:
+ *
+ *   `toolRunner`  -> `createBuiltinTools({ hookRunner })`, the two wrappers.
+ *   `promptPre`   -> `ExecRunner`'s `hookPort`, between `scope.begin()` and the ack.
+ *   `turnStart`   -> `ExecRunner`'s `beforeTurn`, after the budget, before `prompt()`.
+ *
+ * THE RUNTIME IS ALWAYS PRESENT IN BRIDGE MODE, EVEN WITH ZERO HOOKS. Hooks are
+ * registered after the controller - and therefore after `createBuiltinTools` - exists, so
+ * the wrappers have to be installed up front and read the table live. That is the one
+ * place this implementation deliberately departs from the design's "no `hookRunner`, no
+ * wrapper" reading; the OBSERVABLE contract it protects is unchanged (with no hooks
+ * registered, no `hook_request` is emitted and every tool call behaves exactly as it does
+ * today), and the departure is recorded in the spec's implementation-notes section.
+ */
+import type { BridgeHookAnswerFrame, BridgeHookRegisterFrame } from '../bridge/protocol.js';
+import type { HookTimeoutPolicy } from './limits.js';
+import { type HookRegistry } from './registry.js';
+import { type ToolHookRunner } from './tool-wrapper.js';
+import { type TurnHook } from './turn.js';
+import type { AgentTool } from '@aragon-agent/core';
+/** What `prompt_pre` decided about one caller message. */
+export type PromptPreOutcome = {
+    action: 'allow';
+} | {
+    action: 'rewrite';
+    text: string;
+} | {
+    action: 'deny';
+    reason?: string;
+    message?: string;
+    code: string;
+    isError: boolean;
+};
+export interface HookRegisterAck {
+    accepted: boolean;
+    code?: string;
+    message?: string;
+    hooks?: string[];
+    warnings?: string[];
+}
+export interface HookRuntime {
+    readonly registry: HookRegistry;
+    readonly toolRunner: ToolHookRunner;
+    register(frame: BridgeHookRegisterFrame): HookRegisterAck;
+    /** `false` when the frame named no live hook request (`hook_not_registered`). */
+    answer(frame: BridgeHookAnswerFrame): boolean;
+    promptPre(input: {
+        text: string;
+        queued: boolean;
+        requestId: string;
+        signal?: AbortSignal;
+    }): Promise<PromptPreOutcome>;
+    beforeTurn: TurnHook['beforeTurn'];
+    /** Every request in flight settles as `aborted`. */
+    abortAll(): void;
+    close(): void;
+    count(): number;
+    /** Reset the per-request counters (injection budget). */
+    beginRequest(): void;
+}
+export interface HookRuntimeOptions {
+    sessionId: string;
+    write(event: Record<string, unknown>): void;
+    /** Host tools plus this thread's caller tools; the registration whitelist. */
+    knownTools: () => ReadonlySet<string>;
+    /** `--hook-timeout`, already clamped. */
+    timeoutMs: number;
+    policy: () => HookTimeoutPolicy;
+    now?: () => number;
+    onAudit?: (record: {
+        hookId: string;
+        point: string;
+        outcome: string;
+    }) => void;
+}
+export declare function createHookRuntime(options: HookRuntimeOptions): HookRuntime;
+export type { AgentTool };

package/dist/exec/hooks/index.js

@@ -0,0 +1,205 @@
+import { createHookDispatcher, } from './dispatch.js';
+import { createHookRegistry } from './registry.js';
+import { hookBlockedMessage, hookWithheldMessage, revalidateRewrite, } from './tool-wrapper.js';
+import { createTurnHook } from './turn.js';
+export function createHookRuntime(options) {
+    const registry = createHookRegistry({ knownTools: options.knownTools });
+    const dispatch = createHookDispatcher({
+        registry,
+        ports: {
+            write: options.write,
+            sessionId: options.sessionId,
+            timeoutMs: () => options.timeoutMs,
+            policy: options.policy,
+            ...(options.now ? { now: options.now } : {}),
+            ...(options.onAudit
+                ? { onAudit: (record) => options.onAudit?.(record) }
+                : {}),
+        },
+    });
+    const turn = createTurnHook({ registry, dispatch, policy: options.policy });
+    const toolRunner = {
+        hasTools(point, tool) {
+            return registry.chainFor(point, tool).length > 0;
+        },
+        async beforeTool(input) {
+            const chain = registry.chainFor('tool_pre', input.tool.name);
+            let params = input.params;
+            let turnNumber = input.turn;
+            for (const hook of chain) {
+                const reply = await dispatch.request({
+                    hook,
+                    requestId: input.callId,
+                    payload: {
+                        tool: input.tool.name,
+                        callId: input.callId,
+                        input: params,
+                        summary: input.summary,
+                        ...(turnNumber !== undefined ? { turn: turnNumber } : {}),
+                    },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+                if (reply.outcome !== 'answered') {
+                    if (options.policy() === 'allow') {
+                        // THE ORIGINAL PARAMETERS, NOT THE PARTIALLY REWRITTEN ONES: `allow` means
+                        // "a hook that cannot answer must not decide", so the chain is abandoned at
+                        // the answer it never gave.
+                        return { allow: true, params: input.params };
+                    }
+                    return { allow: false, ...hookBlockedMessage(input.tool.name, reply, options.policy()) };
+                }
+                if (reply.answer?.action === 'deny') {
+                    return { allow: false, ...hookBlockedMessage(input.tool.name, reply, options.policy()) };
+                }
+                if (reply.answer?.action === 'rewrite') {
+                    const rewritten = reply.answer.input ?? params;
+                    // EVERY REWRITE IS RE-VALIDATED, because the previous hook's output is this
+                    // hook's input and a chain of local edits can compose into something no
+                    // single hook would have written (I-H3).
+                    const checked = await revalidateRewrite(input.tool, rewritten);
+                    if (!checked.ok) {
+                        // `params`, for the same reason as the timeout branch above: the rewrites that
+                        // DID validate must survive a later hook's illegal edit.
+                        if (options.policy() === 'allow')
+                            return { allow: true, params };
+                        return {
+                            allow: false,
+                            ...hookBlockedMessage(input.tool.name, { outcome: 'invalid', code: 'hook_invalid_answer' }, options.policy()),
+                            reason: checked.message,
+                        };
+                    }
+                    params = checked.params;
+                    turnNumber = undefined;
+                }
+            }
+            return { allow: true, params };
+        },
+        async afterTool(input) {
+            const chain = registry.chainFor('tool_post', input.tool.name);
+            let result = input.result;
+            for (const hook of chain) {
+                const reply = await dispatch.request({
+                    hook,
+                    requestId: input.callId,
+                    payload: {
+                        tool: input.tool.name,
+                        callId: input.callId,
+                        content: result.content,
+                        isError: result.isError === true,
+                    },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+                if (reply.outcome !== 'answered') {
+                    // `result`, NOT `input.result`: under `allow` an unanswered hook must not decide -
+                    // and it must not REWIND either, or a redaction an earlier hook in this chain
+                    // already made would be undone by a later hook that said nothing.
+                    if (options.policy() === 'allow')
+                        return result;
+                    // FAIL CLOSED FOR OUTPUT, WHICH IS THE WHOLE POINT: an unanswered redactor must
+                    // withhold the result rather than leak it.
+                    return {
+                        content: [{ type: 'text', text: hookWithheldMessage(input.tool.name, reply) }],
+                        isError: true,
+                    };
+                }
+                if (reply.answer?.action === 'deny') {
+                    return {
+                        content: [{ type: 'text', text: hookWithheldMessage(input.tool.name, reply) }],
+                        isError: true,
+                    };
+                }
+                if (reply.answer?.action === 'replace') {
+                    result = {
+                        content: normaliseContent(reply.answer.content),
+                        isError: reply.answer.isError === true,
+                    };
+                }
+            }
+            return result;
+        },
+    };
+    return {
+        registry,
+        toolRunner,
+        register(frame) {
+            const result = registry.register(frame.hooks);
+            if (!result.ok)
+                return { accepted: false, code: result.code, message: result.message };
+            const ids = result.hooks.map((hook) => hook.id);
+            return {
+                accepted: true,
+                hooks: ids,
+                ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+            };
+        },
+        answer: (frame) => dispatch.answer(frame),
+        async promptPre(input) {
+            // THE PER-REQUEST BUDGET IS RESET HERE, AND THIS IS THE ONLY PLACE THAT CAN DO IT:
+            // `prompt_pre` is the one hook point the runner enters exactly once per request, before
+            // any turn can start, so it is the request's opening edge. Without the reset
+            // `HOOK_LIMITS.maxInjectionsPerRequest` would in fact be a LIFETIME budget - a
+            // long-lived thread would stop injecting after 32 turns and never say why.
+            turn.reset();
+            const chain = registry.chainFor('prompt_pre');
+            let text = input.text;
+            for (const hook of chain) {
+                const reply = await dispatch.request({
+                    hook,
+                    requestId: input.requestId,
+                    payload: { text, queued: input.queued },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+                if (reply.outcome !== 'answered') {
+                    if (options.policy() === 'allow') {
+                        // THE TEXT THE CHAIN HAS AGREED ON SO FAR. Returning `{action:'allow'}` here would
+                        // discard an earlier hook's rewrite and send the ORIGINAL prompt - the difference
+                        // between "one hook stayed silent" and "one hook's work vanished".
+                        return text === input.text ? { action: 'allow' } : { action: 'rewrite', text };
+                    }
+                    return deny(reply.code ?? 'hook_timeout', options.policy() === 'error');
+                }
+                if (reply.answer?.action === 'deny') {
+                    return {
+                        action: 'deny',
+                        ...(reply.answer.reason ? { reason: reply.answer.reason } : {}),
+                        ...(reply.answer.message ? { message: reply.answer.message } : {}),
+                        code: 'hook_denied',
+                        isError: true,
+                    };
+                }
+                if (reply.answer?.action === 'rewrite')
+                    text = reply.answer.text ?? text;
+            }
+            return text === input.text ? { action: 'allow' } : { action: 'rewrite', text };
+        },
+        beforeTurn: turn.beforeTurn,
+        abortAll: () => dispatch.abortAll(),
+        close: () => dispatch.close(),
+        count: () => registry.count(),
+        beginRequest: () => turn.reset(),
+    };
+}
+/**
+ * A denial is a FAILED request, not a withdrawn one (section 2.4.2).
+ *
+ * `writeCancelledRequestEnd` reports `isError: false` because the caller withdrew its own
+ * request; a hook denial means the caller did not get what it asked for, and the two must
+ * not look alike in `result.isError`.
+ */
+function deny(code, isError) {
+    return {
+        action: 'deny',
+        code,
+        isError,
+        message: `A caller hook did not allow this prompt (${code}), so the model was not called. ` +
+            'Change the input, or ask the host operator to relax the hook.',
+    };
+}
+/** `string` -> one text part; an array is taken as a content-block list. */
+function normaliseContent(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    if (Array.isArray(content))
+        return content;
+    return [{ type: 'text', text: JSON.stringify(content ?? null) }];
+}

package/dist/exec/hooks/limits.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Structural bounds for caller lifecycle hooks (headless-threads-and-lifecycle-hooks
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE ONE NUMBER THAT IS NOT OBVIOUS IS `maxContentChars`. A `tool_post` `replace`
+ * becomes the `tool_result` the model reads, so it lands in every later provider
+ * request. Without a ceiling a caller could replace a 100 KB file read with 10 MB of
+ * its own text and the run would fail with a context overflow the caller cannot
+ * attribute to its own hook.
+ */
+export declare const HOOK_LIMITS: {
+    /** Registered hooks per thread, all points together. */
+    readonly maxHooks: 32;
+    /** Registered hooks on one (point x tool) pair. */
+    readonly maxHooksPerPoint: 4;
+    /** `--hook-timeout`'s lower bound: below this nothing can answer. */
+    readonly minTimeoutMs: 100;
+    /** `--hook-timeout`'s default. One round trip, not one tool call. */
+    readonly defaultTimeoutMs: 5000;
+    /** `--hook-timeout`'s upper bound. */
+    readonly maxTimeoutMs: 60000;
+    /**
+     * The ceiling `--on-hook-timeout allow` clamps to (section 2.4.8). A tool may be
+     * asked twice (`tool_pre` + `tool_post`), and `ToolExecutor`'s budget is 120 000 ms:
+     * two allowed round trips must not be able to consume half of it.
+     */
+    readonly allowModeMaxTimeoutMs: 30000;
+    /** Hook round trips in flight at once. Beyond this the hook is saturated, not queued. */
+    readonly maxConcurrentRequests: 16;
+    /** `prompt_pre` rewrite / `turn_start` inject text length. */
+    readonly maxInjectChars: 8192;
+    /** `tool_post` replacement content length, in characters of its text. */
+    readonly maxContentChars: 32768;
+    /** Injections per request, so a hook cannot drive the model round in a loop. */
+    readonly maxInjectionsPerRequest: 32;
+    /** How much of a hook's own `reason`/`message` survives into model-visible text. */
+    readonly maxReasonChars: 512;
+};
+export type HookLimits = typeof HOOK_LIMITS;
+/** The four points. A CLOSED SET: the design's section 1.4 forbids a fifth. */
+export type HookPoint = 'prompt_pre' | 'turn_start' | 'tool_pre' | 'tool_post';
+export declare const HOOK_POINTS: readonly HookPoint[];
+export declare function isHookPoint(value: unknown): value is HookPoint;
+/**
+ * How a hook round trip ended. `answered` is the only one that carries a value.
+ *
+ * `saturated` and `unregistered` are separate members because they are separate
+ * operational facts - "your hook table is full" and "that hook id does not exist"
+ * send an operator to two different places - and collapsing them into `invalid`
+ * would leave both indistinguishable in an audit trail.
+ */
+export type HookOutcome = 'answered' | 'timeout' | 'aborted' | 'invalid' | 'saturated' | 'unregistered';
+/** `--on-hook-timeout`'s three policies (section 2.4.8). `deny` is fail-closed. */
+export type HookTimeoutPolicy = 'deny' | 'allow' | 'error';

package/dist/exec/hooks/limits.js

@@ -0,0 +1,49 @@
+/**
+ * Structural bounds for caller lifecycle hooks (headless-threads-and-lifecycle-hooks
+ * section 4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE ONE NUMBER THAT IS NOT OBVIOUS IS `maxContentChars`. A `tool_post` `replace`
+ * becomes the `tool_result` the model reads, so it lands in every later provider
+ * request. Without a ceiling a caller could replace a 100 KB file read with 10 MB of
+ * its own text and the run would fail with a context overflow the caller cannot
+ * attribute to its own hook.
+ */
+export const HOOK_LIMITS = {
+    /** Registered hooks per thread, all points together. */
+    maxHooks: 32,
+    /** Registered hooks on one (point x tool) pair. */
+    maxHooksPerPoint: 4,
+    /** `--hook-timeout`'s lower bound: below this nothing can answer. */
+    minTimeoutMs: 100,
+    /** `--hook-timeout`'s default. One round trip, not one tool call. */
+    defaultTimeoutMs: 5_000,
+    /** `--hook-timeout`'s upper bound. */
+    maxTimeoutMs: 60_000,
+    /**
+     * The ceiling `--on-hook-timeout allow` clamps to (section 2.4.8). A tool may be
+     * asked twice (`tool_pre` + `tool_post`), and `ToolExecutor`'s budget is 120 000 ms:
+     * two allowed round trips must not be able to consume half of it.
+     */
+    allowModeMaxTimeoutMs: 30_000,
+    /** Hook round trips in flight at once. Beyond this the hook is saturated, not queued. */
+    maxConcurrentRequests: 16,
+    /** `prompt_pre` rewrite / `turn_start` inject text length. */
+    maxInjectChars: 8_192,
+    /** `tool_post` replacement content length, in characters of its text. */
+    maxContentChars: 32_768,
+    /** Injections per request, so a hook cannot drive the model round in a loop. */
+    maxInjectionsPerRequest: 32,
+    /** How much of a hook's own `reason`/`message` survives into model-visible text. */
+    maxReasonChars: 512,
+};
+export const HOOK_POINTS = [
+    'prompt_pre',
+    'turn_start',
+    'tool_pre',
+    'tool_post',
+];
+export function isHookPoint(value) {
+    return typeof value === 'string' && HOOK_POINTS.includes(value);
+}