@aragon-agent/cli 0.6.38 → 0.6.39

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

@@ -0,0 +1,49 @@
+/**
+ * The hook table: registration, id assignment and chain lookup
+ * (headless-threads-and-lifecycle-hooks section 2.4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * CHAINS, NOT FIRST-MATCH. Several hooks on one (point x tool) run in registration
+ * order and each sees the previous one's output. That is deliberate: redaction and
+ * tenant-scoping are routinely registered by two different teams, and "first match wins"
+ * would turn the order they were installed into an invisible security contract.
+ *
+ * ONE INSTANCE PER THREAD. This object is owned by `ThreadRuntime`, and the
+ * `ToolHookRunner` built from it is handed to THAT thread's `createBuiltinTools`. There
+ * is no path from thread A's runner to thread B's registry that does not go through a
+ * shared reference this class does not have - which is what makes I-H9 ownership rather
+ * than an assertion.
+ */
+import { type HookPoint } from './limits.js';
+import { type ValidatedHookSpec } from './validate.js';
+export interface HookSpec extends ValidatedHookSpec {
+    /** `hook_request.hookId`: `h1`, `h2`, ... strictly increasing within the thread. */
+    id: string;
+}
+export type HookRegisterResult = {
+    ok: true;
+    hooks: HookSpec[];
+    warnings: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export interface HookRegistry {
+    /** Whole-frame registration: all specs or none. */
+    register(raw: readonly unknown[]): HookRegisterResult;
+    /** The chain for one (point x tool), in registration order. */
+    chainFor(point: HookPoint, tool?: string): readonly HookSpec[];
+    /** True when any hook is registered for this point (the fast path for the wrapper). */
+    hasPoint(point: HookPoint): boolean;
+    count(): number;
+    ids(): string[];
+    /** The spec with this id, or `undefined` (used by the dispatcher's `unregistered`). */
+    get(id: string): HookSpec | undefined;
+}
+export interface HookRegistryOptions {
+    /** Names a hook may name: host tools plus this thread's caller tools. */
+    knownTools: () => ReadonlySet<string>;
+}
+export declare function createHookRegistry(options: HookRegistryOptions): HookRegistry;

package/dist/exec/hooks/registry.js

@@ -0,0 +1,91 @@
+/**
+ * The hook table: registration, id assignment and chain lookup
+ * (headless-threads-and-lifecycle-hooks section 2.4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * CHAINS, NOT FIRST-MATCH. Several hooks on one (point x tool) run in registration
+ * order and each sees the previous one's output. That is deliberate: redaction and
+ * tenant-scoping are routinely registered by two different teams, and "first match wins"
+ * would turn the order they were installed into an invisible security contract.
+ *
+ * ONE INSTANCE PER THREAD. This object is owned by `ThreadRuntime`, and the
+ * `ToolHookRunner` built from it is handed to THAT thread's `createBuiltinTools`. There
+ * is no path from thread A's runner to thread B's registry that does not go through a
+ * shared reference this class does not have - which is what makes I-H9 ownership rather
+ * than an assertion.
+ */
+import { HOOK_LIMITS } from './limits.js';
+import { validateHookSpecs } from './validate.js';
+export function createHookRegistry(options) {
+    const hooks = [];
+    let nextId = 0;
+    return {
+        register(raw) {
+            // VALIDATE FIRST, THEN COUNT: the two capacity refusals below must be decided on a
+            // set that is already well formed, or a frame with one bad spec would be reported
+            // as "too many hooks" and the caller would go looking for the wrong problem.
+            const validated = validateHookSpecs(raw, { knownTools: options.knownTools() });
+            if (!validated.ok)
+                return { ok: false, code: validated.code, message: validated.message };
+            if (hooks.length + validated.specs.length > HOOK_LIMITS.maxHooks) {
+                return {
+                    ok: false,
+                    code: 'too_many_hooks',
+                    message: `This thread already holds ${hooks.length} hooks; the ceiling is ` +
+                        `${HOOK_LIMITS.maxHooks}.`,
+                };
+            }
+            // THE PER-POINT CEILING IS CHECKED AGAINST WHAT THE FRAME WOULD ADD, pairwise, so
+            // the refusal names the real limit rather than an aggregate.
+            for (const spec of validated.specs) {
+                for (const tool of spec.tools) {
+                    const existing = chainLength(hooks, spec.point, tool);
+                    // `'*'` COUNTS, exactly as it does in `matches`: counting only an explicit tool
+                    // name let one frame of four wildcards plus four named specs pass validation (each
+                    // naming a different tool) and then run an eight-long chain past a limit of four.
+                    const incoming = validated.specs.filter((other) => other.point === spec.point && matches(other, spec.point, tool)).length;
+                    if (existing + incoming > HOOK_LIMITS.maxHooksPerPoint) {
+                        return {
+                            ok: false,
+                            code: 'too_many_hooks',
+                            message: `${spec.point} x ${tool} would hold ${existing + incoming} hooks; the ` +
+                                `ceiling is ${HOOK_LIMITS.maxHooksPerPoint}.`,
+                        };
+                    }
+                }
+            }
+            const adopted = validated.specs.map((spec) => {
+                nextId += 1;
+                return { ...spec, id: `h${nextId}` };
+            });
+            hooks.push(...adopted);
+            return { ok: true, hooks: adopted, warnings: validated.warnings };
+        },
+        chainFor(point, tool) {
+            return hooks.filter((hook) => hook.point === point && matches(hook, point, tool));
+        },
+        hasPoint: (point) => hooks.some((hook) => hook.point === point),
+        count: () => hooks.length,
+        ids: () => hooks.map((hook) => hook.id),
+        get: (id) => hooks.find((hook) => hook.id === id),
+    };
+}
+/**
+ * `tools` ONLY MEANS SOMETHING ON THE TOOL POINTS.
+ *
+ * A `prompt_pre` hook that names `tools: ['read_file']` is not an error - it is a hook
+ * whose filter has no subject - and refusing it would make a caller write two code paths
+ * for one table. `'*'` matches everything, and an absent entry never reaches here (the
+ * validator defaults it to `['*']`).
+ */
+function matches(hook, point, tool) {
+    if (point !== 'tool_pre' && point !== 'tool_post')
+        return true;
+    if (tool === undefined)
+        return true;
+    return hook.tools.includes('*') || hook.tools.includes(tool);
+}
+function chainLength(hooks, point, tool) {
+    return hooks.filter((hook) => hook.point === point && matches(hook, point, tool)).length;
+}

package/dist/exec/hooks/tool-wrapper.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `tool_pre` and `tool_post`: the two hook points that sit in the tool wrapper chain
+ * (headless-threads-and-lifecycle-hooks section 2.4.4 / 2.4.5 / 2.4.9).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE PLACEMENT IS THE SECURITY PROPERTY, so it is argued here rather than in a diagram
+ * that can drift:
+ *
+ *   tool_post        <- outermost: covers everything below, including denial text
+ *     jobNotices
+ *       planGate
+ *         skillCeiling
+ *           tool_pre   <- inside the two policy gates, outside the approval gate
+ *             approvalGate
+ *               confirmation
+ *                 the tool itself
+ *
+ *   `tool_post` IS OUTSIDE `<job_notices>` because a background job's notice tail carries
+ *   the LAST FEW LINES OF ITS RAW OUTPUT (`proc/notices.ts`). A `bash background:true`
+ *   that printed a key would otherwise smuggle it into the model's view past any redactor
+ *   installed inside that layer - which is precisely the case the feature exists for.
+ *
+ *   `tool_pre` IS OUTSIDE `approvalGate` so a human approves the REWRITTEN arguments. The
+ *   opposite order makes "approved A, ran B" possible, which is a defect rather than a
+ *   style choice. It is INSIDE planGate / skillCeiling, which refuse without I/O: paying a
+ *   round trip to ask about a tool that policy already refuses is a worse trade, and the
+ *   trade-off is recorded as I-H4b so it is not "fixed" by accident.
+ *
+ * VERDICTS ARE TOOL RESULTS, NEVER THROWS. `tool-gate.ts` records why: a `tool_use` with
+ * no `tool_result` is an HTTP 400 on the next provider request.
+ */
+import { type AgentTool, type ToolResult } from '@aragon-agent/core';
+import type { HookReply } from './dispatch.js';
+import type { HookTimeoutPolicy } from './limits.js';
+/** Everything the wrapper needs from the hook runtime. */
+export interface ToolHookRunner {
+    /** `true` when the thread has at least one hook on this point, so no wait is paid. */
+    hasTools(point: 'tool_pre' | 'tool_post', tool: string): boolean;
+    beforeTool(input: {
+        tool: AgentTool;
+        callId: string;
+        params: Record<string, unknown>;
+        summary: string;
+        turn?: number;
+        signal?: AbortSignal;
+    }): Promise<ToolHookBefore>;
+    afterTool(input: {
+        tool: AgentTool;
+        callId: string;
+        result: ToolResult;
+        signal?: AbortSignal;
+    }): Promise<ToolResult>;
+}
+export type ToolHookBefore = {
+    allow: true;
+    params: Record<string, unknown>;
+} | {
+    allow: false;
+    message: string;
+    reason?: string;
+};
+/** What `tool_pre`'s messages say when a hook refuses or fails to answer. */
+export declare function hookBlockedMessage(tool: string, reply: HookReply, policy: HookTimeoutPolicy): {
+    message: string;
+    reason?: string;
+};
+/** What `tool_post` says when the result must be withheld. */
+export declare function hookWithheldMessage(tool: string, reply: HookReply): string;
+/**
+ * `tool_pre`. Returns the tool unchanged when nothing is registered for it - the fast
+ * path that makes "no hooks means today's behaviour" true at the object level too.
+ */
+export declare function withToolPreHooks(tool: AgentTool, runner: ToolHookRunner): AgentTool;
+/**
+ * `tool_post`. The outermost wrapper: it runs after every other decision, so a refusal
+ * written by an inner layer is redacted exactly like a real result.
+ */
+export declare function withToolPostHooks(tool: AgentTool, runner: ToolHookRunner): AgentTool;
+/**
+ * Re-validate a `tool_pre` rewrite against the tool's OWN schema (I-H3).
+ *
+ * TWO FAILURE MODES, ONE ANSWER: an invalid rewrite is reported as `invalid` and treated
+ * by the policy table, never handed to `ToolExecutor`. Letting the executor reject it
+ * would surface as "the model called this tool wrong", and the model would then spend a
+ * turn repairing a mistake a caller's hook made.
+ */
+export declare function revalidateRewrite(tool: AgentTool, input: Record<string, unknown>): Promise<{
+    ok: true;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+}>;

package/dist/exec/hooks/tool-wrapper.js

@@ -0,0 +1,154 @@
+/**
+ * `tool_pre` and `tool_post`: the two hook points that sit in the tool wrapper chain
+ * (headless-threads-and-lifecycle-hooks section 2.4.4 / 2.4.5 / 2.4.9).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE PLACEMENT IS THE SECURITY PROPERTY, so it is argued here rather than in a diagram
+ * that can drift:
+ *
+ *   tool_post        <- outermost: covers everything below, including denial text
+ *     jobNotices
+ *       planGate
+ *         skillCeiling
+ *           tool_pre   <- inside the two policy gates, outside the approval gate
+ *             approvalGate
+ *               confirmation
+ *                 the tool itself
+ *
+ *   `tool_post` IS OUTSIDE `<job_notices>` because a background job's notice tail carries
+ *   the LAST FEW LINES OF ITS RAW OUTPUT (`proc/notices.ts`). A `bash background:true`
+ *   that printed a key would otherwise smuggle it into the model's view past any redactor
+ *   installed inside that layer - which is precisely the case the feature exists for.
+ *
+ *   `tool_pre` IS OUTSIDE `approvalGate` so a human approves the REWRITTEN arguments. The
+ *   opposite order makes "approved A, ran B" possible, which is a defect rather than a
+ *   style choice. It is INSIDE planGate / skillCeiling, which refuse without I/O: paying a
+ *   round trip to ask about a tool that policy already refuses is a worse trade, and the
+ *   trade-off is recorded as I-H4b so it is not "fixed" by accident.
+ *
+ * VERDICTS ARE TOOL RESULTS, NEVER THROWS. `tool-gate.ts` records why: a `tool_use` with
+ * no `tool_result` is an HTTP 400 on the next provider request.
+ */
+import { ToolParamValidator, errorResult, formatValidationErrors, } from '@aragon-agent/core';
+/** What `tool_pre`'s messages say when a hook refuses or fails to answer. */
+export function hookBlockedMessage(tool, reply, policy) {
+    if (reply.outcome === 'answered' && reply.answer?.action === 'deny') {
+        const reason = reply.answer.reason;
+        const message = reply.answer.message;
+        return {
+            message: message ??
+                `A caller hook denied this tool call (${tool}).` +
+                    (reason ? ` Reason: ${reason}.` : '') +
+                    ' Do not retry the same call; explain what you were trying to do or take a ' +
+                    'different approach.',
+            ...(reason ? { reason } : {}),
+        };
+    }
+    const code = reply.code ?? 'hook_error';
+    if (policy === 'allow') {
+        // RESERVED, AND UNREACHABLE FROM HERE: `allow` means the caller's wrapper falls
+        // through to the original parameters before this function is called. Kept so the
+        // three-way policy is exhaustive in one place.
+        return { message: `Hook ${code} (policy allow).` };
+    }
+    return {
+        message: `A caller hook did not allow this tool call (${code}), so ${tool} was not run. ` +
+            'Do not retry the same call; explain what you needed it for instead.',
+        reason: code,
+    };
+}
+/** What `tool_post` says when the result must be withheld. */
+export function hookWithheldMessage(tool, reply) {
+    if (reply.outcome === 'answered' && reply.answer?.action === 'deny') {
+        const message = reply.answer.message;
+        if (message)
+            return message;
+    }
+    return (`The caller withheld this tool result (${reply.code ?? 'hook_error'}). ` +
+        `The ${tool} call completed but its output is not available; take a different approach.`);
+}
+/**
+ * `tool_pre`. Returns the tool unchanged when nothing is registered for it - the fast
+ * path that makes "no hooks means today's behaviour" true at the object level too.
+ */
+export function withToolPreHooks(tool, runner) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            if (!runner.hasTools('tool_pre', tool.name))
+                return original(id, params, ctx);
+            const before = await runner.beforeTool({
+                tool,
+                callId: id,
+                params: (params ?? {}),
+                summary: summarize(tool.name, (params ?? {})),
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            });
+            if (!before.allow)
+                return errorResult(before.message);
+            // THE VALIDATED OBJECT, NOT THE ORIGINAL ONE. `ToolParamValidator` coerces and
+            // applies defaults, and the rewrite may legitimately have changed both.
+            return original(id, before.params, ctx);
+        },
+    };
+}
+/**
+ * `tool_post`. The outermost wrapper: it runs after every other decision, so a refusal
+ * written by an inner layer is redacted exactly like a real result.
+ */
+export function withToolPostHooks(tool, runner) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const result = await original(id, params, ctx);
+            if (!runner.hasTools('tool_post', tool.name))
+                return result;
+            return runner.afterTool({
+                tool,
+                callId: id,
+                result,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            });
+        },
+    };
+}
+/**
+ * Re-validate a `tool_pre` rewrite against the tool's OWN schema (I-H3).
+ *
+ * TWO FAILURE MODES, ONE ANSWER: an invalid rewrite is reported as `invalid` and treated
+ * by the policy table, never handed to `ToolExecutor`. Letting the executor reject it
+ * would surface as "the model called this tool wrong", and the model would then spend a
+ * turn repairing a mistake a caller's hook made.
+ */
+export async function revalidateRewrite(tool, input) {
+    const parameters = tool.parameters;
+    if (!parameters || typeof parameters !== 'object')
+        return { ok: true, params: input };
+    try {
+        const validated = await new ToolParamValidator().validate(parameters, input);
+        return { ok: true, params: validated };
+    }
+    catch (error) {
+        const errors = error.errors;
+        const detail = errors ? formatValidationErrors(errors) : error.message;
+        return { ok: false, message: clip(detail, 512) };
+    }
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+/** One readable line, mirroring `tools/tool-gate.ts`'s copy for the same three tools. */
+function summarize(toolName, params) {
+    if (toolName === 'bash')
+        return `Run: ${String(params.command ?? '')}`;
+    if (toolName === 'write_file')
+        return `Write: ${String(params.path ?? '')}`;
+    if (toolName === 'edit_file')
+        return `Edit: ${String(params.path ?? '')}`;
+    if (toolName === 'skill_create')
+        return `Create skill: ${String(params.name ?? '')}`;
+    return toolName;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `turn_start`: the one injection point that does not break the conversation
+ * (headless-threads-and-lifecycle-hooks section 2.4.6).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * INJECTION GOES THROUGH `queueUserMessage`, WHICH IS STEERING, AND THERE IS NO SECOND
+ * SAFE PLACE. Core drains the steering queue at exactly one checkpoint - the top of the
+ * loop, before the LLM call (`agent-loop.ts`). Draining after the LLM call orphans
+ * `tool_use` blocks and the next provider request is an HTTP 400; draining between two tool
+ * executions silently replaces the remaining calls with "skipped due to steering
+ * interrupt". Both are correct for a human pressing Enter and a defect generator for a
+ * programmatic host, which is why the only route this module has is the safe one.
+ *
+ * THE ORDER IS FIXED TOO, and it lives in the runner rather than here: the request budget
+ * is judged BEFORE the injection is queued. Injecting first and then being stopped by the
+ * budget would leave the text in the steering queue, where the NEXT request's loop top
+ * would push it into history - data quietly appearing in somebody else's request. The
+ * runner's `pendingInjection` is what makes that recoverable, and this file only produces
+ * the text.
+ */
+import type { HookDispatcher, HookReply } from './dispatch.js';
+import { type HookTimeoutPolicy } from './limits.js';
+import type { HookRegistry } from './registry.js';
+export type TurnSource = 'caller' | 'todo_continue' | 'result_repair';
+export interface TurnStartInput {
+    turn: number;
+    source: TurnSource;
+    requestId?: string;
+    signal?: AbortSignal;
+}
+export interface TurnStartOutcome {
+    /** Text to inject, already joined and bounded. Absent means "nothing to say". */
+    injected?: string;
+    /**
+     * WHICH HOOK INJECTED, so a stranded injection can name itself.
+     *
+     * The runner reports `injection_stranded` when the text is queued but the turn never
+     * accepts it; without this field that report carries a placeholder id (`h?`) and the
+     * caller cannot tell which of its hooks to fix (I-H12).
+     */
+    hookId?: string;
+    /** `injection_stranded`, `hook_timeout`, `hook_invalid_answer`, ... (first reason wins). */
+    code?: string;
+    /** `--on-hook-timeout error`: this request must end as an error. */
+    isError?: boolean;
+}
+export interface TurnHook {
+    /** Never rejects: every failure is an outcome the runner records. */
+    beforeTurn(input: TurnStartInput): Promise<TurnStartOutcome>;
+    injections(): number;
+    reset(): void;
+}
+export interface TurnHookOptions {
+    registry: HookRegistry;
+    dispatch: HookDispatcher;
+    policy: () => HookTimeoutPolicy;
+}
+export declare function createTurnHook(options: TurnHookOptions): TurnHook;
+/** Re-exported so `hooks/index.ts` can type its own helper without importing twice. */
+export type { HookReply };

package/dist/exec/hooks/turn.js

@@ -0,0 +1,59 @@
+import { HOOK_LIMITS } from './limits.js';
+export function createTurnHook(options) {
+    const { registry, dispatch } = options;
+    let injections = 0;
+    return {
+        async beforeTurn(input) {
+            const chain = registry.chainFor('turn_start');
+            if (chain.length === 0)
+                return {};
+            const parts = [];
+            let code;
+            let isError = false;
+            /** The first hook that actually injected: the injection's owner, for I-H12. */
+            let injectedBy;
+            for (const hook of chain) {
+                if (injections >= HOOK_LIMITS.maxInjectionsPerRequest) {
+                    // A HOOK LOOP IS A PAID LOOP. The ceiling is per request, not per turn, so a
+                    // hook that injects on every turn cannot drive an unbounded continuation.
+                    code ??= 'hook_injection_limit';
+                    break;
+                }
+                const reply = await dispatch.request({
+                    hook,
+                    // THE REQUEST'S OWN ID, ALWAYS KNOWN BY THIS POINT (`scope.begin()` has run and the
+                    // runner passes it): a synthesized `turn_<n>` would collide across two requests in
+                    // one thread, making the `hook_request` / `hook_resolved` pair impossible to
+                    // correlate. The fallback survives only for a direct caller of this module in a
+                    // test, where `turn` is a literal.
+                    requestId: input.requestId ?? `turn_${input.turn}`,
+                    payload: { turn: input.turn, source: input.source },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+                if (reply.outcome === 'answered' && reply.answer?.action === 'inject') {
+                    parts.push(reply.answer.text);
+                    injections += 1;
+                    continue;
+                }
+                if (reply.outcome === 'answered')
+                    continue;
+                // A NON-ANSWER IS THE POLICY'S PROBLEM, and `deny` (the default) simply injects
+                // nothing: unlike a tool, there is nothing to refuse, so failing closed means
+                // "do not add context" rather than "stop the run".
+                code ??= reply.code ?? 'hook_timeout';
+                if (options.policy() === 'error')
+                    isError = true;
+            }
+            return {
+                ...(parts.length > 0 ? { injected: parts.join('\n\n') } : {}),
+                ...(injectedBy !== undefined ? { hookId: injectedBy } : {}),
+                ...(code !== undefined ? { code } : {}),
+                ...(isError ? { isError: true } : {}),
+            };
+        },
+        injections: () => injections,
+        reset: () => {
+            injections = 0;
+        },
+    };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Validating untrusted hook frames (headless-threads-and-lifecycle-hooks section 2.4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE, AND THAT IS THE POINT. `hook_register` and `hook_answer` arrive from a pipe, so
+ * every field is `unknown` until something says otherwise. This module is that
+ * something, and it is the ONLY reader (I-H7): a second validator somewhere else would
+ * mean an answer that is legal in one path and illegal in another, which is worse than
+ * having no validator at all.
+ *
+ * EVERY REFUSAL IS A STABLE CODE, NEVER A SILENT CORRECTION. The two exceptions are
+ * deliberate and both are documented where they happen: an out-of-range `timeoutMs` is
+ * clamped (with a warning on the ack) because the caller asked for a bounded round trip
+ * and got a smaller one, and a missing `tools` defaults to `['*']` because "every tool"
+ * is the only sensible reading of an absent filter.
+ */
+import { type HookPoint } from './limits.js';
+/** One hook, as the caller declared it, before the registry assigns an id. */
+export interface ValidatedHookSpec {
+    point: HookPoint;
+    name?: string;
+    /** `['*']` when the caller named no tools. Only `tool_pre` / `tool_post` read it. */
+    tools: string[];
+    timeoutMs: number;
+}
+export type HookSpecValidation = {
+    ok: true;
+    specs: ValidatedHookSpec[];
+    warnings: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Whole-frame validation: ALL specs are accepted or the frame is refused.
+ *
+ * PARTIAL SUCCESS IS UNIMPOSSIBLE TO DEBUG. A caller that sent six hooks and got
+ * `accepted:true` with two of them silently dropped has no way to tell which two, and
+ * the failure it causes later ("the redactor did not run for read_file") looks exactly
+ * like a bug in the caller's own matcher.
+ */
+export declare function validateHookSpecs(raw: readonly unknown[], options: {
+    knownTools: ReadonlySet<string>;
+}): HookSpecValidation;
+/** The normalised answer, after the point has decided what is legal for it. */
+export type HookAnswer = {
+    action: 'allow';
+} | {
+    action: 'deny';
+    reason?: string;
+    message?: string;
+} | {
+    action: 'rewrite';
+    text?: string;
+    input?: Record<string, unknown>;
+} | {
+    action: 'inject';
+    text: string;
+} | {
+    action: 'keep';
+} | {
+    action: 'replace';
+    content: unknown;
+    isError?: boolean;
+};
+export type HookAnswerValidation = {
+    ok: true;
+    answer: HookAnswer;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * THE FOUR POINTS' LEGAL ACTIONS, ENFORCED HERE AND NOWHERE ELSE.
+ *
+ * A single `validateHookAnswer(point, raw)` rather than four validators, because the
+ * frame is one shape and the point is a property of the request the CLI made - so the
+ * caller never has to restate which point it is answering.
+ */
+export declare function validateHookAnswer(point: HookPoint, raw: unknown): HookAnswerValidation;
+/** Bound the one caller-supplied string that becomes MODEL-VISIBLE (I-H2's sibling). */
+export declare function clipReason(value: unknown): string | undefined;