@naswerks/periscope 1.0.0

package/dist/gate/gate.js

@@ -0,0 +1,417 @@
+import { refusal } from '../core/refusal.js';
+import { HOOK_TIMEOUT_EVENT } from '../state/model.js';
+import { describeRaw, readDecision } from './decision.js';
+import { EscalationUnavailable } from './escalate.js';
+const DEFAULT_MATCHER_TIMEOUT_SECONDS = 60;
+const DEFAULT_DECISION_TIMEOUT_MS = 50_000;
+/**
+ * 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 function deadlineOrderRefusal(decisionTimeoutMs, matcherTimeoutSeconds) {
+    const decision = decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
+    const matcher = matcherTimeoutSeconds ?? DEFAULT_MATCHER_TIMEOUT_SECONDS;
+    if (decision < matcher * 1000)
+        return null;
+    return (`decisionTimeoutMs (${decision}ms) must be below matcherTimeoutSeconds ` +
+        `(${matcher}s = ${matcher * 1000}ms). The host's own deadline must expire first: if the matcher ` +
+        'expires first the tool is still blocked, but nothing is recorded and the block reads as a hang — ' +
+        'the exact failure this gate exists to avoid.');
+}
+/**
+ * 250ms. Below this, opening and closing a permission entry records a session as "waiting" for
+ * less time than it takes to read the record — noise in the one signal the entry exists to carry.
+ */
+const DEFAULT_HOLD_AFTER_MS = 250;
+/**
+ * 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 function permissionHooks(options) {
+    const decisionTimeoutMs = options.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
+    const holdAfterMs = options.holdAfterMs ?? DEFAULT_HOLD_AFTER_MS;
+    const matcherTimeoutSeconds = options.matcherTimeoutSeconds ?? DEFAULT_MATCHER_TIMEOUT_SECONDS;
+    // The two-deadline invariant, enforced where it still can be. A pair where the matcher expires
+    // first would still block the tool — the CLI is fail-closed — but this handler would never learn
+    // it happened: no outcome, no transition, and a trace showing a `tool` and a `permission` entry
+    // opened and never closed. Refused rather than clamped: a silent clamp would alter a value the
+    // embedder stated, and this happens before any session exists, so failing fast is safe.
+    const inverted = deadlineOrderRefusal(decisionTimeoutMs, matcherTimeoutSeconds);
+    if (inverted !== null)
+        throw new Error(inverted);
+    // Per gate, not per call — see the degrade's own note on why it fires once.
+    let grantDegradeRaised = false;
+    const emit = (outcome) => {
+        try {
+            options.onOutcome(outcome);
+        }
+        catch {
+            // A listener that throws must not reach the CLI as a thrown hook, because a thrown hook is an
+            // absent hook and the tool would run. Losing one record is bad; losing the refusal is worse.
+        }
+    };
+    const handler = async (input, _toolUseId, hookOptions) => {
+        // The hold flag lives here, outside decide(), so the recovery below can tell the truth about
+        // whether a hold entry was opened. A hardcoded `held: false` in the catch would leave any
+        // opened entry with no close — the invariant would hold while the trace showed a session
+        // eternally waiting on a decision that was in fact refused.
+        const held = { value: false };
+        let outcome;
+        try {
+            if (input.hook_event_name !== 'PreToolUse')
+                return {};
+            outcome = await decide(input, options.decide, emit, hookOptions.signal, decisionTimeoutMs, holdAfterMs, held, options.localGate, options.sessionKey);
+        }
+        catch (error) {
+            // The fail-open hole, closed. Anything at all that escaped above — a bug in this file, a
+            // decider that threw synchronously, a request that could not be read — becomes an explicit
+            // refusal rather than an absent hook.
+            outcome = {
+                kind: 'refused',
+                request: readRequest(input, options.sessionKey) ?? unreadableRequest(options.sessionKey),
+                held: held.value,
+                refusal: refusal('permission-decision-unavailable', `the gate itself failed: ${String(error)}`),
+            };
+        }
+        emit(outcome);
+        // The silent failure, made audible — once. An allow the CLI will not act on is the shape of
+        // this gate's worst outcome: the call is approved, the tool does not run, and the agent is told
+        // it lacks a permission nobody was ever going to grant. Raised on the first occurrence only,
+        // because a session that hits this hits it on every approved call and a degrade per call would
+        // bury the signal it exists to carry.
+        if (outcome.kind === 'allow' && !(options.grantOnAllow ?? false) && !grantDegradeRaised) {
+            grantDegradeRaised = true;
+            try {
+                options.onDegrade?.({
+                    name: 'gate-cannot-grant',
+                    detail: `the gate ALLOWED ${outcome.request.toolName} but grantOnAllow is off, so the allow is silent and the ` +
+                        `tool will not run — this gate can refuse a call and cannot let one through. Set grantOnAllow, or ` +
+                        `expect every approved call to fail as an ungranted permission.`,
+                });
+            }
+            catch {
+                // Same reason `emit` swallows: a listener that throws must not reach the CLI as a thrown
+                // hook, because a thrown hook is an absent hook and the tool would then run.
+            }
+        }
+        return outputFor(outcome, options.grantOnAllow ?? false);
+    };
+    const matcher = {
+        hooks: [handler],
+        timeout: matcherTimeoutSeconds,
+    };
+    return { PreToolUse: [matcher] };
+}
+// ---------------------------------------------------------------------------
+/**
+ * Ask, with a hold report and a deadline. Every return is a terminal outcome.
+ *
+ * The decider is started before either timer, so a fast answer never pays for the hold machinery.
+ *
+ * `held` is the caller's box, not a local: the handler's own catch reads it, so even a throw this
+ * function does not anticipate reports whether a hold entry was opened — and the terminal outcome
+ * then closes it instead of orphaning it.
+ */
+async function decide(input, ask, emit, signal, decisionTimeoutMs, holdAfterMs, held, localGate, sessionKey) {
+    const request = readRequest(input, sessionKey);
+    if (request === null) {
+        // The gate cannot say which tool this is, so it cannot authorize it. Blocking is the only
+        // answer that does not amount to permitting an unidentified call.
+        return {
+            kind: 'refused',
+            request: unreadableRequest(sessionKey),
+            held: false,
+            refusal: refusal('permission-decision-unavailable', 'the hook input could not be read, so the call it describes has no name to decide about'),
+        };
+    }
+    // The host's own gate, before anything is asked of anyone. It is consulted here rather than
+    // after the decider because a refusal that waits for an unreachable controller to time out is not
+    // a refusal, it is a `decisionTimeoutMs` silence that ends in an outage report — and the property
+    // this package states is that a locally refused call is refused immediately, by name.
+    const localRefusal = askLocalGate(localGate, request);
+    if (localRefusal !== null && localRefusal.reason !== 'shell-boundary-command') {
+        // `held: false` is a fact, not a default: nothing has been armed yet, so no entry was opened.
+        return { kind: 'refused', request, held: false, refusal: localRefusal };
+    }
+    // regression: a boundary-shaped shell command (publishing, remote surgery, branch deletion, a PR
+    // merge) was refused here, in-process, before the controller was asked, so a controller that
+    // holds such a call for a person could never deliver that answer and nothing on this host could
+    // publish. A boundary shape is escalated like any other call; when the controller cannot be
+    // reached the deadline below refuses it. Every other local refusal (the jail, the credential set,
+    // an unrecognised git verb) stays local and immediate.
+    // Both timers are armed inside the try whose finally disarms them. Between arming and the
+    // `finally` there is no window a throw can cross with a timer left live — that is a structural
+    // property of this block, not an audit of what happens to be between the lines.
+    let holdTimer;
+    let deadlineTimer;
+    let abortListener;
+    try {
+        const answer = (async () => ask(request, signal))();
+        // The promise is consumed by the race below; this keeps a rejection from being unhandled in the
+        // window before the race attaches, which node reports as a process-level warning.
+        answer.catch(() => undefined);
+        holdTimer = setTimeout(() => {
+            held.value = true;
+            emit({ kind: 'holding', request });
+        }, holdAfterMs);
+        holdTimer.unref?.();
+        // The deadline timer is ref'd, and that is the fail-closed guarantee itself.
+        //
+        // An unref'd timer here is the same bug as a gate that cannot say no. An unref'd timer does
+        // not hold the event loop open, so a host with nothing else pending — exactly the state a host
+        // is in while it waits for a decision — drains the loop before the deadline fires. The decider
+        // never answers, the deadline never fires, and this handler never returns: the tool call has no
+        // fate at all, which is strictly worse than either answer.
+        //
+        // Observed on Linux: `gate.test.ts`'s "a decision that never arrives blocks" — the test that
+        // proves this exact property — reported "Promise resolution is still pending but the event
+        // loop has already resolved" and cancelled, taking its sibling tests with it. It passed on
+        // win32 only because something else in that process happened to keep the loop alive; the
+        // guarantee was never unconditional, and it is stated as unconditional.
+        //
+        // Holding the loop open is the correct cost. A tool call is in flight and undecided; a host
+        // that exits underneath it has answered nothing. The bound is `decisionTimeoutMs`, and the
+        // `finally` below clears the timer on every exit path, so nothing outlives the call. The
+        // hold timer stays unref'd — it only emits an observation, and this deadline keeps the loop
+        // alive for both.
+        const deadline = new Promise((resolve) => {
+            deadlineTimer = setTimeout(() => resolve('expired'), decisionTimeoutMs);
+        });
+        // A missing or hostile signal cannot escape: a throw inside a Promise executor rejects the
+        // promise, and the race below carries that rejection into this function's own catch.
+        const aborted = new Promise((resolve) => {
+            if (signal.aborted)
+                resolve('aborted');
+            else {
+                // Held so the `finally` can detach it. `{once: true}` self-removes only when the event
+                // fires, and the ordinary case is that it never does — so on a signal that outlives one tool
+                // call, every call would leave a listener behind on it.
+                abortListener = () => resolve('aborted');
+                signal.addEventListener('abort', abortListener, { once: true });
+            }
+        });
+        const settled = await Promise.race([
+            answer.then((value) => ({ answered: value })),
+            deadline,
+            aborted,
+        ]);
+        if (settled === 'expired') {
+            return {
+                kind: 'expired',
+                request,
+                held: held.value,
+                detail: `no decision for ${request.toolName} within ${decisionTimeoutMs}ms; the tool did not run`,
+            };
+        }
+        if (settled === 'aborted') {
+            return {
+                kind: 'refused',
+                request,
+                held: held.value,
+                refusal: refusal('permission-decision-unavailable', `the turn was cancelled while a decision for ${request.toolName} was outstanding`),
+            };
+        }
+        return terminal(request, held.value, settled.answered);
+    }
+    catch (error) {
+        // The decider rejected. An outage — nobody decided — and never a denial, which is why it is a
+        // refusal reason rather than a deny with a borrowed message.
+        const detail = error instanceof EscalationUnavailable
+            ? error.message
+            : `the decision for ${request.toolName} could not be obtained: ${String(error)}`;
+        return {
+            kind: 'refused',
+            request,
+            held: held.value,
+            refusal: refusal('permission-decision-unavailable', detail),
+        };
+    }
+    finally {
+        // Both timers are cleared however this returned. A hook handler runs once per tool call, so a
+        // timer left armed here is a slow leak that only shows up on a long session. The abort listener
+        // is detached for the same reason and in the same place — one exit, three things released.
+        if (holdTimer !== undefined)
+            clearTimeout(holdTimer);
+        if (deadlineTimer !== undefined)
+            clearTimeout(deadlineTimer);
+        if (abortListener !== undefined) {
+            // A signal that does not implement removal must not turn a resolved decision into a thrown
+            // hook, which the CLI reads as an absent one.
+            try {
+                signal.removeEventListener('abort', abortListener);
+            }
+            catch {
+                // Nothing to recover: the listener resolves a promise nobody is waiting on any more.
+            }
+        }
+    }
+}
+/**
+ * Ask the host's own gate, if there is one.
+ *
+ * A local gate that throws refuses. It must not fall through to the decider, and the wrong
+ * implementation here does not look wrong: falling through is not fail-open — the controller is
+ * still asked — so nothing would break in a test and nothing would show in a trace. What it would do
+ * is silently convert a local refusal into a remote question, which is the offline property
+ * evaporating at the exact moment the controller is unreachable. The invariant is absolute: any
+ * error, any outage, any timeout means the tool does not run.
+ */
+function askLocalGate(localGate, request) {
+    if (localGate === undefined)
+        return null;
+    try {
+        return localGate(request) ?? null;
+    }
+    catch (error) {
+        return refusal('permission-decision-unavailable', `the host's own gate failed while deciding ${request.toolName}, so the call is refused rather than escalated: ${String(error)}`);
+    }
+}
+/** A settled answer, read. The unknown-decision rule lands here. */
+function terminal(request, held, answered) {
+    const reading = readDecision(answered);
+    if (!reading.recognised) {
+        return {
+            kind: 'refused',
+            request,
+            held,
+            refusal: refusal('permission-decision-unrecognised', 
+            // The raw payload travels. A host that drops what it did not understand makes a
+            // controller-side bug invisible on the only side that could have seen it.
+            `the decision for ${request.toolName} was not one this build understands: ${reading.raw}`),
+        };
+    }
+    if (reading.decision.behavior === 'deny') {
+        return { kind: 'deny', request, held, message: reading.decision.message };
+    }
+    const { updatedInput } = reading.decision;
+    return { kind: 'allow', request, held, ...(updatedInput === undefined ? {} : { updatedInput }) };
+}
+/** Everything unknown, for an input that could not be read at all. Never a thrown alternative. */
+function unreadableRequest(sessionKey) {
+    return {
+        toolName: '(unnamed tool)',
+        toolUseId: '(no tool_use_id)',
+        toolInput: null,
+        sessionId: '',
+        // The one field that is still true when nothing else is. Everything above is a placeholder for
+        // an input this code could not read; the controller handle comes from the host, not from that
+        // input, so an unreadable call is still attributable to the session it happened in. That is the
+        // difference between a refusal a controller can file and one it can only count.
+        sessionKey,
+        cwd: '',
+        agentId: null,
+        agentType: null,
+    };
+}
+/**
+ * The hook's input in this package's terms, or null if it could not be read at all.
+ *
+ * The recovery path must not use the thing that broke. This is called from the handler's own
+ * `catch`, so if reading the input is what threw, an unguarded read here throws a second time —
+ * inside the catch — and the whole handler escapes as a thrown hook, which the CLI treats as
+ * absent. A fail-closed wrapper whose recovery path can fail is fail-open, and it looks completely
+ * correct.
+ *
+ * Null rather than a filled-in default, because the two are not the same answer. An input this
+ * code cannot read names a tool it cannot name, and asking a decider to authorize "(unnamed tool)"
+ * would get a decision about nothing. An unnameable call is not an authorizable one.
+ */
+function readRequest(input, sessionKey) {
+    try {
+        const anyInput = input;
+        const text = (value) => (typeof value === 'string' ? value : null);
+        return {
+            toolName: text(anyInput['tool_name']) ?? '(unnamed tool)',
+            toolUseId: text(anyInput['tool_use_id']) ?? '(no tool_use_id)',
+            toolInput: anyInput['tool_input'],
+            sessionId: text(anyInput['session_id']) ?? '',
+            // Never read from the input: the agent does not know what its controller calls this session.
+            sessionKey,
+            cwd: text(anyInput['cwd']) ?? '',
+            // `agent_id` is the discriminator, not `agent_type`: the type is also present on the main
+            // thread of a session started with --agent, so reading it alone calls a main-thread call a
+            // subagent one.
+            agentId: text(anyInput['agent_id']),
+            agentType: text(anyInput['agent_type']),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What the CLI is told.
+ *
+ * Every blocking outcome carries a reason that names which rule fired — a degrade is a named
+ * outcome, and the model receives this string verbatim as an `is_error` tool result, so it is the
+ * only explanation anyone downstream gets.
+ *
+ * `holding` is excluded by the type, not by a branch. A hold is emitted while a decision is
+ * outstanding; it is never a terminal outcome, so it can never be what this function renders. A
+ * branch returning `{}` for it — no opinion, which the CLI reads as allow — would be the one branch
+ * that could open the door while looking most harmless. Narrowing the parameter makes that state
+ * unrepresentable: the compiler refuses it, where a safer return value would only have waited to
+ * be simplified back.
+ */
+function outputFor(outcome, grantOnAllow) {
+    if (outcome.kind === 'allow') {
+        if (grantOnAllow) {
+            // The gate's own decision, made effective. It grants this call and nothing else: the decision
+            // was already taken above, and this only stops it from being silently discarded.
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'allow',
+                    permissionDecisionReason: `the host's gate allowed ${outcome.request.toolName}`,
+                    ...(outcome.updatedInput === undefined ? {} : { updatedInput: outcome.updatedInput }),
+                },
+            };
+        }
+        if (outcome.updatedInput === undefined)
+            return {};
+        // No `permissionDecision`. See this file's header: an explicit allow skips permission mode,
+        // allow rules and `canUseTool` (steps 4-6; operator deny and ask rules still run), so without
+        // `grantOnAllow` this gate only ever adds a refusal.
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                updatedInput: outcome.updatedInput,
+            },
+        };
+    }
+    const reason = outcome.kind === 'deny'
+        ? outcome.message
+        : outcome.kind === 'refused'
+            ? `${outcome.refusal.reason}: ${outcome.refusal.detail}`
+            : // One spelling for one concept: the same name the transition carries, so a reader who
+                // looks this prefix up finds it.
+                `${HOOK_TIMEOUT_EVENT}: ${outcome.detail}`;
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+}
+export { describeRaw };
+//# sourceMappingURL=gate.js.map

package/dist/gate/index.d.ts

@@ -0,0 +1,39 @@
+/** The PreToolUse hook and the permission decision path. */
+export type { Decider, Decision, DecisionReading, DecisionRequest } from './decision.js';
+export { describeRaw, readDecision } from './decision.js';
+export type { GateOutcome } from './outcome.js';
+export { gateTransitions, recordGateOutcome } from './outcome.js';
+export type { OutcomeListener, PermissionGateOptions } from './gate.js';
+/**
+ * The PreToolUse gate itself.
+ *
+ * `composeSession` is a convenience that refuses, not a boundary. `composeSession` declines to
+ * assemble `grantOnAllow` together with a non-empty `settingSources`
+ * (`permission-grant-shadows-settings`), and it is the only place that can see both facts. But
+ * every part it composes is exported, including this one, so four lines reach the refused pair
+ * without going near it:
+ *
+ * ```ts
+ * const hooks = mergeHooks(observationHooks({ observer }), permissionHooks({ decide, onOutcome, grantOnAllow: true }));
+ * registry.create({ cwd, hooks, settingSources: ['project'] });   // no refusal fires
+ * ```
+ *
+ * This is stated rather than closed, deliberately. Hand-composition is a supported posture — the
+ * gate is usable without the host — and un-exporting it would remove a legitimate capability to
+ * discourage a combination that, per the SDK's documented evaluation order, does not actually
+ * override operator deny rules (see `gate.ts` for the order, and for why that is documented rather
+ * than measured). An embedder who assembles the pair on purpose should know they have done it;
+ * an embedder who expected `composeSession`'s refusal to be a package-wide guarantee should know
+ * it is not.
+ */
+export { permissionHooks } from './gate.js';
+export type { EscalationOptions, EscalationResponse, EscalationTransport } from './escalate.js';
+export { EscalationUnavailable, escalatingDecider } from './escalate.js';
+export type { LocalGate, LocalGateOptions, ToolFamilies } from './local.js';
+export { DEFAULT_TOOL_FAMILIES, localGate } from './local.js';
+export type { JailOptions, PathResolver } from './jail.js';
+export { checkPath, checkShellForProtectedPaths, commandFromToolInput, pathFromToolInput } from './jail.js';
+export { classifyShellCommand } from './shell.js';
+export type { GlobalFlag, Invocation, ParsedCommand } from './command.js';
+export { INTERPRETER_NAMES, isInertLiteral, parseCommand, programNameOf, stripComments, tokenize, } from './command.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gate/index.js

@@ -0,0 +1,31 @@
+export { describeRaw, readDecision } from './decision.js';
+export { gateTransitions, recordGateOutcome } from './outcome.js';
+/**
+ * The PreToolUse gate itself.
+ *
+ * `composeSession` is a convenience that refuses, not a boundary. `composeSession` declines to
+ * assemble `grantOnAllow` together with a non-empty `settingSources`
+ * (`permission-grant-shadows-settings`), and it is the only place that can see both facts. But
+ * every part it composes is exported, including this one, so four lines reach the refused pair
+ * without going near it:
+ *
+ * ```ts
+ * const hooks = mergeHooks(observationHooks({ observer }), permissionHooks({ decide, onOutcome, grantOnAllow: true }));
+ * registry.create({ cwd, hooks, settingSources: ['project'] });   // no refusal fires
+ * ```
+ *
+ * This is stated rather than closed, deliberately. Hand-composition is a supported posture — the
+ * gate is usable without the host — and un-exporting it would remove a legitimate capability to
+ * discourage a combination that, per the SDK's documented evaluation order, does not actually
+ * override operator deny rules (see `gate.ts` for the order, and for why that is documented rather
+ * than measured). An embedder who assembles the pair on purpose should know they have done it;
+ * an embedder who expected `composeSession`'s refusal to be a package-wide guarantee should know
+ * it is not.
+ */
+export { permissionHooks } from './gate.js';
+export { EscalationUnavailable, escalatingDecider } from './escalate.js';
+export { DEFAULT_TOOL_FAMILIES, localGate } from './local.js';
+export { checkPath, checkShellForProtectedPaths, commandFromToolInput, pathFromToolInput } from './jail.js';
+export { classifyShellCommand } from './shell.js';
+export { INTERPRETER_NAMES, isInertLiteral, parseCommand, programNameOf, stripComments, tokenize, } from './command.js';
+//# sourceMappingURL=index.js.map

package/dist/gate/jail.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The path jail, and the credential denial.
+ *
+ * The jail bounds where an agent can write at all. It is self-contained: a call whose target
+ * resolves outside the declared workspace root is refused without asking anything, so it holds
+ * with the controller unreachable, unresponsive, or wrong.
+ *
+ * The credential denial covers what a default-open read policy misses. Default-open reads are
+ * correct for source files and wrong for the host's own token cache. The agent runs as the same
+ * OS user as the host, so file permissions are not a boundary against it: an 0600 credential is
+ * readable by the agent exactly as it is by the host. This denial is the local control, and it is
+ * scoped, not total: it refuses reads through the declared read tools (`Read`, `NotebookRead` by
+ * default), writes, and shell commands naming a protected path literally — each by absolute path,
+ * with a named refusal. Built-in tools outside the declared families (`Grep`, `Glob`), shell
+ * expansion forms (`~`, `$HOME`, `%USERPROFILE%`) and symlink indirection get no opinion here —
+ * those calls escalate to the controller, and with it unreachable they are refused as outages
+ * rather than by name. Widening the local denial to cover them is a known open question,
+ * deliberately not taken in passing: every widening is an over-refusal risk that deserves its own
+ * decision.
+ *
+ * Every unknown resolves toward refusing. No path in the input: refuse. A resolver that throws:
+ * refuse. Not absolute: refuse. No declared root: refuse, because a jail with no walls is not a
+ * jail. A false refusal costs one human click; a false allow costs the invariant.
+ */
+import type { Refusal } from '../core/refusal.js';
+/**
+ * Turns a path into its canonical absolute form.
+ *
+ * Injected rather than imported, and `core/paths.ts` says why in its own header: its resolution is
+ * textual and deliberately never consults the filesystem, so a caller enforcing a real jail supplies
+ * a real resolver. `host/` holds the one built on `node:path`; a test supplies one that throws, which
+ * is the only way to exercise the normalization-failure path at all.
+ *
+ * It may throw. A throw is a refusal, never a fall-through.
+ */
+export type PathResolver = (candidate: string) => string;
+export interface JailOptions {
+    /** The absolute root every path-taking call must resolve inside. */
+    readonly workspaceRoot: string | null;
+    readonly resolve: PathResolver;
+    /**
+     * Absolute paths the agent may not read, write or name in a shell command.
+     *
+     * Supplied by the embedder at construction — `host/paths.ts` computes the default set. It is a
+     * list rather than a predicate so an embedder can read back exactly what is protected.
+     */
+    readonly protectedPaths: readonly string[];
+}
+/**
+ * The path this tool call is about, or null when the input carries none.
+ *
+ * Null is a refusable state, not a missing value — see `checkPath`. A call whose target cannot be
+ * found is not a call that can be bounded, and guessing one would authorize something nobody named.
+ */
+export declare function pathFromToolInput(toolInput: unknown): string | null;
+/** The command this shell call is about, or null when the input carries none. */
+export declare function commandFromToolInput(toolInput: unknown): string | null;
+/**
+ * Check a path-taking tool call against the jail and the protected set.
+ *
+ * The credential check runs first and applies whatever the workspace root is: a token cache that
+ * happens to sit inside the workspace is still a token cache. Order matters for the message the
+ * reader gets, not for whether the call is refused — both answers block.
+ */
+export declare function checkPath(candidate: string | null, options: JailOptions): Refusal | null;
+/**
+ * Check a shell command for credential material named anywhere in it.
+ *
+ * This one scans the whole command, and that is deliberately unlike the rest of the local gate.
+ * Everything else here parses precisely so that a mention of a boundary word does not refuse a
+ * benign call, so a reader who notices this function will reasonably wonder whether it was missed.
+ *
+ * It was not. The two cases are not the same shape. A boundary verb is only dangerous at a command
+ * position, so parsing tells you whether it is one. A credential path is dangerous wherever it
+ * appears: as an argument to any reader, inside a redirect, in a substitution, or handed to a program
+ * this parser has no model of. There is no position at which naming the host's token cache in a shell
+ * command is routine, so there is nothing to gain by locating it precisely — and every parser gap
+ * would become a way to read the credential. The cost of the choice is bounded and stated: a command
+ * that merely mentions the path — an `echo` of a diagnostic, say — is refused, which costs one human
+ * click. The alternative costs the credential.
+ *
+ * So do not narrow this to match the rest of the file. Both credential defences — this one and
+ * `checkPath`'s — are covered by tests that fail when either is removed. Reproduce that before
+ * changing anything here: make `protectedPathCovering` return null and make this function's
+ * haystack empty, then run the suite. The over-refusal is the price of those tests, not an
+ * oversight in them.
+ *
+ * The comparison is on the resolved protected paths and on the raw command text, case-insensitively,
+ * because Windows paths reach here in both slash styles and either case.
+ */
+export declare function checkShellForProtectedPaths(command: string, options: JailOptions): Refusal | null;
+//# sourceMappingURL=jail.d.ts.map