@a2f0/agent-tool 0.1.23 → 0.1.25

package/README.md

@@ -45,10 +45,10 @@ checkout and explicit policy file.
 ```sh
 agent-tool branch create chore/maintenance --base main --remote origin
 agent-tool repo context
-agent-tool run --label tests -- bun test
+agent-tool bun test --log
 agent-tool review claude
 agent-tool branch push <reviewed-head> --remote origin
-agent-tool pr open 'chore: maintain repository' < /tmp/pr-body.txt
+agent-tool pr open 'chore: maintain repository' --body-file /tmp/pr-body.txt
 agent-tool pr checks --wait --head <reviewed-head>
 agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>
 agent-tool pr merge 'chore: maintain repository' <reviewed-head> <base-branch>
@@ -85,6 +85,8 @@ validation suite, and release procedures.
 - [Development](docs/development.md): setup, source layout, validation, and release
   procedures for this package.
 - [Images](docs/images.md): declarative brand sources and generated outputs.
+- [Permissions](docs/permissions.md): which commands run without approval in
+  Claude Code and Codex, and the dependency commands that enforce it.
 - [Dependency maintenance](docs/dependency-upgrades.md): active compatibility
   constraints and the dependency-update workflow.
 - [Design](docs/design.md) and [extraction history](docs/extraction.md): component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",

package/skills/open-pr/SKILL.md

@@ -17,11 +17,15 @@ a changed result needs another review. Respect existing push authorization.
 If the user only requested a draft description, prepare it without publishing.
 
 Write a title that satisfies the data-only `agent-tool.json` subject policy.
-Describe the concrete resulting behavior and relevant validation. Put multiline
-body text in a temporary file, then run:
+Describe the concrete resulting behavior and relevant validation. When the
+branch changes package manifests, run
+`agent-tool dependencies diff --base <base-oid>` and name every `newPackages`
+entry in the body with its manifest and version, so a reviewer sees new
+third-party code however it was added. Put multiline body text in a temporary
+file, then run:
 
 ```sh
-agent-tool pr open 'feat: describe the change' < /path/to/pr-body.txt
+agent-tool pr open 'feat: describe the change' --body-file /path/to/pr-body.txt
 ```
 
 Omitting the title uses the latest commit subject. The tool refuses duplicate

package/skills/ship-pr/SKILL.md

@@ -52,7 +52,8 @@ do not reduce test scope, skip checks, silence warnings, or mask failures.
    reply with `pr threads reply <comment-id>` (body file or stdin), and use
    `pr threads resolve <thread-id>` only for fully addressed findings.
    Validate, commit, push, and independently review every feedback or CI repair.
-   Wait with `agent-tool pr checks --wait --head <reviewed-head>`, then run
+   Wait with `agent-tool pr checks --wait --head <reviewed-head>`; when a job
+   fails, read its log with `agent-tool pr logs --head <reviewed-head>`. Then run
    `agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>` to
    recheck CI, live base, PR identity, local state, and explicit version policy.
    A changed base requires integration, validation, and another review. When

package/skills/update-dependencies/SKILL.md

@@ -218,7 +218,12 @@ Capture relevant baseline checks and warnings first, after screening their side
 effects. Update one compatibility group at a time. Read the upstream instructions
 for every breaking step; implement required source/config/schema migrations and
 removed API replacements. Use the manager that owns each lockfile, on the selected
-runtime, and inspect the resulting diff. Refresh transitive dependencies through
+runtime, and inspect the resulting diff. For Bun lockfiles, change declared
+versions with `agent-tool bun update <name[@version]>` and drop packages with
+`agent-tool bun remove <name>`; both use the pinned Bun and refuse to add a
+package. A new dependency goes through `agent-tool bun add <name@version>`, which
+asks for approval; never introduce one by editing `package.json` and
+reinstalling. Refresh transitive dependencies through
 their owning direct dependency; do not hand-edit integrity hashes or lock entries.
 Review intentional patches, overrides, and pins before removal; retain them until
 upstream fixes and regression checks demonstrate they are unnecessary.

package/src/bun/dependencies.ts

@@ -0,0 +1,256 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, fstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createLog } from "../commands/logFile";
+import { DEFAULT_LIMITS, printLogTail } from "../commands/output";
+import { assert, flag, option, output } from "../workflows/core";
+import { bunExecute } from "./execute";
+import { pinnedBun, type BunExecutable } from "./toolchain";
+import { lockedWorkspaceVersions, lostWorkspaceReferences } from "../version/lockfileVersions";
+import { packageDirectories, workspacePackage } from "./workspace";
+
+const SECTIONS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"] as const;
+type Section = typeof SECTIONS[number];
+/** Sections Bun installs. Peer ranges are a published compatibility contract, so `update` never rewrites them. */
+const INSTALLED: Section[] = ["dependencies", "devDependencies", "optionalDependencies"];
+const SECTION_FLAGS: Record<Section, string[]> = { dependencies: [], devDependencies: ["--dev"], optionalDependencies: ["--optional"], peerDependencies: ["--peer"] };
+const NAME = /^(?:@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*$/i;
+const EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const USAGE = `Usage:
+  agent-tool bun install [--cwd <dir>]
+  agent-tool bun add <name@version>... [--dev|--optional|--peer] [--exact] [--cwd <dir>]
+  agent-tool bun update <name[@version]>... [--cwd <dir>]
+  agent-tool bun remove <name>... [--cwd <dir>]
+  agent-tool bun test [--cwd <dir>] [--log] [-- args...]
+  agent-tool bun x <executable> [--cwd <dir>] [--log] [-- args...]`;
+
+type Manifest = Record<string, unknown> & Partial<Record<Section, Record<string, string>>>;
+interface Requested { name: string; spec?: string }
+export interface DependencyChange { name: string; section: Section; from: string | null; to: string | null }
+
+/** Registry versions, ranges, and tags; never a workspace, alias, Git, URL, or path source. */
+export function registrySpec(spec: string): boolean { return /^[\w^~<>=*|][\w^~<>=*|.+ -]*$/.test(spec) && spec.trim() === spec; }
+
+export function parseRequested(value: string): Requested {
+  const at = value.indexOf("@", value.startsWith("@") ? 1 : 0);
+  const name = at === -1 ? value : value.slice(0, at);
+  const spec = at === -1 ? undefined : value.slice(at + 1);
+  assert(NAME.test(name), `Invalid package name '${name}'.`);
+  assert(spec === undefined || (spec.trim().length > 0 && !/[\r\n\t]/.test(spec) && !spec.startsWith("-")), `Invalid version for ${name}.`);
+  return { name, spec };
+}
+
+function readManifest(file: string): Manifest {
+  const value = JSON.parse(readFileSync(file, "utf8")) as unknown;
+  assert(value && typeof value === "object" && !Array.isArray(value), `${file} is not a JSON object.`);
+  for (const section of SECTIONS) {
+    const entries = (value as Manifest)[section];
+    assert(entries === undefined || (typeof entries === "object" && !Array.isArray(entries) && Object.values(entries).every(spec => typeof spec === "string")), `${file} has an invalid ${section} section.`);
+  }
+  return value as Manifest;
+}
+
+function declarations(manifest: Manifest, name: string): { section: Section; spec: string }[] {
+  return SECTIONS.flatMap(section => { const spec = manifest[section]?.[name]; return spec === undefined ? [] : [{ section, spec }]; });
+}
+
+/** Compare everything except dependency sections, which callers check entry by entry. */
+function otherFields(manifest: Manifest): string {
+  const rest: Record<string, unknown> = { ...manifest };
+  for (const section of SECTIONS) delete rest[section];
+  return JSON.stringify(rest);
+}
+
+/**
+ * Check that Bun changed only what the action allows. `update` may change only the
+ * requested versions; `remove` may only delete requested names; `add` may only create
+ * requested names in one section. Any other manifest change fails and is restored.
+ */
+export function manifestViolations(action: "add" | "update" | "remove", before: Manifest, after: Manifest, names: Set<string>, addSection?: Section): string[] {
+  const violations: string[] = [];
+  if (otherFields(before) !== otherFields(after)) violations.push("package.json fields outside dependency sections changed.");
+  if (action === "add") for (const name of names) if (!(name in (after[addSection!] ?? {}))) violations.push(`${name} was not added to ${addSection}.`);
+  for (const section of SECTIONS) {
+    const old = before[section] ?? {}, now = after[section] ?? {};
+    for (const name of new Set([...Object.keys(old), ...Object.keys(now)])) {
+      const requested = names.has(name);
+      if (action === "remove" && requested) { if (name in now) violations.push(`${name} is still declared in ${section}.`); continue; }
+      if (action === "add" && requested && section === addSection) { if (!(name in now)) violations.push(`${name} was not added to ${section}.`); continue; }
+      if (action === "update" && requested && section !== "peerDependencies" && name in old) {
+        if (!(name in now)) violations.push(`${name} was removed from ${section}.`);
+        else if (!registrySpec(now[name]!)) violations.push(`${name} in ${section} no longer uses a registry version (${now[name]}).`);
+        continue;
+      }
+      if (!(name in old)) violations.push(`${name} was unexpectedly added to ${section}.`);
+      else if (!(name in now)) violations.push(`${name} was unexpectedly removed from ${section}.`);
+      else if (old[name] !== now[name]) violations.push(`${name} in ${section} unexpectedly changed from ${old[name]} to ${now[name]}.`);
+    }
+  }
+  return violations;
+}
+
+function changes(before: Manifest, after: Manifest, names: Set<string>): DependencyChange[] {
+  return SECTIONS.flatMap(section => [...names].flatMap(name => {
+    const from = before[section]?.[name] ?? null, to = after[section]?.[name] ?? null;
+    return from === to ? [] : [{ name, section, from, to }];
+  }));
+}
+
+/** Saved bytes for each file, with a way to put them back and to list which ones changed. */
+function snapshot(files: string[]) {
+  const saved = files.map(file => ({ file, contents: existsSync(file) ? readFileSync(file) : null }));
+  return {
+    /** Restore every file even if one fails, recreating directories a script removed. */
+    restore() {
+      const failures: string[] = [];
+      for (const { file, contents } of saved) {
+        try {
+          if (contents) { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, contents); }
+          else if (existsSync(file)) unlinkSync(file);
+        } catch (error) { failures.push(`${file}: ${(error as Error).message}`); }
+      }
+      if (failures.length) throw new Error(`Could not restore ${failures.join("; ")}`);
+    },
+    changed(): string[] {
+      return saved.filter(({ file, contents }) => {
+        const now = existsSync(file) ? readFileSync(file) : null;
+        return !(now === null ? contents === null : contents !== null && now.equals(contents));
+      }).map(({ file }) => file);
+    },
+  };
+}
+
+function runBun(bun: BunExecutable, directory: string, args: string[]) {
+  const { log, fd } = createLog("agent-tool-bun-");
+  const started = performance.now();
+  try {
+    const result = spawnSync(bun.path, args, { cwd: directory, stdio: ["ignore", fd, fd], env: process.env });
+    const exitCode = result.error ? 126 : result.status ?? 1;
+    return { command: ["bun", ...args], exitCode, signal: result.signal ?? null, durationMs: Math.round(performance.now() - started), outputBytes: fstatSync(fd).size, log };
+  } finally { closeSync(fd); }
+}
+
+function parseArgs(action: string, args: string[]) {
+  const sections = (["--dev", "--optional", "--peer"] as const).filter(name => flag(args, name));
+  const exact = flag(args, "--exact");
+  for (const value of args) assert(!value.startsWith("-"), `Unknown bun ${action} argument '${value}'.\n${USAGE}`);
+  if (action === "add") assert(sections.length <= 1, "Choose at most one of --dev, --optional, and --peer.");
+  else assert(!sections.length && !exact, `bun ${action} keeps each dependency's section and pin style; section and --exact flags apply to add.`);
+  const requested = args.map(parseRequested);
+  assert(action === "install" ? !requested.length : requested.length > 0, action === "install" ? "bun install takes no packages; add one with `agent-tool bun add`." : USAGE);
+  assert(new Set(requested.map(item => item.name)).size === requested.length, "Each package may be named once.");
+  const addSection: Section = sections[0] === "--dev" ? "devDependencies" : sections[0] === "--optional" ? "optionalDependencies" : sections[0] === "--peer" ? "peerDependencies" : "dependencies";
+  return { requested, exact, addSection };
+}
+
+/** Plan the Bun invocations for one action, refusing anything outside its permission class. */
+function plan(action: "add" | "update" | "remove", manifest: Manifest, requested: Requested[], exact: boolean, addSection: Section, workspaceNames: Set<string>): string[][] {
+  if (action === "add") {
+    for (const { name, spec } of requested) {
+      assert(!declarations(manifest, name).length, `${name} is already declared; use \`agent-tool bun update ${name}\` to change its version.`);
+      assert(spec && (registrySpec(spec) || /^workspace:[^\s]*$/.test(spec)), `Name an explicit registry or workspace version to add ${name}, for example ${name}@1.2.3.`);
+    }
+    return [["add", ...SECTION_FLAGS[addSection], ...(exact ? ["--exact"] : []), ...requested.map(({ name, spec }) => `${name}@${spec}`)]];
+  }
+  if (action === "remove") {
+    for (const { name, spec } of requested) {
+      assert(spec === undefined, `Name only the package to remove: ${name}.`);
+      assert(declarations(manifest, name).length, `${name} is not declared in this package.json; nothing to remove.`);
+    }
+    return [["remove", ...requested.map(({ name }) => name)]];
+  }
+  // Group by section and pin style so each Bun call keeps both unchanged.
+  const groups = new Map<string, string[]>();
+  for (const { name, spec } of requested) {
+    const installed = declarations(manifest, name).filter(item => INSTALLED.includes(item.section));
+    assert(installed.length, `${name} is not an installed dependency here; adding a package needs \`agent-tool bun add\`.`);
+    // A version change can move a workspace reference to the registry package of the same name.
+    assert(!workspaceNames.has(name), `${name} is a workspace package; change references to it by hand.`);
+    assert(installed.length === 1, `${name} is declared in ${installed.map(item => item.section).join(" and ")}; update it manually.`);
+    const current = installed[0]!;
+    assert(registrySpec(current.spec), `${name} uses a non-registry source (${current.spec}); update it manually.`);
+    assert(spec === undefined || registrySpec(spec), `${name} can only be updated to a registry version or tag.`);
+    // An explicit version is written as given; moving to latest keeps an exact pin exact.
+    const flags = [...SECTION_FLAGS[current.section], ...(EXACT.test(spec ?? current.spec) ? ["--exact"] : [])];
+    const key = flags.join(" ");
+    groups.set(key, [...(groups.get(key) ?? []), `${name}@${spec ?? "latest"}`]);
+  }
+  return [...groups].map(([flags, packages]) => ["add", ...(flags ? flags.split(" ") : []), ...packages]);
+}
+
+export function bunCommand(args: string[]): number | Promise<number> {
+  const action = args.shift();
+  if (action === "test" || action === "x") return bunExecute(action, args);
+  assert(action === "install" || action === "add" || action === "update" || action === "remove", USAGE);
+  const target = path.resolve(option(args, "--cwd") ?? ".");
+  assert(existsSync(path.join(target, "package.json")), `No package.json in ${target}.`);
+  const { root, directory } = workspacePackage(target);
+  const file = path.join(directory, "package.json");
+  const { requested, exact, addSection } = parseArgs(action, args);
+  const bun = pinnedBun(directory, root);
+  const bunInfo = { path: bun.path, version: bun.version, source: bun.source, pinned: bun.pinned };
+  const before = readManifest(file);
+  const lockfiles = [path.join(root, "bun.lock"), path.join(root, "bun.lockb")];
+  // Workspaces share the root lockfile; Bun creating one beside any package means it was treated as standalone.
+  const nested = packageDirectories(root).filter(item => item !== root).flatMap(item => [path.join(item, "bun.lock"), path.join(item, "bun.lockb")]);
+  // Without a lockfile, Bun resolves whatever package.json names, including hand-added packages.
+  assert(lockfiles.some(item => existsSync(item)), "No bun.lock was found; a first install resolves new packages, so run it directly with approval.");
+  // Before a change, the lockfile must already cover every declaration, or Bun would also resolve a hand-added package.
+  const preflight = ["install", "--frozen-lockfile", "--lockfile-only"];
+  const workspaceNames = new Set(packageDirectories(root).map(item => (JSON.parse(readFileSync(path.join(item, "package.json"), "utf8")) as { name?: string }).name).filter((name): name is string => typeof name === "string"));
+  const calls = action === "install" ? [["install", "--frozen-lockfile"]] : [preflight, ...plan(action, before, requested, exact, addSection, workspaceNames)];
+  // The checks below read the text lockfile; a binary bun.lockb cannot be verified.
+  if (action !== "install") assert(existsSync(path.join(root, "bun.lock")), "Changing dependencies needs a text bun.lock; convert bun.lockb with approval first.");
+  if (action !== "install") {
+    // A frozen check can accept stale workspace versions; an unfrozen call would then fetch such a reference.
+    const lost = lostWorkspaceReferences(root, lockedWorkspaceVersions(root));
+    assert(!lost.length, `${lost.join(", ")} no longer match their workspaces, so Bun would fetch them from the registry; fix those references before changing dependencies.`);
+  }
+  // Lifecycle scripts can touch any workspace manifest; every one but the target must stay as it was.
+  const others = packageDirectories(root).map(item => path.join(item, "package.json")).filter(item => item !== file && existsSync(item));
+  const othersBefore = new Map(others.map(item => [item, JSON.stringify(readManifest(item))]));
+  const restored = [...new Set([file, ...others, ...lockfiles, ...nested])];
+  const saved = snapshot(restored);
+  const names = new Set(requested.map(item => item.name));
+  const runs = [];
+  let violations: string[] = [];
+  let after = before;
+  // Validate after every Bun call: a lifecycle script in one call must not feed the next.
+  const known = new Set([file, ...others]);
+  // A lifecycle script can create a workspace, or widen the globs to one, for a later call to resolve.
+  const discover = (): string[] => packageDirectories(root).map(item => path.join(item, "package.json")).filter(item => !known.has(item) && existsSync(item));
+  // Call after restoring the root manifest: under the original globs, every manifest that existed
+  // before is known, so anything else was created during the change. Widened globs never delete.
+  const removeCreated = () => { for (const item of discover()) unlinkSync(item); };
+  const validate = (call: string[]): string[] => {
+    const appeared = discover();
+    if (appeared.length) return appeared.map(item => `${path.relative(root, item)} appeared during the change.`);
+    if (call === preflight || action === "install") return saved.changed().map(item => `${path.relative(directory, item) || "package.json"} changed during a frozen install.`);
+    after = readManifest(file);
+    const found = manifestViolations(action, before, after, names, addSection);
+    for (const item of others) if (JSON.stringify(readManifest(item)) !== othersBefore.get(item)) found.push(`${path.relative(root, item)} changed outside the target package.`);
+    for (const item of saved.changed().filter(changed => nested.includes(changed))) found.push(`${path.relative(root, item)} changed beside a workspace package.`);
+    return found;
+  };
+  try {
+    for (const call of calls) {
+      const run = runBun(bun, directory, call);
+      runs.push(run);
+      if (run.exitCode !== 0) { violations = [call === preflight ? "package.json and the lockfile disagree; resolve that difference with approval before changing dependencies." : `bun ${call[0]} failed with exit ${run.exitCode}.`]; break; }
+      violations = validate(call);
+      if (violations.length) break;
+    }
+  } catch (error) {
+    saved.restore();
+    removeCreated();
+    throw error;
+  }
+  // Leave no partial dependency change behind; node_modules is rebuilt by the next frozen install.
+  if (violations.length) {
+    saved.restore();
+    removeCreated();
+  }
+  output({ ok: !violations.length, action, directory, bun: bunInfo, changes: violations.length ? [] : changes(before, after, names), ...(violations.length ? { violations, restored: restored.map(item => path.relative(directory, item) || "package.json") } : {}), runs });
+  if (runs.at(-1)?.exitCode) printLogTail(runs.at(-1)!.log, DEFAULT_LIMITS, 2);
+  return violations.length ? 1 : 0;
+}

package/src/bun/execute.ts

@@ -0,0 +1,80 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants as files, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { runCommand } from "../commands/run";
+import { assert, flag, option } from "../workflows/core";
+import { CLASSES } from "../permissions/catalog";
+import { checkPermissions } from "../permissions/install";
+import { projectCommands } from "../permissions/project";
+import { pinnedBun } from "./toolchain";
+import { workspacePackage } from "./workspace";
+
+const USAGE = `Usage:
+  agent-tool bun test [--cwd <dir>] [--log] [-- args...]
+  agent-tool bun x <executable> [--cwd <dir>] [--log] [-- args...]`;
+const EXECUTABLE = /^[\w.+-][\w.+-]*$/;
+
+/**
+ * An executable whose class asks relies on a generated ask rule. If the recorded rules predate
+ * its classification, an older allowance could run it without approval, so refuse until they
+ * are regenerated.
+ */
+function assertCurrentRules(root: string, command: string): void {
+  if (!existsSync(path.join(root, ".agent-tool-permissions.json"))) return;
+  // Only a current allow class matches whatever rules exist; a removed or asking class relies on fresh ones.
+  const entry = projectCommands(root).find(item => item.command === command);
+  if (entry && CLASSES[entry.class].decision === "allow") return;
+  const recorded = JSON.parse(readFileSync(path.join(root, ".agent-tool-permissions.json"), "utf8")) as { claude?: unknown; codex?: unknown };
+  const targets = [...(recorded.claude ? ["claude"] : []), ...(recorded.codex ? ["codex"] : [])];
+  const stale = targets.flatMap(target => checkPermissions(root, target)).filter(item => item.status !== "unchanged");
+  assert(!stale.length, `Permission rules predate the current class of '${command}'; regenerate them with approval (agent-tool permissions install --apply) before running it.`);
+}
+
+/** The package directory's or root's `node_modules/.bin/<name>`: an executable regular file inside the checkout. */
+function installedBinary(root: string, directory: string, name: string): string {
+  for (const base of [directory, root]) {
+    const link = path.join(base, "node_modules/.bin", name);
+    if (!existsSync(link)) continue;
+    const file = realpathSync(link), relative = path.relative(root, file);
+    assert(statSync(file).isFile() && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative), `${link} is not an installed binary inside this checkout.`);
+    try { accessSync(file, files.X_OK); } catch { throw new Error(`${link} is not executable.`); }
+    return link;
+  }
+  throw new Error(`${name} is not installed in this checkout's node_modules/.bin.`);
+}
+
+/**
+ * Run the test runner or an installed executable with the pinned Bun. The executable name comes
+ * first and options precede `--`, so a harness rule can classify the command by its prefix.
+ */
+export function bunExecute(action: "test" | "x", args: string[]): number | Promise<number> {
+  const separator = args.indexOf("--");
+  const options = separator === -1 ? args : args.slice(0, separator);
+  const forwarded = separator === -1 ? [] : args.slice(separator + 1);
+  const name = action === "x" ? options.shift() : undefined;
+  assert(action === "test" || (name && !name.startsWith("-")), `Name the executable first.\n${USAGE}`);
+  const target = path.resolve(option(options, "--cwd") ?? ".");
+  const log = flag(options, "--log");
+  assert(!options.length, `Unexpected bun ${action} argument '${options[0]}'; pass the command's own arguments after --.\n${USAGE}`);
+  const { root, directory } = workspacePackage(target);
+  const bun = pinnedBun(directory, root);
+  let executable = bun.path, command: string[];
+  if (action === "x") {
+    assert(EXECUTABLE.test(name!), `Name an installed executable, not a package or version: '${name}'.`);
+    // Run this checkout's own installed binary directly, so neither PATH nor Bun's cache can stand in.
+    executable = installedBinary(root, directory, name!);
+    assertCurrentRules(root, `bun x ${name}`);
+    command = forwarded;
+  } else command = ["test", ...forwarded];
+  // Tests and executables that call bun themselves get the pinned version too.
+  const env = { ...process.env, PATH: [path.dirname(bun.path), process.env.PATH].filter(Boolean).join(path.delimiter) };
+  if (log) {
+    process.chdir(directory);
+    process.env.PATH = env.PATH;
+    return runCommand(["--label", ["bun", action, name].filter(Boolean).join(" "), "--", executable, ...command]);
+  }
+  const result = spawnSync(executable, command, { cwd: directory, env, stdio: "inherit" });
+  if (result.error) throw result.error;
+  return result.signal ? 128 + (constants.signals[result.signal] ?? 0) : result.status ?? 1;
+}

package/src/bun/toolchain.ts

@@ -0,0 +1,58 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { outsideExecutable } from "../review/executable";
+import { assert } from "../workflows/core";
+
+export interface BunExecutable { path: string; version: string; source: "mise" | "path"; pinned: string | null }
+
+/** The nearest mise config's bun pin, read the way `toolchain check` reads `.mise.toml`. */
+export function misePin(directory: string): { file: string; version: string } | null {
+  for (let current = path.resolve(directory); ; current = path.dirname(current)) {
+    for (const name of [".mise.toml", "mise.toml"]) {
+      const file = path.join(current, name);
+      if (!existsSync(file)) continue;
+      const tools = (Bun.TOML.parse(readFileSync(file, "utf8")) as { tools?: Record<string, unknown> }).tools ?? {};
+      const pin = tools.bun;
+      if (pin === undefined) continue;
+      assert(typeof pin === "string" && /^[0-9][0-9A-Za-z.+-]*$/.test(pin), `Unsupported bun pin in ${file}; use a version string.`);
+      return { file, version: pin };
+    }
+    if (current === path.dirname(current)) return null;
+  }
+}
+
+function versionOf(executable: string): string {
+  const result = spawnSync(executable, ["--version"], { encoding: "utf8", timeout: 10000 });
+  assert(result.status === 0, `Could not run ${executable} --version.`);
+  return result.stdout.trim();
+}
+
+function runnable(file: string): boolean {
+  try { accessSync(file, constants.X_OK); return true; } catch { return false; }
+}
+
+/**
+ * Resolve the Bun a checkout pins, without relying on the agent shell's PATH.
+ * Agent shells do not activate mise, so the pinned install is used directly when present.
+ */
+export function pinnedBun(directory: string, root: string): BunExecutable {
+  const pin = misePin(directory)?.version ?? null;
+  const inside = (file: string) => { const relative = path.relative(realpathSync(root), realpathSync(file)); return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); };
+  if (pin) {
+    const data = process.env.MISE_DATA_DIR || path.join(process.env.XDG_DATA_HOME || path.join(homedir(), ".local/share"), "mise");
+    const candidate = path.join(data, "installs", "bun", pin, "bin", "bun");
+    if (runnable(candidate) && !inside(candidate)) {
+      const version = versionOf(candidate);
+      assert(version === pin || version.startsWith(`${pin}.`), `${candidate} reports Bun ${version}, not the pinned ${pin}; reinstall it with mise.`);
+      return { path: candidate, version, source: "mise", pinned: pin };
+    }
+  }
+  // A `bun` inside the checkout (node_modules/.bin is on PATH under `bun run`) is repository code; never run it.
+  const found = outsideExecutable("bun", process.env, root)?.candidate;
+  assert(found, "No Bun outside this checkout is on PATH.");
+  const version = versionOf(found);
+  assert(!pin || version === pin || version.startsWith(`${pin}.`), `Bun ${pin} from the mise config is not installed, and PATH has ${version}. Install the pinned Bun before changing dependencies.`);
+  return { path: found, version, source: "path", pinned: pin };
+}

package/src/bun/workspace.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { assert } from "../workflows/core";
+
+/** The checkout root, where the workspace manifest and its lockfile live. */
+export function projectRoot(directory: string): string {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf8" });
+  assert(result.status === 0, "Run Bun commands inside a Git checkout.");
+  return realpathSync(result.stdout.trim());
+}
+
+/** The root package and its declared Bun workspaces: the packages that share the root lockfile. */
+export function packageDirectories(root: string): string[] {
+  const manifest = path.join(root, "package.json");
+  if (!existsSync(manifest)) return [];
+  const value = JSON.parse(readFileSync(manifest, "utf8")) as { workspaces?: unknown };
+  const patterns = Array.isArray(value.workspaces) ? value.workspaces : (value.workspaces as { packages?: unknown } | undefined)?.packages;
+  const list = (Array.isArray(patterns) ? patterns : []).filter((pattern): pattern is string => typeof pattern === "string");
+  // `!pattern` entries exclude directories that the other patterns match.
+  const excluded = list.filter(pattern => pattern.startsWith("!")).map(pattern => new Bun.Glob(pattern.slice(1).replace(/\/$/, "")));
+  const directories = new Set([root]);
+  for (const pattern of list.filter(pattern => !pattern.startsWith("!"))) {
+    for (const match of new Bun.Glob(`${pattern.replace(/\/$/, "")}/package.json`).scanSync({ cwd: root, onlyFiles: true })) {
+      const relative = path.dirname(match);
+      if (!match.split("/").includes("node_modules") && !excluded.some(glob => glob.match(relative))) directories.add(path.join(root, relative));
+    }
+  }
+  return [...directories];
+}
+
+/** Resolve a package directory that belongs to the checkout's workspace, refusing standalone packages. */
+export function workspacePackage(directory: string): { root: string; directory: string } {
+  const resolved = realpathSync(directory);
+  const root = projectRoot(resolved);
+  // Harness rules come from the invoking checkout; --cwd may not reach another repository.
+  assert(root === projectRoot(process.cwd()), "--cwd must name a package in this checkout.");
+  assert(packageDirectories(root).some(item => realpathSync(item) === resolved), "Use the root package or a declared workspace; standalone packages keep their own lockfiles.");
+  return { root, directory: resolved };
+}

package/src/cli.ts

@@ -4,10 +4,13 @@ import path from "node:path";
 import { DEFAULT_CONFIG, loadConfig } from "./config";
 import { doctor } from "./doctor";
 import { checkTerraformPlan } from "./dependencies/terraformPlan";
+import { dependencyDiff } from "./dependencies/diff";
 import { review } from "./harnesses";
 import { runAgentToolAction } from "./runAgentToolAction";
 import { BUNDLED_SKILLS } from "./skills/bundled";
 import { checkSkills, installSkills } from "./skills/install";
+import { bunCommand } from "./bun/dependencies";
+import { checkPermissions, installPermissions, showPermissions } from "./permissions/install";
 import { bumpVersions, checkVersions, planVersions } from "./version/bumpVersions";
 import { prepareVersions } from "./version/prepareVersions";
 import { resolveVersionConflicts } from "./version/resolveVersionConflicts";
@@ -45,17 +48,28 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   release verify <package> <version> <merge-oid> --workflow name [--timeout seconds]
   logs <file> [--max-bytes N] [--tail-lines N]  Bounded local log tail
   review <claude|codex|opencode> [effort] [--base <local-ref>]
-  pr open [title]                       Body from stdin; branch already pushed
+  pr open [title] [--body-file file]    Body from the file or stdin; branch already pushed
   pr merge <subject-or-empty> <head-oid> <base-branch>
   pr context | checks [--wait] [--head oid] [--timeout seconds]
+  pr logs [--head oid] [--max-bytes N] [--tail-lines N]  Failed GitHub Actions job logs
   pr preflight <reviewed-head> <base-branch> <reviewed-base>
   pr threads list | reply <comment-id> [--body-file file] | resolve <thread-id>
   versions <plan|bump|check|prepare> <base-oid>
   versions resolve-conflicts
   dependencies check-terraform-plan <json-file>  Read-only destructive-plan check
+  dependencies diff --base <ref>        Declared dependencies added, removed, or changed since base
   skills list
   skills install [--harness <all|claude|codex|opencode>] [--apply]
   skills check [--harness <all|claude|codex|opencode>]
+  bun install [--cwd <dir>]             Frozen-lockfile install with the pinned Bun
+  bun add <name@version>... [--dev|--optional|--peer] [--exact] [--cwd <dir>]
+  bun update <name[@version]>... [--cwd <dir>]  Change versions of declared dependencies only
+  bun remove <name>... [--cwd <dir>]    Remove declared dependencies only
+  bun test [--cwd <dir>] [--log] [-- args...]
+  bun x <executable> [--cwd <dir>] [--log] [-- args...]  Installed executables only, never fetched
+  permissions show [--harness <all|claude|codex>]
+  permissions install [--harness <all|claude|codex>] [--apply]
+  permissions check [--harness <all|claude|codex>]
   images list [target...]               JSON files each image target writes
   images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
   init                                  Create agent-tool.json without overwriting
@@ -77,6 +91,8 @@ function gitRoot(): string {
 
 export function main(argv = process.argv.slice(2)): number | Promise<number> {
   const args = [...argv];
+  // File arguments are relative to where agent-tool was invoked, before --repo or the root change.
+  const invoked = process.cwd();
   while (args[0] === "--repo" || args[0] === "--config") {
     const flag = args.shift()!;
     const value = args.shift();
@@ -94,6 +110,10 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
   if (command === "ci") { usage(args.shift() === "gate", "Usage: ci gate <needs.json|-> [--policy policy.json]"); return gateCommand(args); }
   if (command === "release") return releaseCommand(args);
   if (command === "logs") return inspectLog(args);
+  if (command === "dependencies" && args[0] === "diff") {
+    usage(args.length === 3 && args[1] === "--base" && !!args[2] && !args[2].startsWith("-"), "Usage: agent-tool dependencies diff --base <ref>");
+    output(dependencyDiff(args[2]!)); return 0;
+  }
   if (command === "dependencies") {
     usage(args.length === 2 && args[0] === "check-terraform-plan", "Usage: agent-tool dependencies check-terraform-plan <json-file>");
     const source = readFileSync(args[1], "utf8");
@@ -147,6 +167,25 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
     }
     output({ applied: apply, changes: installSkills(process.cwd(), target, apply) }); return 0;
   }
+  if (command === "bun") return bunCommand(args);
+  if (command === "permissions") {
+    const action = args.shift();
+    usage(action === "show" || action === "install" || action === "check", "Usage: agent-tool permissions <show|install|check> [--harness <all|claude|codex>] [--apply]");
+    let target = "all", apply = false;
+    while (args.length) {
+      const flag = args.shift();
+      if (flag === "--apply") { usage(action === "install" && !apply, "--apply applies once, to permissions install."); apply = true; }
+      else if (flag === "--harness") { const value = args.shift(); usage(!!value, "--harness requires a name."); target = value!; }
+      else throw new Error(`Unknown permissions ${action} argument '${flag}'.`);
+    }
+    if (action === "show") { writeSync(1, showPermissions(process.cwd(), target)); return 0; }
+    if (action === "check") {
+      const changes = checkPermissions(process.cwd(), target);
+      const ok = changes.every(change => change.status === "unchanged");
+      output({ ok, changes }); return ok ? 0 : 1;
+    }
+    output({ applied: apply, changes: installPermissions(process.cwd(), target, apply) }); return 0;
+  }
   const root = gitRoot();
   process.chdir(root);
   loadConfig(root); // Validate policy before running a reviewer or mutating GitHub.
@@ -170,9 +209,15 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
     return review(root, name!, effort, base);
   }
   if (command === "pr") {
-    if (["context", "checks", "preflight", "threads"].includes(args[0]!)) return prWorkflowCommand(args);
+    if (["context", "checks", "logs", "preflight", "threads"].includes(args[0]!)) return prWorkflowCommand(args);
     const action = args.shift();
-    if (action === "open") { usage(args.length <= 1, "Usage: agent-tool pr open [title]"); return openPr(root, args[0]); }
+    if (action === "open") {
+      const index = args.indexOf("--body-file");
+      const given = index === -1 ? undefined : args.splice(index, 2)[1];
+      const bodyFile = given === undefined ? undefined : path.resolve(invoked, given);
+      usage((index === -1 || !!given) && args.length <= 1 && !args.includes("--body-file"), "Usage: agent-tool pr open [title] [--body-file <file>]");
+      return openPr(root, args[0], bodyFile);
+    }
     usage(action === "merge" && args.length === 3, "Usage: agent-tool pr merge <subject-or-empty> <reviewed-head-oid> <base-branch>");
     usage(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(args[1]!), "Merge requires a full reviewed HEAD OID.");
     return squashMerge(root, args[0], args[1], args[2]);