@tinycloud/courier 0.2.0-beta.37 → 0.2.0-beta.38

package/dist/guard/paseo.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Guard for agents the `paseo` wake adapter starts. Paseo cannot pass `claude --settings`, so the guard goes where
+ * Claude Code itself looks for it: `<cwd>/.claude/settings.local.json` (project-local, not meant to be committed).
+ * Claude runs its hooks in every permission mode, and project settings merge with the user's, so the hook holds in
+ * `default`, `bypassPermissions` and the rest. The adapter refuses to wake anything it cannot prove guarded.
+ */
+/** Label every guarded Paseo agent carries. An agent without it (created before the guard existed) is never messaged. */
+export declare const GUARD_LABEL = "courier-guard=1";
+/** Paseo env that would send a nested `paseo run` into the caller's own workspace instead of `--cwd`. */
+export declare const PASEO_CALLER_ENV: string[];
+export declare const projectSettingsFile: (cwd: string) => string;
+export interface ProjectGuard {
+    /** `node <entry> [tc prefix] guard` */
+    argv: string[];
+    entry: string;
+}
+/** Install (or refresh) the guard in `<cwd>/.claude/settings.local.json`, merged with whatever is already there. */
+export declare function installProjectGuard(cwd: string, home: string, guard: ProjectGuard): string;
+export declare function assertNoManagedOverride(files?: readonly string[]): void;
+/**
+ * Prove that `file` would block: it parses, hooks are not disabled, the PreToolUse `*` hook is the guard, and that exact
+ * command, run the way Claude runs it, refuses a call no approval can unlock (`courier pair`, which needs no network).
+ * Throws with the reason otherwise.
+ */
+export declare function verifyProjectGuard(file: string, cwd: string): void;
+/** Paseo env for a run: the caller's own agent and workspace must not redirect `--cwd`. */
+export declare function paseoEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** True if `provider` (`claude` or `claude/<model>`) is Claude Code, the only agent the project hook covers. */
+export declare const isClaudeProvider: (provider: string) => boolean;
+export declare function sameDir(a: string, b: string): boolean;

package/dist/guard/paseo.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isRecord } from '../a2a.js';
+import { installBinaryCensus } from './binaries.js';
+import { guardDir } from './install.js';
+import { GUARD_HOOK_RE, guardSettings, projectSettings } from './install.js';
+/**
+ * Guard for agents the `paseo` wake adapter starts. Paseo cannot pass `claude --settings`, so the guard goes where
+ * Claude Code itself looks for it: `<cwd>/.claude/settings.local.json` (project-local, not meant to be committed).
+ * Claude runs its hooks in every permission mode, and project settings merge with the user's, so the hook holds in
+ * `default`, `bypassPermissions` and the rest. The adapter refuses to wake anything it cannot prove guarded.
+ */
+/** Label every guarded Paseo agent carries. An agent without it (created before the guard existed) is never messaged. */
+export const GUARD_LABEL = 'courier-guard=1';
+/** Paseo env that would send a nested `paseo run` into the caller's own workspace instead of `--cwd`. */
+export const PASEO_CALLER_ENV = ['PASEO_AGENT_ID', 'PASEO_AGENT_CWD', 'PASEO_WORKSPACE_ID'];
+export const projectSettingsFile = (cwd) => path.join(cwd, '.claude', 'settings.local.json');
+/** Install (or refresh) the guard in `<cwd>/.claude/settings.local.json`, merged with whatever is already there. */
+export function installProjectGuard(cwd, home, guard) {
+    fs.mkdirSync(guardDir(home), { recursive: true, mode: 0o700 });
+    installBinaryCensus(path.join(guardDir(home), 'binaries.json'), guard.entry, guard.argv, cwd);
+    const file = projectSettingsFile(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let theirs;
+    let mode = 0o600;
+    try {
+        const raw = fs.readFileSync(file, 'utf8');
+        mode = fs.statSync(file).mode & 0o777;
+        theirs = raw.trim() ? JSON.parse(raw) : undefined;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`cannot merge the guard into ${file}: ${error.message}`);
+        }
+    }
+    if (theirs !== undefined && !isRecord(theirs))
+        throw new Error(`${file} is not a JSON object; refusing to overwrite it`);
+    const merged = projectSettings(guardSettings({ argv: guard.argv, home, entry: guard.entry }), theirs);
+    const next = `${JSON.stringify(merged, null, 2)}\n`;
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== next) {
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, next, { mode });
+        fs.renameSync(tmp, file);
+    }
+    return file;
+}
+/** Managed (policy) settings that switch hooks off or pin hooks to the managed set: the guard would not run. */
+const MANAGED_SETTINGS = ['/etc/claude-code/managed-settings.json', '/Library/Application Support/ClaudeCode/managed-settings.json'];
+export function assertNoManagedOverride(files = MANAGED_SETTINGS) {
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+                continue;
+            throw new Error(`cannot read managed settings ${file}: ${error.message}`);
+        }
+        let managed;
+        try {
+            managed = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`managed settings ${file} are not valid JSON; not waking an agent that may run without the guard`);
+        }
+        if (isRecord(managed) && (managed.disableAllHooks === true || managed.allowManagedHooksOnly === true)) {
+            throw new Error(`managed settings ${file} turn off project hooks (disableAllHooks or allowManagedHooksOnly); the guard would not run, so no agent is woken`);
+        }
+    }
+}
+/**
+ * Prove that `file` would block: it parses, hooks are not disabled, the PreToolUse `*` hook is the guard, and that exact
+ * command, run the way Claude runs it, refuses a call no approval can unlock (`courier pair`, which needs no network).
+ * Throws with the reason otherwise.
+ */
+export function verifyProjectGuard(file, cwd) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`guard settings ${file} are unreadable: ${error.message}`);
+    }
+    if (!isRecord(parsed) || parsed.disableAllHooks !== false)
+        throw new Error(`guard settings ${file} do not keep hooks enabled`);
+    // Nothing but the guard's own hook and deny rules (B1): any other hook event, `env`, `apiKeyHelper`, MCP server or allow rule can run a command.
+    const extraKeys = Object.keys(parsed).filter((key) => !['disableAllHooks', 'hooks', 'permissions'].includes(key));
+    if (extraKeys.length)
+        throw new Error(`guard settings ${file} carry other settings (${extraKeys.join(', ')}); only the guard's hook and deny rules are allowed`);
+    const hookEvents = isRecord(parsed.hooks) ? Object.keys(parsed.hooks) : [];
+    if (hookEvents.length !== 1 || hookEvents[0] !== 'PreToolUse')
+        throw new Error(`guard settings ${file} define other hook events (${hookEvents.join(', ')}); only the guard's PreToolUse hook is allowed`);
+    const permKeys = isRecord(parsed.permissions) ? Object.keys(parsed.permissions) : [];
+    if (permKeys.some((key) => key !== 'deny'))
+        throw new Error(`guard settings ${file} carry permission rules other than deny rules`);
+    assertNoManagedOverride();
+    const hooks = isRecord(parsed.hooks) && Array.isArray(parsed.hooks.PreToolUse) ? parsed.hooks.PreToolUse : [];
+    if (hooks.length !== 1)
+        throw new Error(`guard settings ${file} must hold exactly one PreToolUse entry (found ${hooks.length})`);
+    let command;
+    for (const entry of hooks) {
+        if (!isRecord(entry) || entry.matcher !== '*' || !Array.isArray(entry.hooks))
+            continue;
+        for (const hook of entry.hooks) {
+            if (isRecord(hook) && hook.type === 'command' && typeof hook.command === 'string' && GUARD_HOOK_RE.test(hook.command))
+                command = hook.command;
+        }
+    }
+    if (!command)
+        throw new Error(`guard settings ${file} have no courier guard hook`);
+    const probe = spawnSync('/bin/sh', ['-c', command], {
+        input: JSON.stringify({ tool_name: 'Bash', tool_input: { command: 'courier pair start probe' }, cwd }),
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    let denied = probe.status === 2;
+    if (probe.status === 0 && probe.stdout.trim()) {
+        try {
+            const out = JSON.parse(probe.stdout);
+            const decision = isRecord(out) && isRecord(out.hookSpecificOutput) ? out.hookSpecificOutput.permissionDecision : undefined;
+            denied = decision === 'deny';
+        }
+        catch { /* not JSON: not a denial */ }
+    }
+    if (!denied)
+        throw new Error('the guard hook did not refuse a probe command; not waking an agent without a working guard');
+}
+/** Paseo env for a run: the caller's own agent and workspace must not redirect `--cwd`. */
+export function paseoEnv(base) {
+    const env = { ...base };
+    for (const name of PASEO_CALLER_ENV)
+        delete env[name];
+    return env;
+}
+/** True if `provider` (`claude` or `claude/<model>`) is Claude Code, the only agent the project hook covers. */
+export const isClaudeProvider = (provider) => /^claude(\/|$)/.test(provider);
+export function sameDir(a, b) {
+    const real = (p) => { try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    } };
+    return real(a) === real(b);
+}
+//# sourceMappingURL=paseo.js.map

package/dist/guard/paseo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paseo.js","sourceRoot":"","sources":["../../src/guard/paseo.ts"],"names":[],"mappings":"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"}

package/dist/guard/paths.d.ts

@@ -0,0 +1,31 @@
+/** Quotes and backslashes removed, so `.n"p"mrc` and `.n\pmrc` read as the name they spell. */
+export declare const unquoted: (text: string) => string;
+export declare function credentialTextRefusal(text: string): string | undefined;
+/** `literals`: absolute paths of this install (courier home, guard dir, package roots) that a command must not name. */
+export declare function protectedTextRefusal(text: string, literals?: readonly string[]): string | undefined;
+/** The real path of `file`, even when it does not exist yet: the nearest existing ancestor is resolved, the rest appended. */
+export declare function realpathBest(file: string): string;
+export interface ProtectedSet {
+    /** Absolute paths (courier home, guard install dir, node_modules chain, package roots): nothing under them may be written. */
+    roots: string[];
+    /** Home directories whose tool configuration may not be written. */
+    homes: string[];
+    realHome?: string;
+}
+/** True if `file` (relative to `cwd`) may not be written by a woken agent. Compares real paths. */
+export declare function isProtectedFile(file: string, cwd: string, set: ProtectedSet): boolean;
+/** True if a file tool (Read, Grep, Glob, Edit, …) names a credential path. */
+export declare function isCredentialFile(file: string, cwd: string): boolean;
+/**
+ * Directories to protect for this install: the entry's directory, its package root (the first `package.json` above it)
+ * and every `node_modules` directory the hook's imports can resolve to (the ones above the entry). Not the repository
+ * around them: a developer's checkout stays editable.
+ */
+export declare function installRoots(entry: string): string[];
+export declare function protectedSet(home: string, entry: string, extra?: {
+    agentHome?: string;
+}): ProtectedSet;
+/** Reads/searches must not descend into protected state or enumerate an ancestor that contains it. */
+export declare function isProtectedRead(file: string, cwd: string, set: ProtectedSet): boolean;
+/** Check literal shell paths by realpath, including symlinks and broad ancestor searches. */
+export declare function pathTextRefusal(text: string, cwd: string, home: string, roots: readonly string[], realHome?: string): string | undefined;

package/dist/guard/paths.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Paths and words a woken agent has no business with (R2, B1, B2). Three layers use this module:
+ *  - `credentialTextRefusal` / `protectedTextRefusal`: substring checks on the raw command text (quotes and backslashes
+ *    removed first), so `cat ~/.n"p"mrc` and a glob into `.config` are refused. A shell can still build a path
+ *    out of pieces; the inverted expansion rule and the clean HOME cover that, and the README says what is left.
+ *  - `isProtectedFile`: the file tools (Edit, Write, Read, …), compared on real paths so a symlink does not hide a target.
+ */
+/** Where credentials live. A command that names one is refused, whether it reads or writes. */
+const CREDENTIAL_SUBSTRINGS = [
+    '.config/gh', '.config/gcloud', '.config/wrangler', '.config/.wrangler', '.wrangler', '.npmrc', '.netrc', '.ssh', '.aws', '.docker/config',
+    '.git-credentials', '.claude/.credentials', '.claude.json', '.paseo', '.tinycloud', 'hosts.yml', '.courier/broker', 'broker/gh.json',
+    'application_default_credentials', '.kube/config', '.gnupg', '.password-store', '.local/share/keyrings',
+];
+/** Config and hook files that decide what runs next: writing them could switch the guard off or add a command. */
+const PROTECTED_SUBSTRINGS = [
+    '.courier-agent.json', '.claude/settings', 'settings.local.json', '.claude/hooks', '.claude/commands', '.claude/agents', '.mcp.json', '.git/hooks', '.git/config', 'guard/settings.json',
+    '.config/git', '.gitconfig', '.git-hooks',
+];
+const CREDENTIAL_PATTERNS = [
+    ['owner shell startup files', /(?:^|[\s/])\.(?:bashrc|bash_profile|bash_login|profile|zshenv|zshrc|zprofile)(?:[\s/]|$)/i],
+    ['a glob in a process environment path', /\/proc\/[^\s]*[*?[]/i],
+    ['a glob hiding a credential directory', /(?:^|[\s/])[^\s/]*[*?[][^\s/]*(?:config|tinycloud|courier)[^\s/]*\//i],
+    ['a glob hiding gh hosts', /(?:^|[\s/])host[^\s/]*[*?[][^\s/]*\.ya?ml/i],
+    ['an embedded privilege command', /['"(;]\s*(?:sudo|doas|pkexec|runuser)\s/i],
+    ['process environments (/proc/*/environ)', /\/proc\b[^\n]*environ/i],
+    ['a glob in a dot-directory under .config', /\.config\/[^\s/]*[*?[]/],
+    ['a glob in a dot-file name', /(^|[\s/=:])\.[A-Za-z_-]+[*?[]/],
+    ['a credential-printing command (gh auth, gh config)', /(^|[\s/;&|(`])gh\s+(auth|config|extension)(\s|$)/],
+    ['a credential-printing command (git credential)', /(^|[\s/;&|(`])git\s+([^\s]+\s+)*credential(\s|$|-)/],
+    ['a credential-printing command (npm/yarn/pnpm config)', /(^|[\s/;&|(`])(npm|yarn|pnpm|bun)\s+config(\s|$)/],
+    ['a keyring or secret-store command', /(^|[\s/;&|(`])(secret-tool|keyctl|gnome-keyring-daemon|pass|gpg|gpg2|ssh-add|ssh-agent|security\s+(find|dump|export)[-\w]*)(\s|$)/],
+];
+/** Quotes and backslashes removed, so `.n"p"mrc` and `.n\pmrc` read as the name they spell. */
+export const unquoted = (text) => text.replace(/\$?['"]/g, '').replace(/\\\n/g, '').replace(/\\/g, '');
+const variants = (text) => [text, unquoted(text)];
+export function credentialTextRefusal(text) {
+    for (const t of variants(text)) {
+        const lower = t.toLowerCase();
+        for (const s of CREDENTIAL_SUBSTRINGS)
+            if (lower.includes(s))
+                return `it names a credential path (${s})`;
+        for (const [label, re] of CREDENTIAL_PATTERNS)
+            if (re.test(t))
+                return `it uses ${label}`;
+    }
+    return undefined;
+}
+/** `literals`: absolute paths of this install (courier home, guard dir, package roots) that a command must not name. */
+export function protectedTextRefusal(text, literals = []) {
+    for (const t of variants(text)) {
+        for (const s of PROTECTED_SUBSTRINGS)
+            if (t.includes(s))
+                return `it names a guard or tool configuration file (${s})`;
+        for (const literal of literals)
+            if (literal && t.includes(literal))
+                return `it names the Courier install or profile directory (${literal})`;
+    }
+    return undefined;
+}
+// ---------- file tools ----------
+/** The real path of `file`, even when it does not exist yet: the nearest existing ancestor is resolved, the rest appended. */
+export function realpathBest(file) {
+    const abs = path.resolve(file);
+    let probe = abs;
+    const tail = [];
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(probe), ...tail.reverse());
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                return abs;
+            tail.push(path.basename(probe));
+            probe = parent;
+        }
+    }
+}
+const within = (file, root) => file === root || file.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+/** Every directory from `from` up to the filesystem root. */
+function ancestors(from) {
+    const out = [];
+    for (let dir = path.resolve(from);; dir = path.dirname(dir)) {
+        out.push(dir);
+        if (path.dirname(dir) === dir)
+            return out;
+    }
+}
+/** Names that must not be written in any directory above the agent's cwd. */
+const PER_DIRECTORY = ['.claude/settings.json', '.claude/settings.local.json', '.claude/hooks', '.claude/commands', '.claude/agents', '.mcp.json', '.git/hooks', '.git/config', '.gitmodules'];
+/** Names under a home directory (the real one and the agent's clean one). */
+const PER_HOME = ['.courier-agent.json', '.claude/settings.json', '.claude/settings.local.json', '.claude/hooks', '.claude/commands', '.claude/agents', '.claude.json', '.gitconfig', '.config/git', '.bashrc', '.bash_profile', '.profile', '.zshenv', '.zshrc', '.zprofile', '.npmrc'];
+/** True if `file` (relative to `cwd`) may not be written by a woken agent. Compares real paths. */
+export function isProtectedFile(file, cwd, set) {
+    const home = set.homes[set.homes.length - 1] ?? process.env.HOME ?? '';
+    const expanded = file.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home);
+    const real = realpathBest(path.resolve(cwd, expanded));
+    for (const root of set.roots)
+        if (within(real, realpathBest(root)))
+            return true;
+    for (const dir of ancestors(cwd))
+        for (const rel of PER_DIRECTORY)
+            if (within(real, realpathBest(path.join(dir, rel))))
+                return true;
+    for (const home of set.homes)
+        for (const rel of PER_HOME)
+            if (within(real, realpathBest(path.join(home, rel))))
+                return true;
+    return false;
+}
+/** True if a file tool (Read, Grep, Glob, Edit, …) names a credential path. */
+export function isCredentialFile(file, cwd) {
+    const abs = path.resolve(cwd, file);
+    return credentialTextRefusal(abs) !== undefined || credentialTextRefusal(realpathBest(abs)) !== undefined;
+}
+/**
+ * Directories to protect for this install: the entry's directory, its package root (the first `package.json` above it)
+ * and every `node_modules` directory the hook's imports can resolve to (the ones above the entry). Not the repository
+ * around them: a developer's checkout stays editable.
+ */
+export function installRoots(entry) {
+    const real = realpathBest(entry);
+    const roots = new Set([path.dirname(real)]);
+    let sawPackage = false;
+    for (const dir of ancestors(path.dirname(real))) {
+        if (!sawPackage && fs.existsSync(path.join(dir, 'package.json'))) {
+            roots.add(dir);
+            sawPackage = true;
+        }
+        if (path.basename(dir) === 'node_modules')
+            roots.add(dir);
+        if (fs.existsSync(path.join(dir, 'node_modules')))
+            roots.add(path.join(dir, 'node_modules'));
+    }
+    roots.delete(path.parse(real).root);
+    return [...roots];
+}
+export function protectedSet(home, entry, extra = {}) {
+    return {
+        roots: [path.resolve(home), ...installRoots(entry)],
+        homes: [...new Set([os.homedir(), ...(extra.agentHome ? [extra.agentHome] : [])])],
+    };
+}
+/** Reads/searches must not descend into protected state or enumerate an ancestor that contains it. */
+export function isProtectedRead(file, cwd, set) {
+    const home = set.homes[set.homes.length - 1] ?? process.env.HOME ?? '';
+    const expanded = file.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home);
+    const real = realpathBest(path.resolve(cwd, expanded));
+    for (const root of set.roots) {
+        const r = realpathBest(root);
+        if (within(real, r) || within(r, real))
+            return true;
+    }
+    const owner = set.realHome ?? set.homes[0];
+    if (owner && within(real, realpathBest(owner)) && !within(real, realpathBest(cwd)))
+        return true;
+    return false;
+}
+/** Check literal shell paths by realpath, including symlinks and broad ancestor searches. */
+export function pathTextRefusal(text, cwd, home, roots, realHome) {
+    const flat = unquoted(text);
+    if (/\bCOURIER_(HOME|REAL_HOME|BROKER\w*)\b/.test(flat) || /(?:~|\$\{?HOME\}?)\/\.\.(?:\/|\s|$)/.test(flat))
+        return 'broker/profile environment or home traversal';
+    for (let word of flat.split(/[\s;&|<>]+/)) {
+        if (!word || word.startsWith('-') || word.includes('://'))
+            continue;
+        word = word.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home);
+        if (!word.includes('/') && word !== '.' && word !== '..')
+            continue;
+        const prefix = word.split(/[*?[]/, 1)[0];
+        const file = prefix || '.';
+        if (isProtectedRead(file, cwd, { roots: [...roots], homes: realHome ? [realHome] : [], realHome }))
+            return 'a protected root or its parent';
+    }
+    return undefined;
+}
+//# sourceMappingURL=paths.js.map

package/dist/guard/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/guard/paths.ts"],"names":[],"mappings":"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"}

package/dist/guard/policy.d.ts

@@ -0,0 +1,65 @@
+import { type BinaryIdentity } from './binaries.js';
+import type { Verb } from './target.js';
+/**
+ * Which shell commands a woken agent may not run on its own (spec §7), found by reading the command the way a shell
+ * would. It reads quoting, wrappers, chains, subshells and nested `sh -c`/`eval`, and it
+ * treats everything it cannot read exactly as a reason to refuse, never as a reason to allow.
+ */
+export interface Word {
+    value: string;
+    dynamic: boolean;
+}
+export type Finding = 
+/** A gated command with a fully literal argv; `key` identifies it for approval matching. */
+{
+    kind: 'gated';
+    label: string;
+    verb: Verb;
+    target: string;
+    key: string;
+    display: string;
+}
+/** Never allowed in a guarded session, with or without approval. */
+ | {
+    kind: 'never';
+    label: string;
+}
+/** Could be a gated command and cannot be told apart or approved (dynamic words, loops, scripts, pipes). */
+ | {
+    kind: 'unresolved';
+    label: string;
+};
+export type FileRead = {
+    state: 'absent';
+} | {
+    state: 'unreadable';
+} | {
+    state: 'text';
+    text: string;
+};
+export interface PolicyEnv {
+    /** Working directory the tool call starts in. */
+    cwd: string;
+    readFile(file: string): FileRead;
+    /** Run `git <args>` in `dir`; ok=false on any failure. */
+    git(dir: string, args: string[]): {
+        ok: boolean;
+        out: string;
+    };
+    /** Environment variable of the guard process (the woken agent's environment). */
+    getenv(name: string): string | undefined;
+    /** Absolute paths of this install and profile (courier home, guard dir, package roots) that a command must not name. */
+    literals?: string[];
+    binaries?: BinaryIdentity[];
+    /** Returns a canonical tool name only for a census-verified executable identity (mocked by offline grammar tests). */
+    resolveProgram?(word: string, cwd: string): string | undefined;
+    protectedRoots?: string[];
+    realHome?: string;
+    /** Real paths of the courier entry points (`cli.js`, the `tc` entry): `node <entry> pair …` is a courier command. */
+    courierEntries?: string[];
+}
+/** The exec opt-out never starts a second agent CLI. */
+export declare function startsAgentCli(command: string): boolean;
+export declare function progName(value: string): string;
+/** Resolve a command string into findings. */
+export declare function analyze(command: string, env: PolicyEnv): Finding[];