@iinm/plain-agent 1.10.23 → 1.10.25

package/README.md

@@ -1,17 +1,129 @@
 # Plain Agent
 
-A lightweight coding agent for the terminal.
+A lightweight terminal-based coding agent focused on safety and low token cost
 
-- **Multi-provider** — Use Claude, GPT, Gemini, or any OpenAI-compatible model via direct APIs or through Bedrock, Vertex AI, or Azure.
-- **Fine-grained auto-approval** — Auto-approve tool calls by matching tool names and inputs against configurable patterns, while validating string inputs as paths for safety.
-- **Sandboxed execution** — Run commands in a Docker container with filesystem and network isolation.
-- **Supports Claude Code resources** — Use Claude Code plugins, commands, subagents, and skills from `.claude/`.
-- **Zero external dependencies** — Built using only Node.js standard libraries.
+## Design
 
-## Limitations
+### Multi-provider support
 
-- **Path validation only covers tool arguments** — It blocks paths outside the working directory, directory traversal (`..`), symlinks that escape the project, and git-ignored files. However, it only applies to paths explicitly passed as tool-use arguments, so it cannot control file access inside arbitrary scripts. Always use sandboxed execution when running arbitrary scripts.
-- **Sequential subagent execution** — Subagents run one at a time rather than in parallel. The trade-off is that every step is streamed to your terminal, so you can follow exactly what each subagent is doing.
+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.
+
+### 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).
+
+```js
+{
+  "autoApproval": {
+    // What to do when no pattern matches: ask - prompt the user, deny - reject automatically
+    "defaultAction": "ask",
+
+    // Patterns are evaluated top-to-bottom; first match wins
+    "patterns": [
+      // fd example:
+      // Ask for approval when risky flags like --exec or --no-ignore are present
+      {
+        "toolName": "exec_command",
+        "input": {
+          "command": "fd",
+          "args": { "$has": { "$regex": "^(--unrestricted|--no-ignore|--exec|--exec-batch|--follow|-[^-]*[uIxXL])" } }
+        },
+        "action": "ask"
+      },
+      // Allow all other fd calls
+      {
+        "toolName": "exec_command",
+        "input": { "command": "fd" },
+        "action": "allow"
+      },
+
+      // GitHub CLI example:
+      // Allow read access to PRs and issues
+      {
+        "toolName": "exec_command",
+        "input": {
+          "command": "gh",
+          "args": ["api", "--method", "GET", { "$regex": "^repos/[^/]+/[^/]+/(pulls|issues)/" }]
+        },
+        "action": "allow"
+      },
+      // Require --method to be explicit, so GET calls can be safely auto-approved
+      {
+        "toolName": "exec_command",
+        "input": { "command": "gh", "args": ["api", "--method"] },
+        "action": "ask"
+      },
+      {
+        "toolName": "exec_command",
+        "input": { "command": "gh", "args": ["api"] },
+        "action": "deny",
+        "reason": "--method must be specified"
+      }
+    ]
+  }
+}
+```
+
+### Path Validation
+
+String values in tool inputs are treated as file paths and validated against these rules. This takes precedence over `autoApproval` — even if a pattern marks an action as `allow`, a validation failure falls back to `defaultAction`.
+
+- The path must be under the working directory or a path listed in `autoApproval.allowedPaths`
+- No directory traversal (`..` is not allowed)
+- The file must be tracked by Git (not ignored)
+
+**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
+
+The agent can run arbitrary commands via `exec_command` and `tmux_command`. You can configure a wrapper command that intercepts both.
+A Docker-based wrapper called `plain-sandbox` is included, but the interface is designed to work with other tools as well, such as [Anthropic Sandbox Runtime (srt)](https://github.com/anthropic-experimental/sandbox-runtime).
+
+```js
+{
+  "sandbox": {
+    // Commands are wrapped and executed with this command
+    // 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
+    // separator is inserted between sandbox flags and the user command to prevent bypasses
+    "separator": "--",
+
+    "rules": [
+      // Run specific commands outside the sandbox
+      {
+        "pattern": {
+          "command": { "$regex": "^(gh|docker)$" }
+        },
+        "mode": "unsandboxed"
+      },
+      // Run commands in the sandbox with network access
+      {
+        "pattern": {
+          "command": "npm",
+          "args": [{ "$regex": "^(install|ci)$" }]
+        },
+        "mode": "sandbox",
+        "additionalArgs": ["--allow-net", "registry.npmjs.org"]
+      }
+    ]
+  }
+}
+```
+
+### 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.
+
+### Claude Code Compatibility
+
+Claude Code has a plugin ecosystem and is widely used across teams. plain-agent supports `.claude/` commands, subagents, and skills so you can share project skills with Claude Code users. Plugins can also be installed.
+
+**Limitation:** Subagents run sequentially, not in parallel. The upside is that their activity is fully observable and they don't spike token usage. They also inherit the main context rather than starting fresh — a simplification chosen for ease of implementation, which also avoids redundant file reads and reduces the chance of losing context between handoffs.
 
 ## Requirements
 
@@ -345,6 +457,31 @@ Files are loaded in the following order. Settings in later files override earlie
         └── agents/                # Project-specific agent roles
 ```
 
+
+<details>
+<summary><b>Minimal example (file editing and web search only — no script execution, no sandbox required)</b></summary>
+
+```js
+{
+  "autoApproval": {
+    "defaultAction": "ask",
+    "maxApprovals": 100,
+    "patterns": [
+      {
+        "toolName": { "$regex": "^(write_file|patch_file)$" },
+        "action": "allow"
+      },
+      {
+        "toolName": { "$regex": "^(web_search|web_fetch)$" },
+        "action": "allow"
+      }
+    ]
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><b>YOLO mode example (requires a sandbox for safety)</b></summary>
 
@@ -360,11 +497,11 @@ Files are loaded in the following order. Settings in later files override earlie
         "action": "allow"
       },
       {
-        "toolName": "exec_command",
+        "toolName": { "$regex": "^(web_search|web_fetch)$" },
         "action": "allow"
       },
       {
-        "toolName": { "$regex": "^(web_search|web_fetch)$" },
+        "toolName": "exec_command",
         "action": "allow"
       }
       // ⚠️ Never do this. MCP runs outside the sandbox, so it can send anything externally.
@@ -375,8 +512,10 @@ 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
     "command": "plain-sandbox",
-    "args": ["--allow-write", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--skip-build", "--keep-alive", "30"],
+    // ↑ --mount-readonly: prevents the agent from overwriting its own config
     "separator": "--"
   }
 }
@@ -406,7 +545,7 @@ Files are loaded in the following order. Settings in later files override earlie
         "action": "allow"
       },
 
-      // ⚠️ Arbitrary code execution can access unauthorized files and networks. Always use a sandbox.
+      // ⚠️ When auto-approving execution, scripts can access unauthorized files and networks. Always use a sandbox.
       {
         "toolName": "exec_command",
         "input": { "command": "npm", "args": ["run", { "$regex": "^(lint|test)$" }] },
@@ -437,8 +576,10 @@ Files are loaded in the following order. Settings in later files override earlie
   // Sandbox environment for the exec_command and tmux_command tools
   "sandbox": {
     // Commands are wrapped and executed with this command
+    // Build the image before first use: plain-sandbox --verbose echo done
     "command": "plain-sandbox",
-    "args": ["--allow-write", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--skip-build", "--keep-alive", "30"],
+    // ↑ --mount-readonly: prevents the agent from overwriting its own config
     // separator is inserted between sandbox flags and the user command to prevent bypasses
     "separator": "--",
 
@@ -637,33 +778,6 @@ Press **Ctrl-O** to start recording, then press it again to stop. Partial transc
   is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
 - `recorder` — Override automatic recorder detection, e.g. `{ "command": "sox", "args": ["-q", "-d", "-b", "16", "-c", "1", "-r", "24000", "-e", "signed-integer", "-t", "raw", "-"] }`. It must write raw 16-bit little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
 
-## Development
-
-```sh
-# Run lint, typecheck, and tests
-npm run check
-
-# Fix lint issues
-npm run fix
-# or
-npm run fix -- --unsafe
-
-# Update dependencies
-npx npm-check-updates -t minor -c 3
-npx npm-check-updates -t minor -c 3 -u
-```
-
-## Release
-
-```sh
-npm version <major|minor|patch>
-
-git push --follow-tags
-gh release create $(git describe --tags) --generate-notes
-
-npm publish --access public
-```
-
 ## Appendix: Creating Least-Privilege Users for Cloud Providers
 
 <details>
@@ -809,3 +923,19 @@ gcloud iam service-accounts add-iam-policy-binding "$service_account_email" \
 gcloud auth print-access-token --impersonate-service-account "$service_account_email"
 ```
 </details>
+
+## Developer Notes
+
+<details>
+<summary>Release</summary>
+
+```sh
+npm version <major|minor|patch>
+
+git push --follow-tags
+gh release create $(git describe --tags) --generate-notes
+
+npm publish --access public
+```
+</details>
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.10.23",
-  "description": "A lightweight coding agent for the terminal.",
+  "version": "1.10.25",
+  "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",
   "repository": {

package/sandbox/bin/plain-sandbox

@@ -18,8 +18,8 @@ Usage: $SCRIPT_NAME [--dockerfile FILE]
            [--env-file FILE]
            [--allow-write] [--allow-net [DESTINATIONS|--]]
            [--volume [NAME:]PATH]
-           [--mount-writable HOST_DIR:CONTAINER_DIR]
-           [--mount-readonly HOST_DIR:CONTAINER_DIR]
+           [--mount-writable HOST_PATH[:CONTAINER_PATH]]
+           [--mount-readonly HOST_PATH[:CONTAINER_PATH]]
            [--publish [HOST_ADDRESS:]HOST_PORT:CONTAINER_PORT]
            [--tty]
            [--no-cache]
@@ -50,11 +50,19 @@ Options:
                             inside the container.
                             If NAME is not given, the volume name is generated.
 
-  --mount-readonly HOST_DIR:CONTAINER_DIR
+  --mount-readonly HOST_PATH[:CONTAINER_PATH]
                             Mount a host file or directory to a container path as read-only.
+                            If CONTAINER_PATH is omitted, the resolved absolute host path is used.
+                            Relative HOST_PATH is resolved from the current working directory.
+                            Relative CONTAINER_PATH is resolved from the working directory
+                            inside the container.
 
-  --mount-writable HOST_DIR:CONTAINER_DIR
+  --mount-writable HOST_PATH[:CONTAINER_PATH]
                             Mount a host file or directory to a container path as writable.
+                            If CONTAINER_PATH is omitted, the resolved absolute host path is used.
+                            Relative HOST_PATH is resolved from the current working directory.
+                            Relative CONTAINER_PATH is resolved from the working directory
+                            inside the container.
 
   --publish [HOST_ADDRESS:]HOST_PORT:CONTAINER_PORT
                             Publish container port(s) to the host.
@@ -384,12 +392,22 @@ main() {
     for mount in "${readonly_mounts[@]}"; do
       local host_path
       local container_path
-      IFS=':' read -r host_path container_path <<< "$mount"
+      if grep -qE ':' <<< "$mount"; then
+        IFS=':' read -r host_path container_path <<< "$mount"
+      else
+        host_path="$mount"
+        container_path=""
+      fi
       local host_abs_path="$host_path"
       if ! grep -qE '^/' <<< "$host_abs_path"; then
         # shellcheck disable=SC2001
         host_abs_path=$(readlink -f "$(sed "s,~/,$HOME/," <<< "$host_abs_path")")
       fi
+      if test -z "$container_path"; then
+        container_path="$host_abs_path"
+      elif ! grep -qE '^/' <<< "$container_path"; then
+        container_path="${container_workdir}/${container_path}"
+      fi
       docker_run_opts+=(--mount "type=bind,source=${host_abs_path},target=${container_path},readonly,consistency=delegated")
     done
   fi
@@ -398,12 +416,22 @@ main() {
     for mount in "${writable_mounts[@]}"; do
       local host_path
       local container_path
-      IFS=':' read -r host_path container_path <<< "$mount"
+      if grep -qE ':' <<< "$mount"; then
+        IFS=':' read -r host_path container_path <<< "$mount"
+      else
+        host_path="$mount"
+        container_path=""
+      fi
       local host_abs_path="$host_path"
       if ! grep -qE '^/' <<< "$host_abs_path"; then
         # shellcheck disable=SC2001
         host_abs_path=$(readlink -f "$(sed "s,~/,$HOME/," <<< "$host_abs_path")")
       fi
+      if test -z "$container_path"; then
+        container_path="$host_abs_path"
+      elif ! grep -qE '^/' <<< "$container_path"; then
+        container_path="${container_workdir}/${container_path}"
+      fi
       docker_run_opts+=(--mount "type=bind,source=${host_abs_path},target=${container_path},consistency=delegated")
     done
   fi

package/src/cli/interactive.mjs

@@ -391,6 +391,8 @@ export function startInteractiveSession({
 
   // Handle readline close (e.g., stdin closed externally)
   cli.on("close", handleExit);
+  process.on("SIGTERM", handleExit);
+  process.on("SIGHUP", handleExit);
 
   const handleCommand = createCommandHandler({
     agentCommands,

package/src/main.mjs

@@ -165,6 +165,7 @@ export async function main(argv = process.argv) {
       const sandboxStr = [
         appConfig.sandbox.command,
         ...(appConfig.sandbox.args || []),
+        ...(appConfig.sandbox.separator ? [appConfig.sandbox.separator] : []),
       ].join(" ");
       console.log(styleText("green", "\n📦 Sandbox: on"));
       console.log(`  ⤷ ${sandboxStr}`);