@iinm/plain-agent 1.0.5 → 1.0.7

package/README.md

@@ -2,25 +2,24 @@
 
 A lightweight CLI-based coding agent.
 
-- **Safety controls** — Configure per-tool approval rules and run in a sandbox for stronger isolation
-- **Multi-provider** — Works with Anthropic, OpenAI, Gemini, AWS Bedrock, Azure, Vertex AI, and more
-- **Sequential subagent delegation** — Delegate subtasks to specialized subagents with full visibility into their actions
+- **Safety controls** — Configure approval rules and sandboxing for safe execution
+- **Multi-provider** — Supports Anthropic, OpenAI, Gemini, Bedrock, Azure, Vertex AI, and more
+- **Sequential subagent delegation** — Delegate subtasks to specialized subagents with full visibility
 - **MCP support** — Connect to external MCP servers to extend available tools
-- **Claude Code compatible** *(experimental)* — Reuse Claude Code plugins, agents, commands, and skills
+- **Claude Code compatible** — Reuse Claude Code plugins, agents, commands, and skills
 
 ## Safety Controls
 
-This CLI tool automatically allows the execution of certain tools but requires explicit approval for security-sensitive operations, such as accessing parent directories.
-The security rules are defined in [`config.predefined.json`](https://github.com/iinm/plain-agent/blob/main/.config/config.predefined.json) and [`toolInputValidator.mjs`](https://github.com/iinm/plain-agent/blob/main/src/toolInputValidator.mjs) within this repository.
+**Auto-Approval**: Tools with no side effects and no sensitive data access are automatically approved based on patterns defined in [`config.predefined.json#autoApproval`](https://github.com/iinm/plain-agent/blob/main/.config/config.predefined.json).
 
-⚠️ The `write_file` and `patch_file` tools block direct access to git-ignored files. However, `exec_command` can access any files in your environment.
-Use a sandbox for stronger isolation.
+**Path Validation**: All file paths in tool inputs are validated to remain within the working directory and under git control.
+
+⚠️ `write_file` and `patch_file` require explicit path arguments. However, `exec_command` can run arbitrary code where file access cannot be validated. Use a sandbox for stronger isolation.
 
 ## Requirements
 
-- Linux or macOS
 - Node.js 22 or later
-- LLM provider credentials (API keys, AWS SSO, gcloud CLI, or Azure CLI)
+- LLM provider credentials
 - bash / docker for sandboxed execution
 - [ripgrep](https://github.com/burntsushi/ripgrep)
 - [fd](https://github.com/sharkdp/fd)
@@ -34,8 +33,7 @@ npm install -g @iinm/plain-agent
 List available models.
 
 ```sh
-curl https://raw.githubusercontent.com/iinm/plain-agent/refs/heads/main/.config/config.predefined.json \
-  | jq -r '.models[] | "\(.name)+\(.variant)"'
+plain --list-models
 ```
 
 Create the configuration.
@@ -43,9 +41,10 @@ Create the configuration.
 ```js
 // ~/.config/plain-agent/config.local.json
 {
-  // Default model
   "model": "gpt-5.4+thinking-high",
+  // "model": "claude-sonnet-4-6+thinking-16k",
 
+  // Configure the providers you want to use
   "platforms": [
     {
       "name": "anthropic",
@@ -61,13 +60,35 @@ Create the configuration.
       "name": "openai",
       "variant": "default",
       "apiKey": "FIXME"
+    },
+    {
+      // Requires Azure CLI to get access token
+      "name": "azure",
+      "variant": "default",
+      "baseURL": "https://<resource>.openai.azure.com/openai",
+      // Optional
+      "azureConfigDir": "/home/xxx/.azure-for-agent"
+    },
+    {
+      "name": "bedrock",
+      "variant": "default",
+      "baseURL": "https://bedrock-runtime.<region>.amazonaws.com",
+      "awsProfile": "FIXME"
+    },
+    {
+      // Requires gcloud CLI to get authentication token
+      "name": "vertex-ai",
+      "variant": "default",
+      "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project>/locations/<location>",
+      // Optional
+      "account": "<service_account_email>"
     }
   ],
 
   // Optional
   "tools": {
     "askGoogle": {
-      "model": "gemini-3-flash-preview"
+      "model": "gemini-3-flash-preview",
 
       // Google AI Studio
       "apiKey": "FIXME"
@@ -76,42 +97,22 @@ Create the configuration.
       // "platform": "vertex-ai",
       // "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project_id>/locations/<location>",
     },
-    "tavily": {
-      "apiKey": "FIXME"
+
+    "searchWeb": {
+      "tavilyApiKey": "FIXME"
     }
-  }
+  },
+
 }
 
 ```
 
 <details>
-<summary>Extra provider examples</summary>
+<summary>Other provider examples</summary>
 
 ```js
 {
   "platforms": [
-    {
-      // Requires Azure CLI to get access token
-      "name": "azure",
-      "variant": "default",
-      "baseURL": "https://<resource>.openai.azure.com/openai",
-      // Optional
-      "azureConfigDir": "/home/xxx/.azure-for-agent"
-    },
-    {
-      "name": "bedrock",
-      "variant": "default",
-      "baseURL": "https://bedrock-runtime.<region>.amazonaws.com",
-      "awsProfile": "FIXME"
-    },
-    {
-      // Requires gcloud CLI to get authentication token
-      "name": "vertex-ai",
-      "variant": "default",
-      "baseURL": "https://aiplatform.googleapis.com/v1beta1/projects/<project>/locations/<location>",
-      // Optional
-      "account": "<service_account_email>"
-    },
     {
       "name": "openai",
       "variant": "ollama",
@@ -139,7 +140,7 @@ Run the agent.
 ```sh
 plain
 
-# Or specify a specific model
+# Or
 plain -m <model>+<variant>
 ```
 
@@ -164,8 +165,8 @@ The agent can use the following tools to assist with tasks:
 - **patch_file**: Patch a file.
 - **tmux_command**: Run a tmux command.
 - **fetch_web_page**: Fetch and extract web page content from a given URL, returning it as Markdown.
+- **ask_google**: Ask Google a question using natural language (requires Google API key or Vertex AI configuration).
 - **search_web**: Search the web for information (requires Tavily API key).
-- **ask_google**: Ask Google a question using natural language (requires Gemini API key).
 - **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.
 
@@ -205,13 +206,10 @@ The agent loads configuration files in the following order. Settings in later fi
 ```js
 {
   "autoApproval": {
-    // Automatically deny unmatched tools instead of asking
     "defaultAction": "deny",
-    // The maximum number of automatic approvals.
     "maxApprovals": 100,
-    // Patterns are evaluated in order. First match wins.
     "patterns": [
-      // Prohibit direct access to external URLs
+      // Prohibit direct access to external URLs (even GET requests can leak data via URL parameters)
       {
         "toolName": "fetch_web_page",
         "action": "deny",
@@ -268,7 +266,7 @@ 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"
       },
       {
@@ -277,8 +275,7 @@ The agent loads configuration files in the following order. Settings in later fi
         "action": "allow"
       },
 
-      // ⚠️ `npm run test` may execute arbitrary code and access git-ignored files.
-      // It must be run in a sandbox.
+      // ⚠️ 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)$" }] },
@@ -326,7 +323,7 @@ The agent loads configuration files in the following order. Settings in later fi
     ]
   },
 
-  // Configure MCP servers for extended functionality
+  // Configure MCP servers
   "mcpServers": {
     "chrome_devtools": {
       "command": "npx",
@@ -364,12 +361,10 @@ The agent loads configuration files in the following order. Settings in later fi
 
 ## Prompts
 
-You can define reusable prompts in Markdown files. These are especially useful for common tasks like creating commit messages or conducting retrospectives.
+You can define reusable prompts in Markdown files.
 
 ### Prompt File Format
 
-Prompts are Markdown files with a YAML frontmatter:
-
 ```md
 ---
 description: Create a commit message based on staged changes
@@ -406,25 +401,23 @@ Remote prompts are fetched and cached locally. The local content will be appende
 
 The agent searches for prompts in the following directories:
 
-- `~/.config/plain-agent/prompts/` (Global/User-defined prompts)
-- `.plain-agent/prompts/` (Project-specific prompts)
-- `.claude/commands/` (Claude-specific commands, prefixed with `claude/commands:`)
-- `.claude/skills/` (Claude-specific skills, prefixed with `claude/skills:`)
+- `~/.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/retro.md` becomes `/prompts:retro`.
+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/review.md`) can be invoked directly as a top-level command (e.g., `/review`). This is useful for frequently used tasks. If a prompt is in a `shortcuts/` subdirectory, its ID is simplified by removing the `shortcuts/` prefix for use as a shortcut (e.g., `shortcuts/review` becomes `/review`).
+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`).
 
 ## Subagents
 
-Subagents are specialized agents that can be delegated specific tasks. They allow you to break down complex workflows into focused, manageable components.
+Subagents are specialized agents designed for specific tasks.
 
 ### Subagent File Format
 
-Subagent definitions are Markdown files with a YAML frontmatter:
-
 ```md
 ---
 description: Simplifies and refines code for clarity and maintainability
@@ -449,11 +442,9 @@ Remote subagents are fetched and cached locally. The local content will be appen
 
 The agent searches for subagent definitions in the following directories:
 
-- `~/.config/plain-agent/agents/` (Global/User-defined agents)
-- `.plain-agent/agents/` (Project-specific agents)
-- `.claude/agents/` (Claude-specific agents)
-
-The subagent ID is the relative path of the file without the `.md` extension. For example, `.plain-agent/agents/worker.md` becomes `worker`.
+- `~/.config/plain-agent/agents/`
+- `.plain-agent/agents/`
+- `.claude/agents/`
 
 ## Claude Code Plugin Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",

package/src/cliArgs.mjs

@@ -2,6 +2,7 @@
  * @typedef {Object} CliArgs
  * @property {string|null} model - Model name with variant
  * @property {boolean} showHelp - Whether to show help message
+ * @property {boolean} listModels - Whether to list available models
  */
 
 /**
@@ -12,13 +13,15 @@
 export function parseCliArgs(argv) {
   const args = argv.slice(2);
   /** @type {CliArgs} */
-  const result = { model: null, showHelp: false };
+  const result = { model: null, showHelp: false, listModels: false };
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "-m" && args[i + 1]) {
       result.model = args[++i];
     } else if (args[i] === "-h" || args[i] === "--help") {
       result.showHelp = true;
+    } else if (args[i] === "-l" || args[i] === "--list-models") {
+      result.listModels = true;
     }
   }
 
@@ -35,6 +38,7 @@ Usage: agent [options]
 
 Options:
   -m <model+variant>  Model to use
+  -l, --list-models   List available models
   -h, --help          Show this help message
 
 Examples:

package/src/config.d.ts

@@ -18,9 +18,6 @@ export type AppConfig = {
   };
   sandbox?: ExecCommandSanboxConfig;
   tools?: {
-    tavily?: {
-      apiKey?: string;
-    };
     /**
      * - Vertex AI: requires baseURL and account
      * - AI Studio: requires apiKey
@@ -32,6 +29,9 @@ export type AppConfig = {
       apiKey?: string;
       model?: string;
     };
+    searchWeb?: {
+      tavilyApiKey?: string;
+    };
   };
   mcpServers?: Record<string, MCPServerConfig>;
   notifyCmd?: string;

package/src/config.mjs

@@ -16,9 +16,12 @@ import {
 import { evalJSONConfig } from "./utils/evalJSONConfig.mjs";
 
 /**
+ * @param {Object} [options]
+ * @param {boolean} [options.skipTrustCheck] - Skip trust check for config files
  * @returns {Promise<{appConfig: AppConfig, loadedConfigPath: string[]}>}
  */
-export async function loadAppConfig() {
+export async function loadAppConfig(options = {}) {
+  const { skipTrustCheck = false } = options;
   const paths = [
     `${AGENT_ROOT}/.config/config.predefined.json`,
     `${AGENT_USER_CONFIG_DIR}/config.json`,
@@ -33,7 +36,7 @@ export async function loadAppConfig() {
   let merged = {};
 
   for (const filePath of paths) {
-    const config = await loadConfigFile(path.resolve(filePath));
+    const config = await loadConfigFile(path.resolve(filePath), skipTrustCheck);
     if (Object.keys(config).length) {
       loadedConfigPath.push(filePath);
     }
@@ -55,9 +58,9 @@ export async function loadAppConfig() {
       },
       sandbox: config.sandbox ?? merged.sandbox,
       tools: {
-        tavily: {
-          ...(merged.tools?.tavily ?? {}),
-          ...(config.tools?.tavily ?? {}),
+        searchWeb: {
+          ...(merged.tools?.searchWeb ?? {}),
+          ...(config.tools?.searchWeb ?? {}),
         },
         askGoogle: {
           ...(merged.tools?.askGoogle ?? {}),
@@ -81,9 +84,10 @@ export async function loadAppConfig() {
 
 /**
  * @param {string} filePath
+ * @param {boolean} [skipTrustCheck=false]
  * @returns {Promise<AppConfig>}
  */
-export async function loadConfigFile(filePath) {
+export async function loadConfigFile(filePath, skipTrustCheck = false) {
   let content;
   try {
     content = await fs.readFile(filePath, "utf-8");
@@ -95,7 +99,7 @@ export async function loadConfigFile(filePath) {
   }
 
   const hash = crypto.createHash("sha256").update(content).digest("hex");
-  const isTrusted = await isConfigHashTrusted(hash);
+  const isTrusted = skipTrustCheck || (await isConfigHashTrusted(hash));
 
   if (!isTrusted) {
     if (!process.stdout.isTTY) {

package/src/main.mjs

@@ -33,6 +33,21 @@ if (cliArgs.showHelp) {
   printHelp();
 }
 
+if (cliArgs.listModels) {
+  const { appConfig } = await loadAppConfig({ skipTrustCheck: true });
+  if (!appConfig.models || appConfig.models.length === 0) {
+    console.error("No models found in configuration.");
+    process.exit(1);
+  }
+  for (const model of appConfig.models) {
+    const platform = model.platform;
+    console.log(
+      `${model.name}+${model.variant} (platform: ${platform.name}+${platform.variant})`,
+    );
+  }
+  process.exit(0);
+}
+
 (async () => {
   const startTime = new Date();
   const sessionId = [
@@ -118,8 +133,8 @@ if (cliArgs.showHelp) {
     createReportAsSubagentTool(),
   ];
 
-  if (appConfig.tools?.tavily?.apiKey) {
-    builtinTools.push(createTavilySearchTool(appConfig.tools.tavily));
+  if (appConfig.tools?.searchWeb?.tavilyApiKey) {
+    builtinTools.push(createTavilySearchTool(appConfig.tools.searchWeb));
   }
 
   if (appConfig.tools?.askGoogle) {

package/src/tools/tavilySearch.mjs

@@ -6,7 +6,7 @@
 import { noThrow } from "../utils/noThrow.mjs";
 
 /**
- * @param {{apiKey?: string}} config
+ * @param {{tavilyApiKey?: string}} config
  * @returns {Tool}
  */
 export function createTavilySearchTool(config) {
@@ -34,7 +34,7 @@ export function createTavilySearchTool(config) {
         const response = await fetch("https://api.tavily.com/search", {
           method: "POST",
           headers: {
-            Authorization: `Bearer ${config.apiKey}`,
+            Authorization: `Bearer ${config.tavilyApiKey}`,
             "Content-Type": "application/json",
           },
           body: JSON.stringify({