@iinm/plain-agent 1.10.26 → 1.10.28

package/README.md

@@ -1,13 +1,88 @@
 # Plain Agent
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/iinm/plain-agent)
+[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.10.28)](https://socket.dev/npm/package/@iinm/plain-agent)
+
 A lightweight terminal-based coding agent focused on safety and low token cost
 
+## Table of Contents
+
+- [Design](#design)
+  - [Multi-provider support](#multi-provider-support)
+  - [Auto-approval](#auto-approval)
+  - [Path Validation](#path-validation)
+  - [Sandbox](#sandbox)
+  - [Memory file](#memory-file)
+  - [Token Efficiency](#token-efficiency)
+  - [Claude Code Compatibility](#claude-code-compatibility)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Available Tools](#available-tools)
+- [Prompts](#prompts)
+- [Subagents](#subagents)
+- [Claude Code Plugin Support](#claude-code-plugin-support)
+- [Voice Input](#voice-input)
+- [Appendix: Creating Least-Privilege Users for Cloud Providers](#appendix-creating-least-privilege-users-for-cloud-providers)
+- [Developer Notes](#developer-notes)
+
 ## Design
 
 ### Multi-provider support
 
 Supports Claude, OpenAI, Gemini, and any OpenAI-compatible provider. Bedrock, Vertex AI, and Azure are also supported for teams working in environments restricted to managed cloud providers.
 
+Each model definition has two independent parts:
+
+- **`platform`** — where to send the request and how to authenticate (Anthropic, Bedrock, Vertex AI, Azure, etc.)
+- **`model.format`** — which API format to use (`anthropic`, `gemini`, `openai-responses`, `openai-messages`, `bedrock-converse`)
+
+Because these are separate, the same API format works across different platforms. For example, Claude models use the `anthropic` format whether you call Anthropic directly or through Bedrock.
+
+```js
+// Anthropic direct
+{
+  "name": "claude-sonnet-4-6",
+  "variant": "thinking-high",
+  "platform": {
+    "name": "anthropic",
+    "variant": "default"
+  },
+  "model": {
+    "format": "anthropic",
+    "config": {
+      "model": "claude-sonnet-4-6",
+      "max_tokens": 32768,
+      "thinking": { "type": "adaptive" },
+      "output_config": { "effort": "high" }
+    }
+  }
+}
+
+// Bedrock — same format, different platform
+{
+  "name": "claude-sonnet-4-6",
+  "variant": "thinking-high-bedrock-jp",
+  "platform": {
+    "name": "bedrock",
+    "variant": "jp"
+  },
+  "model": {
+    "format": "anthropic",
+    "config": {
+      "model": "jp.anthropic.claude-sonnet-4-6",
+      "max_tokens": 32768,
+      "thinking": { "type": "adaptive" },
+      "output_config": { "effort": "high" }
+    }
+  }
+}
+```
+
+Models are identified by `name+variant` (e.g., `claude-sonnet-4-6+thinking-high`). You can define multiple variants of the same model with different settings — such as thinking budget or region — and switch between them as needed.
+
+You can also add entries to `platforms` and `models` to use any OpenAI-compatible endpoint, such as Ollama or Fireworks. See the Quick Start section for examples.
+
 ### Auto-approval
 
 Configure what the agent can do automatically using a small DSL with regex matching. Below is an excerpt from the [default config](https://github.com/iinm/plain-agent/blob/main/config/config.predefined.json).
@@ -54,6 +129,25 @@ Configure what the agent can do automatically using a small DSL with regex match
         "action": "deny",
         "reason": "--method must be specified right after 'api'"
       }
+    ],
+
+    // Test cases for verifying patterns. Run: plain test-approval
+    "tests": [
+      {
+        "desc": "fd with safe args should be allowed",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "fd", "args": ["README", "./"] } },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "fd with --exec should require approval",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "fd", "args": [".env", "./", "--exec", "cat", "{}"] } },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "gh api without --method should be denied",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "gh", "args": ["api", "/repos/owner/repo/pulls"] } },
+        "expectedAction": "deny"
+      }
     ]
   }
 }
@@ -65,8 +159,23 @@ String values in tool inputs are treated as file paths and validated against the
 
 - The path must be under the working directory or a path listed in `autoApproval.allowedPaths`
 - No directory traversal (`..` is not allowed)
+- Symlinks are resolved to their real path before validation — a symlink inside the working directory that points outside is rejected. Broken and circular symlinks are also rejected.
 - The file must be tracked by Git (not ignored)
 
+Commands are executed without a shell — shell operators like `&&`, `|`, `;`, and redirects are not interpreted unless the agent explicitly uses `bash -c`. This makes each argument a discrete token that can be validated individually.
+
+Compound arguments are decomposed before validation — embedded paths are extracted and checked individually:
+
+| Pattern | Example | Extracted |
+|---|---|---|
+| `@<path>` | `@data.json` | `data.json` |
+| `--opt=<val>` | `--prefix=/tmp/foo` | `/tmp/foo` |
+| `-X<val>` | `-I/usr/include` | `/usr/include` |
+| `VAR=<val>` | `OUTPUT=/etc/passwd` | `/etc/passwd` |
+| `proto://…` | `file:///etc/passwd` | `/etc/passwd` |
+
+`--opt=<val>`, `-X<val>`, and `VAR=<val>` are checked recursively, so chained patterns like `-DINSTALL_DIR=/etc` decompose fully (`-D` → `INSTALL_DIR=/etc` → `/etc`).
+
 **Note**: validation only applies when the agent explicitly passes file paths to tools. It cannot catch file access inside scripts the agent writes — something like `bash -c "rm -rf /"` is beyond its reach. Always use a sandbox when auto-approving script execution.
 
 ### Sandbox
@@ -107,12 +216,22 @@ A Docker-based wrapper called `plain-sandbox` is included, but the interface is
 }
 ```
 
+### Memory file
+
+The agent maintains a memory file (`.plain-agent/memory/`) for each session to:
+
+- Keep task state human-readable — you can open the file to see exactly where things stand.
+- Resume cleanly — the agent can restart a task from the memory file with a clean context.
+- Pass information between dependent tasks — subagents write their results to the memory file, which the main agent or a follow-up session reads to continue.
+
 ### Token Efficiency
 
 A few design choices keep token usage low:
 
 - Minimal system prompt — the [system prompt](https://github.com/iinm/plain-agent/blob/main/src/prompt.mjs) contains only what the agent needs to function. 
 - Output truncation — when a command or MCP tool produces large output, it is truncated and saved to a file. The agent can then read only the relevant parts.
+- Context compaction — when the context grows large, you can run `/compact` to discard old messages and reload task state from a memory file.
+- MCP tool filtering — MCP servers often expose many tools. Use `enabledTools` in the server config to enable only the ones you need, which reduces the number of tool definitions sent to the model.
 
 ### Claude Code Compatibility
 
@@ -507,7 +626,7 @@ Files are loaded in the following order. Settings in later files override earlie
     ]
   },
   "sandbox": {
-    // ⚠️ Build the image before first use: plain-sandbox --verbose echo done
+    // Build the image before first use: plain-sandbox --verbose echo done
     "command": "plain-sandbox",
     "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--skip-build", "--keep-alive", "30"],
     // ↑ --mount-readonly: prevents the agent from overwriting its own config
@@ -557,6 +676,15 @@ Files are loaded in the following order. Settings in later files override earlie
         "toolName": { "$regex": "mcp__slack__slack_(read|search)_.+" },
         "action": "allow"
       }
+    ],
+
+    // Test cases for verifying patterns. Run: plain test-approval
+    "tests": [
+      {
+        "desc": "npm test should be allowed",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "npm", "args": ["run", "test"] } },
+        "expectedAction": "allow"
+      }
     ]
   },
 

package/config/config.predefined.json

@@ -144,6 +144,288 @@
         "action": "deny",
         "reason": "--method must be specified right after 'api'"
       }
+    ],
+    "tests": [
+      {
+        "desc": "ls should be allowed",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "ls" } },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "rm should not match any pattern",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "rm" } },
+        "expectedAction": null
+      },
+      {
+        "desc": "fd with safe args should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["--max-depth", "3"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "fd with -H only should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["-H", "pattern"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "fd with unsafe args should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["--unrestricted"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "fd with -I option should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["-I", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "fd with -HI combined options should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["-HI", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "fd with -IH combined options should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["-IH", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "fd with -Hx=command combined options with value should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "fd", "args": ["-Hx=cat", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "rg with safe args should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["--ignore-case", "pattern"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "rg with -H only should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["-H", "pattern"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "rg with unsafe args should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["--unrestricted"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "rg with -u option should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["-u", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "rg with -Hu combined options should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["-Hu", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "rg with -uH combined options should require approval",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "rg", "args": ["-uH", "pattern"] }
+        },
+        "expectedAction": "ask"
+      },
+      {
+        "desc": "sed with known pattern should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "sed", "args": ["-n", "10,20p", "file.txt"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "sed with single line pattern should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "sed", "args": ["-n", "42p", "file.txt"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "git status should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "git", "args": ["status"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "git branch --show-current should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "git", "args": ["branch", "--show-current"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "git commit should not match any pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "git", "args": ["commit"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "docker ps should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "docker", "args": ["ps"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "docker compose ps should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "docker", "args": ["compose", "ps"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "docker compose logs should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "docker", "args": ["compose", "logs"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "tmux list-sessions should be allowed",
+        "toolUse": {
+          "toolName": "tmux_command",
+          "input": { "command": "list-sessions" }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "gh pr view should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "gh", "args": ["pr", "view"] }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "gh api for PR comments should be allowed",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": {
+            "command": "gh",
+            "args": ["api", "--method", "GET", "repos/owner/repo/pulls/123/comments"]
+          }
+        },
+        "expectedAction": "allow"
+      },
+      {
+        "desc": "gh api without --method should be denied",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "gh", "args": ["api", "repos/owner/repo/pulls"] }
+        },
+        "expectedAction": "deny"
+      },
+      {
+        "desc": "gh api --method POST should fall through to defaultAction",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": {
+            "command": "gh",
+            "args": ["api", "--method", "POST", "repos/owner/repo/issues"]
+          }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c without shell features should be denied",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "echo hello"] }
+        },
+        "expectedAction": "deny"
+      },
+      {
+        "desc": "bash -c with pipe should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "echo hello | grep hello"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c with redirect should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "echo hello > file.txt"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c with ampersand should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "cmd1 && cmd2"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c with semicolon should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "for i in *.txt; do echo $i; done"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c with command substitution should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "echo $(date)"] }
+        },
+        "expectedAction": null
+      },
+      {
+        "desc": "bash -c with backtick should not match deny pattern",
+        "toolUse": {
+          "toolName": "exec_command",
+          "input": { "command": "bash", "args": ["-c", "echo `date`"] }
+        },
+        "expectedAction": null
+      }
     ]
   },
   "models": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.10.26",
+  "version": "1.10.28",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",
@@ -32,11 +32,13 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "npm run lint && tsc && npm run test",
+    "check": "npm run lint && tsc && npm run test && npm run test:predefined-approval",
     "test": "node --test",
     "coverage": "node --experimental-test-coverage --test-coverage-exclude='src/**/*.test.mjs' --test",
+    "test:predefined-approval": "bash -c 'set -e; mkdir -p tmp; cd tmp; env HOME=. ../bin/plain test-approval'",
     "lint": "npx @biomejs/biome check",
-    "fix": "npx @biomejs/biome check --fix"
+    "fix": "npx @biomejs/biome check --fix",
+    "version": "sed -i \"s|badge.socket.dev/npm/package/@iinm/plain-agent/[0-9][0-9.]*|badge.socket.dev/npm/package/@iinm/plain-agent/${npm_package_version}|g\" README.md && git add README.md"
   },
   "dependencies": {},
   "devDependencies": {

package/src/cli/args.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand | ResumeSubcommand} Subcommand
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand | ResumeSubcommand | TestApprovalSubcommand} Subcommand
  */
 
 /**
@@ -26,6 +26,10 @@
  * @typedef {{ type: 'cost', from: string | null, to: string | null }} CostSubcommand
  */
 
+/**
+ * @typedef {{ type: 'test-approval', config: string[] }} TestApprovalSubcommand
+ */
+
 /**
  * Resume a previously interrupted interactive session.
  * - `sessionId === null` and `list === false`: resume the most recently updated session.
@@ -149,6 +153,25 @@ export function parseCliArgs(argv) {
     };
   }
 
+  if (subcommandName === "test-approval") {
+    const subArgs = args.slice(1);
+    /** @type {string[]} */
+    const config = [];
+
+    for (let i = 0; i < subArgs.length; i++) {
+      if (subArgs[i] === "-c" || subArgs[i] === "--config") {
+        if (subArgs[i + 1]) {
+          config.push(subArgs[i + 1]);
+          i++;
+        }
+      }
+    }
+
+    return {
+      subcommand: { type: "test-approval", config },
+    };
+  }
+
   if (subcommandName === "cost") {
     const costArgs = args.slice(1);
     let from = null;
@@ -203,6 +226,7 @@ Subcommands:
                                most recently updated session. Use --list to
                                see resumable sessions. Switching models is
                                not supported (-m is rejected).
+  test-approval                Run auto-approval rule tests defined in config.
   cost                         Show aggregated token cost per day for a period.
                                Defaults to the first day of the current month
                                through today.

package/src/cli/testApproval.mjs

@@ -0,0 +1,162 @@
+/**
+ * @import { AppConfig, AutoApprovalTestCase } from "../config";
+ * @import { ToolUsePattern } from "../tool";
+ */
+
+import { styleText } from "node:util";
+import { matchValue } from "../utils/matchValue.mjs";
+
+/**
+ * @typedef {ToolUsePattern & { source?: string }} ToolUsePatternWithSource
+ */
+
+/**
+ * @typedef {AutoApprovalTestCase & { source?: string }} AutoApprovalTestCaseWithSource
+ */
+
+/**
+ * @typedef {'pass' | 'warn' | 'fail'} TestVerdict
+ */
+
+/**
+ * @typedef {Object} TestResult
+ * @property {TestVerdict} verdict
+ * @property {AutoApprovalTestCaseWithSource} tc
+ * @property {string | undefined} got
+ * @property {string | undefined} expected
+ * @property {string | undefined} patternSource
+ */
+
+/**
+ * Run auto-approval rule tests defined in the app config.
+ * @param {AppConfig} appConfig
+ * @returns {number} exit code (0 = all passed, 1 = any failed)
+ */
+export function runTestApprovalCommand(appConfig) {
+  const patterns = /** @type {ToolUsePatternWithSource[]} */ (
+    appConfig.autoApproval?.patterns ?? []
+  );
+  const tests = /** @type {AutoApprovalTestCaseWithSource[]} */ (
+    appConfig.autoApproval?.tests ?? []
+  );
+
+  if (tests.length === 0) {
+    console.log("No test cases found in autoApproval.tests.");
+    return 0;
+  }
+
+  const results = evaluateTests(tests, patterns);
+  console.log();
+  printResults(results);
+
+  const failCount = results.filter((r) => r.verdict === "fail").length;
+  const warnCount = results.filter((r) => r.verdict === "warn").length;
+
+  if (failCount > 0) {
+    console.error(
+      styleText("red", `${failCount} failed`) +
+        (warnCount > 0
+          ? `, ${styleText("yellow", `${warnCount} overridden`)}`
+          : "") +
+        `, ${tests.length} total`,
+    );
+    return 1;
+  }
+
+  if (warnCount > 0) {
+    console.log(
+      styleText("yellow", `${tests.length} passed (${warnCount} overridden)`),
+    );
+  } else {
+    console.log(styleText("green", `${tests.length} passed`));
+  }
+  return 0;
+}
+
+/**
+ * @param {AutoApprovalTestCaseWithSource[]} tests
+ * @param {ToolUsePatternWithSource[]} patterns
+ * @returns {TestResult[]}
+ */
+function evaluateTests(tests, patterns) {
+  return tests.map((tc) => {
+    const matchedPattern = patterns.find((p) =>
+      matchValue(tc.toolUse, {
+        toolName: p.toolName,
+        ...(p.input !== undefined && { input: p.input }),
+      }),
+    );
+
+    const got = matchedPattern?.action;
+    const expected = tc.expectedAction === null ? undefined : tc.expectedAction;
+    const patternSource = matchedPattern?.source;
+
+    /** @type {TestVerdict} */
+    let verdict;
+    if (got === expected) {
+      verdict = "pass";
+    } else if (isOverriddenByDifferentConfig(tc.source, patternSource, got)) {
+      verdict = "warn";
+    } else {
+      verdict = "fail";
+    }
+
+    return { verdict, tc, got, expected, patternSource };
+  });
+}
+
+/**
+ * @param {TestResult[]} results
+ */
+function printResults(results) {
+  /** @type {Map<string, TestResult[]>} */
+  const grouped = new Map();
+  for (const r of results) {
+    const key = r.tc.source ?? "";
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key)?.push(r);
+  }
+
+  for (const [source, group] of grouped) {
+    if (source) {
+      console.log(styleText("blue", `[${source}]`));
+    }
+    for (const r of group) {
+      printSingleResult(r);
+    }
+    console.log();
+  }
+}
+
+/**
+ * @param {TestResult} r
+ */
+function printSingleResult(r) {
+  const gotStr = r.got ?? "no match";
+  const expectedStr = r.expected ?? "no match";
+
+  if (r.verdict === "pass") {
+    console.log(styleText("green", `  ✓ ${r.tc.desc}`));
+  } else if (r.verdict === "warn") {
+    console.log(
+      styleText("yellow", `  ⚠ ${r.tc.desc}`) +
+        ` — got: ${gotStr} (overridden by ${r.patternSource})`,
+    );
+  } else {
+    console.log(styleText("red", `  ✗ ${r.tc.desc}`));
+    const sourceLabel = r.patternSource ? `  [${r.patternSource}]` : "";
+    console.log(`    expected: ${expectedStr}, got: ${gotStr}${sourceLabel}`);
+  }
+}
+
+/**
+ * @param {string | undefined} testSource
+ * @param {string | undefined} patternSource
+ * @param {string | undefined} got
+ * @returns {boolean}
+ */
+function isOverriddenByDifferentConfig(testSource, patternSource, got) {
+  if (!testSource || !patternSource) return false;
+  if (got === undefined) return false;
+  return testSource !== patternSource;
+}

package/src/config.d.ts

@@ -72,6 +72,7 @@ export type AppConfig = {
   platforms?: PlatformConfig[];
   autoApproval?: {
     patterns?: ToolUsePattern[];
+    tests?: AutoApprovalTestCase[];
     maxApprovals?: number;
     defaultAction?: "deny" | "ask";
     /** Additional absolute paths to allow for auto-approval (outside working directory) */
@@ -91,6 +92,12 @@ export type AppConfig = {
   claudeCodePlugins?: ClaudeCodePluginRepo[];
 };
 
+export type AutoApprovalTestCase = {
+  desc: string;
+  toolUse: { toolName: string; input?: Record<string, unknown> };
+  expectedAction: "allow" | "deny" | "ask" | null;
+};
+
 export type MCPServerConfig = {
   command: string;
   args?: string[];

package/src/config.mjs

@@ -1,5 +1,10 @@
 /**
  * @import { AppConfig } from "./config";
+ * @import { ToolUsePattern } from "./tool";
+ */
+
+/**
+ * @typedef {ToolUsePattern & { source?: string }} ToolUsePatternWithSource
  */
 
 import crypto from "node:crypto";
@@ -67,7 +72,13 @@ export async function loadAppConfig(options = {}) {
           config.autoApproval?.defaultAction ??
           merged.autoApproval?.defaultAction,
         patterns: [
-          ...(config.autoApproval?.patterns ?? []),
+          ...(config.autoApproval?.patterns ?? []).map(
+            (p) =>
+              /** @type {ToolUsePatternWithSource} */ ({
+                ...p,
+                source: filePath,
+              }),
+          ),
           ...(merged.autoApproval?.patterns ?? []),
         ],
         maxApprovals:
@@ -80,6 +91,13 @@ export async function loadAppConfig(options = {}) {
         allowGitUnmanagedFiles:
           config.autoApproval?.allowGitUnmanagedFiles ??
           merged.autoApproval?.allowGitUnmanagedFiles,
+        tests: [
+          ...(config.autoApproval?.tests ?? []).map((t) => ({
+            ...t,
+            source: filePath,
+          })),
+          ...(merged.autoApproval?.tests ?? []),
+        ],
       },
       sandbox: config.sandbox ?? merged.sandbox,
       tools: {

package/src/main.mjs

@@ -14,6 +14,7 @@ import { parseCliArgs, printHelp } from "./cli/args.mjs";
 import { startBatchSession } from "./cli/batch.mjs";
 import { runCostCommand } from "./cli/cost.mjs";
 import { startInteractiveSession } from "./cli/interactive.mjs";
+import { runTestApprovalCommand } from "./cli/testApproval.mjs";
 import { loadAppConfig } from "./config.mjs";
 import { loadAgentRoles } from "./context/loadAgentRoles.mjs";
 import { loadPrompts } from "./context/loadPrompts.mjs";
@@ -80,6 +81,15 @@ export async function main(argv = process.argv) {
     }
   }
 
+  if (cliArgs.subcommand.type === "test-approval") {
+    const { appConfig } = await loadAppConfig({
+      skipTrustCheck: true,
+      configFiles: cliArgs.subcommand.config,
+    });
+    const exitCode = runTestApprovalCommand(appConfig);
+    process.exit(exitCode);
+  }
+
   if (cliArgs.subcommand.type === "resume" && cliArgs.subcommand.list) {
     const sessions = await listSessions();
     if (sessions.length === 0) {

package/src/toolInputValidator.mjs

@@ -62,6 +62,78 @@ export function isSafeToolInputItem(
   arg,
   allowedPaths = [],
   allowGitUnmanagedFiles = false,
+) {
+  // @<path> pattern (e.g., curl -d @file.json)
+  if (arg.startsWith("@")) {
+    const pathPart = arg.slice(1);
+    return (
+      isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles) &&
+      isSafeToolInputItemRaw(pathPart, allowedPaths, allowGitUnmanagedFiles)
+    );
+  }
+
+  // --opt=val pattern (e.g., npm --prefix=foo)
+  const longOptMatch = arg.match(/^--[^=]+=(.+)$/);
+  if (longOptMatch) {
+    return (
+      isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles) &&
+      isSafeToolInputItem(longOptMatch[1], allowedPaths, allowGitUnmanagedFiles)
+    );
+  }
+
+  // -X<val> pattern (e.g., gcc -oout, gcc -I/usr/include)
+  const shortOptMatch = arg.match(/^-[a-zA-Z](.+)$/);
+  if (shortOptMatch) {
+    return (
+      isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles) &&
+      isSafeToolInputItem(
+        shortOptMatch[1],
+        allowedPaths,
+        allowGitUnmanagedFiles,
+      )
+    );
+  }
+
+  // VAR=val pattern (e.g., make OUTPUT=/path, env KEY=val)
+  // Must not start with - or @ (already handled above)
+  const keyValueMatch = arg.match(/^[^-@][^=]*=(.+)$/);
+  if (keyValueMatch) {
+    return (
+      isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles) &&
+      isSafeToolInputItem(
+        keyValueMatch[1],
+        allowedPaths,
+        allowGitUnmanagedFiles,
+      )
+    );
+  }
+
+  // proto://path pattern (e.g., file:///etc/passwd)
+  const protoMatch = arg.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(.+)$/);
+  if (protoMatch) {
+    return (
+      isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles) &&
+      isSafeToolInputItemRaw(
+        `/${protoMatch[1]}`,
+        allowedPaths,
+        allowGitUnmanagedFiles,
+      )
+    );
+  }
+
+  return isSafeToolInputItemRaw(arg, allowedPaths, allowGitUnmanagedFiles);
+}
+
+/**
+ * @param {string} arg
+ * @param {string[]} [allowedPaths=[]] - Additional allowed paths (outside working directory)
+ * @param {boolean} [allowGitUnmanagedFiles=false] - Allow access to git-unmanaged files
+ * @returns {boolean}
+ */
+function isSafeToolInputItemRaw(
+  arg,
+  allowedPaths = [],
+  allowGitUnmanagedFiles = false,
 ) {
   const workingDir = process.cwd();