@iinm/plain-agent 1.7.20 → 1.7.21

package/README.md

@@ -255,30 +255,22 @@ Create the configuration.
 ```
 </details>
 
-
-
 Run the agent.
 
 ```sh
 plain
+```
 
-# Or
+```
 plain -m <model+variant>
 ```
 
-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.
 
-(Optional) Set up a sandbox for your project with the `sandbox-configurator` agent.
+Display the help message.
 
 ```
-/agents:sandbox-configurator Set up a sandbox for this project
-```
-
-After the agent finishes, run the generated setup script once to build the sandbox image and install dependencies.
-
-```sh
-./.plain-agent/setup.sh
+/help
 ```
 
 Run in batch mode (non-interactive).
@@ -291,34 +283,27 @@ plain batch \
       "Add tests for ..."
 ```
 
-Display the help message.
-
-```
-/help
-```
-
 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
 ```
 
-## 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
 
@@ -502,6 +487,20 @@ Files are loaded in the following order. Settings in later files override earlie
 ```
 </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.
@@ -624,6 +623,7 @@ and send them like regular text.
 **OpenAI Realtime**
 
 ```js
+// ~/.config/plain-agent/config.local.json
 {
   "voiceInput": {
     "provider": "openai",
@@ -637,6 +637,7 @@ and send them like regular text.
 **Gemini Live**
 
 ```js
+// ~/.config/plain-agent/config.local.json
 {
   "voiceInput": {
     "provider": "gemini",

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/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.20",
+  "version": "1.7.21",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",