@naswerks/periscope 1.0.0

package/dist/gate/jail.js

@@ -0,0 +1,131 @@
+import { refusal } from '../core/refusal.js';
+import { isContainedBy, isAbsolutePath, normalizePath } from '../core/paths.js';
+/** The tool-input fields that carry a path, in precedence order. First readable one wins. */
+const PATH_FIELDS = ['file_path', 'notebook_path', 'path'];
+/**
+ * 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 function pathFromToolInput(toolInput) {
+    if (typeof toolInput !== 'object' || toolInput === null)
+        return null;
+    const record = toolInput;
+    for (const field of PATH_FIELDS) {
+        const value = record[field];
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return null;
+}
+/** The command this shell call is about, or null when the input carries none. */
+export function commandFromToolInput(toolInput) {
+    if (typeof toolInput !== 'object' || toolInput === null)
+        return null;
+    const value = toolInput['command'];
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+/** Resolve, or say why it could not be done. Never throws — a throwing resolver becomes a refusal. */
+function resolveOrRefuse(candidate, resolve) {
+    let resolved;
+    try {
+        resolved = resolve(candidate);
+    }
+    catch (error) {
+        return {
+            refusal: refusal('path-unresolvable', `${candidate} could not be normalized (${String(error)}), so it is not provably inside the workspace`),
+        };
+    }
+    if (typeof resolved !== 'string' || resolved === '') {
+        return { refusal: refusal('path-unresolvable', `normalizing ${candidate} produced no path at all`) };
+    }
+    if (!isAbsolutePath(resolved)) {
+        return {
+            refusal: refusal('path-not-absolute', `${candidate} does not resolve to an absolute path (${resolved})`),
+        };
+    }
+    return { resolved };
+}
+/**
+ * Is this resolved path at or beneath one of the protected paths?
+ *
+ * `isContainedBy` compares segment-wise after normalizing both sides, so a protected `C:\Users\x\.claude`
+ * does not also protect `C:\Users\x\.claude-notes`, and the protected path itself counts as protected.
+ */
+function protectedPathCovering(resolved, protectedPaths) {
+    for (const candidate of protectedPaths) {
+        if (isContainedBy(resolved, candidate))
+            return candidate;
+    }
+    return 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 function checkPath(candidate, options) {
+    if (candidate === null) {
+        return refusal('path-input-missing', 'this tool takes a path and the input carries none, so there is nothing to bound — refused rather than guessed');
+    }
+    const outcome = resolveOrRefuse(candidate, options.resolve);
+    if ('refusal' in outcome)
+        return outcome.refusal;
+    const { resolved } = outcome;
+    const covering = protectedPathCovering(resolved, options.protectedPaths);
+    if (covering !== null) {
+        return refusal('credential-path-denied', `${resolved} is at or beneath ${covering}, which holds credential material; the agent shares the host's OS user, so this gate is the only control over it`);
+    }
+    if (options.workspaceRoot === null || options.workspaceRoot.trim() === '') {
+        return refusal('path-escapes-root', 'no workspace root is declared, so no path can be shown to be inside one — a jail with no walls is not a jail');
+    }
+    const rootOutcome = resolveOrRefuse(options.workspaceRoot, options.resolve);
+    if ('refusal' in rootOutcome)
+        return rootOutcome.refusal;
+    if (!isContainedBy(resolved, rootOutcome.resolved)) {
+        return refusal('path-escapes-root', `${resolved} is outside the declared workspace root ${rootOutcome.resolved}`);
+    }
+    return 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 function checkShellForProtectedPaths(command, options) {
+    const haystack = normalizePath(command).toLowerCase();
+    for (const candidate of options.protectedPaths) {
+        const outcome = resolveOrRefuse(candidate, options.resolve);
+        // A protected path this host cannot resolve is still protected — fall back to its literal form
+        // rather than dropping it from the set, which would silently shrink the protected surface.
+        const needle = normalizePath('refusal' in outcome ? candidate : outcome.resolved).toLowerCase();
+        if (needle !== '' && haystack.includes(needle)) {
+            return refusal('credential-path-denied', `the command names ${needle}, which holds credential material; the agent shares the host's OS user, so this gate is the only control over it`);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=jail.js.map

package/dist/gate/local.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The host's own gate — a refusal that does not depend on the controller behaving.
+ *
+ * This is what makes the package installable by a stranger. A host that executes whatever a
+ * remote server sends is, mechanically, a code-execution service on somebody else's machine. An
+ * optional callback defaulting to escalate-everything is the opposite of an answer to that. This
+ * module refuses locally, offline, by rules that ship with the package — so the property can be
+ * demonstrated by somebody who does not trust the controller at all, which is the only audience the
+ * claim matters to.
+ *
+ * The vocabulary is owned locally, not received. A policy the controller can change remotely is a
+ * policy that depends on the controller behaving, which defeats the module. At the exact moment this
+ * is load-bearing — the controller unreachable — a cached remote policy is the only thing acting, so
+ * receiving-and-caching is local ownership plus a remote mutation path, for no benefit when it
+ * counts.
+ *
+ * Owned is not hardcoded, and that is what makes it survivable. The embedder chooses the tool
+ * families and the protected-path list at construction, in-process, before any session exists. The
+ * wire carries no policy in either direction.
+ *
+ * It adds refusals and never removes one. A tool this module has no opinion about returns null and
+ * the surrounding gate goes on to ask whoever it was going to ask. Two mechanisms, one invariant —
+ * the same posture the outer gate takes toward the operator's own settings.
+ */
+import type { Refusal } from '../core/refusal.js';
+import type { DecisionRequest } from './decision.js';
+import type { PathResolver } from './jail.js';
+/**
+ * Decides one tool call, locally. Null means no local opinion, never "allowed".
+ *
+ * Synchronous and total by contract: this runs before anything is asked of anyone, and an
+ * asynchronous local policy would be a second place a decision can hang.
+ */
+export type LocalGate = (request: DecisionRequest) => Refusal | null;
+/** The tool families this module recognises. Data, so an embedder can state its own. */
+export interface ToolFamilies {
+    /** Tools whose input names a path they will write. */
+    readonly write: readonly string[];
+    /** Tools whose input names a path they will read. Present because of the credential denial. */
+    readonly read: readonly string[];
+    /** Tools that run a command. */
+    readonly shell: readonly string[];
+}
+/**
+ * The SDK's own tool names.
+ *
+ * Read tools are jailed too. Reading source is benign; reading the host's token cache is not, and
+ * the two arrive through the same tool. The jail
+ * bounds where reads may go and the protected set names what is off-limits wherever it sits.
+ */
+export declare const DEFAULT_TOOL_FAMILIES: ToolFamilies;
+export interface LocalGateOptions {
+    /** The absolute root every path-taking call must resolve inside. */
+    readonly workspaceRoot: string | null;
+    /** The real resolver. `host/paths.ts` holds the one built on `node:path`. */
+    readonly resolve: PathResolver;
+    /** Absolute paths holding credential material. `host/paths.ts` computes the default set. */
+    readonly protectedPaths: readonly string[];
+    /** Defaults to `DEFAULT_TOOL_FAMILIES`. */
+    readonly toolFamilies?: ToolFamilies;
+}
+/**
+ * Build the local gate.
+ *
+ * The returned function is pure, synchronous and total — so it composes into whatever assembles a
+ * session later, and needs no composition root to exist first.
+ */
+export declare function localGate(options: LocalGateOptions): LocalGate;
+//# sourceMappingURL=local.d.ts.map

package/dist/gate/local.js

@@ -0,0 +1,51 @@
+import { refusal } from '../core/refusal.js';
+import { checkPath, checkShellForProtectedPaths, commandFromToolInput, pathFromToolInput } from './jail.js';
+import { classifyShellCommand } from './shell.js';
+import { parseCommand } from './command.js';
+/**
+ * The SDK's own tool names.
+ *
+ * Read tools are jailed too. Reading source is benign; reading the host's token cache is not, and
+ * the two arrive through the same tool. The jail
+ * bounds where reads may go and the protected set names what is off-limits wherever it sits.
+ */
+export const DEFAULT_TOOL_FAMILIES = {
+    write: ['Write', 'Edit', 'MultiEdit', 'NotebookEdit'],
+    read: ['Read', 'NotebookRead'],
+    shell: ['Bash', 'PowerShell'],
+};
+/**
+ * Build the local gate.
+ *
+ * The returned function is pure, synchronous and total — so it composes into whatever assembles a
+ * session later, and needs no composition root to exist first.
+ */
+export function localGate(options) {
+    const families = options.toolFamilies ?? DEFAULT_TOOL_FAMILIES;
+    const jail = {
+        workspaceRoot: options.workspaceRoot,
+        resolve: options.resolve,
+        protectedPaths: options.protectedPaths,
+    };
+    const writeTools = new Set(families.write);
+    const readTools = new Set(families.read);
+    const shellTools = new Set(families.shell);
+    return (request) => {
+        if (shellTools.has(request.toolName)) {
+            const command = commandFromToolInput(request.toolInput);
+            if (command === null) {
+                return refusal('shell-command-missing', 'this tool runs a command and the input carries none, so there is nothing to classify — refused rather than guessed');
+            }
+            // One parse, both consumers. The credential check runs first because a command naming the
+            // token cache is the more serious of the two answers and should be the one the reader gets.
+            const parsed = parseCommand(command);
+            return checkShellForProtectedPaths(command, jail) ?? classifyShellCommand(command, parsed);
+        }
+        if (writeTools.has(request.toolName) || readTools.has(request.toolName)) {
+            return checkPath(pathFromToolInput(request.toolInput), jail);
+        }
+        // No opinion. The surrounding gate asks whoever it was going to ask.
+        return null;
+    };
+}
+//# sourceMappingURL=local.js.map

package/dist/gate/outcome.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What the gate did, and the transitions that say so.
+ *
+ * This file is pure, and that is the point. Turning an outcome into transitions has no clock, no
+ * machine and no SDK in it, so the mapping every emitted trace depends on can be checked exhaustively
+ * without a session anywhere near it. `recordGateOutcome` below is the two-line impure half.
+ *
+ * The gate declares no status of its own. Every outcome here lands on the declared state model's
+ * existing states, activities and causes. A gate that found itself wanting a status word would have
+ * found a state missing from that model — a finding for it, never a column here.
+ *
+ * Five outcomes, three cause kinds, and the separation is the whole value. A denial is
+ * `control/permission_denied` — somebody decided. An outage and an unrecognised answer are
+ * `refusal/…` — nobody decided, and the two are different investigations. An expiry is
+ * `timeout/hook_timed_out`. Every one of them blocks the tool, so the invariant is identical and
+ * only the story differs; conflating an outage with a deliberate "no" is an expensive failure, and
+ * it is why the kinds are separate rather than one kind with a different string in `detail`.
+ */
+import type { Refusal } from '../core/refusal.js';
+import type { SessionStateMachine, TransitionRequest } from '../state/machine.js';
+import type { Result } from '../core/result.js';
+import type { SessionTransition } from '../state/model.js';
+import type { DecisionRequest } from './decision.js';
+/**
+ * What happened to one tool call.
+ *
+ * `held` says whether a permission entry was opened for this call — i.e. whether the decision took
+ * long enough to be worth reporting as a session that is waiting. It is carried on every terminal
+ * outcome because the close is only correct when there was an open.
+ */
+export type GateOutcome = 
+/** The decision is taking long enough to be a hold. Opens the permission entry. */
+{
+    readonly kind: 'holding';
+    readonly request: DecisionRequest;
+} | {
+    readonly kind: 'allow';
+    readonly request: DecisionRequest;
+    readonly updatedInput?: Record<string, unknown>;
+    readonly held: boolean;
+} | {
+    readonly kind: 'deny';
+    readonly request: DecisionRequest;
+    readonly message: string;
+    readonly held: boolean;
+}
+/** Nobody decided: the decider threw, the escalation failed, or the answer was not understood. */
+ | {
+    readonly kind: 'refused';
+    readonly request: DecisionRequest;
+    readonly refusal: Refusal;
+    readonly held: boolean;
+}
+/** The host's own deadline passed before an answer arrived. */
+ | {
+    readonly kind: 'expired';
+    readonly request: DecisionRequest;
+    readonly detail: string;
+    readonly held: boolean;
+};
+/**
+ * The transitions one outcome produces. Pure, total, and often empty.
+ *
+ * An ordinary allow emits nothing, deliberately. The observer's own `PreToolUse` record already
+ * says the tool started, and a second transition saying it was permitted would be one fact recorded
+ * twice — which is how a trace stops being countable. A held allow is different: an entry was
+ * opened, so it has to be closed, and that close is a real event with a real duration behind it.
+ */
+export declare function gateTransitions(outcome: GateOutcome): TransitionRequest[];
+/** The impure half: put an outcome's transitions on a machine. Returns what it recorded. */
+export declare function recordGateOutcome(machine: SessionStateMachine, outcome: GateOutcome): Result<SessionTransition>[];
+//# sourceMappingURL=outcome.d.ts.map

package/dist/gate/outcome.js

@@ -0,0 +1,91 @@
+import { HOOK_TIMEOUT_EVENT } from '../state/model.js';
+const permissionActivity = (toolName) => ({ kind: 'permission', name: toolName });
+/**
+ * How the gate keys its hold entry: by `tool_use_id`, which every `PreToolUse` carries.
+ *
+ * Deliberately not the observer's name-keyed `permission:<toolName>`. The observer's `PreToolUse`
+ * branch closes any open name-keyed permission entry — the allow-path exit for its own
+ * `PermissionRequest` lane — so a name-keyed hold could be closed by the next `PreToolUse` for the
+ * same tool while this call's decision is still outstanding, recording a resolution that never
+ * happened. Two writers, two key spaces: the observer owns `permission:<toolName>`, the gate owns
+ * `permission:<toolUseId>`, and two simultaneous holds for one tool are two entries. The
+ * `permission:` prefix is kept so this key can never collide with the observer's `tool` entry,
+ * which is the raw tool_use_id from the same event.
+ */
+const holdEntryId = (toolUseId) => `permission:${toolUseId}`;
+/**
+ * The transitions one outcome produces. Pure, total, and often empty.
+ *
+ * An ordinary allow emits nothing, deliberately. The observer's own `PreToolUse` record already
+ * says the tool started, and a second transition saying it was permitted would be one fact recorded
+ * twice — which is how a trace stops being countable. A held allow is different: an entry was
+ * opened, so it has to be closed, and that close is a real event with a real duration behind it.
+ */
+export function gateTransitions(outcome) {
+    const { request } = outcome;
+    const entryId = holdEntryId(request.toolUseId);
+    // The event that fired is `PreToolUse`. Naming `PermissionRequest` or `PermissionDenied` here
+    // would be truer to the concept and false about the world — observed, neither of those hooks fires
+    // for a hook-authored decision — and a trace that names an event which never happened teaches its
+    // next reader something untrue.
+    const onTheHook = (detail) => ({ kind: 'hook', event: 'PreToolUse', detail });
+    if (outcome.kind === 'holding') {
+        return [
+            {
+                to: 'working',
+                entry: {
+                    op: 'open',
+                    entryId,
+                    activity: permissionActivity(request.toolName),
+                    agentId: request.agentId,
+                },
+                cause: onTheHook(`a permission decision for ${request.toolName} is outstanding`),
+            },
+        ];
+    }
+    const closeIfHeld = outcome.held ? { op: 'close', entryId } : null;
+    if (outcome.kind === 'allow') {
+        if (!outcome.held)
+            return [];
+        return [
+            {
+                to: 'working',
+                entry: closeIfHeld,
+                cause: onTheHook(`the permission for ${request.toolName} resolved: allowed`),
+            },
+        ];
+    }
+    if (outcome.kind === 'deny') {
+        return [
+            {
+                to: 'working',
+                entry: closeIfHeld,
+                // A call the host made on itself — which is what `control` means here, and what a
+                // hook-authored deny literally is. See CONTROL_EVENTS' own note: kind and event are
+                // validated independently and never as a pair, so this pairing is an authorial choice.
+                cause: { kind: 'control', event: 'permission_denied', detail: outcome.message },
+            },
+        ];
+    }
+    if (outcome.kind === 'refused') {
+        return [
+            {
+                to: 'working',
+                entry: closeIfHeld,
+                cause: { kind: 'refusal', event: outcome.refusal.reason, detail: outcome.refusal.detail },
+            },
+        ];
+    }
+    return [
+        {
+            to: 'working',
+            entry: closeIfHeld,
+            cause: { kind: 'timeout', event: HOOK_TIMEOUT_EVENT, detail: outcome.detail },
+        },
+    ];
+}
+/** The impure half: put an outcome's transitions on a machine. Returns what it recorded. */
+export function recordGateOutcome(machine, outcome) {
+    return gateTransitions(outcome).map((request) => machine.record(request));
+}
+//# sourceMappingURL=outcome.js.map

package/dist/gate/shell.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The shell backstop — two layers, and the second exists because the first was insufficient.
+ *
+ * A shell command cannot be proven safe by looking at a path, so this is the only control over what
+ * a shell tool call can reach outside the workspace. Both layers run; either one refusing is enough.
+ *
+ *   Layer 1, the denylist. Named boundary operations — publishing, remote surgery, branch deletion,
+ *   merging — matched over the whole scannable text with `[\s\S]`, so a newline cannot hide one
+ *   inside a compound command.
+ *
+ *   Layer 2, the git verb allowlist. This layer is not redundancy; it closes a real defect class.
+ *   `git send-pack` — the plumbing that `git push` calls underneath — matches no denylist pattern,
+ *   and a denylist-only classifier approved it as benign shell, which force-pushed a main branch
+ *   under an automated actor. A denylist under-includes by construction: it can only refuse what
+ *   somebody thought of. So a git invocation whose verb is not provably safe is refused without
+ *   enumeration, which covers `send-pack`, `receive-pack`, aliases, and every verb git ships in a
+ *   future release.
+ *
+ * The input is parsed, not raw — see `command.ts` for the defects a raw scan produces. Layer 1
+ * scans `ParsedCommand.scannable`, which is the raw command minus comments and provably-inert data
+ * payloads; layer 2 reads the parsed invocations. That narrows what is scanned and never what is
+ * denied.
+ *
+ * The rule that decides every ambiguous case: a false refusal costs one human click; a false allow
+ * costs the invariant. Every unknown shape in this file resolves toward refusing.
+ */
+import type { Refusal } from '../core/refusal.js';
+import type { ParsedCommand } from './command.js';
+/**
+ * Classify a shell command. Returns the refusal that fired, or null when nothing did.
+ *
+ * `parsed` may be supplied by a caller that already parsed the command — the credential check does,
+ * and parsing twice would be work for nothing.
+ */
+export declare function classifyShellCommand(command: string, parsed?: ParsedCommand): Refusal | null;
+//# sourceMappingURL=shell.d.ts.map