@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/adapters/codex.d.ts

@@ -0,0 +1,74 @@
+import type { SandboxMode, ThreadOptions, Usage } from '@openai/codex-sdk';
+import type { Perm } from '../perm.js';
+import type { AdapterResult, AdapterRunOptions, RuntimeAdapter } from './types.js';
+/** USD per 1M tokens. Configurable via ACH_CODEX_PRICE='{"input":..,"cached_input":..,"output":..}'. */
+export interface PriceTable {
+    input: number;
+    cached_input: number;
+    output: number;
+}
+export declare const DEFAULT_CODEX_PRICE: PriceTable;
+export declare function priceFromEnv(env?: Record<string, string | undefined>): PriceTable;
+export declare function estimateCost(u: Partial<Usage>, p: PriceTable): number;
+export declare function codexSandbox(perm: Perm): SandboxMode;
+/**
+ * Thread options (§14.3 as amended by round 1). Pure, unit-tested.
+ * - Answer runs: read-only sandbox, network off. The agent returns JSON
+ *   (outputSchema) and the runner posts it, so it never needs the hub (S4).
+ * - Work runs keep network on for `ach`.
+ * - No additionalDirectories: the main repo's .git is never writable (S10);
+ *   the runner commits after the run.
+ */
+export declare function codexThreadOptions(perm: Perm, cwd: string, model?: string, mode?: 'work' | 'answer' | 'mention'): ThreadOptions;
+/** Codex `--config` overrides set by the runner (key names checked against the bundled codex 0.165 binary). */
+export type CodexRunnerConfig = {
+    allow_login_shell: boolean;
+    sandbox_workspace_write: {
+        exclude_slash_tmp: boolean;
+        exclude_tmpdir_env_var: boolean;
+    };
+};
+/**
+ * Codex client options.
+ * - allow_login_shell=false: by default Codex runs tool commands in a login
+ *   shell, whose profile (path_helper, `brew shellenv`) reorders PATH, so a
+ *   globally installed `ach` (another program's) shadowed the runner's
+ *   <home>/bin/ach shim and every `ach complete` failed (live test).
+ * - sandbox_workspace_write.exclude_slash_tmp / exclude_tmpdir_env_var = true:
+ *   in workspace-write, Codex by default also lets the agent write /tmp and
+ *   $TMPDIR, which other processes of the user read (live test). Writes are now
+ *   the working directory only.
+ */
+export declare function codexClientOptions(env: Record<string, string | undefined>): {
+    env: Record<string, string>;
+    config: CodexRunnerConfig;
+};
+/** `root` and all its descendants, from `ps -axo pid=,ppid=,command=` output. Pure. */
+export declare function processTree(psOut: string, root: number): number[];
+/** Pids of `codex exec ... --cd <cwd>` processes that are children of `parent`. Pure. */
+export declare function codexChildren(psOut: string, parent: number, cwd: string): number[];
+/**
+ * C7: @openai/codex-sdk 0.165.0 spawns `codex exec` itself (no new process
+ * group, pid not exposed) and on abort SIGTERMs only that process. Codex runs
+ * each tool command in its own process group, so those survived a cancel
+ * (live test: `sleep 300 && echo done > done.txt` kept running, re-parented to
+ * init). On abort we find this run's codex child by its `--cd`, then SIGTERM
+ * every descendant and its process group, and SIGKILL survivors after a grace.
+ */
+export declare function killCodexTree(cwd: string, o?: {
+    parent?: number;
+    ps?: () => string;
+    kill?: (pid: number, sig: NodeJS.Signals) => void;
+    graceMs?: number;
+}): number[];
+/** Codex runtime adapter (@openai/codex-sdk). Cancel: see killCodexTree. */
+export declare class CodexAdapter implements RuntimeAdapter {
+    private o;
+    readonly name = "codex";
+    readonly structuredAnswers = true;
+    constructor(o?: {
+        model?: string;
+        price?: PriceTable;
+    });
+    run(opts: AdapterRunOptions): Promise<AdapterResult>;
+}

package/dist/src/adapters/codex.js

@@ -0,0 +1,237 @@
+import { execFileSync } from 'node:child_process';
+import { KILL_GRACE_MS } from './procgroup.js';
+export const DEFAULT_CODEX_PRICE = { input: 1.25, cached_input: 0.125, output: 10 };
+export function priceFromEnv(env = process.env) {
+    try {
+        if (env.ACH_CODEX_PRICE)
+            return { ...DEFAULT_CODEX_PRICE, ...JSON.parse(env.ACH_CODEX_PRICE) };
+    }
+    catch {
+        /* fall through */
+    }
+    return DEFAULT_CODEX_PRICE;
+}
+export function estimateCost(u, p) {
+    const cached = u.cached_input_tokens ?? 0;
+    const input = Math.max(0, (u.input_tokens ?? 0) - cached);
+    const output = (u.output_tokens ?? 0) + (u.reasoning_output_tokens ?? 0);
+    return (input * p.input + cached * p.cached_input + output * p.output) / 1_000_000;
+}
+export function codexSandbox(perm) {
+    return perm === 'read' ? 'read-only' : perm === 'workdir' ? 'workspace-write' : 'danger-full-access';
+}
+/**
+ * Thread options (§14.3 as amended by round 1). Pure, unit-tested.
+ * - Answer runs: read-only sandbox, network off. The agent returns JSON
+ *   (outputSchema) and the runner posts it, so it never needs the hub (S4).
+ * - Work runs keep network on for `ach`.
+ * - No additionalDirectories: the main repo's .git is never writable (S10);
+ *   the runner commits after the run.
+ */
+export function codexThreadOptions(perm, cwd, model, mode = 'work') {
+    // answer and mention runs are read-only and offline; the runner posts their JSON
+    const answer = mode === 'answer' || mode === 'mention';
+    return {
+        workingDirectory: cwd,
+        sandboxMode: answer ? 'read-only' : codexSandbox(perm),
+        networkAccessEnabled: !answer,
+        approvalPolicy: 'never',
+        skipGitRepoCheck: true,
+        ...(model ? { model } : {}),
+    };
+}
+/**
+ * Codex client options.
+ * - allow_login_shell=false: by default Codex runs tool commands in a login
+ *   shell, whose profile (path_helper, `brew shellenv`) reorders PATH, so a
+ *   globally installed `ach` (another program's) shadowed the runner's
+ *   <home>/bin/ach shim and every `ach complete` failed (live test).
+ * - sandbox_workspace_write.exclude_slash_tmp / exclude_tmpdir_env_var = true:
+ *   in workspace-write, Codex by default also lets the agent write /tmp and
+ *   $TMPDIR, which other processes of the user read (live test). Writes are now
+ *   the working directory only.
+ */
+export function codexClientOptions(env) {
+    const clean = {};
+    for (const [k, v] of Object.entries(env))
+        if (typeof v === 'string')
+            clean[k] = v;
+    return {
+        env: clean,
+        config: {
+            allow_login_shell: false,
+            sandbox_workspace_write: { exclude_slash_tmp: true, exclude_tmpdir_env_var: true },
+        },
+    };
+}
+/** `root` and all its descendants, from `ps -axo pid=,ppid=,command=` output. Pure. */
+export function processTree(psOut, root) {
+    const kids = new Map();
+    for (const line of psOut.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)/);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (!kids.has(ppid))
+            kids.set(ppid, []);
+        kids.get(ppid).push(pid);
+    }
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const p = stack.pop();
+        out.push(p);
+        for (const c of kids.get(p) ?? [])
+            if (!out.includes(c))
+                stack.push(c);
+    }
+    return out;
+}
+/** Pids of `codex exec ... --cd <cwd>` processes that are children of `parent`. Pure. */
+export function codexChildren(psOut, parent, cwd) {
+    const res = [];
+    for (const line of psOut.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m || Number(m[2]) !== parent)
+            continue;
+        const cmd = m[3];
+        if (/codex/.test(cmd) && / exec /.test(cmd) && (cmd.includes(`--cd ${cwd} `) || cmd.endsWith(`--cd ${cwd}`)))
+            res.push(Number(m[1]));
+    }
+    return res;
+}
+/**
+ * C7: @openai/codex-sdk 0.165.0 spawns `codex exec` itself (no new process
+ * group, pid not exposed) and on abort SIGTERMs only that process. Codex runs
+ * each tool command in its own process group, so those survived a cancel
+ * (live test: `sleep 300 && echo done > done.txt` kept running, re-parented to
+ * init). On abort we find this run's codex child by its `--cd`, then SIGTERM
+ * every descendant and its process group, and SIGKILL survivors after a grace.
+ */
+export function killCodexTree(cwd, o = {}) {
+    if (process.platform === 'win32' && !o.ps)
+        return [];
+    const ps = o.ps ?? (() => execFileSync('ps', ['-axo', 'pid=,ppid=,command='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+    const kill = o.kill ?? ((pid, sig) => process.kill(pid, sig));
+    let out;
+    try {
+        out = ps();
+    }
+    catch {
+        return [];
+    }
+    const pids = codexChildren(out, o.parent ?? process.pid, cwd).flatMap((c) => processTree(out, c));
+    const send = (sig) => {
+        for (const pid of pids) {
+            for (const target of [-pid, pid]) {
+                try {
+                    kill(target, sig);
+                }
+                catch {
+                    /* not a group leader, or already gone */
+                }
+            }
+        }
+    };
+    send('SIGTERM');
+    if (pids.length)
+        setTimeout(() => send('SIGKILL'), o.graceMs ?? KILL_GRACE_MS).unref();
+    return pids;
+}
+/** Codex runtime adapter (@openai/codex-sdk). Cancel: see killCodexTree. */
+export class CodexAdapter {
+    o;
+    name = 'codex';
+    structuredAnswers = true;
+    constructor(o = {}) {
+        this.o = o;
+    }
+    async run(opts) {
+        const { Codex } = await import('@openai/codex-sdk');
+        const codex = new Codex(codexClientOptions(opts.env));
+        const to = codexThreadOptions(opts.perm, opts.cwd, this.o.model, opts.mode);
+        const thread = opts.resume ? codex.resumeThread(opts.resume, to) : codex.startThread(to);
+        const price = this.o.price ?? priceFromEnv(opts.env);
+        let sessionId = opts.resume;
+        if (sessionId)
+            opts.onEvent({ type: 'session', data: sessionId });
+        let finalText = '';
+        let cost = 0;
+        let sawUsage = false;
+        let error;
+        // registered before the SDK spawns codex, so it runs before the SDK's own kill
+        const onAbort = () => killCodexTree(opts.cwd);
+        opts.signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            const { events } = await thread.runStreamed(opts.prompt, {
+                signal: opts.signal,
+                ...(opts.outputSchema ? { outputSchema: opts.outputSchema } : {}),
+            });
+            for await (const ev of events) {
+                switch (ev.type) {
+                    case 'thread.started':
+                        if (ev.thread_id !== sessionId) {
+                            sessionId = ev.thread_id;
+                            opts.onEvent({ type: 'session', data: sessionId });
+                        }
+                        break;
+                    case 'item.completed':
+                        if (ev.item.type !== 'agent_message' && ev.item.type !== 'reasoning')
+                            opts.onEvent({ type: 'tool_end', data: { id: ev.item.id } });
+                        if (ev.item.type === 'agent_message') {
+                            finalText = ev.item.text;
+                            opts.onEvent({ type: 'text', data: ev.item.text });
+                        }
+                        else if (ev.item.type === 'error') {
+                            opts.onEvent({ type: 'error', data: ev.item.message });
+                        }
+                        else {
+                            opts.onEvent({ type: 'tool', data: { type: ev.item.type } });
+                        }
+                        break;
+                    case 'item.started':
+                        if (ev.item.type !== 'agent_message' && ev.item.type !== 'reasoning') {
+                            opts.onEvent({ type: 'tool_start', data: { id: ev.item.id, type: ev.item.type } });
+                        }
+                        else
+                            opts.onEvent({ type: 'tool', data: { type: ev.type } });
+                        break;
+                    case 'item.updated':
+                    case 'turn.started':
+                        opts.onEvent({ type: 'tool', data: { type: ev.type } });
+                        break;
+                    case 'turn.completed':
+                        sawUsage = true;
+                        cost += estimateCost(ev.usage, price);
+                        opts.onEvent({ type: 'usage', data: { usage: ev.usage, costUsd: cost, estimated: true } });
+                        break;
+                    case 'turn.failed':
+                        error = ev.error.message;
+                        opts.onEvent({ type: 'error', data: error });
+                        break;
+                    case 'error':
+                        error = ev.message;
+                        opts.onEvent({ type: 'error', data: error });
+                        break;
+                }
+            }
+        }
+        catch (e) {
+            error = opts.signal.aborted ? 'aborted' : String(e?.message ?? e);
+            opts.onEvent({ type: 'error', data: error });
+        }
+        finally {
+            opts.signal.removeEventListener('abort', onAbort);
+        }
+        sessionId = sessionId ?? thread.id ?? undefined;
+        return {
+            finalText,
+            sessionId,
+            costUsd: sawUsage ? cost : undefined,
+            estimated: true,
+            ok: !error,
+            error,
+        };
+    }
+}

package/dist/src/adapters/fake.d.ts

@@ -0,0 +1,65 @@
+import type { AdapterResult, AdapterRunOptions, RuntimeAdapter } from './types.js';
+export interface AchCallResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Invokes the `ach` CLI with the spawned agent's env. */
+export type AchCall = (args: string[], env: Record<string, string>, cwd: string) => Promise<AchCallResult>;
+export type FakeStep = {
+    ach: string[];
+    unset?: string[];
+    set?: Record<string, string>;
+} | {
+    text: string;
+} | {
+    wait: number;
+} | {
+    waitForAbort: true;
+} | {
+    fail: string;
+} | {
+    cost: number;
+} | {
+    toolStart: string;
+} | {
+    toolEnd: string;
+} | {
+    throw: string;
+};
+export interface FakeRunInfo {
+    index: number;
+    prompt: string;
+    resume?: string;
+    cwd: string;
+    perm: string;
+    mode?: 'work' | 'answer' | 'mention';
+    env: Record<string, string>;
+    denyReadPaths?: string[];
+    readRoots?: string[];
+    outputSchema?: unknown;
+    netAllow?: string[];
+}
+export interface FakeAdapterOptions {
+    /** Steps for each run; receives the run info so a script can branch on prompt / resume. */
+    script: (info: FakeRunInfo) => FakeStep[];
+    ach?: AchCall;
+    /** Behave like codex: answer runs return JSON and the runner posts it. */
+    structuredAnswers?: boolean;
+}
+/** Default: spawn this package's CLI with node. */
+export declare const spawnAch: AchCall;
+/** Scripted runtime for tests. Never calls a model. */
+export declare class FakeAdapter implements RuntimeAdapter {
+    private o;
+    readonly name = "fake";
+    readonly structuredAnswers: boolean;
+    runs: FakeRunInfo[];
+    achCalls: {
+        args: string[];
+        env: Record<string, string>;
+        result: AchCallResult;
+    }[];
+    constructor(o: FakeAdapterOptions);
+    run(opts: AdapterRunOptions): Promise<AdapterResult>;
+}

package/dist/src/adapters/fake.js

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** Default: spawn this package's CLI with node. */
+export const spawnAch = (args, env, cwd) => new Promise((res) => {
+    const cli = fileURLToPath(new URL('../cli.js', import.meta.url));
+    const p = spawn(process.execPath, [cli, ...args], { env, cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    p.stdout.on('data', (d) => (stdout += d));
+    p.stderr.on('data', (d) => (stderr += d));
+    p.on('close', (code) => res({ code: code ?? 1, stdout, stderr }));
+});
+function sleep(ms, signal) {
+    return new Promise((res, rej) => {
+        if (signal.aborted)
+            return rej(new Error('aborted'));
+        const t = setTimeout(() => {
+            signal.removeEventListener('abort', on);
+            res();
+        }, ms);
+        const on = () => {
+            clearTimeout(t);
+            rej(new Error('aborted'));
+        };
+        signal.addEventListener('abort', on, { once: true });
+    });
+}
+/** Scripted runtime for tests. Never calls a model. */
+export class FakeAdapter {
+    o;
+    name = 'fake';
+    structuredAnswers;
+    runs = [];
+    achCalls = [];
+    constructor(o) {
+        this.o = o;
+        this.structuredAnswers = !!o.structuredAnswers;
+    }
+    async run(opts) {
+        const info = {
+            index: this.runs.length,
+            prompt: opts.prompt,
+            resume: opts.resume,
+            cwd: opts.cwd,
+            perm: opts.perm,
+            mode: opts.mode,
+            env: opts.env,
+            denyReadPaths: opts.denyReadPaths,
+            readRoots: opts.readRoots,
+            outputSchema: opts.outputSchema,
+            netAllow: opts.netAllow,
+        };
+        this.runs.push(info);
+        const sessionId = opts.resume ?? `fake-session-${info.index}-${Math.random().toString(36).slice(2, 8)}`;
+        opts.onEvent({ type: 'session', data: sessionId });
+        const ach = this.o.ach ?? spawnAch;
+        let text = '';
+        let cost;
+        try {
+            for (const step of this.o.script(info)) {
+                if (opts.signal.aborted)
+                    throw new Error('aborted');
+                if ('ach' in step) {
+                    // unset/set: what a misbehaving agent could do to its own env (`env -u ACH_RUN_TOKEN ach ...`)
+                    const env = { ...opts.env, ...(step.set ?? {}) };
+                    for (const k of step.unset ?? [])
+                        delete env[k];
+                    const result = await ach(step.ach, env, opts.cwd);
+                    this.achCalls.push({ args: step.ach, env, result });
+                    opts.onEvent({ type: 'tool', data: { ach: step.ach, code: result.code } });
+                }
+                else if ('text' in step) {
+                    text = step.text;
+                    opts.onEvent({ type: 'text', data: step.text });
+                }
+                else if ('wait' in step) {
+                    await sleep(step.wait, opts.signal);
+                }
+                else if ('waitForAbort' in step) {
+                    await sleep(2 ** 30, opts.signal);
+                }
+                else if ('cost' in step) {
+                    cost = step.cost;
+                    opts.onEvent({ type: 'usage', data: { costUsd: cost } });
+                }
+                else if ('toolStart' in step) {
+                    opts.onEvent({ type: 'tool_start', data: { id: step.toolStart } });
+                }
+                else if ('toolEnd' in step) {
+                    opts.onEvent({ type: 'tool_end', data: { id: step.toolEnd } });
+                }
+                else if ('fail' in step) {
+                    return { finalText: text, sessionId, costUsd: cost, ok: false, error: step.fail };
+                }
+                else if ('throw' in step) {
+                    throw new Error(step.throw);
+                }
+            }
+        }
+        catch (e) {
+            return { finalText: text, sessionId, costUsd: cost, ok: false, error: opts.signal.aborted ? 'aborted' : String(e?.message ?? e) };
+        }
+        return { finalText: text, sessionId, costUsd: cost, ok: true };
+    }
+}

package/dist/src/adapters/index.d.ts

@@ -0,0 +1,11 @@
+import type { RuntimeAdapter } from './types.js';
+export * from './types.js';
+export { ClaudeAdapter } from './claude.js';
+export { CodexAdapter } from './codex.js';
+export { FakeAdapter } from './fake.js';
+export * from './paths.js';
+/** The git common dir of a worktree (readable for git log/diff; never writable, S10). */
+export declare function gitCommonDir(cwd: string): string[];
+export declare function makeAdapter(runtime: string, o?: {
+    model?: string;
+}): RuntimeAdapter;

package/dist/src/adapters/index.js

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { ClaudeAdapter } from './claude.js';
+import { CodexAdapter } from './codex.js';
+export * from './types.js';
+export { ClaudeAdapter } from './claude.js';
+export { CodexAdapter } from './codex.js';
+export { FakeAdapter } from './fake.js';
+export * from './paths.js';
+/** The git common dir of a worktree (readable for git log/diff; never writable, S10). */
+export function gitCommonDir(cwd) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return out ? [resolve(cwd, out)] : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function makeAdapter(runtime, o = {}) {
+    if (runtime === 'claude')
+        return new ClaudeAdapter({ model: o.model });
+    if (runtime === 'codex')
+        return new CodexAdapter({ model: o.model });
+    throw new Error(`Unknown runtime "${runtime}" (use claude or codex)`);
+}

package/dist/src/adapters/paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * realpath of p, or of its nearest existing ancestor plus the rest (for files
+ * that do not exist yet). macOS maps /tmp to /private/tmp and /var to
+ * /private/var, so every comparison goes through this.
+ */
+export declare function realish(p: string, depth?: number): string;
+export declare function isInside(root: string, p: string): boolean;
+/** Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. */
+export declare function packageRoot(): string;
+/**
+ * Paths under $HOME a spawned agent may read besides its cwd (S4): the node
+ * install, npm and git config, and this package (the `ach` CLI). The git
+ * common dir of the worktree is added by the caller.
+ */
+export declare function toolchainReadRoots(home?: string): string[];
+export interface PathPolicy {
+    home: string;
+    cwd: string;
+    /** Readable roots under $HOME besides cwd. */
+    readRoots: string[];
+    /** Writable roots (empty = read-only). */
+    writeRoots: string[];
+    /** Never readable or writable, even inside an allowed root. */
+    deny: string[];
+}
+/** Undefined = allowed, else the reason for denying a read of p. */
+export declare function readDenied(pol: PathPolicy, p: string): string | undefined;
+export declare function writeDenied(pol: PathPolicy, p: string): string | undefined;
+export declare const READ_TOOLS: Set<string>;
+export declare const WRITE_TOOLS: Set<string>;
+/** File paths a tool call touches (relative paths are resolved against cwd by the policy). */
+export declare function toolPaths(toolName: string, input: Record<string, unknown>): string[];
+/** Deny reason for a tool call under the policy, or undefined to allow. */
+export declare function toolDenied(pol: PathPolicy, toolName: string, input: Record<string, unknown>): string | undefined;
+export declare function existing(paths: string[]): string[];

package/dist/src/adapters/paths.js

@@ -0,0 +1,113 @@
+import { existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * realpath of p, or of its nearest existing ancestor plus the rest (for files
+ * that do not exist yet). macOS maps /tmp to /private/tmp and /var to
+ * /private/var, so every comparison goes through this.
+ */
+export function realish(p, depth = 0) {
+    let cur = resolve(p);
+    const rest = [];
+    for (;;) {
+        try {
+            return join(realpathSync(cur), ...rest.reverse());
+        }
+        catch {
+            // A dangling symlink still points somewhere: follow it.
+            try {
+                if (depth < 40 && lstatSync(cur).isSymbolicLink()) {
+                    return realish(join(resolve(dirname(cur), readlinkSync(cur)), ...rest.reverse()), depth + 1);
+                }
+            }
+            catch {
+                /* not there at all */
+            }
+            const up = dirname(cur);
+            if (up === cur)
+                return resolve(p);
+            rest.push(basename(cur));
+            cur = up;
+        }
+    }
+}
+export function isInside(root, p) {
+    const rel = relative(realish(root), realish(p));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/** Root of this npm package (dist/src/adapters/paths.js -> package dir): the `ach` shim runs code from here. */
+export function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+}
+/**
+ * Paths under $HOME a spawned agent may read besides its cwd (S4): the node
+ * install, npm and git config, and this package (the `ach` CLI). The git
+ * common dir of the worktree is added by the caller.
+ */
+export function toolchainReadRoots(home = homedir()) {
+    const nodePrefix = resolve(dirname(process.execPath), '..');
+    return [
+        nodePrefix,
+        packageRoot(),
+        join(home, '.gitconfig'),
+        join(home, '.config', 'git'),
+        join(home, '.npmrc'),
+        join(home, '.npm'),
+    ];
+}
+/** Undefined = allowed, else the reason for denying a read of p. */
+export function readDenied(pol, p) {
+    const abs = resolve(pol.cwd, p);
+    if (pol.deny.some((d) => isInside(d, abs)))
+        return `${p} is a protected AgentChannel file`;
+    if (!isInside(pol.home, abs))
+        return undefined;
+    if ([pol.cwd, ...pol.readRoots].some((r) => isInside(r, abs)))
+        return undefined;
+    return `reads under ${pol.home} are limited to the task directory and toolchain paths`;
+}
+export function writeDenied(pol, p) {
+    const abs = resolve(pol.cwd, p);
+    if (pol.deny.some((d) => isInside(d, abs)))
+        return `${p} is a protected AgentChannel file`;
+    if (pol.writeRoots.some((r) => isInside(r, abs)))
+        return undefined;
+    return `writes are only allowed inside ${pol.cwd}`;
+}
+export const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS', 'NotebookRead']);
+export const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+/** File paths a tool call touches (relative paths are resolved against cwd by the policy). */
+export function toolPaths(toolName, input) {
+    const out = [];
+    for (const k of ['file_path', 'notebook_path', 'path']) {
+        if (typeof input[k] === 'string' && input[k])
+            out.push(input[k]);
+    }
+    // Glob/Grep patterns may be absolute ("/Users/x/**/*.pem"): check their fixed prefix.
+    for (const k of ['pattern', 'glob']) {
+        const v = input[k];
+        if ((toolName === 'Glob' || k === 'glob') && typeof v === 'string' && (isAbsolute(v) || v.startsWith('~'))) {
+            const fixed = v.replace(/^~(?=\/|$)/, homedir()).split(/[*?[{]/)[0];
+            out.push(fixed || '/');
+        }
+    }
+    if ((READ_TOOLS.has(toolName) || toolName === 'Glob' || toolName === 'Grep') && !out.length)
+        out.push('.');
+    return out;
+}
+/** Deny reason for a tool call under the policy, or undefined to allow. */
+export function toolDenied(pol, toolName, input) {
+    const write = WRITE_TOOLS.has(toolName);
+    if (!write && !READ_TOOLS.has(toolName))
+        return undefined;
+    for (const p of toolPaths(toolName, input)) {
+        const why = write ? writeDenied(pol, p) ?? readDenied(pol, p) : readDenied(pol, p);
+        if (why)
+            return why;
+    }
+    return undefined;
+}
+export function existing(paths) {
+    return paths.filter((p) => existsSync(p));
+}