From d5ed4a7ba682f9a351ebfd45985d29e82e2391e0 Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Sat, 9 May 2026 08:25:06 +1000
Subject: [PATCH 1/6] feat: add go, mcp-atlassian, pnpm-package-script
 policies; expand pure commands

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 policies/allow-go.ts                          |  32 ++++
 policies/allow-mcp-atlassian.ts               |  16 ++
 policies/allow-pnpm-package-script.ts         |  40 +++++
 policies/index.ts                             |   6 +
 policies/parse-bash-ast.ts                    |  10 ++
 policies/tests/allow-go.test.ts               | 118 +++++++++++++
 .../tests/allow-pnpm-package-script.test.ts   | 159 ++++++++++++++++++
 7 files changed, 381 insertions(+)
 create mode 100644 policies/allow-go.ts
 create mode 100644 policies/allow-mcp-atlassian.ts
 create mode 100644 policies/allow-pnpm-package-script.ts
 create mode 100644 policies/tests/allow-go.test.ts
 create mode 100644 policies/tests/allow-pnpm-package-script.test.ts

diff --git a/policies/allow-go.ts b/policies/allow-go.ts
new file mode 100644
index 0000000..3fe8984
--- /dev/null
+++ b/policies/allow-go.ts
@@ -0,0 +1,32 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+const SAFE_SUBCOMMANDS = new Set([
+  "build",
+  "test",
+  "vet",
+  "version",
+  "env",
+  "list",
+  "doc",
+  "fmt",
+  "mod",
+  "help",
+  "tool",
+  "work",
+]);
+
+const allowGo: Policy = {
+  name: "Allow go commands",
+  description:
+    "Permits non-destructive Go commands (build, test, vet, env, list, doc, fmt, mod, etc.)",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens) return next();
+    if (tokens[0] !== "go") return next();
+    if (tokens.length < 2) return next();
+    if (!SAFE_SUBCOMMANDS.has(tokens[1])) return next();
+    return allow();
+  },
+};
+export default allowGo;
diff --git a/policies/allow-mcp-atlassian.ts b/policies/allow-mcp-atlassian.ts
new file mode 100644
index 0000000..0794534
--- /dev/null
+++ b/policies/allow-mcp-atlassian.ts
@@ -0,0 +1,16 @@
+import { allow, deny, next, type Policy } from "../src";
+
+/**
+ * Allow all mcp__atlassian__* tool calls except delete operations.
+ */
+const allowMcpAtlassian: Policy = {
+  name: "Allow MCP Atlassian",
+  description:
+    "Permits all Atlassian MCP tool calls except deleting Confluence pages",
+  handler: async (call) => {
+    if (!call.tool.startsWith("mcp__atlassian__")) return next();
+    if (call.tool.includes("delete")) return deny("Atlassian delete operations require manual approval");
+    return allow();
+  },
+};
+export default allowMcpAtlassian;
diff --git a/policies/allow-pnpm-package-script.ts b/policies/allow-pnpm-package-script.ts
new file mode 100644
index 0000000..a3a8c86
--- /dev/null
+++ b/policies/allow-pnpm-package-script.ts
@@ -0,0 +1,40 @@
+import { dirname } from "node:path";
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+async function findPackageScripts(startDir: string): Promise<Set<string> | null> {
+  let dir = startDir;
+  while (true) {
+    const pkgPath = `${dir}/package.json`;
+    const file = Bun.file(pkgPath);
+    if (await file.exists()) {
+      try {
+        const pkg = await file.json();
+        return new Set(Object.keys(pkg.scripts ?? {}));
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const allowPnpmPackageScript: Policy = {
+  name: "Allow pnpm run for package.json scripts",
+  description: "Permits pnpm run <script> when <script> is defined in the nearest package.json",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens) return next();
+    if (tokens[0] !== "pnpm" || tokens[1] !== "run") return next();
+    const script = tokens[2];
+    if (!script) return next();
+
+    const scripts = await findPackageScripts(call.context.cwd);
+    if (!scripts || !scripts.has(script)) return next();
+
+    return allow();
+  },
+};
+export default allowPnpmPackageScript;
diff --git a/policies/index.ts b/policies/index.ts
index 57f3521..ca7a98e 100644
--- a/policies/index.ts
+++ b/policies/index.ts
@@ -54,12 +54,15 @@ import allowCronCrud from "./allow-cron-crud";
 import allowRmProjectTmp from "./allow-rm-project-tmp";
 import allowNpmInstall from "./allow-npm-install";
 import allowNpxSafe from "./allow-npx-safe";
+import allowPnpmPackageScript from "./allow-pnpm-package-script";
 import allowSleep from "./allow-sleep";
 import allowNonDestructiveGit from "./allow-non-destructive-git";
 import allowGhIssuePr from "./allow-gh-issue-pr";
 import allowTmux from "./allow-tmux";
 import allowAwsCli from "./allow-aws-cli";
 import allowBrew from "./allow-brew";
+import allowMcpAtlassian from "./allow-mcp-atlassian";
+import allowGo from "./allow-go";
 
 export const builtinPolicies = [
   denyGitAddAndCommit,
@@ -119,9 +122,12 @@ export const builtinPolicies = [
   allowRmProjectTmp,
   allowNpmInstall,
   allowNpxSafe,
+  allowPnpmPackageScript,
   allowSleep,
   allowNonDestructiveGit,
   allowTmux,
   allowAwsCli,
   allowBrew,
+  allowMcpAtlassian,
+  allowGo,
 ];
diff --git a/policies/parse-bash-ast.ts b/policies/parse-bash-ast.ts
index 5acc3d4..99a2799 100644
--- a/policies/parse-bash-ast.ts
+++ b/policies/parse-bash-ast.ts
@@ -682,13 +682,23 @@ export function findWriteCommandTargets(file: ShellFile): string[] {
  * required first arguments (subcommand/flag constraints).
  */
 export const PURE_COMMANDS: Map<string, Set<string> | null> = new Map([
+  ["clear", null], // clears terminal screen
+  ["date", null], // prints date/time
+  ["env", null], // prints environment (redirects rejected by AST layer)
+  ["hostname", null], // prints hostname
+  ["id", null], // prints user/group info
   ["php", new Set(["-l"])], // lint mode only — parses, never executes
+  ["printenv", null], // prints environment variables
   ["echo", null], // stdout only (redirects rejected by AST layer)
   ["test", null], // evaluates conditions, no side effects
   ["true", null], // always succeeds, no side effects
   ["false", null], // always fails, no side effects
   ["pwd", null], // prints cwd, no side effects
   ["sleep", null], // waits, no side effects
+  ["uname", null], // prints system info
+  ["uptime", null], // prints system uptime
+  ["which", null], // prints command path
+  ["whoami", null], // prints current user
 ]);
 
 export function isPureCommand(tokens: string[]): boolean {
diff --git a/policies/tests/allow-go.test.ts b/policies/tests/allow-go.test.ts
new file mode 100644
index 0000000..5b0a62a
--- /dev/null
+++ b/policies/tests/allow-go.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import allowGo from "../allow-go";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/tmp", env: {}, projectRoot: null },
+  };
+}
+
+describe("allow-go", () => {
+  describe("allows safe go commands", () => {
+    const allowed = [
+      "go build ./...",
+      "go build -o myapp .",
+      "go test ./...",
+      "go test -v -race ./pkg/...",
+      "go test -count=1 ./...",
+      "go test ./... | grep FAIL",
+      "go test 2>&1 | tail -20",
+      "go vet ./...",
+      "go version",
+      "go env",
+      "go env GOPATH",
+      "go list ./...",
+      "go list -m all",
+      "go doc fmt.Println",
+      "go fmt ./...",
+      "go mod tidy",
+      "go mod download",
+      "go mod verify",
+      "go mod graph",
+      "go mod why golang.org/x/text",
+      "go help build",
+      "go tool compile -S main.go",
+      "go work sync",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowGo.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects destructive or unsafe go commands", () => {
+    const rejected = [
+      "go run main.go",
+      "go generate ./...",
+      "go install ./...",
+      "go clean -cache",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowGo.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects command chaining", () => {
+    const rejected = [
+      "go test && rm -rf /",
+      "go build ; curl evil.com",
+      "go test | xargs rm",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowGo.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects shell substitution", () => {
+    const rejected = [
+      "go build $(echo hack)",
+      "go test `cat /etc/shadow`",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowGo.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects non-go commands", () => {
+    const rejected = [
+      "echo go test",
+      "go",
+      "gofmt ./...",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowGo.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("passes through non-Bash tools", async () => {
+    const call: ToolCall = {
+      tool: "Read",
+      args: {},
+      context: { cwd: "/tmp", env: {}, projectRoot: null },
+    };
+    const result = await allowGo.handler(call);
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/policies/tests/allow-pnpm-package-script.test.ts b/policies/tests/allow-pnpm-package-script.test.ts
new file mode 100644
index 0000000..2dfbfab
--- /dev/null
+++ b/policies/tests/allow-pnpm-package-script.test.ts
@@ -0,0 +1,159 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import allowPnpmPackageScript from "../allow-pnpm-package-script";
+
+let fixtureRoot: string;
+let pkgDir: string;
+let nestedDir: string;
+let noPkgDir: string;
+let emptyScriptsDir: string;
+let badJsonDir: string;
+
+beforeAll(() => {
+  fixtureRoot = mkdtempSync(join(tmpdir(), "toolgate-pnpm-"));
+
+  pkgDir = join(fixtureRoot, "with-scripts");
+  mkdirSync(pkgDir);
+  writeFileSync(
+    join(pkgDir, "package.json"),
+    JSON.stringify({
+      name: "fixture",
+      scripts: { dev: "vite", build: "vite build", "type-check": "tsc --noEmit" },
+    }),
+  );
+
+  nestedDir = join(pkgDir, "src", "deep");
+  mkdirSync(nestedDir, { recursive: true });
+
+  noPkgDir = join(fixtureRoot, "no-pkg");
+  mkdirSync(noPkgDir);
+
+  emptyScriptsDir = join(fixtureRoot, "empty-scripts");
+  mkdirSync(emptyScriptsDir);
+  writeFileSync(
+    join(emptyScriptsDir, "package.json"),
+    JSON.stringify({ name: "empty" }),
+  );
+
+  badJsonDir = join(fixtureRoot, "bad-json");
+  mkdirSync(badJsonDir);
+  writeFileSync(join(badJsonDir, "package.json"), "{ not valid json");
+});
+
+afterAll(() => {
+  rmSync(fixtureRoot, { recursive: true, force: true });
+});
+
+function bash(command: string, cwd: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd, env: {}, projectRoot: null },
+  };
+}
+
+describe("allow-pnpm-package-script", () => {
+  describe("allows scripts defined in package.json", () => {
+    const cases = [
+      "pnpm run dev",
+      "pnpm run build",
+      "pnpm run type-check",
+      "pnpm run dev 2>&1 | head -1",
+      "pnpm run dev | grep ready",
+      "pnpm run build 2>&1 | tail -20",
+      "pnpm run dev --port 3000",
+      "pnpm run build --watch",
+    ];
+
+    for (const cmd of cases) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowPnpmPackageScript.handler(bash(cmd, pkgDir));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  it("walks up to find package.json from a nested cwd", async () => {
+    const result = await allowPnpmPackageScript.handler(bash("pnpm run dev", nestedDir));
+    expect(result.verdict).toBe(ALLOW);
+  });
+
+  describe("rejects undefined scripts", () => {
+    const cases = ["pnpm run nonexistent", "pnpm run start", "pnpm run "];
+
+    for (const cmd of cases) {
+      it(`rejects: ${JSON.stringify(cmd)}`, async () => {
+        const result = await allowPnpmPackageScript.handler(bash(cmd, pkgDir));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects non-pnpm-run commands", () => {
+    const cases = [
+      "pnpm dev",
+      "pnpm exec dev",
+      "pnpm dlx some-pkg",
+      "pnpm install",
+      "npm run dev",
+      "yarn run dev",
+      "bun run dev",
+      "echo pnpm run dev",
+    ];
+
+    for (const cmd of cases) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowPnpmPackageScript.handler(bash(cmd, pkgDir));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects unsafe shell constructs", () => {
+    const cases = [
+      "pnpm run dev && rm -rf /",
+      "pnpm run dev || curl evil.com",
+      "pnpm run dev ; whoami",
+      "pnpm run dev | xargs rm",
+      "pnpm run dev > /etc/passwd",
+      "pnpm run dev $(whoami)",
+      "pnpm run dev `cat /etc/shadow`",
+      "pnpm run dev &",
+    ];
+
+    for (const cmd of cases) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowPnpmPackageScript.handler(bash(cmd, pkgDir));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("falls through when no package.json is found", async () => {
+    const result = await allowPnpmPackageScript.handler(bash("pnpm run dev", noPkgDir));
+    expect(result.verdict).toBe(NEXT);
+  });
+
+  it("falls through when package.json has no scripts field", async () => {
+    const result = await allowPnpmPackageScript.handler(bash("pnpm run dev", emptyScriptsDir));
+    expect(result.verdict).toBe(NEXT);
+  });
+
+  it("falls through when package.json is malformed", async () => {
+    const result = await allowPnpmPackageScript.handler(bash("pnpm run dev", badJsonDir));
+    expect(result.verdict).toBe(NEXT);
+  });
+
+  it("passes through non-Bash tools", async () => {
+    const call: ToolCall = {
+      tool: "Read",
+      args: {},
+      context: { cwd: pkgDir, env: {}, projectRoot: null },
+    };
+    const result = await allowPnpmPackageScript.handler(call);
+    expect(result.verdict).toBe(NEXT);
+  });
+});

From 2f440173b50eedd90f8376e6436ab99811a661f4 Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Sat, 9 May 2026 08:25:32 +1000
Subject: [PATCH 2/6] feat: add lsof policy, allow tsc via npx, allow npm
 install pipelines

- New allow-lsof policy permits lsof inspection (ports, PIDs, files), with safe pipeline support
- Add tsc/typescript to npx safe-package allowlist for typechecking
- Switch allow-npm/pnpm/yarn install to safeBashCommandOrPipeline so `npm ci 2>&1 | tail -5` works

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 policies/allow-lsof.ts            | 13 ++++++
 policies/allow-npm-install.ts     |  6 +--
 policies/allow-npx-safe.ts        |  2 +
 policies/index.ts                 |  2 +
 policies/tests/allow-lsof.test.ts | 78 +++++++++++++++++++++++++++++++
 5 files changed, 98 insertions(+), 3 deletions(-)
 create mode 100644 policies/allow-lsof.ts
 create mode 100644 policies/tests/allow-lsof.test.ts

diff --git a/policies/allow-lsof.ts b/policies/allow-lsof.ts
new file mode 100644
index 0000000..858a0e5
--- /dev/null
+++ b/policies/allow-lsof.ts
@@ -0,0 +1,13 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+const allowLsof: Policy = {
+  name: "Allow lsof",
+  description: "Permits lsof for inspecting open files, sockets, and ports, optionally piped through safe filters",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens || tokens[0] !== "lsof") return next();
+    return allow();
+  },
+};
+export default allowLsof;
diff --git a/policies/allow-npm-install.ts b/policies/allow-npm-install.ts
index 16701c4..c19ce55 100644
--- a/policies/allow-npm-install.ts
+++ b/policies/allow-npm-install.ts
@@ -1,11 +1,11 @@
 import { allow, next, type Policy } from "../src";
-import { safeBashCommand } from "./parse-bash-ast";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
 
 const allowNpmInstall: Policy = {
   name: "Allow npm/pnpm/yarn install",
-  description: "Permits npm install, pnpm install, and yarn install commands",
+  description: "Permits npm install, pnpm install, and yarn install commands, optionally piped through safe filters",
   handler: async (call) => {
-    const tokens = await safeBashCommand(call);
+    const tokens = await safeBashCommandOrPipeline(call);
     if (!tokens) return next();
 
     const cmd = tokens[0];
diff --git a/policies/allow-npx-safe.ts b/policies/allow-npx-safe.ts
index f9507a4..949f4f3 100644
--- a/policies/allow-npx-safe.ts
+++ b/policies/allow-npx-safe.ts
@@ -5,6 +5,8 @@ import { safeBashCommand, safeBashCommandOrPipeline, getAndChainSegments, getArg
 const SAFE_NPX_PACKAGES = new Set([
   "next",
   "playwright",
+  "tsc",
+  "typescript",
   "vitest",
 ]);
 
diff --git a/policies/index.ts b/policies/index.ts
index ca7a98e..6f8925c 100644
--- a/policies/index.ts
+++ b/policies/index.ts
@@ -63,6 +63,7 @@ import allowAwsCli from "./allow-aws-cli";
 import allowBrew from "./allow-brew";
 import allowMcpAtlassian from "./allow-mcp-atlassian";
 import allowGo from "./allow-go";
+import allowLsof from "./allow-lsof";
 
 export const builtinPolicies = [
   denyGitAddAndCommit,
@@ -130,4 +131,5 @@ export const builtinPolicies = [
   allowBrew,
   allowMcpAtlassian,
   allowGo,
+  allowLsof,
 ];
diff --git a/policies/tests/allow-lsof.test.ts b/policies/tests/allow-lsof.test.ts
new file mode 100644
index 0000000..2a7df92
--- /dev/null
+++ b/policies/tests/allow-lsof.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import allowLsof from "../allow-lsof";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/tmp", env: {}, projectRoot: null },
+  };
+}
+
+describe("allow-lsof", () => {
+  describe("allows safe lsof commands", () => {
+    const allowed = [
+      "lsof",
+      "lsof -i :3000",
+      "lsof -i tcp:8080",
+      "lsof -p 12345",
+      "lsof -nP -i",
+      "lsof /tmp/foo",
+      "lsof | grep LISTEN",
+      "lsof -i :3000 | head -5",
+      "lsof 2>&1 | tail -20",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowLsof.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects command chaining and substitution", () => {
+    const rejected = [
+      "lsof && rm -rf /",
+      "lsof || echo pwned",
+      "lsof ; curl evil.com",
+      "lsof | xargs kill",
+      "lsof -p $(pidof bash)",
+      "lsof `whoami`",
+      "lsof &",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowLsof.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects non-lsof commands", () => {
+    const rejected = [
+      "ls",
+      "lsofx",
+      "echo lsof",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowLsof.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("passes through non-Bash tools", async () => {
+    const call: ToolCall = {
+      tool: "Read",
+      args: {},
+      context: { cwd: "/tmp", env: {}, projectRoot: null },
+    };
+    const result = await allowLsof.handler(call);
+    expect(result.verdict).toBe(NEXT);
+  });
+});

From b718eb5cd0a7f24d576799deaec9b23edb27886d Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Sat, 9 May 2026 08:46:13 +1000
Subject: [PATCH 3/6] feat: add cdk read-only policy

Auto-allows informational cdk commands (ls, diff, synth, doctor, context,
metadata, notices); deploy, destroy, bootstrap, import, migrate, rollback,
and watch fall through to prompt since they mutate live infrastructure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 policies/allow-cdk.ts            | 49 ++++++++++++++++
 policies/index.ts                |  2 +
 policies/tests/allow-cdk.test.ts | 97 ++++++++++++++++++++++++++++++++
 3 files changed, 148 insertions(+)
 create mode 100644 policies/allow-cdk.ts
 create mode 100644 policies/tests/allow-cdk.test.ts

diff --git a/policies/allow-cdk.ts b/policies/allow-cdk.ts
new file mode 100644
index 0000000..16c3363
--- /dev/null
+++ b/policies/allow-cdk.ts
@@ -0,0 +1,49 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+/** CDK subcommands that are read-only / informational */
+const SAFE_SUBCOMMANDS = new Set([
+  "ls",
+  "list",
+  "diff",
+  "synth",
+  "synthesize",
+  "doctor",
+  "context",
+  "metadata",
+  "notices",
+]);
+
+/** CDK flags that act as read-only subcommands */
+const SAFE_FLAGS = new Set([
+  "--version",
+  "-v",
+  "--help",
+  "-h",
+]);
+
+const allowCdk: Policy = {
+  name: "Allow cdk read-only",
+  description:
+    "Auto-allows read-only cdk commands (ls, diff, synth, doctor, etc.); requires approval for deploy, destroy, bootstrap, import, migrate, rollback, watch",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens || tokens[0] !== "cdk") return next();
+
+    if (tokens.length >= 2 && SAFE_FLAGS.has(tokens[1])) return allow();
+
+    let subcommand: string | undefined;
+    for (let i = 1; i < tokens.length; i++) {
+      if (!tokens[i].startsWith("-")) {
+        subcommand = tokens[i];
+        break;
+      }
+    }
+    if (!subcommand) return next();
+
+    if (SAFE_SUBCOMMANDS.has(subcommand)) return allow();
+
+    return next();
+  },
+};
+export default allowCdk;
diff --git a/policies/index.ts b/policies/index.ts
index 6f8925c..e5d4921 100644
--- a/policies/index.ts
+++ b/policies/index.ts
@@ -64,6 +64,7 @@ import allowBrew from "./allow-brew";
 import allowMcpAtlassian from "./allow-mcp-atlassian";
 import allowGo from "./allow-go";
 import allowLsof from "./allow-lsof";
+import allowCdk from "./allow-cdk";
 
 export const builtinPolicies = [
   denyGitAddAndCommit,
@@ -132,4 +133,5 @@ export const builtinPolicies = [
   allowMcpAtlassian,
   allowGo,
   allowLsof,
+  allowCdk,
 ];
diff --git a/policies/tests/allow-cdk.test.ts b/policies/tests/allow-cdk.test.ts
new file mode 100644
index 0000000..5e2c53a
--- /dev/null
+++ b/policies/tests/allow-cdk.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import allowCdk from "../allow-cdk";
+
+const PROJECT = "/home/user/project";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: PROJECT, env: {}, projectRoot: PROJECT },
+  };
+}
+
+describe("allow-cdk", () => {
+  describe("auto-allows read-only commands", () => {
+    const allowed = [
+      "cdk ls",
+      "cdk list",
+      "cdk diff",
+      "cdk diff MyStack",
+      "cdk synth",
+      "cdk synthesize",
+      "cdk doctor",
+      "cdk context",
+      "cdk metadata MyStack",
+      "cdk notices",
+      "cdk --version",
+      "cdk -v",
+      "cdk --help",
+      "cdk -h",
+      "cdk ls --long",
+      "cdk diff | head -50",
+      "cdk synth 2>&1 | tail -20",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowCdk.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("requires approval for mutating commands", () => {
+    const requireApproval = [
+      "cdk deploy",
+      "cdk deploy MyStack",
+      "cdk deploy --all",
+      "cdk destroy",
+      "cdk destroy MyStack",
+      "cdk destroy --all",
+      "cdk bootstrap",
+      "cdk bootstrap aws://123/us-east-1",
+      "cdk import",
+      "cdk migrate",
+      "cdk rollback",
+      "cdk watch",
+      "cdk acknowledge",
+      "cdk init app",
+    ];
+
+    for (const cmd of requireApproval) {
+      it(`requires approval: ${cmd}`, async () => {
+        const result = await allowCdk.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("passes through non-cdk commands", () => {
+    it("ignores non-Bash tools", async () => {
+      const call: ToolCall = {
+        tool: "Read",
+        args: { file_path: "/foo" },
+        context: { cwd: PROJECT, env: {}, projectRoot: PROJECT },
+      };
+      const result = await allowCdk.handler(call);
+      expect(result.verdict).toBe(NEXT);
+    });
+
+    it("ignores non-cdk bash commands", async () => {
+      const result = await allowCdk.handler(bash("git status"));
+      expect(result.verdict).toBe(NEXT);
+    });
+
+    it("ignores compound commands", async () => {
+      const result = await allowCdk.handler(bash("cdk ls && cdk deploy"));
+      expect(result.verdict).toBe(NEXT);
+    });
+  });
+
+  it("falls through for bare cdk with no subcommand", async () => {
+    const result = await allowCdk.handler(bash("cdk"));
+    expect(result.verdict).toBe(NEXT);
+  });
+});

From cc3ace47fb7420c6a8e55f626f003793bbc9d14a Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Sat, 9 May 2026 08:47:33 +1000
Subject: [PATCH 4/6] chore: bump to 0.5.0, fix test imports to use scoped
 package name

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 package.json                                     | 2 +-
 policies/tests/allow-cdk.test.ts                 | 2 +-
 policies/tests/allow-go.test.ts                  | 2 +-
 policies/tests/allow-lsof.test.ts                | 2 +-
 policies/tests/allow-pnpm-package-script.test.ts | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/package.json b/package.json
index 1e87c15..1832ba8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@brycehanscomb/toolgate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "devDependencies": {
     "bun-types": "latest"
   },
diff --git a/policies/tests/allow-cdk.test.ts b/policies/tests/allow-cdk.test.ts
index 5e2c53a..489b1f1 100644
--- a/policies/tests/allow-cdk.test.ts
+++ b/policies/tests/allow-cdk.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
 import allowCdk from "../allow-cdk";
 
 const PROJECT = "/home/user/project";
diff --git a/policies/tests/allow-go.test.ts b/policies/tests/allow-go.test.ts
index 5b0a62a..a681720 100644
--- a/policies/tests/allow-go.test.ts
+++ b/policies/tests/allow-go.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
 import allowGo from "../allow-go";
 
 function bash(command: string): ToolCall {
diff --git a/policies/tests/allow-lsof.test.ts b/policies/tests/allow-lsof.test.ts
index 2a7df92..73dd7a6 100644
--- a/policies/tests/allow-lsof.test.ts
+++ b/policies/tests/allow-lsof.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
 import allowLsof from "../allow-lsof";
 
 function bash(command: string): ToolCall {
diff --git a/policies/tests/allow-pnpm-package-script.test.ts b/policies/tests/allow-pnpm-package-script.test.ts
index 2dfbfab..04d5b3d 100644
--- a/policies/tests/allow-pnpm-package-script.test.ts
+++ b/policies/tests/allow-pnpm-package-script.test.ts
@@ -2,7 +2,7 @@ import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { ALLOW, NEXT, type ToolCall } from "toolgate";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
 import allowPnpmPackageScript from "../allow-pnpm-package-script";
 
 let fixtureRoot: string;

From 635196af669df2b06a3ed2fbe77f3ecb95d5f0f0 Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Tue, 19 May 2026 09:41:15 +1000
Subject: [PATCH 5/6] feat: honour AWS_PROFILE env when no --profile flag

The AWS CLI policy previously only matched profiles passed via --profile.
Shells that export AWS_PROFILE (a common workflow) fell through to a
permission prompt even for ReadOnly profiles, and Admin profiles weren't
gated at all. Profile resolution now falls back to call.context.env.AWS_PROFILE
when no flag is set, matching AWS CLI's own precedence (flag wins over env).

Bumps to 0.7.0. Adds six tests covering ReadOnly/Admin via env, destructive
override, flag-wins-over-env, and unknown-profile fall-through.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 package.json                         |  2 +-
 policies/allow-aws-cli.ts            |  5 +--
 policies/tests/allow-aws-cli.test.ts | 48 ++++++++++++++++++++++++++--
 3 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/package.json b/package.json
index 1832ba8..ce154b1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@brycehanscomb/toolgate",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "devDependencies": {
     "bun-types": "latest"
   },
diff --git a/policies/allow-aws-cli.ts b/policies/allow-aws-cli.ts
index 389cb2e..1b5f73b 100644
--- a/policies/allow-aws-cli.ts
+++ b/policies/allow-aws-cli.ts
@@ -128,12 +128,13 @@ export function createAwsCliPolicy(config: AwsCliPolicyConfig = {}): Policy {
   return {
     name: "Allow AWS CLI",
     description:
-      "Auto-allows non-destructive AWS CLI commands with ReadOnly profiles; requires approval for Admin profiles; denies destructive commands",
+      "Auto-allows non-destructive AWS CLI commands with ReadOnly profiles (via --profile or AWS_PROFILE env); requires approval for Admin profiles; denies destructive commands",
     handler: async (call) => {
       const tokens = await safeBashCommandOrPipeline(call);
       if (!tokens || tokens[0] !== "aws") return next();
 
-      const profile = extractProfile(tokens);
+      // --profile flag wins, then AWS_PROFILE env, matching AWS CLI's own precedence
+      const profile = extractProfile(tokens) ?? call.context.env.AWS_PROFILE ?? null;
 
       // Destructive commands — always require approval
       if (isDestructiveCommand(tokens, extraDestructive)) return next();
diff --git a/policies/tests/allow-aws-cli.test.ts b/policies/tests/allow-aws-cli.test.ts
index 605495a..7acc265 100644
--- a/policies/tests/allow-aws-cli.test.ts
+++ b/policies/tests/allow-aws-cli.test.ts
@@ -4,11 +4,11 @@ import allowAwsCli, { createAwsCliPolicy } from "../allow-aws-cli";
 
 const PROJECT = "/home/user/project";
 
-function bash(command: string): ToolCall {
+function bash(command: string, env: Record<string, string> = {}): ToolCall {
   return {
     tool: "Bash",
     args: { command },
-    context: { cwd: PROJECT, env: {}, projectRoot: PROJECT },
+    context: { cwd: PROJECT, env, projectRoot: PROJECT },
   };
 }
 
@@ -121,6 +121,50 @@ describe("allow-aws-cli", () => {
     });
   });
 
+  describe("falls back to AWS_PROFILE env when no --profile flag", () => {
+    it("allows non-destructive command with ReadOnly profile from env", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws s3 ls", { AWS_PROFILE: "ko-ReadOnly" }),
+      );
+      expect(result.verdict).toBe(ALLOW);
+    });
+
+    it("allows piped non-destructive command with ReadOnly env", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws ec2 describe-instances | head -20", { AWS_PROFILE: "ko-Auditor" }),
+      );
+      expect(result.verdict).toBe(ALLOW);
+    });
+
+    it("requires approval for Admin profile from env", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws s3 ls", { AWS_PROFILE: "ko-Admin" }),
+      );
+      expect(result.verdict).toBe(NEXT);
+    });
+
+    it("requires approval for destructive command regardless of ReadOnly env", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws s3 rm s3://bucket/key", { AWS_PROFILE: "ko-ReadOnly" }),
+      );
+      expect(result.verdict).toBe(NEXT);
+    });
+
+    it("--profile flag wins over AWS_PROFILE env", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws s3 ls --profile ko-Admin", { AWS_PROFILE: "ko-ReadOnly" }),
+      );
+      expect(result.verdict).toBe(NEXT);
+    });
+
+    it("falls through when env profile is unknown", async () => {
+      const result = await allowAwsCli.handler(
+        bash("aws s3 ls", { AWS_PROFILE: "ko-Developer" }),
+      );
+      expect(result.verdict).toBe(NEXT);
+    });
+  });
+
   describe("case-insensitive profile matching", () => {
     it("matches readonly case-insensitively", async () => {
       const result = await allowAwsCli.handler(bash("aws s3 ls --profile ko-readonly"));

From c2699a63f273c7d43970067cf0b0c6e563ad3ec4 Mon Sep 17 00:00:00 2001
From: Luke Boyle <me@lukeboyle.com>
Date: Tue, 9 Jun 2026 11:28:12 +1000
Subject: [PATCH 6/6] feat: add ask() verdict + docker/subshell/toolgate-cli
 policies

- ASK verdict short-circuits the policy chain like allow/deny, emitting
  permissionDecision='ask' to force a prompt regardless of settings.json
  auto-allows. Used by ko-work's "Ask before Xero writes" project policy.
  Exposed as ask(reason?) helper from src/index.
- New built-in policies:
  - allow-docker-read-only, allow-docker-compose-exec-mysql-readonly,
    allow-docker-compose-exec-tests for non-destructive docker use
  - allow-subshell-cd-test for cd-in-subshell patterns used by tests
  - allow-toolgate-cli-readonly for toolgate's own read-only CLI subcommands
  - allow-rm-project-tmp expanded for additional temp paths
- runner.ts now logs every NEXT-verdict tool call to
  ~/.claude/permission-requests.jsonl for audit visibility.
- Version 0.7.0 -> 0.10.0

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 package.json                                  |   2 +-
 policies/_test-runners.ts                     |  47 +++
 ...llow-docker-compose-exec-mysql-readonly.ts | 341 ++++++++++++++++++
 policies/allow-docker-compose-exec-tests.ts   | 105 ++++++
 policies/allow-docker-read-only.ts            |  97 +++++
 policies/allow-rm-project-tmp.ts              |  12 +-
 policies/allow-subshell-cd-test.ts            | 149 ++++++++
 policies/allow-toolgate-cli-readonly.ts       |  47 +++
 policies/index.ts                             |  10 +
 ...docker-compose-exec-mysql-readonly.test.ts | 119 ++++++
 .../allow-docker-compose-exec-tests.test.ts   | 104 ++++++
 policies/tests/allow-docker-read-only.test.ts | 139 +++++++
 policies/tests/allow-rm-project-tmp.test.ts   |  18 +
 policies/tests/allow-subshell-cd-test.test.ts |  85 +++++
 .../tests/allow-toolgate-cli-readonly.test.ts |  59 +++
 src/index.ts                                  |   2 +-
 src/policy.ts                                 |   2 +-
 src/runner.ts                                 |  20 +-
 src/types.ts                                  |   3 +-
 src/verdicts.ts                               |   7 +-
 20 files changed, 1359 insertions(+), 9 deletions(-)
 create mode 100644 policies/_test-runners.ts
 create mode 100644 policies/allow-docker-compose-exec-mysql-readonly.ts
 create mode 100644 policies/allow-docker-compose-exec-tests.ts
 create mode 100644 policies/allow-docker-read-only.ts
 create mode 100644 policies/allow-subshell-cd-test.ts
 create mode 100644 policies/allow-toolgate-cli-readonly.ts
 create mode 100644 policies/tests/allow-docker-compose-exec-mysql-readonly.test.ts
 create mode 100644 policies/tests/allow-docker-compose-exec-tests.test.ts
 create mode 100644 policies/tests/allow-docker-read-only.test.ts
 create mode 100644 policies/tests/allow-subshell-cd-test.test.ts
 create mode 100644 policies/tests/allow-toolgate-cli-readonly.test.ts

diff --git a/package.json b/package.json
index ce154b1..12b3af6 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@brycehanscomb/toolgate",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "devDependencies": {
     "bun-types": "latest"
   },
diff --git a/policies/_test-runners.ts b/policies/_test-runners.ts
new file mode 100644
index 0000000..b6e25ac
--- /dev/null
+++ b/policies/_test-runners.ts
@@ -0,0 +1,47 @@
+/**
+ * Shared allowlist of test-runner command prefixes. Used by policies that
+ * permit running a test runner in various contexts (docker compose exec,
+ * subshell-wrapped cd, etc.).
+ *
+ * Each entry is an ordered token prefix. A command matches if its first
+ * N tokens equal the prefix exactly; the rest are treated as opaque args.
+ */
+export const TEST_RUNNER_PREFIXES: readonly (readonly string[])[] = [
+  // PHP / Laravel
+  ["php", "artisan", "test"],
+  ["php", "vendor/bin/phpunit"],
+  ["php", "vendor/bin/pest"],
+  ["php", "vendor/bin/phpstan"],
+  ["vendor/bin/phpunit"],
+  ["vendor/bin/pest"],
+  ["vendor/bin/phpstan"],
+  ["./vendor/bin/phpunit"],
+  ["./vendor/bin/pest"],
+  ["./vendor/bin/phpstan"],
+  // JS / TS
+  ["bun", "test"],
+  ["npm", "test"],
+  ["pnpm", "test"],
+  ["yarn", "test"],
+  // Python
+  ["pytest"],
+  ["python", "-m", "pytest"],
+  ["python", "-m", "unittest"],
+  ["python3", "-m", "pytest"],
+  ["python3", "-m", "unittest"],
+];
+
+export function matchesTestRunner(tokens: string[], start = 0): boolean {
+  for (const prefix of TEST_RUNNER_PREFIXES) {
+    if (tokens.length - start < prefix.length) continue;
+    let ok = true;
+    for (let i = 0; i < prefix.length; i++) {
+      if (tokens[start + i] !== prefix[i]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) return true;
+  }
+  return false;
+}
diff --git a/policies/allow-docker-compose-exec-mysql-readonly.ts b/policies/allow-docker-compose-exec-mysql-readonly.ts
new file mode 100644
index 0000000..199ae28
--- /dev/null
+++ b/policies/allow-docker-compose-exec-mysql-readonly.ts
@@ -0,0 +1,341 @@
+import type { ToolCall } from "../src";
+import { allow, next, type Policy } from "../src";
+import {
+  Op,
+  type BinaryCmd,
+  type DblQuoted,
+  type Lit,
+  type SglQuoted,
+  type Stmt,
+  type Word,
+  getArgs,
+  hasUnsafeNodes,
+  isSafeFilter,
+  parseShell,
+  wordToString,
+} from "./parse-bash-ast";
+
+/**
+ * Permit read-only mysql queries through `docker compose exec`. Supports two
+ * forms:
+ *
+ *   docker compose [flags] exec [flags] <svc> mysql [flags...] -e '<SQL>'
+ *   docker compose [flags] exec [flags] <svc> sh -c "mysql [flags...] -e '<SQL>'"
+ *
+ * The whole thing may optionally be piped to safe filters (head/tail/grep/etc).
+ * `<SQL>` must be one or more read-only statements (SELECT/SHOW/DESC/EXPLAIN/...).
+ */
+
+const COMPOSE_FLAGS_WITH_VALUE = new Set([
+  "-f", "--file",
+  "--env-file",
+  "-p", "--project-name",
+  "--project-directory",
+  "--profile",
+  "--ansi",
+  "--progress",
+  "--parallel",
+]);
+
+const EXEC_FLAGS_WITH_VALUE = new Set([
+  "-u", "--user",
+  "-w", "--workdir",
+  "-e", "--env",
+  "--index",
+]);
+
+const EXEC_BOOLEAN_FLAGS = new Set([
+  "-T",
+  "--no-TTY",
+  "-i", "--interactive",
+  "-t", "--tty",
+]);
+
+const EXEC_FORBIDDEN_FLAGS = new Set([
+  "-d", "--detach",
+  "--privileged",
+]);
+
+const MYSQL_FLAGS_WITH_VALUE = new Set([
+  "-h", "--host",
+  "-u", "--user",
+  "-P", "--port",
+  "-S", "--socket",
+  "-D", "--database",
+  "--default-character-set",
+  "--protocol",
+  "--connect-timeout",
+]);
+
+// Flags like `-p` and `-pPASSWORD` (mysql lets you concat the password) — the
+// value form `-p` followed by separate token *prompts* interactively, which
+// blocks. The concatenated form `-pPASSWORD` is a single token. We treat any
+// lone `-p` as boolean (no value consumed) since requiring a value tends to
+// hang anyway.
+const MYSQL_BOOLEAN_OR_CONCAT_FLAGS = new Set([
+  "-p",
+  "--password",
+  "-N", "--skip-column-names",
+  "-s", "--silent",
+  "-v", "--verbose",
+  "-t", "--table",
+  "-B", "--batch",
+  "-X", "--xml",
+  "--html",
+  "-r", "--raw",
+  "--vertical",
+  "-E",
+  "--show-warnings",
+  "--ssl",
+  "--ssl-mode=DISABLED",
+]);
+
+const READ_ONLY_SQL_VERBS = new Set([
+  "SELECT", "SHOW", "DESCRIBE", "DESC", "EXPLAIN", "USE", "HELP", "WITH", "VALUES",
+]);
+
+function isReadOnlySql(sql: string): boolean {
+  // Reject SQL comments — they can hide payload.
+  if (sql.includes("--") || sql.includes("/*") || sql.includes("#")) return false;
+  const stmts = sql.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (stmts.length === 0) return false;
+  for (const stmt of stmts) {
+    const firstWord = stmt.split(/\s+/)[0]?.toUpperCase();
+    if (!firstWord || !READ_ONLY_SQL_VERBS.has(firstWord)) return false;
+  }
+  return true;
+}
+
+/**
+ * Resolve a Word to a static string, allowing mixed Lit + single/double-quoted
+ * parts (including DblQuoted that wraps further Lit/SglQuoted). Returns null
+ * if any part involves expansion (ParamExp, CmdSubst, ArithmExp, ProcSubst).
+ */
+function staticString(word: Word): string | null {
+  const out: string[] = [];
+  for (const part of word.Parts) {
+    if (part.Type === "Lit") {
+      out.push((part as Lit).Value);
+    } else if (part.Type === "SglQuoted") {
+      out.push((part as SglQuoted).Value);
+    } else if (part.Type === "DblQuoted") {
+      const dbl = part as DblQuoted;
+      for (const inner of dbl.Parts ?? []) {
+        if (inner.Type === "Lit") {
+          out.push((inner as Lit).Value);
+        } else if (inner.Type === "SglQuoted") {
+          out.push((inner as SglQuoted).Value);
+        } else {
+          return null;
+        }
+      }
+    } else {
+      return null;
+    }
+  }
+  return out.join("");
+}
+
+/** Re-parse a string and return its single CallExpr's args, or null. */
+async function reparseToCallExpr(s: string): Promise<string[] | null> {
+  const file = await parseShell(s);
+  if (!file) return null;
+  if (file.Stmts.length !== 1) return null;
+  if (hasUnsafeNodes(file)) return null;
+  const stmt = file.Stmts[0];
+  if (stmt.Background || stmt.Negated) return null;
+  if ((stmt as any).Comments?.length > 0) return null;
+  if (stmt.Redirs && stmt.Redirs.length > 0) return null;
+  if (stmt.Cmd?.Type !== "CallExpr") return null;
+  return getArgs(stmt);
+}
+
+/** Walk past flags, returning index of the next positional arg or null. */
+function skipFlags(
+  tokens: string[],
+  start: number,
+  flagsWithValue: Set<string>,
+  booleanFlags: Set<string> | null,
+  forbiddenFlags: Set<string> | null,
+): number | null {
+  let i = start;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (!t.startsWith("-")) return i;
+    if (forbiddenFlags && forbiddenFlags.has(t)) return null;
+    if (t.includes("=")) {
+      const flagName = t.slice(0, t.indexOf("="));
+      if (forbiddenFlags && forbiddenFlags.has(flagName)) return null;
+      i += 1;
+      continue;
+    }
+    if (flagsWithValue.has(t)) {
+      i += 2;
+      continue;
+    }
+    if (!booleanFlags || booleanFlags.has(t)) {
+      i += 1;
+      continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Validate that `mysql [flags...] -e <SQL> [...]` is read-only. Every -e
+ * value must be read-only SQL. Returns true if the command is a safe mysql
+ * invocation.
+ */
+function isReadOnlyMysqlCall(tokens: string[]): boolean {
+  if (tokens[0] !== "mysql") return false;
+  let sawDashE = false;
+  let i = 1;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (t === "-e" || t === "--execute") {
+      if (i + 1 >= tokens.length) return false;
+      const sql = tokens[i + 1];
+      if (!isReadOnlySql(sql)) return false;
+      sawDashE = true;
+      i += 2;
+      continue;
+    }
+    // --execute=SQL or --execute='SQL'
+    if (t.startsWith("--execute=")) {
+      const sql = t.slice("--execute=".length);
+      if (!isReadOnlySql(sql)) return false;
+      sawDashE = true;
+      i += 1;
+      continue;
+    }
+    if (MYSQL_FLAGS_WITH_VALUE.has(t)) {
+      i += 2;
+      continue;
+    }
+    if (t.includes("=") && t.startsWith("--")) {
+      i += 1;
+      continue;
+    }
+    if (MYSQL_BOOLEAN_OR_CONCAT_FLAGS.has(t)) {
+      i += 1;
+      continue;
+    }
+    // Concatenated flag forms (-pPASS, -hHOST, -uUSER, etc.) — single token.
+    if (t.startsWith("-") && t.length > 2 && !t.startsWith("--")) {
+      i += 1;
+      continue;
+    }
+    // --long=value already handled above; any other --long flag we don't
+    // recognise → bail (could change behavior unexpectedly).
+    if (t.startsWith("--")) {
+      i += 1;
+      continue;
+    }
+    // Positional arg (e.g. database name without -D) — accept.
+    i += 1;
+  }
+  return sawDashE;
+}
+
+/**
+ * Walk the outermost stmt as: 0+ pipes to safe filters, with our target
+ * docker-compose call at the leftmost leaf.
+ */
+function unwrapTopLevelPipes(stmt: Stmt): { leaf: Stmt } | null {
+  let cur: Stmt = stmt;
+  if (cur.Background || cur.Negated) return null;
+  if ((cur as any).Comments?.length > 0) return null;
+  while (cur.Cmd?.Type === "BinaryCmd") {
+    const bin = cur.Cmd as BinaryCmd;
+    if (bin.Op !== Op.Pipe) return null;
+    if (bin.Y.Background || bin.Y.Negated) return null;
+    const rightArgs = getArgs(bin.Y);
+    if (!rightArgs || !isSafeFilter(rightArgs)) return null;
+    cur = bin.X;
+  }
+  return { leaf: cur };
+}
+
+async function check(call: ToolCall): Promise<boolean> {
+  if (call.tool !== "Bash") return false;
+  const command = call.args?.command;
+  if (typeof command !== "string") return false;
+
+  const file = await parseShell(command);
+  if (!file) return false;
+  if (file.Stmts.length !== 1) return false;
+  if (hasUnsafeNodes(file)) return false;
+
+  const unwrapped = unwrapTopLevelPipes(file.Stmts[0]);
+  if (!unwrapped) return false;
+  const leaf = unwrapped.leaf;
+  if (leaf.Cmd?.Type !== "CallExpr") return false;
+  if (leaf.Background || leaf.Negated) return false;
+
+  // Extract docker compose [flags] exec [flags] <svc> <rest...>
+  // We need the raw Word array because the inner sh -c arg may be a multi-part
+  // quoted string that wordToString rejects. Walk args manually.
+  const argWords = (leaf.Cmd as any).Args as Word[];
+  if (!argWords || argWords.length < 4) return false;
+
+  // Resolve each Word to a string using staticString (allows multi-part static).
+  const tokens: string[] = [];
+  for (const w of argWords) {
+    // Prefer wordToString for the common case; fall back to staticString.
+    const simple = wordToString(w);
+    if (simple !== null) {
+      tokens.push(simple);
+    } else {
+      const sx = staticString(w);
+      if (sx === null) return false;
+      tokens.push(sx);
+    }
+  }
+
+  if (tokens[0] !== "docker" || tokens[1] !== "compose") return false;
+
+  const execIdx = skipFlags(tokens, 2, COMPOSE_FLAGS_WITH_VALUE, null, null);
+  if (execIdx === null || tokens[execIdx] !== "exec") return false;
+
+  const serviceIdx = skipFlags(
+    tokens,
+    execIdx + 1,
+    EXEC_FLAGS_WITH_VALUE,
+    EXEC_BOOLEAN_FLAGS,
+    EXEC_FORBIDDEN_FLAGS,
+  );
+  if (serviceIdx === null) return false;
+
+  const innerStart = serviceIdx + 1;
+  if (innerStart >= tokens.length) return false;
+
+  // Direct form: docker compose exec <svc> mysql ...
+  if (tokens[innerStart] === "mysql") {
+    return isReadOnlyMysqlCall(tokens.slice(innerStart));
+  }
+
+  // sh -c form: docker compose exec <svc> sh -c "<inner>"
+  if (tokens[innerStart] === "sh" && tokens[innerStart + 1] === "-c") {
+    const inner = tokens[innerStart + 2];
+    if (inner === undefined) return false;
+    // Reject if there are extra tokens after the sh -c arg (positional $0 etc.)
+    if (innerStart + 3 !== tokens.length) return false;
+    const innerArgs = await reparseToCallExpr(inner);
+    if (!innerArgs) return false;
+    return isReadOnlyMysqlCall(innerArgs);
+  }
+
+  return false;
+}
+
+const allowDockerComposeExecMysqlReadOnly: Policy = {
+  name: "Allow docker compose exec mysql (read-only)",
+  description:
+    "Permits `docker compose exec <svc> mysql -e '<SQL>'` (and `sh -c \"mysql -e '<SQL>'\"`) when every SQL statement is read-only (SELECT/SHOW/DESC/EXPLAIN/USE/HELP/WITH/VALUES)",
+  handler: async (call) => {
+    return (await check(call)) ? allow() : next();
+  },
+};
+
+export default allowDockerComposeExecMysqlReadOnly;
diff --git a/policies/allow-docker-compose-exec-tests.ts b/policies/allow-docker-compose-exec-tests.ts
new file mode 100644
index 0000000..e42399f
--- /dev/null
+++ b/policies/allow-docker-compose-exec-tests.ts
@@ -0,0 +1,105 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+import { matchesTestRunner } from "./_test-runners";
+
+const COMPOSE_FLAGS_WITH_VALUE = new Set([
+  "-f", "--file",
+  "--env-file",
+  "-p", "--project-name",
+  "--project-directory",
+  "--profile",
+  "--ansi",
+  "--progress",
+  "--parallel",
+]);
+
+const EXEC_FLAGS_WITH_VALUE = new Set([
+  "-u", "--user",
+  "-w", "--workdir",
+  "-e", "--env",
+  "--index",
+]);
+
+// Boolean exec flags we permit (no value, just skip).
+const EXEC_BOOLEAN_FLAGS = new Set([
+  "-T",
+  "--no-TTY",
+  "-i", "--interactive",
+  "-t", "--tty",
+]);
+
+// Exec flags whose presence should reject the command — they signal
+// something other than a foreground test invocation.
+const EXEC_FORBIDDEN_FLAGS = new Set([
+  "-d", "--detach",
+  "--privileged",
+]);
+
+/** Skip flags and return the index of the next positional, or null. */
+function skipFlags(
+  tokens: string[],
+  start: number,
+  flagsWithValue: Set<string>,
+  booleanFlags: Set<string> | null,
+  forbiddenFlags: Set<string> | null,
+): number | null {
+  let i = start;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (!t.startsWith("-")) return i;
+    if (forbiddenFlags && forbiddenFlags.has(t)) return null;
+    if (t.includes("=")) {
+      // --flag=value — must not be a forbidden flag
+      const eqIdx = t.indexOf("=");
+      const flagName = t.slice(0, eqIdx);
+      if (forbiddenFlags && forbiddenFlags.has(flagName)) return null;
+      i += 1;
+      continue;
+    }
+    if (flagsWithValue.has(t)) {
+      i += 2;
+      continue;
+    }
+    if (!booleanFlags || booleanFlags.has(t)) {
+      i += 1;
+      continue;
+    }
+    // Unknown flag — bail out conservatively.
+    return null;
+  }
+  return null;
+}
+
+const allowDockerComposeExecTests: Policy = {
+  name: "Allow docker compose exec test runners",
+  description:
+    "Permits `docker compose exec <service> <test-cmd>` when the inner command is a known test runner (php artisan test, phpunit, pest, bun test, pytest, etc.)",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens) return next();
+    if (tokens[0] !== "docker" || tokens[1] !== "compose") return next();
+
+    // Skip compose-level flags.
+    const execIdx = skipFlags(tokens, 2, COMPOSE_FLAGS_WITH_VALUE, null, null);
+    if (execIdx === null) return next();
+    if (tokens[execIdx] !== "exec") return next();
+
+    // Skip exec-level flags (rejecting forbidden ones).
+    const serviceIdx = skipFlags(
+      tokens,
+      execIdx + 1,
+      EXEC_FLAGS_WITH_VALUE,
+      EXEC_BOOLEAN_FLAGS,
+      EXEC_FORBIDDEN_FLAGS,
+    );
+    if (serviceIdx === null) return next();
+
+    // Service name is a single positional, then the inner command begins.
+    const innerStart = serviceIdx + 1;
+    if (innerStart >= tokens.length) return next();
+
+    return matchesTestRunner(tokens, innerStart) ? allow() : next();
+  },
+};
+
+export default allowDockerComposeExecTests;
diff --git a/policies/allow-docker-read-only.ts b/policies/allow-docker-read-only.ts
new file mode 100644
index 0000000..671fa16
--- /dev/null
+++ b/policies/allow-docker-read-only.ts
@@ -0,0 +1,97 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+// Compose CLI flags that consume the next token as a value.
+const COMPOSE_FLAGS_WITH_VALUE = new Set([
+  "-f", "--file",
+  "--env-file",
+  "-p", "--project-name",
+  "--project-directory",
+  "--profile",
+  "--ansi",
+  "--progress",
+  "--parallel",
+]);
+
+// docker <subcommand> — read-only top-level commands.
+const DOCKER_READ_ONLY = new Set([
+  "ps", "images", "logs", "inspect", "version", "info",
+  "stats", "top", "port", "events", "history", "diff",
+]);
+
+// docker <resource> <action> — read-only namespaced commands.
+const DOCKER_NAMESPACED_READ_ONLY: Record<string, Set<string>> = {
+  image: new Set(["ls", "inspect", "history"]),
+  container: new Set(["ls", "inspect", "logs", "top", "port", "diff", "stats"]),
+  network: new Set(["ls", "inspect"]),
+  volume: new Set(["ls", "inspect"]),
+  system: new Set(["info", "df", "events"]),
+  node: new Set(["ls", "inspect"]),
+  service: new Set(["ls", "inspect", "logs", "ps"]),
+  stack: new Set(["ls", "ps", "services"]),
+  context: new Set(["ls", "inspect", "show"]),
+  plugin: new Set(["ls", "inspect"]),
+  config: new Set(["ls", "inspect"]),
+  secret: new Set(["ls", "inspect"]),
+};
+
+// docker compose <subcommand> — read-only.
+const COMPOSE_READ_ONLY = new Set([
+  "ps", "logs", "top", "images", "config", "port", "ls",
+  "version", "events", "convert",
+]);
+
+/**
+ * Walk past flags (including `--flag value` pairs) and return the index of
+ * the first positional argument, or null if none.
+ */
+function findNextPositional(
+  tokens: string[],
+  start: number,
+  flagsWithValue: Set<string>,
+): number | null {
+  let i = start;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (!t.startsWith("-")) return i;
+    if (t.includes("=")) {
+      i += 1;
+      continue;
+    }
+    if (flagsWithValue.has(t)) {
+      i += 2;
+      continue;
+    }
+    i += 1;
+  }
+  return null;
+}
+
+const allowDockerReadOnly: Policy = {
+  name: "Allow docker read-only",
+  description:
+    "Permits read-only docker / docker compose subcommands (ps, logs, inspect, config, etc.)",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens || tokens[0] !== "docker") return next();
+
+    // docker compose [compose-flags] <subcommand>
+    if (tokens[1] === "compose") {
+      const subIdx = findNextPositional(tokens, 2, COMPOSE_FLAGS_WITH_VALUE);
+      if (subIdx === null) return next();
+      return COMPOSE_READ_ONLY.has(tokens[subIdx]) ? allow() : next();
+    }
+
+    const sub = tokens[1];
+    if (!sub) return next();
+
+    if (DOCKER_READ_ONLY.has(sub)) return allow();
+
+    const namespaced = DOCKER_NAMESPACED_READ_ONLY[sub];
+    if (namespaced && tokens[2] && namespaced.has(tokens[2])) return allow();
+
+    return next();
+  },
+};
+
+export default allowDockerReadOnly;
diff --git a/policies/allow-rm-project-tmp.ts b/policies/allow-rm-project-tmp.ts
index 5e8d11c..430cdc4 100644
--- a/policies/allow-rm-project-tmp.ts
+++ b/policies/allow-rm-project-tmp.ts
@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { allow, next, type Policy } from "../src";
+import { isWithinProject } from "../src/project-dirs";
 import { safeBashCommand } from "./parse-bash-ast";
 
 /**
@@ -10,14 +11,19 @@ import { safeBashCommand } from "./parse-bash-ast";
 const allowRmProjectTmp: Policy = {
   name: "Allow rm in project tmp/",
   description:
-    "Permits rm commands when all targets are within the project's tmp/ directory",
+    "Permits rm commands when all targets are within the project's tmp/ directory (or a worktree-local tmp/ when cwd is inside the project)",
   handler: async (call) => {
     const args = await safeBashCommand(call);
     if (!args || args[0] !== "rm") return next();
     if (!call.context.projectRoot) return next();
 
-    const tmpDirs = [call.context.projectRoot, ...(call.context.additionalDirs ?? [])]
-      .map((d) => resolve(d, "tmp"));
+    const baseDirs = [call.context.projectRoot, ...(call.context.additionalDirs ?? [])];
+    // Worktrees live under <projectRoot>/.claude/worktrees/<name> with their
+    // own tmp/. Treat cwd/tmp as a valid target when cwd is inside the project.
+    if (isWithinProject(call.context.cwd, call.context)) {
+      baseDirs.push(call.context.cwd);
+    }
+    const tmpDirs = baseDirs.map((d) => resolve(d, "tmp"));
     const flags = args.slice(1).filter((t) => t.startsWith("-"));
     const paths = args.slice(1).filter((t) => !t.startsWith("-"));
 
diff --git a/policies/allow-subshell-cd-test.ts b/policies/allow-subshell-cd-test.ts
new file mode 100644
index 0000000..6e98255
--- /dev/null
+++ b/policies/allow-subshell-cd-test.ts
@@ -0,0 +1,149 @@
+import type { ToolCall } from "../src";
+import { allow, next, type Policy } from "../src";
+import {
+  Op,
+  type BinaryCmd,
+  type Stmt,
+  getArgs,
+  hasUnsafeNodes,
+  isSafeFilter,
+  parseShell,
+  wordToString,
+} from "./parse-bash-ast";
+import { matchesTestRunner } from "./_test-runners";
+
+/**
+ * Permit `(cd <path> && <test-runner>)` and pipelined variants. The subshell
+ * confines the cd to the child shell so the parent cwd is unchanged, and the
+ * inner command is constrained to a known test runner.
+ *
+ * Accepted shapes (where TR is a known test runner; F is a safe filter like
+ * head/tail/grep; R is a safe redirect like 2>&1):
+ *
+ *   (cd X && TR [R])
+ *   (cd X && TR [R] | F [| F]...)
+ *   (cd X && TR [R]) | F [| F]...
+ */
+
+const SAFE_REDIRECT_TARGETS = new Set(["/dev/null", "/dev/stderr", "/dev/stdout"]);
+
+function hasOnlySafeRedirects(stmt: Stmt): boolean {
+  if (!stmt.Redirs) return true;
+  for (const r of stmt.Redirs) {
+    if (r.Op === Op.DplOut) continue; // 2>&1
+    if (r.N) {
+      const target = wordToString(r.Word);
+      if (target && SAFE_REDIRECT_TARGETS.has(target)) continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+function isCleanStmt(stmt: Stmt): boolean {
+  if (stmt.Background) return false;
+  if (stmt.Negated) return false;
+  if ((stmt as any).Comments?.length > 0) return false;
+  if (!hasOnlySafeRedirects(stmt)) return false;
+  return true;
+}
+
+/**
+ * Walk a pipeline from the leftmost end. The leaf must be a CallExpr; all
+ * intermediate right-hand sides must be safe filters. Returns the leaf args,
+ * or null if the shape is invalid.
+ */
+function extractPipelineLeaf(stmt: Stmt): string[] | null {
+  if (!isCleanStmt(stmt)) return null;
+  let cur: Stmt = stmt;
+  while (cur.Cmd?.Type === "BinaryCmd") {
+    const bin = cur.Cmd as BinaryCmd;
+    if (bin.Op !== Op.Pipe) return null;
+    if (!isCleanStmt(bin.Y)) return null;
+    const rightArgs = getArgs(bin.Y);
+    if (!rightArgs || !isSafeFilter(rightArgs)) return null;
+    cur = bin.X;
+  }
+  if (cur.Cmd?.Type !== "CallExpr") return null;
+  if (!isCleanStmt(cur)) return null;
+  return getArgs(cur);
+}
+
+interface SubshellWithFilters {
+  subshellStmts: Stmt[];
+}
+
+/**
+ * Walk the outermost statement: zero or more pipes to safe filters, with a
+ * Subshell at the leftmost leaf.
+ */
+function extractOuterSubshell(stmt: Stmt): SubshellWithFilters | null {
+  if (!isCleanStmt(stmt)) return null;
+  let cur: Stmt = stmt;
+  while (cur.Cmd?.Type === "BinaryCmd") {
+    const bin = cur.Cmd as BinaryCmd;
+    if (bin.Op !== Op.Pipe) return null;
+    if (!isCleanStmt(bin.Y)) return null;
+    const rightArgs = getArgs(bin.Y);
+    if (!rightArgs || !isSafeFilter(rightArgs)) return null;
+    cur = bin.X;
+  }
+  const cmd = cur.Cmd as any;
+  if (!cmd || cmd.Type !== "Subshell") return null;
+  if (!isCleanStmt(cur)) return null;
+  if (!Array.isArray(cmd.Stmts)) return null;
+  return { subshellStmts: cmd.Stmts };
+}
+
+function isCdStmt(stmt: Stmt): boolean {
+  if (!isCleanStmt(stmt)) return false;
+  if (stmt.Cmd?.Type !== "CallExpr") return false;
+  const args = getArgs(stmt);
+  if (!args) return false;
+  // `cd <path>` — exactly one positional path argument, no flags.
+  if (args.length !== 2) return false;
+  if (args[0] !== "cd") return false;
+  if (args[1].startsWith("-")) return false;
+  return true;
+}
+
+async function check(call: ToolCall): Promise<boolean> {
+  if (call.tool !== "Bash") return false;
+  const command = call.args?.command;
+  if (typeof command !== "string") return false;
+
+  const file = await parseShell(command);
+  if (!file) return false;
+  if (file.Stmts.length !== 1) return false;
+  // Reject any unsafe nodes anywhere in the tree (command/param/process subst).
+  if (hasUnsafeNodes(file)) return false;
+
+  const outer = extractOuterSubshell(file.Stmts[0]);
+  if (!outer) return false;
+  if (outer.subshellStmts.length !== 1) return false;
+
+  const inner = outer.subshellStmts[0];
+  if (!isCleanStmt(inner)) return false;
+  if (inner.Cmd?.Type !== "BinaryCmd") return false;
+  const bin = inner.Cmd as BinaryCmd;
+  if (bin.Op !== Op.And) return false;
+
+  // Left: cd <path>
+  if (!isCdStmt(bin.X)) return false;
+
+  // Right: test runner, optionally piped to safe filters.
+  const leafArgs = extractPipelineLeaf(bin.Y);
+  if (!leafArgs) return false;
+  return matchesTestRunner(leafArgs);
+}
+
+const allowSubshellCdTest: Policy = {
+  name: "Allow (cd && test) subshell",
+  description:
+    "Permits `(cd <path> && <test-runner>)` and pipelined variants — the subshell isolates the cd so cwd is unchanged",
+  handler: async (call) => {
+    return (await check(call)) ? allow() : next();
+  },
+};
+
+export default allowSubshellCdTest;
diff --git a/policies/allow-toolgate-cli-readonly.ts b/policies/allow-toolgate-cli-readonly.ts
new file mode 100644
index 0000000..8a1d2a6
--- /dev/null
+++ b/policies/allow-toolgate-cli-readonly.ts
@@ -0,0 +1,47 @@
+import { allow, next, type Policy } from "../src";
+import { safeBashCommandOrPipeline } from "./parse-bash-ast";
+
+/**
+ * Permit read-only toolgate CLI subcommands:
+ *   toolgate test <tool> [args]   — dry-run policy evaluation (no side effects)
+ *   toolgate list                 — list loaded policies
+ *   toolgate logs                 — print log file paths
+ *   toolgate audit [--json]       — analyse settings.local.json against policies
+ *   toolgate disable --json       — dump policy/disable state as JSON
+ *
+ * Excludes `init`, `run`, `suspend`, and interactive `disable` — those mutate
+ * config or are hook-only invocations and should still prompt.
+ */
+
+const READ_ONLY_SUBCOMMANDS = new Set([
+  "test",
+  "list",
+  "logs",
+  "audit",
+]);
+
+const allowToolgateCliReadOnly: Policy = {
+  name: "Allow toolgate CLI read-only",
+  description:
+    "Permits read-only toolgate CLI subcommands (test, list, logs, audit, disable --json)",
+  handler: async (call) => {
+    const tokens = await safeBashCommandOrPipeline(call);
+    if (!tokens) return next();
+    if (tokens[0] !== "toolgate") return next();
+
+    const sub = tokens[1];
+    if (!sub) return next();
+
+    if (READ_ONLY_SUBCOMMANDS.has(sub)) return allow();
+
+    // `toolgate disable --json` is read-only (TUI variant is not).
+    if (sub === "disable") {
+      if (tokens.slice(2).some((t) => t === "--json")) return allow();
+      return next();
+    }
+
+    return next();
+  },
+};
+
+export default allowToolgateCliReadOnly;
diff --git a/policies/index.ts b/policies/index.ts
index e5d4921..2db203a 100644
--- a/policies/index.ts
+++ b/policies/index.ts
@@ -65,6 +65,11 @@ import allowMcpAtlassian from "./allow-mcp-atlassian";
 import allowGo from "./allow-go";
 import allowLsof from "./allow-lsof";
 import allowCdk from "./allow-cdk";
+import allowDockerReadOnly from "./allow-docker-read-only";
+import allowDockerComposeExecTests from "./allow-docker-compose-exec-tests";
+import allowSubshellCdTest from "./allow-subshell-cd-test";
+import allowDockerComposeExecMysqlReadOnly from "./allow-docker-compose-exec-mysql-readonly";
+import allowToolgateCliReadOnly from "./allow-toolgate-cli-readonly";
 
 export const builtinPolicies = [
   denyGitAddAndCommit,
@@ -134,4 +139,9 @@ export const builtinPolicies = [
   allowGo,
   allowLsof,
   allowCdk,
+  allowDockerReadOnly,
+  allowDockerComposeExecTests,
+  allowSubshellCdTest,
+  allowDockerComposeExecMysqlReadOnly,
+  allowToolgateCliReadOnly,
 ];
diff --git a/policies/tests/allow-docker-compose-exec-mysql-readonly.test.ts b/policies/tests/allow-docker-compose-exec-mysql-readonly.test.ts
new file mode 100644
index 0000000..f59caf1
--- /dev/null
+++ b/policies/tests/allow-docker-compose-exec-mysql-readonly.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
+import allowDockerComposeExecMysqlReadOnly from "../allow-docker-compose-exec-mysql-readonly";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/home/user/project", env: {}, projectRoot: "/home/user/project" },
+  };
+}
+
+describe("allow-docker-compose-exec-mysql-readonly", () => {
+  describe("allows read-only mysql via direct exec", () => {
+    const allowed = [
+      "docker compose exec app mysql -e 'SHOW DATABASES;'",
+      "docker compose exec app mysql -h 127.0.0.1 -uroot -proot -e 'SELECT 1;'",
+      "docker compose exec -T app mysql -e 'SHOW TABLES;'",
+      "docker compose -f compose.yml exec app mysql -e 'DESCRIBE users;'",
+      "docker compose exec app mysql -e 'EXPLAIN SELECT * FROM users;'",
+      "docker compose exec app mysql -e 'USE db; SHOW TABLES;'",
+      "docker compose exec app mysql --execute='SELECT NOW();'",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecMysqlReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("allows read-only mysql via sh -c", () => {
+    const allowed = [
+      `docker compose exec app sh -c "mysql -e 'SHOW DATABASES;'"`,
+      `docker compose exec app sh -c "mysql -h127.0.0.1 -uroot -proot -e 'SHOW DATABASES;'"`,
+      // The reported failing case:
+      `docker compose --env-file .worktree-env -f docker-compose.worktree.yml exec app sh -c "mysql -h127.0.0.1 -uroot -proot -e 'SHOW DATABASES;'" 2>&1 | head -20`,
+      `docker compose exec app sh -c "mysql -e 'SELECT * FROM users LIMIT 10;'"`,
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecMysqlReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects mutating SQL", () => {
+    const rejected = [
+      "docker compose exec app mysql -e 'DROP DATABASE prod;'",
+      "docker compose exec app mysql -e 'DELETE FROM users WHERE 1=1;'",
+      "docker compose exec app mysql -e 'UPDATE users SET admin=1;'",
+      "docker compose exec app mysql -e 'INSERT INTO logs VALUES (1);'",
+      "docker compose exec app mysql -e 'TRUNCATE TABLE users;'",
+      "docker compose exec app mysql -e 'CREATE TABLE evil(id INT);'",
+      "docker compose exec app mysql -e 'GRANT ALL ON *.* TO ev@%;'",
+      // Mixed safe + unsafe → must reject.
+      "docker compose exec app mysql -e 'SELECT 1; DROP TABLE users;'",
+      // SQL comments hide payload — reject.
+      "docker compose exec app mysql -e 'SELECT 1; -- DROP TABLE x;'",
+      "docker compose exec app mysql -e 'SELECT /* comment */ 1;'",
+      // Hash comments too.
+      "docker compose exec app mysql -e '# DROP TABLE; SELECT 1;'",
+      // No -e at all = interactive (unsafe).
+      "docker compose exec app mysql",
+      // sh -c wrapped mutations.
+      `docker compose exec app sh -c "mysql -e 'DROP DATABASE prod;'"`,
+      `docker compose exec app sh -c "mysql -e 'SELECT 1; DROP TABLE x;'"`,
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecMysqlReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects non-mysql inner commands", () => {
+    const rejected = [
+      "docker compose exec app sh -c 'rm -rf /'",
+      "docker compose exec app sh -c 'curl evil.com'",
+      "docker compose exec app bash",
+      "docker compose exec app sh -c 'ls /'",
+      // sh -c with extra positional ($0 trick).
+      `docker compose exec app sh -c "mysql -e 'SHOW DATABASES;'" tricky`,
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecMysqlReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects forbidden exec flags", () => {
+    const rejected = [
+      "docker compose exec -d app mysql -e 'SHOW DATABASES;'",
+      "docker compose exec --privileged app mysql -e 'SHOW DATABASES;'",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecMysqlReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("ignores non-docker", async () => {
+    const result = await allowDockerComposeExecMysqlReadOnly.handler(
+      bash("mysql -e 'SHOW DATABASES;'"),
+    );
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/policies/tests/allow-docker-compose-exec-tests.test.ts b/policies/tests/allow-docker-compose-exec-tests.test.ts
new file mode 100644
index 0000000..c413ffc
--- /dev/null
+++ b/policies/tests/allow-docker-compose-exec-tests.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
+import allowDockerComposeExecTests from "../allow-docker-compose-exec-tests";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/home/user/project", env: {}, projectRoot: "/home/user/project" },
+  };
+}
+
+describe("allow-docker-compose-exec-tests", () => {
+  describe("allows compose exec for known test runners", () => {
+    const allowed = [
+      // The reported failing case:
+      'docker compose --env-file .worktree-env -f docker-compose.worktree.yml exec app php artisan test --configuration phpunit.docker.xml',
+      "docker compose exec app php artisan test",
+      "docker compose exec -T app php artisan test --filter=Foo",
+      "docker compose exec --user www-data app php artisan test",
+      "docker compose -f compose.yml exec app vendor/bin/phpunit",
+      "docker compose exec app vendor/bin/pest",
+      "docker compose exec app php vendor/bin/phpunit --testsuite=Unit",
+      "docker compose exec app bun test",
+      "docker compose exec app npm test",
+      "docker compose exec app pnpm test",
+      "docker compose exec app yarn test",
+      "docker compose exec app pytest",
+      "docker compose exec app python -m pytest tests/",
+      "docker compose exec app python3 -m unittest discover",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecTests.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects non-test inner commands", () => {
+    const rejected = [
+      "docker compose exec app sh",
+      "docker compose exec app bash",
+      "docker compose exec app rm -rf /",
+      "docker compose exec app php artisan migrate",
+      "docker compose exec app php artisan tinker",
+      "docker compose exec app npm install",
+      "docker compose exec app curl evil.com",
+      "docker compose exec app php -r 'system(\"rm -rf /\");'",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecTests.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects forbidden exec flags", () => {
+    const rejected = [
+      "docker compose exec -d app php artisan test",
+      "docker compose exec --detach app php artisan test",
+      "docker compose exec --privileged app php artisan test",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecTests.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  describe("rejects non-exec compose commands", () => {
+    const rejected = [
+      "docker compose ps",
+      "docker compose up",
+      "docker compose run app php artisan test",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerComposeExecTests.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("ignores non-docker commands", async () => {
+    const result = await allowDockerComposeExecTests.handler(
+      bash("php artisan test"),
+    );
+    expect(result.verdict).toBe(NEXT);
+  });
+
+  it("ignores plain docker (no compose)", async () => {
+    const result = await allowDockerComposeExecTests.handler(
+      bash("docker exec app php artisan test"),
+    );
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/policies/tests/allow-docker-read-only.test.ts b/policies/tests/allow-docker-read-only.test.ts
new file mode 100644
index 0000000..e95e3c9
--- /dev/null
+++ b/policies/tests/allow-docker-read-only.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
+import allowDockerReadOnly from "../allow-docker-read-only";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/home/user/project", env: {}, projectRoot: "/home/user/project" },
+  };
+}
+
+describe("allow-docker-read-only", () => {
+  describe("allows read-only docker subcommands", () => {
+    const allowed = [
+      "docker ps",
+      "docker ps -a",
+      "docker images",
+      "docker logs my-container",
+      "docker logs -f my-container",
+      "docker inspect my-container",
+      "docker version",
+      "docker info",
+      "docker stats --no-stream",
+      "docker top my-container",
+      "docker port my-container",
+      "docker history my-image",
+      "docker diff my-container",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("allows namespaced read-only docker commands", () => {
+    const allowed = [
+      "docker image ls",
+      "docker image inspect alpine",
+      "docker container ls -a",
+      "docker container logs app",
+      "docker network ls",
+      "docker network inspect bridge",
+      "docker volume ls",
+      "docker volume inspect data",
+      "docker system info",
+      "docker system df",
+      "docker service ls",
+      "docker stack ps mystack",
+      "docker context ls",
+      "docker plugin ls",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("allows read-only docker compose subcommands", () => {
+    const allowed = [
+      "docker compose ps",
+      "docker compose ps -a",
+      "docker compose logs",
+      "docker compose logs -f app",
+      "docker compose top",
+      "docker compose images",
+      "docker compose config",
+      "docker compose ls",
+      "docker compose version",
+      // The reported failing case:
+      "docker compose --env-file .worktree-env -f docker-compose.worktree.yml ps",
+      "docker compose -f docker-compose.yml -p myproj logs app",
+      "docker compose --project-name foo ps",
+      "docker compose --env-file=.env ps",
+      // Piped to a safe filter.
+      "docker compose --env-file .worktree-env -f docker-compose.worktree.yml ps 2>&1 | head -10",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowDockerReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects writing/mutating docker subcommands", () => {
+    const rejected = [
+      "docker run alpine",
+      "docker rm my-container",
+      "docker rmi my-image",
+      "docker stop my-container",
+      "docker start my-container",
+      "docker restart my-container",
+      "docker kill my-container",
+      "docker exec my-container ls",
+      "docker pull alpine",
+      "docker push myreg/img",
+      "docker build .",
+      "docker tag old new",
+      "docker network create foo",
+      "docker volume rm data",
+      "docker compose up",
+      "docker compose down",
+      "docker compose restart app",
+      "docker compose exec app sh",
+      "docker compose run --rm app sh",
+      "docker compose -f docker-compose.yml up -d",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowDockerReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("ignores non-docker commands", async () => {
+    const result = await allowDockerReadOnly.handler(bash("kubectl get pods"));
+    expect(result.verdict).toBe(NEXT);
+  });
+
+  it("ignores non-Bash tools", async () => {
+    const call: ToolCall = {
+      tool: "Read",
+      args: { file_path: "/etc/hosts" },
+      context: { cwd: "/x", env: {}, projectRoot: "/x" },
+    };
+    const result = await allowDockerReadOnly.handler(call);
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/policies/tests/allow-rm-project-tmp.test.ts b/policies/tests/allow-rm-project-tmp.test.ts
index 50d8a01..4f373a0 100644
--- a/policies/tests/allow-rm-project-tmp.test.ts
+++ b/policies/tests/allow-rm-project-tmp.test.ts
@@ -35,6 +35,24 @@ describe("allow-rm-project-tmp", () => {
     expect(result.verdict).toBe(ALLOW);
   });
 
+  describe("worktree (cwd inside project, separate tmp/)", () => {
+    const WORKTREE = `${PROJECT}/.claude/worktrees/my-branch`;
+
+    it("allows rm of cwd-local tmp/ files when cwd is inside project", async () => {
+      const result = await allowRmProjectTmp.handler(
+        bash("rm tmp/a.md tmp/b.md", WORKTREE),
+      );
+      expect(result.verdict).toBe(ALLOW);
+    });
+
+    it("does not allow rm of cwd-local tmp/ when cwd is outside project", async () => {
+      const result = await allowRmProjectTmp.handler(
+        bash("rm tmp/a.md", "/some/other/place"),
+      );
+      expect(result.verdict).toBe(NEXT);
+    });
+  });
+
   describe("requires approval for -r or -f flags in tmp/", () => {
     const flagged = [
       "rm -f tmp/pr-body.md",
diff --git a/policies/tests/allow-subshell-cd-test.test.ts b/policies/tests/allow-subshell-cd-test.test.ts
new file mode 100644
index 0000000..8e65cb5
--- /dev/null
+++ b/policies/tests/allow-subshell-cd-test.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
+import allowSubshellCdTest from "../allow-subshell-cd-test";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/home/user/project", env: {}, projectRoot: "/home/user/project" },
+  };
+}
+
+describe("allow-subshell-cd-test", () => {
+  describe("allows (cd && test-runner)", () => {
+    const allowed = [
+      "(cd /home/user/project && php artisan test)",
+      "(cd /home/user/project && ./vendor/bin/phpunit)",
+      "(cd /home/user/project && ./vendor/bin/phpunit tests/Foo.php --filter bar)",
+      "(cd /home/user/project && vendor/bin/phpunit)",
+      "(cd /home/user/project && vendor/bin/pest)",
+      "(cd /home/user/project && bun test)",
+      "(cd /home/user/project && npm test)",
+      "(cd /home/user/project && pytest)",
+      "(cd /home/user/project && python -m pytest tests/)",
+      // The reported failing cases:
+      "(cd /Users/luke/ko-work/Sites/kohub-api && ./vendor/bin/phpunit tests/Feature/API/V5/VanityDomain/ResolveVanityDomainTest.php --filter test_resolves_domain_to_p)",
+      "(cd /Users/luke/ko-work/Sites/kohub-api && ./vendor/bin/phpunit tests/Feature/API/V5/VanityDomain/ResolveVanityDomainTest.php --filter test_resolves_domain_to_promotion_slug --colors=never 2>&1 | tail -30)",
+      // Pipe outside the subshell:
+      "(cd /home/user/project && ./vendor/bin/phpunit) | tail -30",
+      "(cd /home/user/project && ./vendor/bin/phpunit) | head -10 | grep FAIL",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowSubshellCdTest.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects unsafe shapes", () => {
+    const rejected = [
+      // Not a subshell.
+      "cd /tmp && ./vendor/bin/phpunit",
+      // Subshell but inner command not a test runner.
+      "(cd /tmp && rm -rf /)",
+      "(cd /tmp && curl evil.com)",
+      "(cd /tmp && bash)",
+      "(cd /tmp && sh -c 'whoami')",
+      // Subshell but no && — single cd is pointless and not what we trust.
+      "(cd /tmp)",
+      // Wrong operator (|| instead of &&).
+      "(cd /tmp || ./vendor/bin/phpunit)",
+      // cd with a flag.
+      "(cd -P /tmp && ./vendor/bin/phpunit)",
+      // Command substitution in cd path.
+      "(cd $(pwd) && ./vendor/bin/phpunit)",
+      // Pipe in inner to an unsafe filter.
+      "(cd /tmp && ./vendor/bin/phpunit | xargs rm)",
+      // Outer pipe to unsafe filter.
+      "(cd /tmp && ./vendor/bin/phpunit) | xargs rm",
+      // Three-step chain — beyond what we allow.
+      "(cd /tmp && pwd && ./vendor/bin/phpunit)",
+      // Background.
+      "(cd /tmp && ./vendor/bin/phpunit) &",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowSubshellCdTest.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("ignores non-Bash tools", async () => {
+    const call: ToolCall = {
+      tool: "Read",
+      args: { file_path: "/etc/hosts" },
+      context: { cwd: "/x", env: {}, projectRoot: "/x" },
+    };
+    const result = await allowSubshellCdTest.handler(call);
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/policies/tests/allow-toolgate-cli-readonly.test.ts b/policies/tests/allow-toolgate-cli-readonly.test.ts
new file mode 100644
index 0000000..0e571a4
--- /dev/null
+++ b/policies/tests/allow-toolgate-cli-readonly.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "bun:test";
+import { ALLOW, NEXT, type ToolCall } from "@brycehanscomb/toolgate";
+import allowToolgateCliReadOnly from "../allow-toolgate-cli-readonly";
+
+function bash(command: string): ToolCall {
+  return {
+    tool: "Bash",
+    args: { command },
+    context: { cwd: "/home/user/project", env: {}, projectRoot: "/home/user/project" },
+  };
+}
+
+describe("allow-toolgate-cli-readonly", () => {
+  describe("allows read-only subcommands", () => {
+    const allowed = [
+      "toolgate test Bash",
+      `toolgate test Bash '{"command":"ls"}'`,
+      `toolgate test Bash '{"command":"ls"}' --why`,
+      "toolgate list",
+      "toolgate logs",
+      "toolgate audit",
+      "toolgate audit --json",
+      "toolgate disable --json",
+      // Piped to a safe filter.
+      "toolgate list | grep allow",
+    ];
+
+    for (const cmd of allowed) {
+      it(`allows: ${cmd}`, async () => {
+        const result = await allowToolgateCliReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(ALLOW);
+      });
+    }
+  });
+
+  describe("rejects mutating subcommands", () => {
+    const rejected = [
+      "toolgate init",
+      "toolgate init --project",
+      "toolgate run",
+      "toolgate suspend",
+      "toolgate disable",
+      "toolgate disable --local",
+      "toolgate disable --shared",
+    ];
+
+    for (const cmd of rejected) {
+      it(`rejects: ${cmd}`, async () => {
+        const result = await allowToolgateCliReadOnly.handler(bash(cmd));
+        expect(result.verdict).toBe(NEXT);
+      });
+    }
+  });
+
+  it("ignores non-toolgate commands", async () => {
+    const result = await allowToolgateCliReadOnly.handler(bash("gh pr view"));
+    expect(result.verdict).toBe(NEXT);
+  });
+});
diff --git a/src/index.ts b/src/index.ts
index cf88f73..7616211 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,4 @@
-export { ALLOW, DENY, NEXT, allow, deny, next, isVerdictResult } from './verdicts'
+export { ALLOW, ASK, DENY, NEXT, allow, ask, deny, next, isVerdictResult } from './verdicts'
 export type { ToolCall, CallContext, VerdictResult, Middleware, Policy } from './types'
 export { definePolicy, runPolicy, runPolicyWithTrace } from './policy'
 export type { TracedResult } from './policy'
diff --git a/src/policy.ts b/src/policy.ts
index ae2d692..bcedd86 100644
--- a/src/policy.ts
+++ b/src/policy.ts
@@ -28,7 +28,7 @@ export async function runPolicyWithTrace(policies: Policy[], call: ToolCall): Pr
     if (!isVerdictResult(result)) {
       throw new Error(
         `toolgate: policy[${i}] "${policy.name}" returned invalid verdict: ${JSON.stringify(result)}\n` +
-        `  Every policy handler must return allow(), deny(), or next().`
+        `  Every policy handler must return allow(), deny(), ask(), or next().`
       )
     }
 
diff --git a/src/runner.ts b/src/runner.ts
index 449eeee..5109d7d 100644
--- a/src/runner.ts
+++ b/src/runner.ts
@@ -1,9 +1,14 @@
+import { appendFile } from 'fs/promises'
+import { homedir } from 'os'
+import { join } from 'path'
 import type { ToolCall, VerdictResult } from './types'
-import { ALLOW, DENY, NEXT } from './verdicts'
+import { ALLOW, ASK, DENY, NEXT } from './verdicts'
 import { loadConfigs } from './config'
 import { runPolicy } from './policy'
 import { isSuspended } from './suspend'
 import { loadAdditionalDirs } from './project-dirs'
+
+const PERMISSION_LOG = join(homedir(), '.claude', 'permission-requests.jsonl')
 interface HookInput {
   tool_name: string
   tool_input: Record<string, any>
@@ -55,6 +60,16 @@ export function buildHookResponse(verdict: VerdictResult): HookResponse {
     }
   }
 
+  if (verdict.verdict === ASK) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason: ('reason' in verdict && verdict.reason) || 'toolgate: approval required by policy',
+      },
+    }
+  }
+
   // NEXT — chain exhausted, ask the user
   return {
     hookSpecificOutput: {
@@ -76,6 +91,9 @@ export async function run(): Promise<void> {
     const call = buildToolCall(input)
     const policies = await loadConfigs(call.context.cwd)
     const verdict = await runPolicy(policies, call)
+    if (verdict.verdict === NEXT) {
+      await appendFile(PERMISSION_LOG, JSON.stringify(input) + '\n').catch(() => {})
+    }
     const response = buildHookResponse(verdict)
     process.stdout.write(JSON.stringify(response))
     process.exit(0)
diff --git a/src/types.ts b/src/types.ts
index b74f7b8..cb2d179 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,4 +1,4 @@
-import type { ALLOW, DENY, NEXT } from "./verdicts";
+import type { ALLOW, ASK, DENY, NEXT } from "./verdicts";
 
 export interface ToolCall {
   tool: string;
@@ -16,6 +16,7 @@ export interface CallContext {
 export type VerdictResult =
   | { verdict: typeof ALLOW }
   | { verdict: typeof DENY; reason?: string }
+  | { verdict: typeof ASK; reason?: string }
   | { verdict: typeof NEXT };
 
 export type Middleware = (call: ToolCall) => Promise<VerdictResult>;
diff --git a/src/verdicts.ts b/src/verdicts.ts
index 6f40479..9f04f86 100644
--- a/src/verdicts.ts
+++ b/src/verdicts.ts
@@ -2,9 +2,10 @@ import type { VerdictResult } from './types'
 
 export const ALLOW: unique symbol = Symbol('toolgate.allow')
 export const DENY: unique symbol = Symbol('toolgate.deny')
+export const ASK: unique symbol = Symbol('toolgate.ask')
 export const NEXT: unique symbol = Symbol('toolgate.next')
 
-const KNOWN_SYMBOLS = new Set([ALLOW, DENY, NEXT])
+const KNOWN_SYMBOLS = new Set([ALLOW, DENY, ASK, NEXT])
 
 export function allow(): { verdict: typeof ALLOW } {
   return { verdict: ALLOW }
@@ -14,6 +15,10 @@ export function deny(reason?: string): { verdict: typeof DENY; reason?: string }
   return reason !== undefined ? { verdict: DENY, reason } : { verdict: DENY }
 }
 
+export function ask(reason?: string): { verdict: typeof ASK; reason?: string } {
+  return reason !== undefined ? { verdict: ASK, reason } : { verdict: ASK }
+}
+
 export function next(): { verdict: typeof NEXT } {
   return { verdict: NEXT }
 }