@naswerks/periscope 1.0.0

package/dist/gate/shell.js

@@ -0,0 +1,226 @@
+import { refusal } from '../core/refusal.js';
+import { parseCommand } from './command.js';
+/**
+ * Separators that end one top-level command, mirroring `command.ts`'s own set.
+ *
+ * Quote spans are not tracked here on purpose: an unbalanced or quoted separator yields more
+ * segments, and more segments can only ever make a pattern harder to satisfy... which would be the
+ * wrong direction. So the split runs over `scannable`, whose inert payloads are already masked, and
+ * a segment that cannot be determined is scanned as part of a larger one — the refusing direction.
+ */
+const SEGMENT_SPLIT = /[|&;\n\r()`]+/;
+/** Does `pattern` match inside any single top-level segment of `text`? */
+function matchesInAnySegment(pattern, text) {
+    return text.split(SEGMENT_SPLIT).some((segment) => pattern.test(segment));
+}
+/**
+ * The denylist, in match order. `[\s\S]` rather than `.` throughout: a compound command spanning a
+ * newline must not be able to hide a boundary operation behind the line break.
+ */
+const BOUNDARY_RULES = [
+    {
+        name: 'git-push',
+        // The lookbehind excises exactly one token pair: `stash push`. `git stash push -- <paths>` is the
+        // only canonical partial-stash form, and it parsed as a publish — so that operation was literally
+        // unperformable. A stash cannot publish anything, and layer 2 admits `stash` as a known-safe verb.
+        // The exclusion is whole-token (a bare `\b` matches inside a hyphenated token, so `my-stash push`
+        // had the suffix of `my-stash` read as the excluded token) and adjacency-strict, so
+        // `git stash push … ; git push origin main` still matches on the second occurrence.
+        pattern: /\bgit\b[\s\S]*?(?<!(?:^|[\s;&|(){}])stash\s{1,8})\bpush\b/i,
+        detail: 'publishing to a remote is a human decision, not an agent one',
+    },
+    {
+        name: 'git-remote-surgery',
+        // The lookbehind keeps `git ls-remote` — a remote query — out of this rule, whole-token for the
+        // same reason as above (a bare substring exclusion lets any token ending in `ls-` suppress it).
+        //
+        // The read-only forms are exempt, and the exemption is exactly these shapes: `-v`,
+        // `--verbose`, `show`, and the bare list. Everything mutating still refuses — `add`, `set-url`,
+        // `set-head`, `set-branches`, `rename`, `remove`, `prune`, `update`. `get-url` is read-only and
+        // still refuses on purpose: an exemption set that grows by inference is how a boundary erodes.
+        pattern: /\bgit\b[\s\S]*?(?<!(?:^|[\s;&|(){}])ls-)\bremote\b(?!\s+(?:-v|--verbose|show)\b)(?!\s*$)/i,
+        detail: 'changing where this repository publishes is a human decision',
+    },
+    {
+        name: 'git-branch-delete',
+        // Plain `git branch`, `--show-current` and `checkout -b` all flow; `git push --delete` is caught
+        // by the publish rule above.
+        //
+        // Segment-scoped. `[\s\S]*?` crosses pipes, so a read-only listing would borrow its `-d` from
+        // a downstream `tr -d ' '` and refuse as a deletion. The publish rule is deliberately not
+        // scoped: a push anywhere in a piped command is a push.
+        pattern: /\bgit\b[\s\S]*?\bbranch\b[\s\S]*?(\s-[dD]\b|--delete\b)/i,
+        detail: 'deleting a branch destroys history a human may still need',
+        segmentScoped: true,
+    },
+    {
+        name: 'gh-pr-merge',
+        pattern: /\bgh\b[\s\S]*?\bpr\b[\s\S]*?\bmerge\b/i,
+        detail: 'merging is a human boundary',
+    },
+];
+/**
+ * Git verbs that are known-safe: reads, local-only writes, and download-only network.
+ *
+ * The organising idea is publish. None of these can send anything to a remote, which is why
+ * `fetch`, `pull` and `ls-remote` sit here despite touching the network, and why `commit` does too —
+ * a local commit publishes nothing.
+ *
+ * Exact-case: git subcommands are lowercase, so a cased oddity is not proven safe and refuses.
+ */
+const ALLOWED_GIT_VERBS = new Set([
+    // reads
+    'status',
+    'log',
+    'diff',
+    'show',
+    'rev-parse',
+    'describe',
+    'blame',
+    'grep',
+    'shortlog',
+    'reflog',
+    'ls-files',
+    'ls-tree',
+    'cat-file',
+    'merge-base',
+    'rev-list',
+    'check-ignore',
+    'check-attr',
+    // read-only terminal flags, surfaced as the verb when nothing else is: git prints and exits.
+    '--version',
+    '--help',
+    // local-only writes. `branch -d` and friends are already refused by the denylist above.
+    'add',
+    'commit',
+    'restore',
+    'checkout',
+    'switch',
+    'branch',
+    'stash',
+    'init',
+    'merge',
+    'rebase',
+    'cherry-pick',
+    'revert',
+    'reset',
+    'rm',
+    'mv',
+    'tag',
+    'clean',
+    'apply',
+    // `hash-object` sits with the local writes rather than the reads, and the placement is the point.
+    // Its common form only prints a sha, but `-w` writes a loose object — and this allowlist is
+    // verb-level, so admitting the verb admits `-w`. It qualifies on the same ground `init` does: an
+    // unreferenced loose object cannot publish anything.
+    'hash-object',
+    // download-only network — cannot publish.
+    'fetch',
+    'pull',
+    'ls-remote',
+]);
+/** `git config` flags that only read. Exact tokens, never prefixes. */
+const CONFIG_READ_FLAGS = new Set([
+    '--get',
+    '--get-all',
+    '--get-regexp',
+    '--get-urlmatch',
+    '--get-color',
+    '--get-colorbool',
+    '--list',
+    '-l',
+]);
+/** `git config` flags that mutate. If present, refuse, even beside a read flag. */
+const CONFIG_WRITE_FLAGS = new Set([
+    '--add',
+    '--unset',
+    '--unset-all',
+    '--replace-all',
+    '--set-all',
+    '--edit',
+    '-e',
+    '--rename-section',
+    '--remove-section',
+    '--default',
+]);
+/** The `git remote` shapes that only print. The same three the denylist above exempts. */
+const REMOTE_READ_FLAGS = new Set(['-v', '--verbose']);
+/**
+ * `git config` is a read verb and a write verb wearing one name, so it cannot sit in the allowlist:
+ * a bare `git config user.email you@example` is a write and reads identically to a query without
+ * this rule. Only the provably-reading shapes are admitted.
+ */
+function isReadOnlyConfig(args) {
+    let sawRead = false;
+    for (const argument of args) {
+        if (CONFIG_WRITE_FLAGS.has(argument))
+            return false;
+        if (CONFIG_READ_FLAGS.has(argument))
+            sawRead = true;
+    }
+    return sawRead;
+}
+/**
+ * `git remote`, same problem and same treatment. Admitted: the bare list, `-v`/`--verbose`, and
+ * `show <name>`. Anything else — a subcommand, an unknown flag — is not proven read-only and refuses.
+ *
+ * Both layers must agree before a remote command flows. The vocabulary is stated twice on purpose
+ * rather than shared through one looser predicate: two independent statements of the same three
+ * shapes cannot both be widened by accident.
+ */
+function isReadOnlyRemote(args) {
+    for (const argument of args) {
+        if (argument === 'show')
+            return true;
+        if (REMOTE_READ_FLAGS.has(argument))
+            continue;
+        return false;
+    }
+    return true;
+}
+function isAllowedGitInvocation(verb, args) {
+    if (ALLOWED_GIT_VERBS.has(verb))
+        return true;
+    if (verb === 'config')
+        return isReadOnlyConfig(args);
+    if (verb === 'remote')
+        return isReadOnlyRemote(args);
+    return false;
+}
+// ---------------------------------------------------------------------------
+/**
+ * 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 function classifyShellCommand(command, parsed = parseCommand(command)) {
+    // Layer 1 — the denylist, over text the shell could actually execute.
+    for (const rule of BOUNDARY_RULES) {
+        const fired = rule.segmentScoped === true
+            ? matchesInAnySegment(rule.pattern, parsed.scannable)
+            : rule.pattern.test(parsed.scannable);
+        if (fired) {
+            return refusal('shell-boundary-command', `${rule.name}: ${rule.detail}`);
+        }
+    }
+    // Layer 2 — the git verb allowlist. Non-git invocations are not this layer's business; shell
+    // commands as a whole are covered by the workspace jail, this file, and the audit trail together.
+    //
+    // It is deliberately git-only. Extending an allowlist posture to another program is a boundary
+    // decision that belongs to the embedder's policy (`ToolFamilies`, the local gate's options), not
+    // to this file.
+    for (const invocation of parsed.invocations) {
+        if (invocation.program !== 'git')
+            continue;
+        if (invocation.verb === null) {
+            return refusal('shell-verb-unrecognised', 'a git invocation with no determinable verb cannot be shown to be safe, so it is refused');
+        }
+        if (!isAllowedGitInvocation(invocation.verb, invocation.args)) {
+            return refusal('shell-verb-unrecognised', `git ${invocation.verb} is not a verb this host can prove is safe; the allowlist refuses ` +
+                'anything it cannot name, which is what covers the plumbing forms of publishing');
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=shell.js.map

package/dist/host/agent-process.d.ts

@@ -0,0 +1,452 @@
+import type { EffortLevel, HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, McpSdkServerConfigWithInstance, McpServerConfig, Options, PermissionMode, SDKMessage, SDKUserMessage, SdkPluginConfig, SessionStore, SessionStoreFlush, SettingSource, SpawnOptions, SpawnedProcess, ThinkingConfig } from '@anthropic-ai/claude-agent-sdk';
+export type { HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, McpSdkServerConfigWithInstance, McpServerConfig, SDKMessage, SDKUserMessage, SdkPluginConfig, SessionStore, SessionStoreFlush, SettingSource, SpawnOptions, SpawnedProcess, ThinkingConfig, EffortLevel, PermissionMode, };
+/** Exactly the shape `Options.hooks` takes, so a composer above cannot drift from it. */
+export type HookRegistrations = Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+/**
+ * The message union's discriminator, as one string per shape — `type`, or `type/subtype` for the
+ * `system` family.
+ *
+ * Derived from the union rather than listed, so a message type the SDK adds shows up as a missing
+ * key wherever this is used exhaustively instead of being silently absent.
+ */
+type SystemSubtype = Extract<SDKMessage, {
+    type: 'system';
+}>['subtype'];
+export type MessageDiscriminator = Exclude<SDKMessage['type'], 'system'> | `system/${SystemSubtype}`;
+/** The discriminator of one message, in the same form `MessageDiscriminator` names. */
+export declare function discriminatorOf(message: SDKMessage): MessageDiscriminator;
+/** How the agent's process is created. Replaces the SDK's own local spawn when supplied. */
+export type SpawnAgentProcess = (options: SpawnOptions) => SpawnedProcess;
+/**
+ * What the layer above asks for. Deliberately NOT the SDK's `Options`: composing it is pure work
+ * that belongs outside this directory, and keeping the SDK's shape on this side of the seam is what
+ * lets the composition be unit-tested with no process anywhere near it.
+ */
+export interface AgentProcessRequest {
+    /** Absolute, always. The agent's working directory. */
+    readonly cwd: string;
+    /** The complete environment. Never merged with `process.env` — see sessions/spawn-env.ts. */
+    readonly env: Record<string, string>;
+    /**
+     * Which on-disk settings tiers the agent may load. `[]` means none.
+     *
+     * The SDK loads ALL of them when this is omitted, so it is passed explicitly on every start: a
+     * default that reads whatever files happen to be beside the working directory is not a default a
+     * host can reason about.
+     */
+    readonly settingSources: readonly SettingSource[];
+    readonly plugins: readonly SdkPluginConfig[] | null;
+    /**
+     * The hook callbacks this session runs. Passed straight through, never composed here.
+     *
+     * Each event maps to an ARRAY of matchers and the SDK runs every entry, so observation and
+     * decision are separate registrations on the same event rather than one handler doing both. See
+     * `hooks.ts` for the composer that merges them.
+     */
+    readonly hooks: HookRegistrations | null;
+    /** A session id to continue. Null starts a new one. */
+    readonly resume: string | null;
+    /** With `resume`, continue into a NEW session id instead of extending the old one. */
+    readonly fork: boolean;
+    /**
+     * Emit `stream_event` messages while the agent composes a turn.
+     *
+     * Nothing partial reaches the message stream without this: with it off there is no
+     * `SDKPartialAssistantMessage` at all, so text arrives only when a block completes and a turn
+     * cannot be rendered as it happens. It is also the precondition for any thinking prose.
+     */
+    readonly includePartialMessages: boolean;
+    /**
+     * How much of the agent's reasoning is emitted. `null` leaves the SDK's own default.
+     *
+     * `{type:'adaptive'}` fires `thinking_delta` events whose prose is EMPTY;
+     * `{type:'adaptive', display:'summarized'}` streams real reasoning text — which costs tokens on
+     * the wire and puts reasoning into transcripts and mirrors, so it is asked for rather than
+     * assumed. Requires `includePartialMessages`.
+     */
+    readonly thinking: ThinkingConfig | null;
+    /**
+     * Forward a subagent's full conversation, not only its tool calls.
+     *
+     * Off, the stream carries a subagent's `tool_use`/`tool_result` blocks and nothing else — enough
+     * to count activity, not enough to read. On, its text and thinking arrive as ordinary messages
+     * with `parent_tool_use_id` set, which is the only way a nested turn can be rendered live.
+     */
+    readonly forwardSubagentText: boolean;
+    /**
+     * The agent process's stderr, line by line.
+     *
+     * Wired on every start because some conditions are reported here and NOWHERE else — an untrusted
+     * workspace voids its permission rules with a stderr line and no error.
+     */
+    readonly onStderr: ((data: string) => void) | null;
+    /**
+     * In-process MCP servers this session may call, by server name.
+     *
+     * This key enlarges the set of tools the gate must decide about. It is safe for a structural
+     * reason, stated at `TOOL_SURFACE_OPTION_KEYS` below, and not for the reason the streaming keys
+     * are safe.
+     */
+    readonly mcpServers: Readonly<Record<string, McpServerConfig>> | null;
+    /**
+     * Use ONLY the servers above, ignoring project `.mcp.json`, user settings, plugin MCP and on-disk
+     * agent frontmatter. `null` leaves the SDK's own default.
+     *
+     * The composer above defaults this on (see sessions/registry.ts). It is the workspace-MCP
+     * attack-surface switch: without it, a repository the host provisioned as a workspace can declare
+     * its own MCP servers and the agent picks them up, which means a directory's CONTENTS decide what
+     * tools exist. That is the one lane where a workspace becomes a tool-registration channel.
+     */
+    readonly strictMcpConfig: boolean | null;
+    /**
+     * Mirror this session's transcript to a store the embedder supplies. `null` mirrors nowhere.
+     *
+     * This object receives every message the agent saw. It is a confidentiality and egress surface,
+     * and it must not be filed with the streaming keys, which only widen what this host itself
+     * observes.
+     *
+     * What makes it safe is structural, and it is the same shape as the gate's no-matcher argument:
+     * a store is a live object with methods, so it cannot be expressed in JSON and cannot cross the
+     * link. It can only be supplied by the code that composes this host, which is the embedder. No
+     * controller, and nothing arriving over the wire, can name a destination for a transcript. Pinned
+     * by pins/persistence-egress.test.ts rather than left as a sentence.
+     *
+     * The one documented incompatibility is unreachable by construction. A store may not be
+     * combined with session persistence turned off, because the mirror runs after the local write
+     * succeeds. `persistSession` is not composable through this type, so the SDK's own default stands
+     * and the combination cannot be built here.
+     */
+    readonly sessionStore: SessionStore | null;
+    /**
+     * How eagerly mirrored entries are flushed. `null` leaves the SDK's own default of batching.
+     *
+     * Eager gives near-real-time delivery at the cost of one call per frame with no coalescing, so it
+     * is asked for rather than assumed. Ignored entirely when no store is set.
+     */
+    readonly sessionStoreFlush: SessionStoreFlush | null;
+    /**
+     * Create the process yourself, for a VM, a container or a remote machine.
+     *
+     * Two things a custom spawn loses, and both are silent.
+     * 1. `windowsHide`. The SDK's own spawn passes it; Node's default is `false`, so a custom spawn
+     *    written without it allocates a real visible window per session wherever no ancestor process
+     *    owns a console. See this file's header.
+     * 2. stderr. `SpawnedProcess` carries only stdin and stdout, so a custom spawn that does not
+     *    route the child's stderr somewhere loses `onStderr` entirely, and the untrusted-workspace
+     *    condition is reported only there.
+     */
+    readonly spawn: SpawnAgentProcess | null;
+    /**
+     * Which model runs this session. `null` leaves the CLI's own default.
+     *
+     * Absent, not narrowed: `model` and `systemPrompt` were never among this type's keys, so adding
+     * them filled a gap; it did not widen a security narrowing. The eight `SHADOWING_LANES` below are
+     * a deliberate narrowing and they stay closed. Two different facts, and conflating them costs a
+     * reader a whole cycle on the wrong objection.
+     *
+     * What made the gap expensive: a host that cannot state a model cannot run the same agent twice on
+     * purpose, and every caller silently got whatever the installed CLI defaulted to.
+     */
+    readonly model: string | null;
+    /**
+     * What the agent is told at the start. `null` leaves the CLI's own preset.
+     *
+     * The one composable key that cannot be proven from the agent's own report. `AgentInitFacts`
+     * below is lifted entirely out of the SDK's `system/init` message, and that message carries no
+     * system prompt, so unlike `model`, `tools` or `mcpServers`, nothing coming back from the agent
+     * confirms this took effect. It ships unproven-by-report, and that is stated here rather than left
+     * for someone to discover while trying to write the assertion.
+     *
+     * Typed off the SDK's own option so it cannot drift from what `query()` accepts.
+     */
+    readonly systemPrompt: AgentSystemPrompt | null;
+    /** The effort level. `null` leaves the SDK's own default. */
+    readonly effort: EffortLevel | null;
+    /**
+     * The permission mode. `null` leaves the SDK's default. Deliberately opened: see
+     * `CLI_PARITY_OPTION_KEYS` for the reason stated as data, and `SHADOWING_LANES` for what stays
+     * closed. The gate's authority is the `PreToolUse` hook; a mode never pre-answers it.
+     */
+    readonly permissionMode: PermissionMode | null;
+}
+/**
+ * What the SDK accepts as a system prompt — a string, a list of strings, or a preset descriptor.
+ *
+ * Derived from `Options` rather than restated: this package's rule is that the types win, and a
+ * hand-copied union is a second copy that can disagree with the first.
+ */
+export type AgentSystemPrompt = NonNullable<Options['systemPrompt']>;
+/**
+ * Every key `Options` is composed from, as data.
+ *
+ * This is the permission-config pin's subject, and it is why that pin is a compile error rather
+ * than a grep. The SDK's `Options` carries nine lanes that alter permission outcomes:
+ * `permissionMode`, `settings`, `managedSettings`, `toolAliases`, `permissionPromptToolName`,
+ * `allowedTools`, `disallowedTools`, `canUseTool`, and the `permissions` block a settings object can
+ * carry. Eight of them (`SHADOWING_LANES`) are unreachable, because a caller can only supply the
+ * keys below and `startAgentProcess` composes `Options` from exactly these; `permissionMode` is the
+ * one opened by name, in `CLI_PARITY_OPTION_KEYS`. Adding a composable option breaks this
+ * declaration, and the pin fails at build time instead of when someone remembers to look.
+ *
+ * The composable set is declared as several lists, each with its own reason, because the moment two
+ * different justifications share one constant, neither can be checked:
+ *
+ * - `STREAMING_OPTION_KEYS` select what the process emits, never what it may do. A widening for
+ *   visibility is not a weakening for permission.
+ * - `TOOL_SURFACE_OPTION_KEYS` change which tools exist. Read that list's note for why it is
+ *   nonetheless safe.
+ * - `PERSISTENCE_OPTION_KEYS` decide where the transcript goes: the egress lane. Its safety
+ *   argument is structural and is pinned rather than stated.
+ * - `AGENT_SELECTION_OPTION_KEYS` choose which agent runs and what it is told at the start.
+ * - `CLI_PARITY_OPTION_KEYS` expose what the CLI itself exposes, including the one shadowing lane
+ *   that is a posture rather than a rule file.
+ *
+ * The distinction that decides whether a widening is a weakening: `model` and `systemPrompt` were
+ * absent, not narrowed. They were never among the composable keys, so opening them filled a gap.
+ * The eight lanes in `SHADOWING_LANES` are a deliberate security narrowing and stay closed, and the
+ * pin still asserts each one by name. A gap filled and a narrowing widened are different acts and
+ * this file tells them apart.
+ *
+ * `toolAliases` is the one worth naming: it redirects tool names after the model emits them, so a
+ * gate matching on `tool_name` would see the alias source while the target executed. A silent
+ * mismatch, and unreachable here by construction.
+ */
+export declare const AGENT_PROCESS_REQUEST_KEYS: {
+    readonly cwd: true;
+    readonly env: true;
+    readonly settingSources: true;
+    readonly plugins: true;
+    readonly hooks: true;
+    readonly resume: true;
+    readonly fork: true;
+    readonly onStderr: true;
+    readonly spawn: true;
+    readonly includePartialMessages: true;
+    readonly thinking: true;
+    readonly forwardSubagentText: true;
+    readonly mcpServers: true;
+    readonly strictMcpConfig: true;
+    readonly sessionStore: true;
+    readonly sessionStoreFlush: true;
+    readonly model: true;
+    readonly systemPrompt: true;
+    readonly effort: true;
+    readonly permissionMode: true;
+};
+/**
+ * The eight closed lanes, as data: the subject both permission pins are about.
+ *
+ * The defect this guards against: the lanes were once written out twice, once per pin, and the two
+ * copies disagreed. The scan pin listed `permissionPrompt`, which does not exist in `sdk.d.ts` at
+ * all, and omitted `permissions`, which does. So the "two mechanisms, one invariant" argument (a
+ * type cannot see a module that reaches past the composer, a scan cannot see a type) was being made
+ * by two lists guarding different sets, with the real option covered by only one of them.
+ *
+ * One declaration now, derived by both, and every name checked against the shipped types.
+ */
+export declare const SHADOWING_LANES: readonly string[];
+/**
+ * The keys that widened the composable set for visibility, kept as data so the reason is checkable
+ * rather than remembered.
+ *
+ * One reason covers all three: each selects what the process emits. None appears in any permission
+ * evaluation path, so none can change whether a tool runs, only how much of the run is visible.
+ * That is why widening the set here does not weaken the boundary above.
+ *
+ * The pin asserts every member is composable and is none of the eight shadowing lanes, so a later
+ * addition cannot join this list by assertion alone.
+ */
+export declare const STREAMING_OPTION_KEYS: readonly ["includePartialMessages", "thinking", "forwardSubagentText"];
+/**
+ * The keys that change which tools exist: a different class from the streaming three, kept
+ * separate so the two reasons cannot be confused for one.
+ *
+ * These are not data keys. `mcpServers` introduces tools, and `PreToolUse` fires for MCP tools and
+ * inside subagents (observed, not assumed). So this widening enlarges the surface the gate must
+ * cover, and the streaming keys' reason ("it only selects what is emitted") is false of it.
+ *
+ * Nor are they shadowing lanes. The closed lanes share one property: they can answer a permission
+ * before the gate does. These answer nothing. What makes them safe is structural: `permissionHooks`
+ * registers `PreToolUse` with no `matcher`, so a tool this host has never heard of reaches exactly
+ * the same handler as `Bash`. Coverage is by construction rather than by enumeration, which is why a
+ * tool set the host cannot predict is still a tool set the host decides about.
+ *
+ * If a `matcher` were ever introduced, this classification stops being true, and these two keys
+ * become the first way to add a tool nothing decides about. That sentence is the whole reason this
+ * list exists as data instead of as a decision somebody made once.
+ *
+ * `strictMcpConfig` belongs here because it acts on the same surface, but it moves the opposite
+ * way: it only ever removes servers the host did not declare. It is the safe direction of the same
+ * lane, and grouping them keeps that visible.
+ */
+export declare const TOOL_SURFACE_OPTION_KEYS: readonly ["mcpServers", "strictMcpConfig"];
+/**
+ * The keys that decide where a transcript goes: a third class again, and the reason is not the
+ * other two lists' reason.
+ *
+ * These are a confidentiality and egress surface. The streaming keys widen what this host observes
+ * about its own session. The tool-surface keys widen what the agent may do, and are covered because
+ * the gate has no matcher. These do neither: they hand a live object every message the agent saw,
+ * and a store is by definition somewhere else. Filing them under "it only selects what is emitted"
+ * would put a false sentence inside the constant whose entire job is to make the reason checkable.
+ *
+ * Nor are they shadowing lanes. The closed lanes share one property: they can answer a permission
+ * before the gate does. A store answers nothing and is never consulted about whether a tool runs.
+ *
+ * What makes them safe is that a destination cannot be named from off-box, and it is structural
+ * rather than enforced: `SessionStore` is an object with methods, so it has no JSON representation
+ * and cannot arrive over the link. The only code that can supply one is the code that composes this
+ * host. That is the same shape of argument as the gate's no-matcher coverage (a property of what
+ * the type is, not of a check somebody remembered to write) and it is pinned by
+ * pins/persistence-egress.test.ts.
+ *
+ * If a store ever becomes constructible from data (a URL, a connection string, a descriptor the
+ * host resolves into a client), this classification stops being true, and these become the first
+ * way a transcript can be sent somewhere the operator did not choose. That sentence is why this list
+ * is data instead of a decision somebody made once.
+ */
+export declare const PERSISTENCE_OPTION_KEYS: readonly ["sessionStore", "sessionStoreFlush"];
+/**
+ * The keys that choose which agent runs and what it is told at the start: a fourth class, and its
+ * reason is not any of the other three's.
+ *
+ * These were absent, not narrowed, and that is the whole classification. `model` and
+ * `systemPrompt` were simply not in this type, so nothing was ever protecting them; there was no
+ * decision to reverse, only a capability nobody had wired. The eight `SHADOWING_LANES` are the
+ * opposite case: each was considered and closed. Opening a gap and re-opening a closed lane look
+ * identical in a diff, and this list is how they stop looking identical.
+ *
+ * Neither appears in any permission evaluation path. They do not pre-answer a call, do not
+ * redirect a tool name, do not load a rule file and are never consulted about whether a tool runs,
+ * which is exactly the property the closed lanes share and these do not. What they change is which
+ * weights answer and what standing instructions those weights start with.
+ *
+ * The cost, because a widening with no stated cost is a widening nobody checked: a controller that
+ * can set a system prompt can give the agent standing instructions this host will never see the
+ * effect of, since the SDK's init message does not report one. The gate still decides every tool
+ * call, so the boundary is unmoved, but "the host can state what this agent was told" is not a
+ * property this package has; `AgentInitFacts` is where that can be verified.
+ *
+ * The pin asserts every member is composable and is none of the eight, exactly as the other lists
+ * do.
+ */
+export declare const AGENT_SELECTION_OPTION_KEYS: readonly ["model", "systemPrompt"];
+/**
+ * The CLI-parity keys, and the list that re-opens a closed lane on purpose. `effort` was absent (a
+ * gap, like `model`). `permissionMode` was once a shadowing lane, considered and closed, and it is
+ * opened here by name, with the reason:
+ *
+ *   a session through this host must expose what `claude` exposes, and bypass is a common default
+ *   for an operator. The gate never depended on the mode: `PreToolUse` fires under every mode, so
+ *   the boundary set is still held under `bypassPermissions`. What the mode changes is the CLI's
+ *   own prompt flow, which this host's gate already answers.
+ *
+ * The other eight stay closed: they are rule files and pre-answers, which is a different thing from a
+ * posture chosen in the open. Pinned by `pins/permission-config.test.ts`.
+ */
+export declare const CLI_PARITY_OPTION_KEYS: readonly ["effort", "permissionMode"];
+/** A started agent process, in this package's terms. */
+export interface AgentProcess {
+    /**
+     * Everything the agent emits, in order. One consumer.
+     *
+     * This is a narrowing wrapper, not the SDK's `Query`, and that is load-bearing. `query()`
+     * returns an object that IS an async generator AND carries `setPermissionMode`,
+     * `applyFlagSettings`, `setMcpServers` and `setMcpPermissionModeOverride` — four calls that change
+     * permission outcomes mid-session, after any construction-time check has run. Handing that object
+     * out under an `AsyncGenerator` annotation hides them from the compiler and from nobody else: one
+     * cast, or any plain JavaScript, reaches all four. So it is wrapped rather than annotated, and
+     * "the composed options cannot ship a shadowing setting" stays true without the words "unless you
+     * cast" attached to it.
+     *
+     * Where a mid-session control goes instead: a named method on this handle, beside `prompt`,
+     * `interrupt` and `close`. Never by widening this property back to the `Query`, and never by
+     * casting it; the point is that one file decides which of the SDK's controls this package
+     * offers.
+     */
+    readonly messages: AsyncGenerator<SDKMessage, void>;
+    /** Queue a turn. Returns false once the process is closed. */
+    prompt(text: string): boolean;
+    /** Stop the current turn in band, leaving the session alive. */
+    interrupt(): Promise<void>;
+    /**
+     * The named mid-session controls this package offers (the doc above says where they go): the
+     * three members of `session_configure`, each the SDK's own streaming-input setter behind a method.
+     * `setPermissionMode` is here deliberately: the one permission mutator that is a posture, reached
+     * only from the wire through `readSessionConfigure`; the other three stay unreachable.
+     */
+    setModel(model: string | null): Promise<void>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    setThinking(thinking: ThinkingConfig): Promise<void>;
+    /** End the process and release everything it holds. Idempotent. */
+    close(): void;
+}
+/**
+ * Facts the agent states about itself at start, lifted out of the SDK's init message.
+ *
+ * This is the per-spawn version receipt, and its shape is why it cannot rot: `cliVersion` arrives
+ * on the session's own stream, so there is no place to cache it even by accident. The CLI can
+ * auto-update underneath a long-running host, and a value read once at startup would then be a
+ * confident lie on every later session — which is the failure this receipt exists to catch.
+ *
+ * Absent is `null`, never an omitted property: this record is destined for the wire, where JSON has
+ * no `undefined` and an optional field makes "not reported" and "reported as unset" the same thing.
+ */
+export interface AgentInitFacts {
+    readonly sessionId: string;
+    readonly cliVersion: string;
+    readonly cwd: string;
+    readonly model: string;
+    readonly permissionMode: string;
+    /** Where the agent found its credentials. The evidence that ambient auth actually resolved. */
+    readonly apiKeySource: string;
+    readonly tools: readonly string[];
+    readonly skills: readonly string[];
+    readonly plugins: readonly AgentPluginFact[];
+    readonly capabilities: readonly string[];
+    /**
+     * The MCP servers this agent actually connected to, and what happened to each.
+     *
+     * The agent reports this on the init message. Without it, "did my server register?" is answered
+     * by inferring it from tool names, which cannot tell a server that failed to connect from one that
+     * connected and exposed no tools, and an HTTP or stdio server, unlike an in-process one, can fail
+     * to connect. With it, the answer is the agent's own word, per server, by name and status.
+     *
+     * The status string is carried verbatim and never interpreted here. It is the agent's vocabulary,
+     * not this package's, and mapping it onto this package's words would be a second translation
+     * site, the thing `state/observer.ts` exists to be the only one of.
+     */
+    readonly mcpServers: readonly AgentMcpServerFact[];
+}
+/** One MCP server as the agent reported it at start. `status` is the SDK's word, carried as-is. */
+export interface AgentMcpServerFact {
+    readonly name: string;
+    readonly status: string;
+}
+export interface AgentPluginFact {
+    readonly name: string;
+    readonly path: string;
+    readonly version: string | null;
+}
+/**
+ * The init message's facts, or null for every other message.
+ *
+ * Reading it here rather than above the seam keeps the SDK's message union on this side; the layer
+ * above branches on a plain record.
+ */
+export declare function readInitFacts(message: SDKMessage): AgentInitFacts | null;
+/**
+ * The message stream, and ONLY the message stream.
+ *
+ * `return` and `throw` are delegated, not just `next`. `for await…of` calls `iterator.return()`
+ * when the loop leaves early — a `break`, a `return`, or a throw inside the body — and that call is
+ * what lets the underlying query release the subprocess. A wrapper implementing only `next` would
+ * swallow it, leaking a session per abandoned loop with no error, no log and nothing null: exactly
+ * the silent-loss shape this package is built against. Pinned by agent-process.test.ts.
+ *
+ * Exported for that pin. It is not part of the package's public surface.
+ */
+export declare function messagesOf(source: AsyncGenerator<SDKMessage, void>): AsyncGenerator<SDKMessage, void>;
+/** Start an agent process. The subprocess exists when this returns. */
+export declare function startAgentProcess(request: AgentProcessRequest): AgentProcess;
+//# sourceMappingURL=agent-process.d.ts.map