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

package/dist/guard/command.js

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { CourierError } from '../errors.js';
+import { cmd } from '../program.js';
+import { profileDir } from '../profile.js';
+import { writeOut } from '../inbox.js';
+import { binaryName } from './binaries.js';
+import { brokerRoot } from '../broker-config.js';
+import { decide, hookOutput } from './hook.js';
+import { guardSettings, writeGuardSettings } from './install.js';
+import { installRoots, protectedSet, realpathBest } from './paths.js';
+const MAX_FILE = 1_000_000;
+const MAX_STDIN = 4_000_000;
+/** The whole decision, network included, must finish well inside the hook timeout (60 s) or the call is refused. */
+const DEADLINE_MS = 25_000;
+/** Where this install lives: what the hook refuses to let a command name or an edit tool write. */
+export function installLiterals(home, entry) {
+    return [realpathBest(home), ...installRoots(entry)].filter((p) => p.length >= 8);
+}
+export function realEnv(cwd, home = profileDir(), entry = process.argv[1] ?? '') {
+    const censusFile = path.join(home, 'guard/binaries.json');
+    let installed;
+    try {
+        installed = JSON.parse(fs.readFileSync(censusFile, 'utf8'));
+    }
+    catch {
+        throw new Error('invalid installed executable census');
+    }
+    if (!Array.isArray(installed) || installed.some(b => !b || typeof b.name !== 'string' || typeof b.path !== 'string' || !Number.isFinite(b.dev) || !Number.isFinite(b.ino)))
+        throw new Error('invalid installed executable census');
+    const searchPath = process.env.PATH ?? '';
+    return {
+        cwd,
+        binaries: installed,
+        resolveProgram: (word, dir) => binaryName(word, dir, searchPath, installed),
+        literals: [...installLiterals(home, entry), brokerRoot()],
+        protectedRoots: [home, brokerRoot(), path.join(os.homedir(), '.courier')],
+        realHome: process.env.COURIER_REAL_HOME || os.userInfo().homedir,
+        courierEntries: installed.filter(b => b.path === realpathBest(entry) && ['courier', 'tc'].includes(b.name)).map(b => b.path),
+        readFile(file) {
+            try {
+                const st = fs.statSync(file);
+                if (!st.isFile())
+                    return { state: 'absent' };
+                if (st.size > MAX_FILE)
+                    return { state: 'unreadable' };
+                return { state: 'text', text: fs.readFileSync(file, 'utf8') };
+            }
+            catch (error) {
+                const code = error?.code;
+                return code === 'ENOENT' || code === 'ENOTDIR' ? { state: 'absent' } : { state: 'unreadable' };
+            }
+        },
+        git(dir, args) {
+            const git = installed.find(b => b.name === 'git');
+            if (!git || binaryName(git.path, dir, searchPath, installed) !== 'git')
+                return { ok: false, out: '' };
+            const r = spawnSync(git.path, args, {
+                cwd: dir,
+                encoding: 'utf8',
+                timeout: 5000,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' },
+            });
+            return { ok: r.status === 0 && !r.error, out: typeof r.stdout === 'string' ? r.stdout : '' };
+        },
+        getenv: (name) => process.env[name],
+    };
+}
+function readStdin() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    let total = 0;
+    for (;;) {
+        let n = 0;
+        try {
+            n = fs.readSync(0, buf, 0, buf.length, null);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'EAGAIN')
+                continue;
+            if (code === 'EOF')
+                break;
+            throw error;
+        }
+        if (n === 0)
+            break;
+        total += n;
+        if (total > MAX_STDIN)
+            throw new Error('hook input too large');
+        chunks.push(Buffer.from(buf.subarray(0, n)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function refuse(message) {
+    // Exit 2 is the only non-zero status Claude Code treats as "block the tool call"; flush stderr first.
+    fs.writeSync(2, `${message}\n`);
+    process.exit(2);
+}
+export const guardUsage = () => `Usage: ${cmd('guard')}   (Claude Code PreToolUse hook: reads the tool call JSON on stdin)\n` +
+    `       ${cmd('guard settings [--out file] [--claude-settings file]')}   Print or write the Claude Code settings that install the hook`;
+/**
+ * `courier guard`: the Claude Code PreToolUse hook. Reads one tool call on stdin, prints a permission decision. Any
+ * failure refuses the call (exit 2). `courier guard settings` prints the settings that wire it in.
+ */
+export async function cmdGuard(args) {
+    if (args.positional[0] === 'settings')
+        return guardSettingsCommand(args);
+    if (args.positional.length)
+        throw new CourierError('usage', guardUsage());
+    try {
+        const input = JSON.parse(readStdin());
+        const home = profileDir();
+        const entry = process.argv[1] ?? '';
+        // The hook runs with the agent's environment: HOME is the agent's clean one, so the owner's real home comes from the settings.
+        const realHome = process.env.COURIER_REAL_HOME || os.homedir();
+        const deps = {
+            env: realEnv(process.cwd(), home, entry),
+            protectedSet: { ...protectedSet(home, entry, { agentHome: os.homedir() }), roots: [...protectedSet(home, entry).roots, brokerRoot(), path.join(os.homedir(), '.courier')], homes: [...new Set([realHome, os.homedir()])], realHome },
+        };
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), DEADLINE_MS).unref());
+        const decision = await Promise.race([decide(input, deps), timeout]);
+        await writeOut(hookOutput(decision));
+    }
+    catch (error) {
+        refuse(`Courier guard refused: ${String(error?.message ?? error).slice(0, 200)}`);
+    }
+}
+/** The command (`node <entry> [tc prefix] guard`) a hook should run, derived from how this process was started. */
+export function guardArgv(invocation = process.argv) {
+    const rest = invocation.slice(2);
+    const at = rest.indexOf('watch');
+    const gi = rest.indexOf('guard');
+    const prefix = rest.slice(0, at >= 0 ? at : gi >= 0 ? gi : rest.length > 0 && rest[0] === 'courier' ? 1 : 0);
+    return [process.execPath, invocation[1], ...prefix, 'guard'];
+}
+async function guardSettingsCommand(args) {
+    const home = profileDir();
+    const argv = guardArgv();
+    const entry = process.argv[1] ?? '';
+    const user = args.get('claude-settings');
+    if (user === 'true')
+        throw new CourierError('usage', '--claude-settings needs a file.');
+    const out = args.get('out');
+    if (out === 'true')
+        throw new CourierError('usage', '--out needs a file.');
+    if (out === undefined && user === undefined) {
+        await writeOut(`${JSON.stringify(guardSettings({ argv, home, entry }), null, 2)}\n`);
+        return;
+    }
+    const file = writeGuardSettings({ argv, home, entry, ...(user !== undefined ? { userSettings: user } : {}) });
+    if (out !== undefined)
+        fs.copyFileSync(file, path.resolve(out));
+    await writeOut(`${path.resolve(out ?? file)}\n`);
+}
+//# sourceMappingURL=command.js.map

package/dist/guard/command.js.map

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

package/dist/guard/expansion.d.ts

@@ -0,0 +1,10 @@
+import type { ParseResult } from './shell.js';
+/** Which gated tool or verb appears in `text`, if any. */
+export declare function gatedName(text: string): string | undefined;
+/** The expansion or indirection syntax in `text` (and, from the parse, in a command word), if any. */
+export declare function expansionSyntax(text: string, parsed?: ParseResult): string | undefined;
+/**
+ * The refusal for `text`, or undefined if the guard may read it word by word. The message names the rule, so an agent
+ * knows what to change: write the command out with plain words.
+ */
+export declare function expansionRefusal(text: string, parsed?: ParseResult): string | undefined;

package/dist/guard/expansion.js

@@ -0,0 +1,74 @@
+/**
+ * Commands containing runtime expansion or indirection and a gated tool/verb name refuse.
+ * Commands without that combination are inspected word by word by the policy.
+ */
+/** Syntax whose result is decided by the shell at run time, found in the raw text. */
+const SYNTAX = [
+    ['parameter, command or arithmetic expansion ($)', /\$/],
+    ['backticks', /`/],
+    ['brace expansion', /\{[^{}\n]*(,|\.\.)[^{}\n]*\}/],
+    ['eval, source, alias or a function definition', /(^|[\s;&|(])(eval|source|alias|unalias|coproc|function)(\s|$)|(^|[;&|(\n]\s*)\.\s+\S|(^|[\s;&|(])[A-Za-z_][\w-]*\s*\(\)\s*(\{|$)/],
+    ['a command prefix (env, command, builtin, exec, sudo, nohup, timeout, …)', /(^|[\s;&|(])(env|command|builtin|exec|sudo|doas|nohup|timeout|setsid|stdbuf|watch|nice|ionice|time|xargs|parallel|trap|script|su|runuser|flock|strace|ltrace|unbuffer|chronic|taskset|chrt|unshare|nsenter|chroot|busybox|toybox|systemd-run|xvfb-run|ssh|at|batch|entr|caffeinate)(\s|$)/i],
+    ['find -exec', /\s-(exec|execdir|ok|okdir)(\s|$)/],
+    ['env -S', /(^|[\s;&|(])env\s+(-\w*S|--split-string)/],
+    ['a here-document, here-string or process substitution', /<<|<\(|>\(/],
+    ['text piped into a shell', /\|\s*(sh|bash|dash|zsh|ksh|fish|source|\.|xargs|eval)(\s|$)/],
+    ['decoded text', /\b(base64|b64decode|xxd|openssl\s+enc)\b[^|;&]*(-d|--decode|-r)\b/],
+];
+const NAMES = [
+    'gh', 'npm', 'pnpm', 'yarn', 'bun', 'bunx', 'npx', 'changeset', 'wrangler', 'phala', 'tc', 'tinycloud', 'lerna',
+    'secret-bridge', 'secret_bridge', 'secretbridge', 'paseo', 'claude', 'codex', 'omp', 'opencode', 'gemini', 'cursor-agent', 'aider', 'goose', 'amp',
+];
+const VERBS = ['merge', 'publish', 'deploy', 'push', 'release', 'secrets', 'secret', 'pair', 'revoke'];
+/** `name` as a word of its own: not part of a longer identifier and not a `$NAME` variable. */
+const token = (names) => new RegExp(`(?<![A-Za-z0-9_$.-])(${names.map((n) => n.replace(/[-_]/g, '[-_]?')).join('|')})(?![A-Za-z0-9_-])`, 'i');
+const NAME_RE = token(NAMES);
+const VERB_RE = token(VERBS);
+const FETCH_RE = token(['curl', 'wget', 'http', 'https', 'xh', 'xhs', 'httpie', 'aria2c']);
+const GRAPHQL_RE = /mergePullRequest|enablePullRequestAutoMerge|updateRef|createCommitOnBranch|mergeBranch/i;
+const COURIER_HUMAN_RE = token(['courier']);
+const COURIER_SUB_RE = token(['pair', 'revoke', 'init', 'pause', 'resume', 'watch']);
+/** Quotes and backslashes removed, so `g""h`, `'g'h` and `\gh` read as the name they spell. */
+const unquoted = (text) => text.replace(/\$?['"]/g, '').replace(/\\\n/g, '').replace(/\\/g, '');
+/** Which gated tool or verb appears in `text`, if any. */
+export function gatedName(text) {
+    for (const t of [text, unquoted(text)]) {
+        const name = NAME_RE.exec(t)?.[1] ?? VERB_RE.exec(t)?.[1];
+        if (name)
+            return name.toLowerCase();
+        if (GRAPHQL_RE.test(t))
+            return 'a GitHub merge mutation';
+        if (FETCH_RE.test(t) && /github/i.test(t))
+            return 'a GitHub API call';
+        if (COURIER_HUMAN_RE.test(t) && COURIER_SUB_RE.test(t))
+            return 'courier pair|revoke|init|pause|resume|watch';
+    }
+    return undefined;
+}
+/** The expansion or indirection syntax in `text` (and, from the parse, in a command word), if any. */
+export function expansionSyntax(text, parsed) {
+    for (const t of [text, unquoted(text)])
+        for (const [label, re] of SYNTAX)
+            if (re.test(t))
+                return label;
+    // A glob, `~` or substitution in the command position does not show up as `$`: the parser knows it.
+    for (const cmd of parsed?.cmds ?? []) {
+        if (cmd.words[0]?.parts.some((part) => part.t === 'dyn'))
+            return 'a glob, tilde or substitution in the command word';
+    }
+    return undefined;
+}
+/**
+ * The refusal for `text`, or undefined if the guard may read it word by word. The message names the rule, so an agent
+ * knows what to change: write the command out with plain words.
+ */
+export function expansionRefusal(text, parsed) {
+    const syntax = expansionSyntax(text, parsed);
+    if (!syntax)
+        return undefined;
+    const name = gatedName(text);
+    if (!name)
+        return undefined;
+    return `expansion syntax with a gated tool name (${syntax}; "${name}"). The guard refuses a command that can be built at run time and mentions a gated tool; write it out with plain words`;
+}
+//# sourceMappingURL=expansion.js.map

package/dist/guard/expansion.js.map

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

package/dist/guard/hook.d.ts

@@ -0,0 +1,38 @@
+import { type ResolveHost } from './network.js';
+import { type PolicyEnv } from './policy.js';
+import { type ProtectedSet } from './paths.js';
+/**
+ * Claude Code `PreToolUse` decision for one tool call (spec §7). The hook never allows a gated action: it classifies and
+ * refuses. Merges run through `courier run-approved <requestId>` (the broker, `broker.ts`), which checks the owner's
+ * approval itself and runs a fixed command with the owner's credential outside the agent's environment. Two outcomes:
+ *  - `pass`: not a gated command; say nothing, so Claude's own permission rules decide as usual;
+ *  - `deny`: everything else, including every error.
+ * Only the tool call itself is read. Message text, task text and the owner's records never are, and the hook never opens the approval store. DNS destination checks fail closed; no approval is consumed here.
+ */
+export type Decision = {
+    kind: 'pass';
+} | {
+    kind: 'deny';
+    reason: string;
+};
+export interface GuardDeps {
+    env: PolicyEnv;
+    /** Real paths no tool call may write (courier home, install roots) and the homes whose tool configuration is protected. */
+    protectedSet: ProtectedSet;
+    /** MCP tool names (exact, or `mcp__server__*`) a woken agent may use. Default: none. */
+    mcpAllow?: readonly string[];
+    resolveHost?: ResolveHost;
+}
+/** The file-ish and command-ish strings of a tool call. */
+export declare function toolCommand(input: unknown): {
+    tool: string;
+    command?: string;
+    files: string[];
+    patterns: string[];
+    url?: string;
+} | undefined;
+export declare function decide(input: unknown, deps: GuardDeps): Promise<Decision>;
+/** The merge verb with a PR target is the one action the broker runs; everything else is for the owner to do. */
+export declare const isBrokered: (verb: string, target: string) => boolean;
+/** What Claude Code reads from the hook's stdout. `pass` writes nothing. */
+export declare function hookOutput(decision: Decision): string;

package/dist/guard/hook.js

@@ -0,0 +1,124 @@
+import { registeredFile } from './binaries.js';
+import { blockedDestination, dnsRefusal } from './network.js';
+import path from 'node:path';
+import { isRecord } from '../a2a.js';
+import { cmd } from '../program.js';
+import { analyze } from './policy.js';
+import { isCredentialFile, isProtectedFile, isProtectedRead } from './paths.js';
+const WRITE_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit']);
+const READ_TOOLS = new Set(['read', 'grep', 'glob', 'notebookread', 'ls', 'lsp']);
+const short = (text, n = 160) => text.replace(/\s+/g, ' ').slice(0, n);
+const deny = (reason) => ({ kind: 'deny', reason });
+/** The file-ish and command-ish strings of a tool call. */
+export function toolCommand(input) {
+    if (!isRecord(input) || typeof input.tool_name !== 'string')
+        return undefined;
+    const toolInput = isRecord(input.tool_input) ? input.tool_input : {};
+    const str = (key) => (typeof toolInput[key] === 'string' ? toolInput[key] : undefined);
+    const files = ['file_path', 'notebook_path', 'path'].map(str).filter((v) => v !== undefined);
+    const patterns = ['pattern', 'glob'].map(str).filter((v) => v !== undefined);
+    return { tool: input.tool_name, command: str('command'), files, patterns, ...(str('url') !== undefined ? { url: str('url') } : {}) };
+}
+function mcpAllowed(tool, allow) {
+    return allow.some((entry) => entry === tool || (entry.endsWith('*') && tool.startsWith(entry.slice(0, -1))));
+}
+export async function decide(input, deps) {
+    try {
+        const call = toolCommand(input);
+        if (!call)
+            return deny('Courier guard could not read this tool call; refusing.');
+        const cwd = isRecord(input) && typeof input.cwd === 'string' && path.isAbsolute(input.cwd) ? input.cwd : deps.env.cwd;
+        const tool = call.tool.toLowerCase();
+        if (tool.startsWith('mcp__')) {
+            return mcpAllowed(call.tool, deps.mcpAllow ?? [])
+                ? { kind: 'pass' }
+                : deny('MCP tools are not available to a woken agent (they run with their own credentials, outside the Courier guard).');
+        }
+        if (WRITE_TOOLS.has(tool)) {
+            if (call.files.length === 0)
+                return deny('Courier guard could not read the file path of this edit; refusing.');
+            for (const file of call.files) {
+                if (registeredFile(file, cwd, deps.env.binaries ?? []))
+                    return deny('Registered executable files cannot be edited by a woken agent.');
+                if (isProtectedFile(file, cwd, deps.protectedSet))
+                    return deny('That file belongs to the Courier guard, the Courier profile or the tool configuration (settings, hooks, MCP, git hooks) and cannot be edited from a woken agent.');
+                if (isCredentialFile(file, cwd))
+                    return deny('That file holds credentials and cannot be written from a woken agent.');
+            }
+            return { kind: 'pass' };
+        }
+        if (READ_TOOLS.has(tool)) {
+            for (const file of call.files.length ? call.files : [cwd])
+                if (isCredentialFile(file, cwd) || isProtectedRead(file, cwd, deps.protectedSet))
+                    return deny('That path holds credentials and cannot be read from a woken agent.');
+            for (const pattern of call.patterns)
+                if (isCredentialFile(pattern, cwd) || isProtectedRead(pattern, cwd, deps.protectedSet))
+                    return deny('That pattern reaches credential paths and cannot be used from a woken agent.');
+            return { kind: 'pass' };
+        }
+        if (tool === 'webfetch' || tool === 'websearch') {
+            if (call.url) {
+                try {
+                    new URL(call.url);
+                }
+                catch {
+                    return deny('Courier guard could not read that URL; refusing.');
+                }
+                if (blockedDestination(call.url) || await dnsRefusal(call.url, deps.resolveHost))
+                    return deny('Requests to this machine (loopback) are not available to a woken agent: local services such as the Paseo daemon can start agents outside the guard.');
+            }
+            return { kind: 'pass' };
+        }
+        if (tool === 'powershell')
+            return deny('PowerShell cannot be inspected by the Courier guard; use Bash.');
+        if (call.command === undefined) {
+            if (tool === 'bash')
+                return deny('Courier guard could not read the Bash command; refusing.');
+            return { kind: 'pass' };
+        }
+        const decision = decideCommand(call.command, { ...deps, env: { ...deps.env, cwd } });
+        if (decision.kind === 'deny')
+            return decision;
+        if (await dnsRefusal(call.command, deps.resolveHost))
+            return deny('Network destination resolves to this machine or cannot be verified; refusing.');
+        return decision;
+    }
+    catch (error) {
+        return deny(`Courier guard failed (${short(String(error?.message ?? error), 120)}); refusing.`);
+    }
+}
+/** The merge verb with a PR target is the one action the broker runs; everything else is for the owner to do. */
+export const isBrokered = (verb, target) => verb === 'merge' && /#\d+$/.test(target);
+function decideCommand(command, deps) {
+    const findings = analyze(command, deps.env);
+    const never = findings.filter((f) => f.kind === 'never');
+    if (never.length)
+        return deny(`Blocked: ${never[0].label}. This is not something an owner approval can unlock.`);
+    const unresolved = findings.filter((f) => f.kind === 'unresolved');
+    if (unresolved.length) {
+        return deny(`Blocked: ${unresolved[0].label}. The Courier guard cannot tell this command apart from a gated one (merge, deploy, publish, push to main, secrets). ` +
+            'Write the command out with plain words, one action per call.');
+    }
+    const gated = findings.filter((f) => f.kind === 'gated');
+    if (!gated.length)
+        return { kind: 'pass' };
+    const [g] = gated;
+    const more = gated.length > 1 ? ` (and ${gated.length - 1} more gated action${gated.length > 2 ? 's' : ''} in the same call)` : '';
+    const how = isBrokered(g.verb, g.target)
+        ? `Merging goes through the broker: ${cmd(`request <threadId> --peer <peer> --task <taskId> --verb ${g.verb} --target ${g.target} --summary "…"`)}, stop and wait for your owner's approval, then run exactly ${cmd('run-approved <requestId>')}.`
+        : `Agents do not run this action in v0: ask your owner with ${cmd(`request <threadId> --peer <peer> --task <taskId> --verb ${g.verb} --target ${g.target} --summary "…"`)}; your owner runs it.`;
+    return deny(`Blocked: ${g.verb} ${g.target}${more} is a gated action and a woken agent never runs it directly. ${how}`);
+}
+/** What Claude Code reads from the hook's stdout. `pass` writes nothing. */
+export function hookOutput(decision) {
+    if (decision.kind === 'pass')
+        return '';
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+        },
+    })}\n`;
+}
+//# sourceMappingURL=hook.js.map

package/dist/guard/hook.js.map

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

package/dist/guard/install.d.ts

@@ -0,0 +1,67 @@
+/** Where this OS user keeps credentials that a woken agent can read through the Read tool (and a shell) unless HOME differs. */
+export declare const CREDENTIAL_FILES: string[];
+/** The command Claude Code runs for the hook. `|| exit 2` turns any crash into a blocking error (exit 1 would fail open). */
+export declare function hookCommand(argv: string[], home: string, realHome?: string): string;
+/** Everything the guard keeps for a profile lives here; no tool call may write it. */
+export declare const guardDir: (home: string) => string;
+export declare const guardSettingsFile: (home: string) => string;
+/** `TC_HOME` for woken agents: an empty directory, so the owner's `tc` profile is not found. */
+export declare const profileId: (home: string) => string;
+export declare const agentHome: (home: string) => string;
+export declare const noOwnerProfileDir: (home: string) => string;
+/** Paths no tool call may write: the courier profile (keys, grant, state), the guard files, the hook program and what it imports. */
+export declare function protectedPaths(home: string, entry: string): string[];
+export interface GuardSettings {
+    hooks: {
+        PreToolUse: {
+            matcher: string;
+            hooks: {
+                type: 'command';
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+    };
+    permissions: {
+        deny: string[];
+    };
+    disableAllHooks: false;
+}
+export declare function guardSettings(options: {
+    argv: string[];
+    home: string;
+    entry: string;
+}): GuardSettings;
+/** The guard's own hook command, as {@link hookCommand} writes it. */
+export declare const GUARD_HOOK_RE: RegExp;
+/**
+ * `ours` merged over a user's settings: the guard's hook goes first, its deny rules are added, `disableAllHooks` is
+ * forced to false, and an older copy of the guard's hook in `theirs` is replaced, not duplicated.
+ */
+export declare function mergeGuardSettings(ours: GuardSettings, theirs: unknown): Record<string, unknown>;
+/**
+ * The settings the guard installs in a woken agent's project directory. The file is the guard's: only the guard's hook
+ * (as the one PreToolUse entry, with no other hook event) and the union of deny rules survive. Everything else in it
+ * (other hooks, `env`, `apiKeyHelper`, `statusLine`, MCP servers, allow rules) is replaced, because any of it can run a
+ * command or widen what the agent may do (B1).
+ */
+export declare function projectSettings(ours: GuardSettings, theirs: unknown): Record<string, unknown>;
+/**
+ * Write the guard settings for `home`. A settings file the owner passed with `--claude-settings` is merged in, with the
+ * guard's hook and deny rules added to (never replacing) whatever it holds. Returns the path to give `claude --settings`.
+ */
+export declare function writeGuardSettings(options: {
+    argv: string[];
+    home: string;
+    entry: string;
+    userSettings?: string;
+}): string;
+/** Private shell/config roots shared by the direct adapters and stock Paseo overrides. */
+export declare function agentHomeEnv(home: string): Record<string, string>;
+/**
+ * Environment for a woken agent: an allowlist (see {@link ALLOWED_ENV}) plus `extra` names the operator passed with
+ * `--env-pass`. The owner's `tc` profile is hidden by pointing `TC_HOME` at an empty directory.
+ */
+export declare function courierOnlyEnv(base: NodeJS.ProcessEnv, home: string, extra?: readonly string[]): NodeJS.ProcessEnv;
+/** Environment overrides for Paseo: blank credential names and set the clean agent HOME. */
+export declare function courierEnvOverrides(base: NodeJS.ProcessEnv, home: string, extra?: readonly string[]): Record<string, string>;