@iinm/plain-agent 1.10.27 → 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).
@@ -64,8 +139,8 @@ Configure what the agent can do automatically using a small DSL with regex match
         "expectedAction": "allow"
       },
       {
-        "desc": "fd with -I should require approval",
-        "toolUse": { "toolName": "exec_command", "input": { "command": "fd", "args": ["-I", ".env", "./"] } },
+        "desc": "fd with --exec should require approval",
+        "toolUse": { "toolName": "exec_command", "input": { "command": "fd", "args": [".env", "./", "--exec", "cat", "{}"] } },
         "expectedAction": "ask"
       },
       {
@@ -84,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
@@ -126,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
 
@@ -526,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.10.27",
+  "version": "1.10.28",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
     "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/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();