@naswerks/periscope 1.0.0

package/dist/gate/decision.d.ts

@@ -0,0 +1,111 @@
+/**
+ * What a decision about a tool call is, and how an unrecognised one is read.
+ *
+ * The shape is the SDK's `PermissionResult`, field for field. Not a shape of this package's own
+ * that happens to mean the same thing: the host's own local gate returns the same type, and a
+ * `canUseTool` implementation would return it directly, so a second spelling would need a
+ * translation in the one place a translation buys nothing. The SDK's word wins, exactly.
+ *
+ * The SDK documentation page names `PermissionResultDeny`, which the shipped `sdk.d.ts` does not
+ * declare (`grep -c PermissionResultDeny` returns 0). The docs page additionally states
+ * `{allow: false, reason}`, which does not exist either. Anything written that way fails to
+ * compile or, worse, type-widens.
+ *
+ * A decider returns `unknown`, deliberately. A decision arriving from a controller was never seen
+ * by this build's compiler — it is a value off a wire, from a peer that may be newer than this host.
+ * Typing the decider as returning a `Decision` would make the compiler assert a fact only the
+ * runtime can establish, and the unknown-decision rule below exists precisely because that fact is
+ * sometimes false. So the type says `unknown` and `readDecision` is the total function that narrows
+ * it — the honesty is in the signature, not in a comment.
+ */
+/**
+ * What a decision about one tool call says.
+ *
+ * `allow` may rewrite the call's arguments through `updatedInput`. The model is never told that
+ * happened — observed on a real session — so a rewrite is invisible from the transcript's side.
+ */
+export type Decision = {
+    readonly behavior: 'allow';
+    readonly updatedInput?: Record<string, unknown>;
+} | {
+    readonly behavior: 'deny';
+    readonly message: string;
+    readonly interrupt?: boolean;
+};
+/** What a decider is asked about. Everything the hook knows, in this package's own terms. */
+export interface DecisionRequest {
+    readonly toolName: string;
+    readonly toolUseId: string;
+    readonly toolInput: unknown;
+    /**
+     * The agent's own session id, read off the hook input. Not the controller's handle.
+     *
+     * Read `sessionKey` below before using this to correlate anything. This value is minted by the
+     * agent at `system/init`; every frame on the link is keyed by the controller's handle instead. So
+     * a decision request identified only by this arrives naming an id the controller may never have
+     * seen — a session that dies during start-up never mints one at all, and the first transitions of
+     * every session carry `null` here. Correlating on it is a correlation that silently fails exactly
+     * when the session is in trouble, which is when a decision matters most.
+     */
+    readonly sessionId: string;
+    /**
+     * The controller's handle — the same string every wire frame for this session is keyed by.
+     *
+     * This is the field to correlate on, and it exists because nothing else here could. The gate is
+     * the second transport: it is an ordinary HTTP POST to a URL nothing on the wire announces, so the
+     * body is the only place the two transports can be tied together. Without it a controller has to
+     * build an agent-id index and answer non-2xx for any id it has not seen yet.
+     *
+     * The host supplies it; it is never read from the agent's input, because the agent has no idea
+     * what its controller calls it.
+     */
+    readonly sessionKey: string;
+    readonly cwd: string;
+    /**
+     * The subagent this call came from, or null on the main thread.
+     *
+     * `agent_id` is the field that distinguishes a subagent call — `agent_type` is also present on the
+     * main thread of a session started with `--agent`, so branching on the type alone would read a
+     * main-thread call as a subagent one.
+     */
+    readonly agentId: string | null;
+    readonly agentType: string | null;
+}
+/**
+ * Answers one tool call. Returns `unknown` — see this file's header.
+ *
+ * The `signal` aborts when the surrounding turn is cancelled. A decider that reaches a controller
+ * passes it through so a cancelled turn does not leave a request in flight.
+ */
+export type Decider = (request: DecisionRequest, signal: AbortSignal) => Promise<unknown>;
+/**
+ * A decision read from an untrusted value: either one this build understands, or the raw payload.
+ *
+ * The raw payload is preserved rather than discarded. A host that silently drops what it did not
+ * understand makes a controller-side bug invisible on the only side that could have seen it — the
+ * controller believes it answered, the tool is blocked, and nothing anywhere says why.
+ */
+export type DecisionReading = {
+    readonly recognised: true;
+    readonly decision: Decision;
+} | {
+    readonly recognised: false;
+    readonly raw: string;
+};
+/** The raw value as one line, bounded and marked. Never throws — a cyclic value is still evidence. */
+export declare function describeRaw(raw: unknown): string;
+/**
+ * Read an untrusted value as a decision. Total: every input produces a reading.
+ *
+ * A value this build has never seen is never an allow. A controller running ahead of a host, a
+ * decision tier added later, a rolled-back deploy — each produces a `behavior` this code does not
+ * know, and the only safe reading of "I do not understand your answer" is that no answer was given.
+ * Borrowed from the Agent Client Protocol's `RequestPermissionOutcome::Other`, whose rule is that an
+ * agent which does not understand an outcome MUST NOT treat it as approval.
+ *
+ * It is refused here, by the gate, rather than at the transport. A strict codec could reject the
+ * frame instead — but then the gate never runs, and the tool's fate depends on a parse error rather
+ * than on a policy act with a receipt.
+ */
+export declare function readDecision(raw: unknown): DecisionReading;
+//# sourceMappingURL=decision.d.ts.map

package/dist/gate/decision.js

@@ -0,0 +1,97 @@
+/**
+ * What a decision about a tool call is, and how an unrecognised one is read.
+ *
+ * The shape is the SDK's `PermissionResult`, field for field. Not a shape of this package's own
+ * that happens to mean the same thing: the host's own local gate returns the same type, and a
+ * `canUseTool` implementation would return it directly, so a second spelling would need a
+ * translation in the one place a translation buys nothing. The SDK's word wins, exactly.
+ *
+ * The SDK documentation page names `PermissionResultDeny`, which the shipped `sdk.d.ts` does not
+ * declare (`grep -c PermissionResultDeny` returns 0). The docs page additionally states
+ * `{allow: false, reason}`, which does not exist either. Anything written that way fails to
+ * compile or, worse, type-widens.
+ *
+ * A decider returns `unknown`, deliberately. A decision arriving from a controller was never seen
+ * by this build's compiler — it is a value off a wire, from a peer that may be newer than this host.
+ * Typing the decider as returning a `Decision` would make the compiler assert a fact only the
+ * runtime can establish, and the unknown-decision rule below exists precisely because that fact is
+ * sometimes false. So the type says `unknown` and `readDecision` is the total function that narrows
+ * it — the honesty is in the signature, not in a comment.
+ */
+/**
+ * How much of an unrecognised payload is carried into the trace.
+ *
+ * Bounded because the value goes into a transition that is retained and may cross the wire, and an
+ * unbounded field there is a way for a peer to fill this host's memory. Truncation is marked, so a
+ * reader can tell a short payload from a clipped one.
+ */
+const RAW_PAYLOAD_LIMIT = 512;
+/** The raw value as one line, bounded and marked. Never throws — a cyclic value is still evidence. */
+export function describeRaw(raw) {
+    let text;
+    try {
+        text = raw === undefined ? 'undefined' : JSON.stringify(raw);
+        if (text === undefined)
+            text = String(raw);
+    }
+    catch {
+        // A cyclic or otherwise unserialisable payload still tells the reader its type, which is more
+        // than nothing and is the whole point of preserving it.
+        text = `[unserialisable ${typeof raw}]`;
+    }
+    return text.length > RAW_PAYLOAD_LIMIT ? `${text.slice(0, RAW_PAYLOAD_LIMIT)}…[truncated]` : text;
+}
+/**
+ * Read an untrusted value as a decision. Total: every input produces a reading.
+ *
+ * A value this build has never seen is never an allow. A controller running ahead of a host, a
+ * decision tier added later, a rolled-back deploy — each produces a `behavior` this code does not
+ * know, and the only safe reading of "I do not understand your answer" is that no answer was given.
+ * Borrowed from the Agent Client Protocol's `RequestPermissionOutcome::Other`, whose rule is that an
+ * agent which does not understand an outcome MUST NOT treat it as approval.
+ *
+ * It is refused here, by the gate, rather than at the transport. A strict codec could reject the
+ * frame instead — but then the gate never runs, and the tool's fate depends on a parse error rather
+ * than on a policy act with a receipt.
+ */
+export function readDecision(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return { recognised: false, raw: describeRaw(raw) };
+    const candidate = raw;
+    if (candidate.behavior === 'allow') {
+        const updatedInput = candidate.updatedInput;
+        // An `allow` whose updatedInput is present but not an object is not an allow with the field
+        // dropped: it is a decision this build cannot carry out, and carrying out the half it
+        // understood would run the tool with arguments nobody approved.
+        if (updatedInput === undefined)
+            return { recognised: true, decision: { behavior: 'allow' } };
+        if (typeof updatedInput !== 'object' || updatedInput === null || Array.isArray(updatedInput)) {
+            return { recognised: false, raw: describeRaw(raw) };
+        }
+        return {
+            recognised: true,
+            decision: { behavior: 'allow', updatedInput: updatedInput },
+        };
+    }
+    if (candidate.behavior === 'deny') {
+        // `message` is required on a deny by the SDK's own type. A deny without one would reach the
+        // model as a blocked call with no stated reason, which is the silent refusal this package
+        // forbids everywhere else — so it is unrecognised rather than quietly given a default.
+        if (typeof candidate.message !== 'string' || candidate.message.length === 0) {
+            return { recognised: false, raw: describeRaw(raw) };
+        }
+        const interrupt = candidate.interrupt;
+        if (interrupt !== undefined && typeof interrupt !== 'boolean')
+            return { recognised: false, raw: describeRaw(raw) };
+        return {
+            recognised: true,
+            decision: {
+                behavior: 'deny',
+                message: candidate.message,
+                ...(interrupt === undefined ? {} : { interrupt }),
+            },
+        };
+    }
+    return { recognised: false, raw: describeRaw(raw) };
+}
+//# sourceMappingURL=decision.js.map

package/dist/gate/escalate.d.ts

@@ -0,0 +1,82 @@
+import type { ControllerCredential } from '../control/credential.js';
+import type { Decider } from './decision.js';
+/** Just enough of a response to decide on it. `fetch`'s own `Response` satisfies this. */
+export interface EscalationResponse {
+    readonly status: number;
+    text(): Promise<string>;
+}
+export type EscalationTransport = (url: string, init: {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly signal: AbortSignal;
+}) => Promise<EscalationResponse>;
+export interface EscalationOptions {
+    /** Where the controller answers. Supplied by the embedder; never derived here. */
+    readonly url: string;
+    readonly transport: EscalationTransport;
+    /** Sent verbatim, on every request. For a scheme whose value does not change. */
+    readonly headers?: Record<string, string>;
+    /**
+     * The credential this host presents on each decision request. Resolved per request.
+     *
+     * Why it is a credential and not a header. The static `headers` above cannot carry a bearer
+     * token: a token is refreshed on a schedule this module does not know, so a value captured once
+     * would be presented for the life of the host and start failing silently at the first expiry —
+     * as an outage, on every tool call, which is the failure shape this whole file is written against.
+     * The same seam the link uses is asked again here, and it hands back a live value.
+     *
+     * Its failure posture is the opposite of the link's, deliberately. The link connects with no
+     * headers when its credential refuses — a stated decision, on the ground that a version without
+     * identity is better than one pretending to have a scheme. That reasoning does not transfer here.
+     * The link carries observations; this endpoint decides whether a tool runs. An unauthenticated
+     * request to it is an unauthenticated permission decision, and anyone who can reach the URL can
+     * answer for the agent. So a credential that refuses is an outage and the tool does not run — the
+     * gate's own invariant, applied to the gate's own transport. Two transports, two postures, and the
+     * difference is what each one can be used to do.
+     *
+     * Absent means no credential is presented, which is the previous behaviour and stays available for
+     * an embedder whose endpoint is reachable only from inside its own network.
+     *
+     * The precondition: a credential that refuses is not a quieter credential — it is an outage on
+     * every tool call, so the option must be omitted rather than filled with a placeholder when there
+     * is no identity. `bin/periscope.ts` does exactly that, and the composition is the contract.
+     *
+     * What this package can present is narrower than what a controller may require. `identity/`
+     * implements the authorization-code, refresh-token and device-code grants — every one of which
+     * mints a delegated user token. There is no client-credentials grant here, so this host cannot
+     * obtain an app-only token at all, and `Authorization` carries one header, so it cannot present a
+     * second scheme selector alongside the bearer. A controller that admits only a machine app role
+     * therefore refuses both postures — a configured host with a user token and an unconfigured host
+     * with none — and it refuses them at the door, fail-closed. Nothing in this file grants this host
+     * a machine identity, and a reader should not infer from the presence of this option that one
+     * exists.
+     */
+    readonly credential?: ControllerCredential;
+}
+/**
+ * Thrown for every way the ask failed, as distinct from a decision that said no.
+ *
+ * It is an error rather than a returned value because the gate's contract is that the decider
+ * returns whatever the controller said; "the controller said nothing" is not something it said.
+ * The gate turns this into `permission-decision-unavailable` — an outage, never a denial.
+ */
+export declare class EscalationUnavailable extends Error {
+    constructor(detail: string);
+}
+/**
+ * A decider that asks a controller over HTTP.
+ *
+ * Returns the parsed body as `unknown`: reading it as a decision is `readDecision`'s job, and a
+ * well-formed answer this build does not recognise must reach the gate to be refused by the gate.
+ *
+ * The two failure kinds are split on purpose, and the split is not obvious.
+ *   - A non-2xx, a transport error, or a body that is not JSON is an outage. The controller did not
+ *     answer, or answered something that is not an answer. A controller-side fix.
+ *   - Valid JSON that is not a decision this build knows is not handled here. It is returned intact
+ *     and the gate refuses it as unrecognised. A controller-version fix.
+ * Malformed JSON is an outage rather than an unrecognised decision because version skew produces a
+ * *different* decision, never a broken one.
+ */
+export declare function escalatingDecider(options: EscalationOptions): Decider;
+//# sourceMappingURL=escalate.d.ts.map

package/dist/gate/escalate.js

@@ -0,0 +1,92 @@
+/**
+ * Asking a controller. The one place this package makes an outbound decision request.
+ *
+ * The status is discriminated before the body is read, and that order is the whole file. A client
+ * that parses first and branches second turns a 500 carrying a perfectly valid problem-details body
+ * into an object with no `allow` field, whose falsy value renders as a refusal somebody made. That
+ * is a controller outage impersonating a human decision — nobody had said no, and the trace said
+ * somebody had. Reading `status` first makes that shape unwritable.
+ *
+ * The transport is injected and structural. A minimal `{status, text()}` shape rather than the DOM
+ * `Response` type: the global `fetch` satisfies it, a test double satisfies it without a server, and
+ * nothing here acquires a dependency on a browser lib for a package that runs on a server.
+ */
+import { certificateRemedy, describeFailure, isCertificateRefusal } from '../core/failure.js';
+/**
+ * Thrown for every way the ask failed, as distinct from a decision that said no.
+ *
+ * It is an error rather than a returned value because the gate's contract is that the decider
+ * returns whatever the controller said; "the controller said nothing" is not something it said.
+ * The gate turns this into `permission-decision-unavailable` — an outage, never a denial.
+ */
+export class EscalationUnavailable extends Error {
+    constructor(detail) {
+        super(detail);
+        this.name = 'EscalationUnavailable';
+    }
+}
+/**
+ * A decider that asks a controller over HTTP.
+ *
+ * Returns the parsed body as `unknown`: reading it as a decision is `readDecision`'s job, and a
+ * well-formed answer this build does not recognise must reach the gate to be refused by the gate.
+ *
+ * The two failure kinds are split on purpose, and the split is not obvious.
+ *   - A non-2xx, a transport error, or a body that is not JSON is an outage. The controller did not
+ *     answer, or answered something that is not an answer. A controller-side fix.
+ *   - Valid JSON that is not a decision this build knows is not handled here. It is returned intact
+ *     and the gate refuses it as unrecognised. A controller-version fix.
+ * Malformed JSON is an outage rather than an unrecognised decision because version skew produces a
+ * *different* decision, never a broken one.
+ */
+export function escalatingDecider(options) {
+    return async (request, signal) => {
+        // ---- The credential, before the request exists. A refusal here never becomes a request: an
+        // unauthenticated ask is not a quieter version of an authenticated one, it is a different act.
+        const authorization = {};
+        if (options.credential !== undefined) {
+            const authorized = await options.credential.authorize();
+            if (!authorized.ok) {
+                throw new EscalationUnavailable(`this host has no credential to present on a decision request for ${request.toolName} ` +
+                    `(${authorized.refusal.reason}: ${authorized.refusal.detail}). The request was NOT sent: ` +
+                    `an unauthenticated permission decision is one anybody who can reach the endpoint could ` +
+                    `answer, so the gate treats this as an outage and the tool does not run`);
+            }
+            authorization[authorized.value.header] = authorized.value.value;
+        }
+        let response;
+        try {
+            response = await options.transport(options.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...(options.headers ?? {}), ...authorization },
+                body: JSON.stringify(request),
+                signal,
+            });
+        }
+        catch (error) {
+            const why = describeFailure(error);
+            throw new EscalationUnavailable(isCertificateRefusal(error)
+                ? `the decision request to ${options.url} was refused at TLS (${why}). ${certificateRemedy('the decision endpoint')}`
+                : `the decision request to ${options.url} did not complete: ${why}`);
+        }
+        // ---- Status first. Nothing below this line has read the body. ----
+        if (response.status < 200 || response.status >= 300) {
+            throw new EscalationUnavailable(`the controller answered ${response.status} to a decision request for ${request.toolName}; ` +
+                'the body was not read, because a body that parses is not an answer that was given');
+        }
+        let body;
+        try {
+            body = await response.text();
+        }
+        catch (error) {
+            throw new EscalationUnavailable(`the decision response body could not be read: ${String(error)}`);
+        }
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            throw new EscalationUnavailable(`the controller answered ${response.status} with a body that is not JSON (${body.length} bytes)`);
+        }
+    };
+}
+//# sourceMappingURL=escalate.js.map

package/dist/gate/gate.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The gate: `options.hooks.PreToolUse` as the permission mechanism.
+ *
+ * Why the hook and not `canUseTool`, settled by execution rather than by reading. The hook fires
+ * for every tool call — MCP tools and calls inside spawned subagents included, carrying
+ * `agent_id`/`agent_type`. `canUseTool` is shadowed by a settings-file allow rule, by
+ * `allowedTools`, and by `bypassPermissions` (which additionally emits
+ * `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED` on stderr and does not call it). Those are configurations an
+ * embedder chooses, so a gate built on `canUseTool` would silently not run on somebody else's setup
+ * — and a refusal that does not happen leaves no trace saying so.
+ *
+ * A hook that throws is fail-open. The CLI treats a throwing handler as absent rather than as a
+ * denial, so under `bypassPermissions` — where nothing else is left to say no — a bug in this file
+ * would be an open door. Every path here is inside a `try/catch` that returns an explicit
+ * `permissionDecision: 'deny'`. This is not defensive style; it is the difference between
+ * fail-closed and fail-open, and `gate.test.ts` pins it by throwing on purpose.
+ *
+ * The emission is unconditional and sits outside the deny path. A gate that fails closed must
+ * still say that it did — otherwise the invariant holds while the trace goes silent, and a denial
+ * becomes indistinguishable from an outage. So the outcome is computed on both paths, emitted once,
+ * and only then converted to a hook output; and the emission has its own guard, because a listener
+ * that throws must not be able to convert a deny back into an absent hook.
+ *
+ * An allow returns no opinion by default, never an explicit `permissionDecision: 'allow'`. This
+ * gate exists to add a refusal, never to remove one — two mechanisms, one invariant.
+ *
+ * What an explicit allow actually skips. The Claude Code permissions documentation states that a
+ * PreToolUse hook's decision does not bypass permission rules: deny and ask rules are evaluated
+ * whatever the hook returned. So an allow from this gate leaves the operator's deny and ask rules
+ * standing and skips only the permission mode, the allow rules and `canUseTool`. Source:
+ * https://code.claude.com/docs/en/permissions#extend-permissions-with-hooks
+ *
+ * That order is documented, not measured, and this package treats the two differently: the runtime
+ * beats the docs, and this module exists because executing something found what the documentation
+ * denied. The probe that would settle it is written in `gate.live.test.ts` ("does a hook allow
+ * override an operator deny rule?") and is not exercised: attempts to run it from inside an agent
+ * session were contaminated by the enclosing tool surface, so the denied tool was never the one
+ * called. Do not restate this paragraph as a measured claim without that receipt.
+ *
+ * Without `grantOnAllow` the gate is a veto rather than a gate, which was observed rather than
+ * inferred. Saying nothing leaves the agent's own permission mode as the decider, and an embedder
+ * who loads no settings files — the default, and the only posture under which this host can state
+ * what an agent's permissions are — has left nobody who can say yes. On a real session the gate
+ * allowed a `Write`, the tool did not run, and the result read "Claude requested permissions to
+ * write to …, but you haven't granted it yet" — in a host with no user to grant anything.
+ * `grantOnAllow` does not weaken this gate; it makes the decision this gate already made take
+ * effect, one call at a time, for exactly the calls it approved.
+ *
+ * Two deadlines, and the inner one belongs to this host. `HookCallbackMatcher.timeout` is
+ * per-matcher, in seconds, and expires fail-closed on CLI 2.1.210 and later — but the CLI enforces
+ * it, so this handler never learns it happened and the trace would show nothing at all. So the
+ * host runs its own shorter deadline: it fires first, blocks, and names the expiry; the matcher's
+ * remains as the backstop for the case where this code is the thing that hung.
+ */
+import type { HookRegistrations } from '../host/agent-process.js';
+import type { RefusalReason } from '../core/refusal.js';
+import type { Decider } from './decision.js';
+import { describeRaw } from './decision.js';
+import type { GateOutcome } from './outcome.js';
+import type { LocalGate } from './local.js';
+/** Told about every outcome — allows, denials, outages, expiries. Never only the interesting ones. */
+export type OutcomeListener = (outcome: GateOutcome) => void;
+export interface PermissionGateOptions {
+    readonly decide: Decider;
+    readonly onOutcome: OutcomeListener;
+    /**
+     * The controller's handle for this session — carried onto every decision request.
+     *
+     * Required rather than optional on purpose: a gate composed without it would send escalations a
+     * controller cannot route, and an optional field defaulting to `''` would make that failure
+     * silent. Every construction site already has the value. See `DecisionRequest.sessionKey`.
+     */
+    readonly sessionKey: string;
+    /**
+     * The host's own gate, consulted before anything is asked of anyone. Optional; absent means the
+     * gate behaves exactly as it did without it.
+     *
+     * The order is the point, not an optimisation. A local policy consulted after the decider would
+     * still block a boundary command, but only by waiting out a 50-second deadline and reporting
+     * `permission-decision-unavailable` — an outage, which is not what happened. Consulted first, an
+     * unreachable controller is never asked at all and the refusal is immediate, local and named.
+     * That is the difference between "refused" and "deferred, and eventually nothing", and it is the
+     * property somebody deciding whether to install this package actually checks.
+     *
+     * It returns a refusal rather than a decision, and that is the audit contract. A `deny` decision
+     * is recorded `control/permission_denied` — the same cause a controller's deny produces — so a
+     * locally-decided refusal expressed that way would be indistinguishable from a remote one except
+     * by free text nobody branches on. A `Refusal` becomes `refusal/<reason>` on the transition, which
+     * separates the three cases that must never blur: somebody decided, this host decided, nobody
+     * decided.
+     */
+    readonly localGate?: LocalGate;
+    /**
+     * How long the host waits for a decision before blocking and saying so. Milliseconds.
+     *
+     * Kept meaningfully below `matcherTimeoutSeconds` so this handler is the one that expires. If the
+     * matcher's timeout fired first the tool would still be blocked — the CLI is fail-closed — but
+     * nothing would be recorded, and a block nobody can explain reads as a hang. Enforced at
+     * construction: `permissionHooks` refuses a pair where this does not expire first.
+     */
+    readonly decisionTimeoutMs?: number;
+    /** After this long with no answer, the call is reported as held. Milliseconds. */
+    readonly holdAfterMs?: number;
+    /** Handed to the CLI as the matcher's own timeout. Seconds — the SDK's unit, not this package's. */
+    readonly matcherTimeoutSeconds?: number;
+    /**
+     * Make an allow effective, rather than silent. Defaults to false.
+     *
+     * Off by default, and on is a decision with a named cost. An effective allow skips the
+     * permission mode, the allow rules and `canUseTool`. With no settings
+     * files loaded, the only one of those with anything to say is the agent's own permission mode,
+     * which has nobody to answer it, so skipping it is the whole point.
+     *
+     * It does not skip operator deny or ask rules; the documentation states those are evaluated
+     * whatever a hook returns (see this module's header for the source and for why that is documented
+     * rather than measured). The `composeSession` refusal on this flag plus `settingSources` therefore
+     * guards two authorities with no stated precedence, not a bypass.
+     *
+     * An embedder who composes by hand and leaves this off gets a gate that cannot say yes: the tool
+     * simply does not run and the agent reports a permission it was never going to be granted. That
+     * case raises `gate-cannot-grant` through `onDegrade` on the first allow that does not take
+     * effect.
+     */
+    readonly grantOnAllow?: boolean;
+    /**
+     * A named degrade, raised at most once per gate.
+     *
+     * A degrade is a named outcome, not a comment. The `grantOnAllow`-off residual is raised where an
+     * embedder hits it — a running session in which every approved tool call silently fails to
+     * happen — rather than only documented where an installer reads. Optional: an embedder who does
+     * not pass it gets exactly the previous behaviour, so this adds an observation and never a
+     * requirement.
+     *
+     * `name` is a `RefusalReason`, not a free string — so a degrade cannot be invented at the call
+     * site. Adding one means declaring it in `core/refusal.ts` beside every other named outcome, which
+     * is what keeps the vocabulary a vocabulary.
+     */
+    readonly onDegrade?: (degrade: {
+        readonly name: RefusalReason;
+        readonly detail: string;
+    }) => void;
+}
+/**
+ * The two-deadline invariant, as one declaration with two consumers.
+ *
+ * It is a function rather than a repeated `if` because two enforcement points for one rule drift
+ * apart: `permissionHooks` throws on an inverted pair for an embedder, and `composeSession` must
+ * refuse on one for a controller. So the rule lives here and both read it.
+ *
+ * Returns the explanation when the pair is invalid, or null when it is fine. The caller decides
+ * whether that becomes a throw or a named refusal — which is the only thing the two sites disagree
+ * about, and it is a decision about audience rather than about the rule.
+ */
+export declare function deadlineOrderRefusal(decisionTimeoutMs: number | undefined, matcherTimeoutSeconds: number | undefined): string | null;
+/**
+ * The `PreToolUse` registration for a session's gate.
+ *
+ * Register this after `observationHooks()` — `mergeHooks(observationHooks(…), permissionHooks(…))`.
+ * Handlers on one event have their synchronous prologues run in array order and are then awaited
+ * concurrently (measured; `mergeHooks`'s own "earlier arguments run first" describes dispatch, not
+ * completion). The order is a convention, not a race guard: this gate opens its `permission` entry
+ * only from the hold timer (`holdAfterMs`, 250ms by default), after every same-event synchronous
+ * prologue has finished — so under either order the observer's `PreToolUse` check runs before any
+ * hold entry from this event exists, and cannot close one. Across events the guard is the key, not
+ * the timing: the hold entry is keyed by tool_use_id (`gate/outcome.ts`), so a later `PreToolUse`
+ * for the same tool — whose observer branch closes name-keyed permission entries — cannot close a
+ * hold whose decision is still outstanding.
+ *
+ * No `matcher` is set. A matcher filters by tool name, and every tool call must reach the gate.
+ */
+export declare function permissionHooks(options: PermissionGateOptions): HookRegistrations;
+export { describeRaw };
+//# sourceMappingURL=gate.d.ts.map