agy-worker-mcp 0.3.1

package/dist/gate/hooks-file.js

@@ -0,0 +1,104 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJsonIfExists, writeJsonAtomic } from '../contract/paths.js';
+/**
+ * Single owner of `<workspace>/.agents/hooks.json`'s lifecycle: `start.ts` writes
+ * our entry when a job spawns, `reconcile.ts` removes it once no live job on that
+ * `cwd` needs it any more. Kept in one module — with the key constant — so the two
+ * call sites can never drift on what "our entry" means.
+ */
+/** The one key this package ever writes into `hooks.json`. Never touch any other key. */
+export const GATE_HOOK_KEY = 'agy-worker-gate';
+export function hooksFilePath(workspace) {
+    return join(workspace, '.agents', 'hooks.json');
+}
+/** Single-quote for a POSIX `sh -c` string, escaping any embedded `'`. */
+function shQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Write (merging, never clobbering unrelated keys) `<workspace>/.agents/hooks.json`
+ * so the PreToolUse gate loads for this workspace. `--add-dir` is what makes agy
+ * load it at all (see docs/permissions.md) — this is the piece that puts the
+ * file there in the first place, since nothing else in the package owns it.
+ *
+ * The command is just `node '<gatePath>'` — quoted (an unquoted absolute path
+ * breaks on any install path containing a space). There used to be a
+ * `|| printf '{"decision":"ask"}'` fallback here; it is gone. agy already fails closed on its own —
+ * empty/non-JSON stdout or a non-zero exit is a *denial*, not a pass-through
+ * (measured against 1.1.23, `src/gate/gate.ts`'s own header comment) — so the
+ * fallback never protected anything: its only effect was to convert that
+ * already-safe failure into `{"decision":"ask"}`, which in print mode reaches
+ * agy's built-in engine and lets a `run_command` call proceed with whatever
+ * `BypassSandbox` value the model itself asked for (M3-C) — the exact hole I2 exists to close.
+ * Losing the fallback also means `ensureGateHook` must only ever be called once
+ * `gatePath` is confirmed to exist (`agy_start`'s own `existsSync` check).
+ *
+ * Our key is written **first** in the object, ahead of every pre-existing key.
+ * Measured (M6): agy evaluates
+ * `hooks.json`'s PreToolUse groups in declaration order and a `deny` from an
+ * earlier group short-circuits the rest — a group installed ahead of ours that
+ * denies would mean our gate never runs at all for that call, and the runtime
+ * watchdog (`src/runner/gate-watchdog.ts`) would misread the resulting silence
+ * in `gate-log.jsonl` as "hooks never loaded". Writing ours first guarantees it
+ * runs on every tool call regardless of what else is declared in this file.
+ * (A hook group installed *outside* this file entirely — e.g. a user's global
+ * `~/.gemini/config/hooks.json` — that denies ahead of ours is the one case
+ * this cannot cover; the watchdog still reports it correctly if bluntly, as
+ * "gate never fired", which is safe — fail closed — just imprecise about why.
+ * Not handled here, by design.)
+ */
+export function ensureGateHook(workspace, gatePath) {
+    const hooksPath = hooksFilePath(workspace);
+    const existing = readJsonIfExists(hooksPath) ?? {};
+    const command = `node ${shQuote(gatePath)}`;
+    const ours = {
+        PreToolUse: [
+            {
+                matcher: '*',
+                hooks: [{ type: 'command', command, timeout: 15 }],
+            },
+        ],
+    };
+    delete existing[GATE_HOOK_KEY];
+    const merged = { [GATE_HOOK_KEY]: ours, ...existing };
+    writeJsonAtomic(hooksPath, merged);
+}
+/**
+ * Remove only {@link GATE_HOOK_KEY} from `<workspace>/.agents/hooks.json`,
+ * preserving every other key untouched. Deletes the file when it held nothing
+ * else, and the `.agents` directory when that leaves it empty. A no-op when the
+ * file does not exist or never carried our key.
+ *
+ * Best effort by design: called from
+ * `reconcile`, which must never fail a tool call over hook-file housekeeping. A
+ * stale entry left behind by a failure here is harmless until the next
+ * `agy_start` on the same workspace, which overwrites it unconditionally.
+ */
+export function removeGateHook(workspace) {
+    try {
+        const hooksPath = hooksFilePath(workspace);
+        const existing = readJsonIfExists(hooksPath);
+        if (!existing || !(GATE_HOOK_KEY in existing))
+            return;
+        delete existing[GATE_HOOK_KEY];
+        if (Object.keys(existing).length > 0) {
+            writeJsonAtomic(hooksPath, existing);
+            return;
+        }
+        rmSync(hooksPath, { force: true });
+        const agentsDir = join(workspace, '.agents');
+        try {
+            if (existsSync(agentsDir) && readdirSync(agentsDir).length === 0) {
+                rmSync(agentsDir, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // Best effort — an unreadable/already-gone directory is not a failure.
+        }
+    }
+    catch {
+        // Best effort — reconcile must never break over hook-file housekeeping.
+    }
+}
+//# sourceMappingURL=hooks-file.js.map

package/dist/gate/hooks-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-file.js","sourceRoot":"","sources":["../../src/gate/hooks-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAExE;;;;;GAKG;AAEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAA;AAE9C,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,OAAO,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,YAAY,CAAC,CAAA;AACjD,CAAC;AAED,0EAA0E;AAC1E,SAAS,OAAO,CAAC,CAAS;IACxB,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,QAAgB;IAChE,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,gBAAgB,CAA0B,SAAS,CAAC,IAAI,EAAE,CAAA;IAC3E,MAAM,OAAO,GAAG,QAAQ,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAA;IAC3C,MAAM,IAAI,GAAG;QACX,UAAU,EAAE;YACV;gBACE,OAAO,EAAE,GAAG;gBACZ,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;aACnD;SACF;KACF,CAAA;IACD,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAA;IAC9B,MAAM,MAAM,GAA4B,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAA;IAC9E,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,CAAA;QAC1C,MAAM,QAAQ,GAAG,gBAAgB,CAA0B,SAAS,CAAC,CAAA;QACrE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,aAAa,IAAI,QAAQ,CAAC;YAAE,OAAM;QAErD,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAA;QAE9B,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrC,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;YACpC,OAAM;QACR,CAAC;QAED,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;QAC5C,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjE,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACrD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;QACzE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;IAC1E,CAAC;AACH,CAAC"}

package/dist/gate.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":""}

package/dist/gate.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the PreToolUse hook. Compiles to `dist/gate.js`, the path
+ * written into `<workspace>/.agents/hooks.json`.
+ *
+ * ⚠ Never exit without printing a decision. `{}` and empty output are treated
+ * as denials by agy, and this process also runs for the user's own interactive agy
+ * sessions whenever a conversation cannot be matched to one of our jobs.
+ */
+import { PASSTHROUGH, emit, guardStdout, main } from './gate/gate.js';
+// Before anything else can print. A hook that exits 0 with unparseable stdout
+// is treated as a denial by agy, and this process always exits 0.
+guardStdout();
+main()
+    .then((code) => process.exit(code))
+    .catch(() => {
+    emit(PASSTHROUGH);
+    process.exit(0);
+});
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAErE,8EAA8E;AAC9E,kEAAkE;AAClE,WAAW,EAAE,CAAA;AAEb,IAAI,EAAE;KACH,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KAClC,KAAK,CAAC,GAAG,EAAE;IACV,IAAI,CAAC,WAAW,CAAC,CAAA;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/policy/ceiling-review.d.ts

@@ -0,0 +1,22 @@
+import type { CeilingDraftReview, CeilingRuleRisk } from '../contract/types.js';
+/**
+ * Risk class of one rule string. Order matters: the most consequential class
+ * wins when a pattern could be read two ways (`git push --force` is
+ * destructive before it is vcs_remote; `sudo npm install` is privilege before
+ * install). `filesystem` covers every non-command verb — the containment
+ * roots, not the rule list, bound those.
+ */
+export declare function classifyRuleRisk(rule: string): CeilingRuleRisk;
+/** Rules a human should read twice before approving. */
+export declare const ELEVATED_RISK: ReadonlySet<CeilingRuleRisk>;
+/**
+ * Validate and annotate a draft `policy.json`.
+ *
+ * `errors` are exactly what `loadCeiling` would refuse (so `ok: true` means
+ * the file would load). `warnings` are advisory: redundant rules, exceptions
+ * that lift nothing, `denylist` mode. `rules` carries one row per rule with
+ * its risk class, so the parent agent can put the class next to every line
+ * it shows the user.
+ */
+export declare function reviewCeilingDraft(draft: unknown): CeilingDraftReview;
+//# sourceMappingURL=ceiling-review.d.ts.map

package/dist/policy/ceiling-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling-review.d.ts","sourceRoot":"","sources":["../../src/policy/ceiling-review.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAqB,MAAM,sBAAsB,CAAA;AA0DlG;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CA0B9D;AAED,wDAAwD;AACxD,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAErD,CAAA;AAEF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAgDrE"}

package/dist/policy/ceiling-review.js

@@ -0,0 +1,170 @@
+import { ValidationError } from '../contract/errors.js';
+import { parseCeilingJson } from './ceiling.js';
+import { HARD_DENY } from './hard-deny.js';
+import { getProfile } from './profiles.js';
+import { parseRule } from './rules.js';
+/**
+ * Review a ceiling draft for `agy_ceiling` (0.3.0 PR3). Deterministic
+ * and file-free: the same checks `loadCeiling` runs,
+ * plus the advisory layer a human wants before approving the file — what is
+ * redundant, what is being lifted, and how risky each rule is.
+ *
+ * The server never writes the ceiling. This module only tells the parent
+ * agent what a human is about to be asked to approve.
+ */
+/**
+ * Every concrete command a `command(...)` pattern names, lower-cased. `|` is
+ * per-token alternation in `rules.ts` (`git status|log|diff` is three git
+ * subcommands, not `git status` or a bare `log`), so expand it token by token.
+ */
+function commandHeads(pattern) {
+    const tokens = pattern.trim().toLowerCase().split(/\s+/);
+    let heads = [''];
+    for (const token of tokens) {
+        const alternatives = token.split('|');
+        heads = heads.flatMap((h) => alternatives.map((a) => (h ? `${h} ${a}` : a)));
+    }
+    return heads;
+}
+const READ_UTILITY = new Set([
+    'ls', 'cat', 'head', 'tail', 'wc', 'grep', 'rg', 'find', 'stat', 'sed', 'sed -n', 'sort', 'uniq', 'diff',
+    'cut', 'tr', 'xargs', 'basename', 'dirname', 'realpath', 'which', 'echo', 'printf', 'test', 'true', 'false',
+    'pwd', 'env', 'date', 'uname', 'file', 'less', 'more', 'tree', 'jq', 'awk',
+]);
+const BUILD_HEADS = [
+    'gradle', './gradlew', 'gradlew', 'mvn', './mvnw', 'make', 'cmake', 'ninja', 'cargo', 'go', 'npm', 'npx', 'pnpm', 'yarn',
+    'node', 'node -e', 'python', 'python3', 'python -c', 'python3 -c', 'pytest', 'javac', 'java', 'tsc', 'vitest', 'jest',
+    'dotnet', 'swift', 'rustc', 'gcc', 'clang', 'bash -c', 'sh -c', 'bash', 'sh', 'zsh',
+];
+const NETWORK_HEADS = ['curl', 'wget', 'ssh', 'scp', 'sftp', 'nc', 'ncat', 'telnet', 'rsync', 'ping', 'dig', 'nslookup'];
+const VCS_REMOTE_HEADS = ['git push', 'git fetch', 'git pull', 'git clone', 'git remote', 'git submodule', 'gh'];
+const INSTALL_HEADS = [
+    'npm install', 'npm i', 'npm ci', 'npm add', 'pnpm install', 'pnpm add', 'yarn add', 'yarn install', 'pip install',
+    'pip3 install', 'brew', 'apt', 'apt-get', 'yum', 'dnf', 'cargo install', 'go install', 'gem install',
+];
+const DESTRUCTIVE_HEADS = [
+    'rm -rf', 'rm -r', 'git reset --hard', 'git clean', 'git filter-branch', 'git branch -d', 'git stash drop',
+    'git checkout -- .', 'git restore .', 'git restore --staged .', 'git push --force', 'git push -f', 'mkfs', 'dd',
+    'chmod -r', 'chown -r', 'kill', 'killall', 'pkill',
+];
+const PRIVILEGE_HEADS = ['sudo', 'doas', 'su', 'docker', 'podman', 'launchctl', 'systemctl'];
+function startsWithAny(head, list) {
+    return list.some((h) => head === h || head.startsWith(`${h} `));
+}
+/**
+ * Risk class of one rule string. Order matters: the most consequential class
+ * wins when a pattern could be read two ways (`git push --force` is
+ * destructive before it is vcs_remote; `sudo npm install` is privilege before
+ * install). `filesystem` covers every non-command verb — the containment
+ * roots, not the rule list, bound those.
+ */
+export function classifyRuleRisk(rule) {
+    let parsed;
+    try {
+        parsed = parseRule(rule);
+    }
+    catch {
+        return 'other';
+    }
+    if (parsed.verb !== 'command')
+        return parsed.verb === 'fetch' || parsed.verb === 'url' ? 'network' : 'filesystem';
+    if (parsed.regex || parsed.pattern === '*')
+        return 'other';
+    const heads = commandHeads(parsed.pattern);
+    const classes = heads.map((head) => {
+        if (startsWithAny(head, PRIVILEGE_HEADS))
+            return 'privilege';
+        if (startsWithAny(head, DESTRUCTIVE_HEADS))
+            return 'destructive';
+        if (startsWithAny(head, INSTALL_HEADS))
+            return 'install';
+        if (startsWithAny(head, NETWORK_HEADS))
+            return 'network';
+        if (startsWithAny(head, VCS_REMOTE_HEADS))
+            return 'vcs_remote';
+        if (head.startsWith('git ') || head === 'git')
+            return 'vcs_local';
+        if (READ_UTILITY.has(head) || startsWithAny(head, [...READ_UTILITY]))
+            return 'read_utility';
+        if (startsWithAny(head, BUILD_HEADS))
+            return 'build';
+        return 'other';
+    });
+    const order = [
+        'privilege', 'destructive', 'install', 'network', 'vcs_remote', 'other', 'build', 'vcs_local', 'read_utility', 'filesystem',
+    ];
+    for (const c of order)
+        if (classes.includes(c))
+            return c;
+    return 'other';
+}
+/** Rules a human should read twice before approving. */
+export const ELEVATED_RISK = new Set([
+    'privilege', 'destructive', 'install', 'network', 'vcs_remote',
+]);
+/**
+ * Validate and annotate a draft `policy.json`.
+ *
+ * `errors` are exactly what `loadCeiling` would refuse (so `ok: true` means
+ * the file would load). `warnings` are advisory: redundant rules, exceptions
+ * that lift nothing, `denylist` mode. `rules` carries one row per rule with
+ * its risk class, so the parent agent can put the class next to every line
+ * it shows the user.
+ */
+export function reviewCeilingDraft(draft) {
+    const errors = [];
+    let ceiling = null;
+    try {
+        ceiling = parseCeilingJson(draft, '<draft>');
+    }
+    catch (e) {
+        errors.push(e instanceof ValidationError ? e.message : String(e));
+    }
+    const warnings = [];
+    const rules = [];
+    if (ceiling) {
+        warnings.push(...ceiling.warnings);
+        const profile = getProfile('general_worker');
+        const profileAllow = new Set(profile.allow);
+        const profileDeny = new Set(profile.deny);
+        const hardDeny = new Set(HARD_DENY);
+        for (const rule of ceiling.allow) {
+            const notes = [];
+            if (profileAllow.has(rule))
+                notes.push('already in the general_worker allow list');
+            if (profileDeny.has(rule))
+                notes.push('general_worker denies this; allow does not override deny — use exceptions');
+            if (hardDeny.has(rule))
+                notes.push('HARD_DENY; no file can allow this');
+            rules.push({ key: 'allow', rule, risk: classifyRuleRisk(rule), notes });
+        }
+        for (const rule of ceiling.deny) {
+            const notes = [];
+            if (profileDeny.has(rule))
+                notes.push('already denied by general_worker');
+            if (hardDeny.has(rule))
+                notes.push('already on HARD_DENY');
+            if (ceiling.exceptions.includes(rule))
+                notes.push('also listed in exceptions; deny wins, net effect denied');
+            rules.push({ key: 'deny', rule, risk: classifyRuleRisk(rule), notes });
+        }
+        for (const rule of ceiling.exceptions) {
+            const notes = [];
+            if (!profileDeny.has(rule))
+                notes.push('not on the general_worker deny list; lifts nothing (exact-string match)');
+            const risk = classifyRuleRisk(rule);
+            if (ELEVATED_RISK.has(risk))
+                notes.push(`${risk}: needs explicit line-by-line approval`);
+            rules.push({ key: 'exceptions', rule, risk, notes });
+        }
+        for (const r of rules) {
+            for (const n of r.notes)
+                warnings.push(`${r.key}: ${r.rule} — ${n}`);
+        }
+        if (ceiling.command_policy === 'denylist') {
+            warnings.push('command_policy: denylist lets every command not on a deny list run; needs explicit approval');
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings, rules };
+}
+//# sourceMappingURL=ceiling-review.js.map

package/dist/policy/ceiling-review.js.map

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

package/dist/policy/ceiling.d.ts

@@ -0,0 +1,128 @@
+import type { CeilingSummary, SandboxMode } from '../contract/types.js';
+/**
+ * The human-owned permission ceiling (see docs/permissions.md
+ * — the middle row of the three-owner table: code / **human** / parent agent).
+ *
+ * Lives at `<project state dir>/policy.json` — `projectPaths(root).dir` from
+ * `contract/paths.ts`, i.e. `<AGY_WORKER_HOME or ~/.agy-worker>/projects/<hash>/`,
+ * the very directory that already holds `project.json` and `index.db`. That
+ * directory sits outside the workspace by construction: it is keyed by
+ * `sha256(canonical_root)` under the user's home (or `AGY_WORKER_HOME`), never
+ * under the project's own tree. This is what makes it an actual ceiling — I6
+ * is exactly the invariant that a bound job
+ * can write anywhere `{workspace}/**` a `write_file` rule permits, so a
+ * ceiling file living inside the workspace could rewrite its own limits. Never
+ * move this file, or look it up, anywhere under a job's `cwd`.
+ */
+export interface Ceiling {
+    /** Whether a policy.json was actually found. False = the profile as shipped. */
+    present: boolean;
+    /** Absolute path the ceiling was (or would be) read from; null for a draft or the frozen empty ceiling. */
+    path: string | null;
+    /** Rules added to every profile's own allow ceiling (`{workspace}` left unsubstituted). */
+    allow: string[];
+    /** Rules added to every profile's own deny list (`{workspace}` left unsubstituted). */
+    deny: string[];
+    /**
+     * Profile deny rules this project lifts (0.3.0). Matched by exact string
+     * against the profile's `deny` in `resolvePolicy`; a rule on `HARD_DENY`
+     * here is a file error, never a silent no-op.
+     */
+    exceptions: string[];
+    /**
+     * OS boundary for general_worker commands (0.3.0 PR6): `none` (default,
+     * the 0.2.1 behaviour), `seatbelt` (our write-only `sandbox-exec` profile),
+     * or `agy` (agy's own sandbox, the 0.2.0 behaviour). A v2 `sandboxed: true`
+     * and every v1 `sandboxed: true` read as `agy`.
+     */
+    sandbox: SandboxMode;
+    /**
+     * Read/exec roots outside the workspace (`--add-dir`). `~`-expanded,
+     * best-effort canonicalized glob patterns (`*`, `**` allowed, `rules.ts`'s
+     * own glob semantics — `matchesPathGlob`). Not job-specific, so resolved
+     * once here rather than deferred like the rule strings above.
+     */
+    read_roots: string[];
+    /**
+     * Directories outside the workspace a job may write to. Canonical absolute
+     * paths (no globs — a write root is a directory, not a pattern). Extends
+     * `write_roots` for containment and the seatbelt profile alike.
+     */
+    write_roots: string[];
+    /** Command evaluation mode: "allowlist" (default) or "denylist" (0.2.2 PR3). */
+    command_policy: 'allowlist' | 'denylist';
+    /** Schema version the file was written in; null when no file. */
+    version: 1 | 2 | null;
+    /** Non-fatal notes for `agy_capabilities` (e.g. v1 key names). */
+    warnings: string[];
+}
+export declare const EMPTY_CEILING: Ceiling;
+/** `<project state dir>/policy.json`. Exported so callers (capabilities, tests) don't hardcode the filename. */
+export declare function ceilingPath(paths: {
+    dir: string;
+}): string;
+/**
+ * Convert a ceiling `read_roots` pattern (potentially a glob like `~/.jdks/**`)
+ * into a concrete directory root for `--add-dir`.
+ *
+ * Takes the fixed prefix before the first wildcard (`*`), strips trailing `/`,
+ * resolves home expansion and canonicalization via `resolveDirPattern`, and returns
+ * the canonical directory path if it exists and is a directory; otherwise null.
+ */
+export declare function additionalDirRoot(pattern: string): string | null;
+/**
+ * Load and validate the project ceiling.
+ *
+ * Missing file → {@link EMPTY_CEILING} (a project with no ceiling file grants
+ * nothing beyond the profiles' own defaults — narrower, not wider, than
+ * having one). Present but invalid — bad JSON, `version` other than `1`/`2`, a
+ * non-string entry, an entry that does not parse as `verb(pattern)`
+ * (`parseRule`), or a legacy `unsandboxed` entry — throws
+ * {@link ValidationError} with `field: 'ceiling'` and the file path, so
+ * `agy_start` fails closed and tells the human what to fix instead of quietly
+ * falling back to an empty ceiling (which would look like "nothing is
+ * misconfigured" when something very much is).
+ *
+ * `{workspace}` substitution on `allow`/`deny`/`exceptions` is
+ * deferred to `resolvePolicy` — this file has no workspace of its own; one
+ * project can run jobs against several `cwd` values under the same ceiling.
+ * `read_roots` entries are not job-specific, so they are `~`-expanded and
+ * canonicalized once, here.
+ */
+export declare function loadCeiling(paths: {
+    dir: string;
+}): Ceiling;
+/**
+ * The validation half of {@link loadCeiling}, separated so `agy_ceiling` can
+ * check a draft that exists only in the caller's hands — same rules, same
+ * error texts, no file. `path` only labels the error.
+ */
+export declare function parseCeilingJson(json: unknown, path: string): Ceiling;
+/**
+ * Is `canonicalDir` (already `~`-expanded/canonicalized, e.g. via
+ * {@link resolveDirPattern}) covered by some glob in the ceiling's
+ * `read_roots`? The one place `read_roots` matching happens, so
+ * `resolvePolicy` and any test never re-implement the glob semantics.
+ */
+export declare function additionalDirCovered(ceiling: Ceiling, canonicalDir: string): boolean;
+/** `~`-expand and canonicalize a requested `read_roots` entry the same way ceiling entries are resolved. */
+export declare function resolveRequestedDir(pattern: string): string;
+/**
+ * Render a loaded ceiling for `agy_capabilities`.
+ *
+ * No `{workspace}` substitution: capabilities has no per-job workspace (a
+ * project can run jobs against several `cwd` values), so a rule string
+ * carrying the literal `{workspace}` placeholder is returned exactly as
+ * written in `policy.json`. A caller sees the substituted, job-real form in
+ * `agy_start`'s own `policy_summary` instead.
+ */
+/**
+ * The one sentence every surface says when there is no ceiling file. Not an
+ * error — the profile as shipped is the safe default — but the agent and the
+ * user should both know that the door exists and who holds the key: the user
+ * approves, the agent (via `agy_ceiling` / the `agy-ceiling` skill) or the
+ * user (via `/agy-ceiling`) drafts.
+ */
+export declare function ceilingAbsenceHint(path: string | null): string;
+export declare function describeCeiling(ceiling: Ceiling, path: string, present: boolean): CeilingSummary;
+//# sourceMappingURL=ceiling.d.ts.map

package/dist/policy/ceiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling.d.ts","sourceRoot":"","sources":["../../src/policy/ceiling.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAIvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO;IACtB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;IAChB,2GAA2G;IAC3G,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,2FAA2F;IAC3F,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,uFAAuF;IACvF,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;OAKG;IACH,OAAO,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB;;;;OAIG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,gFAAgF;IAChF,cAAc,EAAE,WAAW,GAAG,UAAU,CAAA;IACxC,iEAAiE;IACjE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;IACrB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,eAAO,MAAM,aAAa,EAAE,OAY1B,CAAA;AAiCF,gHAAgH;AAChH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE1D;AAoBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBhE;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAmB3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAqFrE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED,4GAA4G;AAC5G,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;GAQG;AACH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQ9D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAchG"}