@iinm/plain-agent 1.7.19 → 1.7.21

package/README.md

@@ -1,10 +1,6 @@
-<p align="center">
-  <img src="https://pub-0bb49aa929f242d49c89ed8c297932b5.r2.dev/plain-agent/plain-agent-logo.png" alt="plain-agent logo" width="320">
-</p>
-
 # Plain Agent
 
-A lightweight CLI-based coding agent with zero framework dependencies.
+A lightweight CLI-based coding agent.
 
 ## Why Plain Agent?
 
@@ -23,6 +19,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 ## Limitations
 
+- **CLI only** — Plain Agent does not provide a terminal UI.
 - **Sequential subagent execution** — Subagents run one at a time rather than
   in parallel. The trade-off is full visibility: every step is streamed to
   your terminal so you can follow exactly what each subagent is doing.
@@ -31,7 +28,7 @@ A lightweight CLI-based coding agent with zero framework dependencies.
 
 - Node.js 22 or later
 - LLM provider credentials
-- bash / docker for sandboxed execution
+- Bash / Docker for sandboxed execution
 - [ripgrep](https://github.com/burntsushi/ripgrep)
 - [fd](https://github.com/sharkdp/fd)
 
@@ -52,8 +49,8 @@ Create the configuration.
 ```js
 // ~/.config/plain-agent/config.local.json
 {
-  "model": "gpt-5.4+thinking-high",
-  // "model": "claude-sonnet-4-6+thinking-high",
+  "model": "claude-sonnet-4-6+thinking-high",
+  // "model": "gpt-5.5+thinking-high",
 
   // Configure the providers you want to use
   "platforms": [
@@ -83,15 +80,11 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>",
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
       // "provider": "gemini-vertex-ai",
       // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
       // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     },
 
     // askURL: Answers questions based on provided URL content.
@@ -100,15 +93,8 @@ Create the configuration.
       "provider": "gemini",
       "apiKey": "<GEMINI_API_KEY>"
       "model": "gemini-3-flash-preview"
-      // Optional
-      // "baseURL": "<proxy_url>"
 
       // Or use Vertex AI (Requires gcloud CLI to get authentication token)
-      // "provider": "gemini-vertex-ai",
-      // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
-      // "model": "gemini-3-flash-preview"
-      // Optional:
-      // "account": "<service_account_email>"
     }
   },
 
@@ -166,6 +152,7 @@ Create the configuration.
 ```
 
 ```js
+// OpenAI-compatible provider (Ollama) example with a custom model
 {
   "platforms": [
     {
@@ -268,31 +255,26 @@ Create the configuration.
 ```
 </details>
 
-
-
 Run the agent.
 
 ```sh
 plain
-
-# Or
-plain -m <model+variant>
 ```
 
-(Optional) Set up a sandbox for your project with the `sandbox-configurator` agent.
-
 ```
-/agents:sandbox-configurator Set up a sandbox for this project
+plain -m <model+variant>
 ```
 
-After the agent finishes, run the generated setup script once to build the sandbox image and install dependencies.
+Press **Ctrl-C** to pause auto-approve. The agent will finish the current tool call, then return to the prompt.
 
-```sh
-./.plain-agent/setup.sh
+Display the help message.
+
+```
+/help
 ```
 
 Run in batch mode (non-interactive).
-In batch mode, config files are not loaded automatically. Only the files specified with `--config` are loaded.
+In batch mode, config files are not loaded automatically. Only the files specified with `-c` are loaded.
 
 ```sh
 plain batch \
@@ -301,66 +283,48 @@ plain batch \
       "Add tests for ..."
 ```
 
-Display the help message.
-
-```
-/help
-```
-
-Show aggregated token cost per day across sessions.
-Each finished session appends a record to `~/.local/share/plain-agent/usage.jsonl`,
-and `plain cost` reads that log. The period defaults to the first day of the
-current month through today; override it with `--from` / `--to`. Multiple
-currencies (e.g., USD and JPY) are aggregated separately.
+Show daily token costs across sessions. `plain cost` reads
+`~/.local/share/plain-agent/usage.jsonl`; use `--from` / `--to` to set the
+period. Currencies are shown separately.
 
 ```sh
 plain cost
-plain cost --from 2026-04-01 --to 2026-04-30
 ```
 
-Interrupt the agent while it's running:
-
-Press **Ctrl-C** to pause auto-approve. The agent will finish the current tool call, then return to the prompt.
+```
+plain cost --from 2026-04-01 --to 2026-04-30
+```
 
-## Available Tools
+(Optional) Configure plain-agent for your project.
 
-The agent can use the following tools to assist with tasks:
+```
+/configure Auto-approve file writes and patches
+```
 
-- **exec_command**: Run a command without shell interpretation.
-- **write_file**: Write a file.
-- **patch_file**: Patch a file.
-- **tmux_command**: Run a tmux command.
-- **ask_web**: Use the web search to answer questions that need up-to-date information or supporting sources. (requires Google API key or Vertex AI configuration).
-- **ask_url**: Use one or more provided URLs to answer a question. Include the URLs in your question. (requires Google API key or Vertex AI configuration).
-- **delegate_to_subagent**: Delegate a subtask to a subagent. The agent switches to a subagent role within the same conversation, focusing on the specified goal.
-- **report_as_subagent**: Report completion and return to the main agent. Used by subagents to communicate results and restore the main agent role. After reporting, the subagent's conversation history is removed from the context.
-- **compact_context**: Compact the conversation context by discarding prior messages and reloading task state from a memory file. Use when the context has grown large but the task is not yet complete. Can also be invoked via the `/compact` slash command.
+```
+/configure Set up a sandbox for this project
+```
 
 ## Configuration
 
+Files are loaded in the following order. Settings in later files override earlier ones.
+
 ```
 ~/.config/plain-agent/
-  \__ config.json        # User configuration
-  \__ config.local.json  # User local configuration (including secrets)
-  \__ prompts/           # Global/User-defined prompts
-  \__ agents/            # Global/User-defined agent roles
+  ├── (1) config.json        # User configuration
+  ├── (2) config.local.json  # User local configuration (including secrets)
+  ├── prompts/               # Global/User-defined prompts
+  └── agents/                # Global/User-defined agent roles
 
 <project-root>
-  \__ .plain-agent/
-        \__ config.json            # Project-specific configuration
-        \__ config.local.json      # Project-specific local configuration (including secrets)
-        \__ memory/                # Task-specific memory files
-        \__ prompts/               # Project-specific prompts
-        \__ agents/                # Project-specific agent roles
+  └── .plain-agent/
+        ├── (3) config.json        # Project-specific configuration
+        ├── (4) config.local.json  # Project-specific local configuration (including secrets)
+        ├── memory/                  # Task-specific memory files
+        ├── prompts/                 # Project-specific prompts
+        └── agents/                  # Project-specific agent roles
 ```
 
-The agent loads configuration files in the following order. Settings in later files will override those in earlier files.
-
-- `~/.config/plain-agent/config.json`
-- `~/.config/plain-agent/config.local.json`
-- `.plain-agent/config.json`
-- `.plain-agent/config.local.json`
-
 ### Example
 
 <details>
@@ -423,19 +387,19 @@ The agent loads configuration files in the following order. Settings in later fi
     "patterns": [
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?\\.plain-agent/memory/.+\\.md$" } },
+        "input": { "filePath": { "$regex": "^\\.plain-agent/memory/.+\\.md$" } },
         "action": "allow"
       },
       {
         "toolName": { "$regex": "^(write_file|patch_file)$" },
-        "input": { "filePath": { "$regex": "^(\\./)?src/" } },
+        "input": { "filePath": { "$regex": "^src/" } },
         "action": "allow"
       },
 
       // ⚠️ Arbitrary code execution can access unauthorized files and networks. Always use a sandbox.
       {
         "toolName": "exec_command",
-        "input": { "command": "npm", "args": ["run", { "$regex": "^(check|test|lint|fix)$" }] },
+        "input": { "command": "npm", "args": ["run", { "$regex": "^(lint|test)$" }] },
         "action": "allow"
       },
 
@@ -511,8 +475,8 @@ The agent loads configuration files in the following order. Settings in later fi
     }
   },
 
-  // Override default notification command
-  // "notifyCmd": "/path/to/notification-command"
+  // Override default notification command (falls back to terminal bell)
+  // "notifyCmd": { "command": "plain-notify-desktop", "args": [] }
 
   // (Optional) Voice input. See "Voice Input" below.
   // "voiceInput": {
@@ -523,10 +487,35 @@ The agent loads configuration files in the following order. Settings in later fi
 ```
 </details>
 
+## Available Tools
+
+The agent can use the following tools to assist with tasks:
+
+- **exec_command**: Run a command without shell interpretation.
+- **write_file**: Write a file.
+- **patch_file**: Patch a file.
+- **tmux_command**: Run a tmux command.
+- **ask_web**: Use the web search to answer questions that need up-to-date information or supporting sources. (requires Google API key or Vertex AI configuration).
+- **ask_url**: Use one or more provided URLs to answer a question. Include the URLs in your question. (requires Google API key or Vertex AI configuration).
+- **delegate_to_subagent**: Delegate a subtask to a subagent. The agent switches to a subagent role within the same conversation, focusing on the specified goal.
+- **report_as_subagent**: Report completion and return to the main agent. Used by subagents to communicate results and restore the main agent role. After reporting, the subagent's conversation history is removed from the context.
+- **compact_context**: Compact the conversation context by discarding prior messages and reloading task state from a memory file. Use when the context has grown large but the task is not yet complete. Can also be invoked via the `/compact` slash command.
+
 ## Prompts
 
 You can define reusable prompts in Markdown files.
 
+### Locations
+
+The agent searches for prompts in the following directories:
+
+- `~/.config/plain-agent/prompts/`
+- `.plain-agent/prompts/`
+- `.claude/commands/`
+- `.claude/skills/`
+
+The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
+
 ### Prompt File Format
 
 ```md
@@ -548,30 +537,8 @@ import: https://raw.githubusercontent.com/anthropics/claude-code/5cff78741f54a0d
 - Parallel execution of subagents is not supported. Delegate to subagents sequentially.
 ```
 
-```md
----
-import: https://raw.githubusercontent.com/anthropics/claude-code/db8834ba1d72e9a26fba30ac85f3bc4316bb0689/plugins/code-review/commands/code-review.md
----
-
-- Parallel execution of subagents is not supported. Delegate to subagents sequentially.
-- If CLAUDE.md is not found, refer to AGENTS.md instead for project rules and conventions.
-- If the PR branch is already checked out, review changes from local files instead of fetching from GitHub.
-- After explaining the review results to the user, ask whether to post the comments to GitHub as well.
-```
-
 Remote prompts are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for prompts in the following directories:
-
-- `~/.config/plain-agent/prompts/`
-- `.plain-agent/prompts/`
-- `.claude/commands/`
-- `.claude/skills/`
-
-The prompt ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/prompts/commit.md` becomes `/prompts:commit`.
-
 ### Shortcuts
 
 Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shortcuts/commit.md`) can be invoked directly as a top-level command (e.g., `/commit`).
@@ -580,6 +547,14 @@ Prompts located in a `shortcuts/` subdirectory (e.g., `.plain-agent/prompts/shor
 
 Subagents are specialized agents designed for specific tasks.
 
+### Locations
+
+The agent searches for subagent definitions in the following directories:
+
+- `~/.config/plain-agent/agents/`
+- `.plain-agent/agents/`
+- `.claude/agents/`
+
 ### Subagent File Format
 
 ```md
@@ -602,14 +577,6 @@ Use AGENTS.md instead of CLAUDE.md in this project.
 
 Remote subagents are fetched and cached locally. The local content will be appended to the imported content.
 
-### Locations
-
-The agent searches for subagent definitions in the following directories:
-
-- `~/.config/plain-agent/agents/`
-- `.plain-agent/agents/`
-- `.claude/agents/`
-
 ## Claude Code Plugin Support
 
 Example:
@@ -653,9 +620,10 @@ and send them like regular text.
 
 ### Providers
 
-**OpenAI Realtime** (default, recommended):
+**OpenAI Realtime**
 
 ```js
+// ~/.config/plain-agent/config.local.json
 {
   "voiceInput": {
     "provider": "openai",
@@ -666,9 +634,10 @@ and send them like regular text.
 }
 ```
 
-**Gemini Live** (preview API; model names and pricing may change):
+**Gemini Live**
 
 ```js
+// ~/.config/plain-agent/config.local.json
 {
   "voiceInput": {
     "provider": "gemini",
@@ -683,8 +652,7 @@ and send them like regular text.
 
 - `toggleKey` — Rebind the toggle. Accepts `"ctrl-<char>"` where `<char>`
   is a letter (a-z) or one of `[ \ ] ^ _`. Defaults to `"ctrl-o"`.
-- `recorder` — Override recorder auto-detection. Must write raw 16-bit
-  little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
+- `recorder` — Override recorder auto-detection, e.g. `{ "command": "sox", "args": ["-q", "-d", "-b", "16", "-c", "1", "-r", "24000", "-e", "signed-integer", "-t", "raw", "-"] }`. Must write raw 16-bit little-endian mono PCM to stdout at 24 kHz (OpenAI) or 16 kHz (Gemini).
 
 ## Development
 
@@ -705,13 +673,9 @@ npx npm-check-updates -t minor -c 3 -u
 ## Release
 
 ```sh
-npm run check
-
-git commit -m "<message>"
-
 npm version <major|minor|patch>
-git push --follow-tags
 
+git push --follow-tags
 gh release create $(git describe --tags) --generate-notes
 
 npm publish --access public

package/config/agents.predefined/sandbox-configurator.md

@@ -63,9 +63,10 @@ Present the analysis results and ask the user to confirm. Show:
 3. **Volume configuration** (e.g., "node_modules + npm cache")
 4. **Setup install command** (e.g., "npm ci")
 
-Ask only one additional question:
+Ask the following questions one at a time, waiting for the user's answer before proceeding to the next:
 
-> Do you want to mount `~/.gitconfig` into the sandbox? (This allows git commit inside the sandbox.)
+1. Do you want to mount `~/.gitconfig` into the sandbox? (This allows git commit inside the sandbox.)
+2. Are there any commands that must run on the host instead of inside the container? (e.g. `gh`, `docker` — tools that require host credentials or sockets.) If so, which ones?
 
 ## Step 3: Generate run.sh
 
@@ -115,7 +116,7 @@ set -eu -o pipefail
 
 this_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Setup sandbox (install runtime and dependencies with network access)
+# Build Docker image and setup sandbox (install runtime and dependencies with network access)
 "$this_dir/sandbox/run.sh" --verbose --allow-net 0.0.0.0/0 mise use node@lts
 "$this_dir/sandbox/run.sh" --verbose --allow-net 0.0.0.0/0 npm ci
 
@@ -125,21 +126,19 @@ npm ci
 
 `--allow-net 0.0.0.0/0` is needed only during setup for downloading packages. It should NOT be in run.sh for normal usage.
 
-## Step 5: Show config.json Example
+## Step 5: Update config.json
 
-After generating all files, instruct the user to add the following to their `.plain-agent/config.json`:
+Show the user the following config and explain:
+
+- `--skip-build` assumes the image is already built (run `setup.sh` first to build)
+- `--keep-alive 30` reuses the container for 30 seconds between commands for performance
+
+If the user specified any unsandboxed commands in Step 2, also include and explain:
+
+- They run **unsandboxed** because they need host access.
 
 ```json
 {
-  "autoApproval": {
-    "patterns": [
-      {
-        "toolName": "exec_command",
-        "input": { "command": { "$regex": "^(gh|docker)$" } },
-        "action": "ask"
-      }
-    ]
-  },
   "sandbox": {
     "command": ".plain-agent/sandbox/run.sh",
     "args": ["--skip-build", "--keep-alive", "30"],
@@ -154,7 +153,6 @@ After generating all files, instruct the user to add the following to their `.pl
 }
 ```
 
-If the project already has a `.plain-agent/config.json`, show only the keys that should be added/merged. Remind the user:
-- `--skip-build` assumes the image is already built (run `setup.sh` first to build)
-- `--keep-alive 30` reuses the container for 30 seconds between commands for performance
-- `gh` and `docker` run unsandboxed (host access needed), so they should also be set to `ask` in `autoApproval` to avoid being auto-approved alongside other shell commands. Place this `ask` pattern before any broad `allow` pattern for `exec_command`, since `autoApproval` patterns are evaluated in order and the first match wins.
+Adjust the regex to match the commands the user specified. If none, omit `sandbox.rules`.
+
+After the user confirms, write the config into `.plain-agent/config.json` (merge if the file already exists).

package/config/config.predefined.json

@@ -813,7 +813,7 @@
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-medium",
       "platform": {
         "name": "openai",
@@ -823,7 +823,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "medium", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -833,14 +833,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-high",
       "platform": {
         "name": "openai",
@@ -850,7 +850,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "high", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -860,14 +860,14 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },
     {
-      "name": "gpt-5.4",
+      "name": "gpt-5.5",
       "variant": "thinking-xhigh",
       "platform": {
         "name": "openai",
@@ -877,7 +877,7 @@
       "model": {
         "format": "openai-responses",
         "config": {
-          "model": "gpt-5.4",
+          "model": "gpt-5.5",
           "reasoning": { "effort": "xhigh", "summary": "auto" },
           "store": false,
           "include": ["reasoning.encrypted_content"]
@@ -887,9 +887,9 @@
         "currency": "USD",
         "unit": "1M",
         "costs": {
-          "input_tokens": 2.5,
-          "input_tokens_details.cached_tokens": -2.25,
-          "output_tokens": 15
+          "input_tokens": 5,
+          "input_tokens_details.cached_tokens": -4.5,
+          "output_tokens": 30
         }
       }
     },

package/config/prompts.predefined/shortcuts/configure.md

@@ -0,0 +1,60 @@
+---
+description: Update plain-agent configuration based on user needs.
+---
+
+Fetch the latest README and help the user configure plain-agent for this project. Before each step, briefly explain to the user what you are about to do and why.
+
+## Security Rule (Non-Negotiable)
+
+**Never write credentials** (API keys, tokens, passwords, secrets) into any config file.
+
+When a setting requires a credential:
+1. Tell the user it must go into `.plain-agent/config.local.json`.
+2. Show the exact JSON snippet they need to add.
+3. Do not modify that file yourself.
+
+If the user wants a setting applied globally (`~/.config/plain-agent/`), show them the exact snippet and tell them to add it manually. Do not access the home directory.
+
+## Step 1: Fetch the Latest README
+
+Fetch the latest README from GitHub as the authoritative reference for all configuration options:
+
+```sh
+gh api --method GET -H "Accept: application/vnd.github.v3.raw" "repos/iinm/plain-agent/contents/README.md?ref=main"
+```
+
+## Step 2: Read the Current Config
+
+```sh
+cat .plain-agent/config.json
+```
+
+## Step 3: Ask the User What They Want
+
+Ask what the user wants to configure. Common topics:
+
+- **Model** — which LLM to use (`model` field)
+- **Auto-approval rules** — which tool calls to allow automatically (`autoApproval`)
+- **Sandbox** — isolated execution environment (`sandbox`)
+- **MCP servers** — external tool integrations (`mcpServers`)
+- **Claude Code plugins** — reuse Claude Code plugin prompts/agents (`claudeCodePlugins`)
+- **Voice input** — voice transcription settings (`voiceInput`)
+- **Notifications** — custom notify command (`notifyCmd`)
+
+If the request is vague, ask a focused clarifying question before proceeding.
+
+**If the user wants to configure Sandbox**: immediately delegate to the `sandbox-configurator` agent and do not proceed further yourself.
+
+## Step 4: Apply Changes
+
+Update `.plain-agent/config.json`. Rules:
+
+- Merge carefully — preserve all existing keys.
+- Only write to `.plain-agent/config.json`. Never access files outside the project directory.
+- For credential-requiring fields, use a placeholder like `"<YOUR_API_KEY>"` and instruct the user to add the real value to `.plain-agent/config.local.json` themselves.
+
+## Step 5: Summarize
+
+1. Show a diff or summary of what changed.
+2. If any credentials were skipped, show the snippet the user needs to add to `config.local.json`.
+3. Tell the user to restart `plain` for changes to take effect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.19",
+  "version": "1.7.21",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",
@@ -10,9 +10,7 @@
   },
   "bin": {
     "plain": "./bin/plain",
-    "plain-interrupt": "./bin/plain-interrupt",
     "plain-notify-desktop": "./bin/plain-notify-desktop",
-    "plain-notify-terminal-bell": "./bin/plain-notify-terminal-bell",
     "plain-sandbox": "./sandbox/bin/plain-sandbox"
   },
   "files": [

package/src/agentLoop.mjs

@@ -128,7 +128,9 @@ export function createAgentLoop({
 
       const { message: assistantMessage, providerTokenUsage } = modelOutput;
       stateManager.appendMessages([assistantMessage]);
-      agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      if (providerTokenUsage) {
+        agentEventEmitter.emit("providerTokenUsage", providerTokenUsage);
+      }
 
       // Gemini may stop with "thinking" -> continue
       const lastContent = assistantMessage.content.at(-1);