@naswerks/periscope 1.0.0 → 1.0.1

package/src/gate/index.ts

@@ -0,0 +1,53 @@
+/** 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';
+
+// The host's own gate — the offline-provable local refusal.
+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';

package/src/gate/jail.ts

@@ -0,0 +1,210 @@
+/**
+ * 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';
+import { refusal } from '../core/refusal.js';
+import { isContainedBy, isAbsolutePath, normalizePath } from '../core/paths.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 tool-input fields that carry a path, in precedence order. First readable one wins. */
+const PATH_FIELDS = ['file_path', 'notebook_path', 'path'] as const;
+
+/**
+ * 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: unknown): string | null {
+  if (typeof toolInput !== 'object' || toolInput === null) return null;
+  const record = toolInput as Record<string, unknown>;
+  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: unknown): string | null {
+  if (typeof toolInput !== 'object' || toolInput === null) return null;
+  const value = (toolInput as Record<string, unknown>)['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: string,
+  resolve: PathResolver,
+): { resolved: string } | { refusal: Refusal } {
+  let resolved: string;
+  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: string, protectedPaths: readonly string[]): string | null {
+  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: string | null, options: JailOptions): Refusal | null {
+  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: string, options: JailOptions): Refusal | null {
+  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;
+}

package/src/gate/local.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { refusal } from '../core/refusal.js';
+import type { DecisionRequest } from './decision.js';
+import type { JailOptions, PathResolver } from './jail.js';
+import { checkPath, checkShellForProtectedPaths, commandFromToolInput, pathFromToolInput } from './jail.js';
+import { classifyShellCommand } from './shell.js';
+import { parseCommand } from './command.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 const DEFAULT_TOOL_FAMILIES: ToolFamilies = {
+  write: ['Write', 'Edit', 'MultiEdit', 'NotebookEdit'],
+  read: ['Read', 'NotebookRead'],
+  shell: ['Bash', 'PowerShell'],
+};
+
+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 function localGate(options: LocalGateOptions): LocalGate {
+  const families = options.toolFamilies ?? DEFAULT_TOOL_FAMILIES;
+  const jail: JailOptions = {
+    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: DecisionRequest): Refusal | null => {
+    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;
+  };
+}

package/src/gate/outcome.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 { SessionActivity, TransitionCause } from '../state/model.js';
+import { HOOK_TIMEOUT_EVENT } from '../state/model.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;
+    };
+
+const permissionActivity = (toolName: string): SessionActivity => ({ 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: string): string => `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: GateOutcome): TransitionRequest[] {
+  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: string): TransitionCause => ({ 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 } as const) : 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: SessionStateMachine,
+  outcome: GateOutcome,
+): Result<SessionTransition>[] {
+  return gateTransitions(outcome).map((request) => machine.record(request));
+}