@iinm/plain-agent 1.10.26 → 1.10.27

package/README.md

@@ -54,6 +54,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 -I should require approval",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "fd", "args": ["-I", ".env", "./"] } },
+        "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"
+      }
     ]
   }
 }
@@ -557,6 +576,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.27",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",
@@ -32,9 +32,10 @@
     "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"
   },

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) {