@iinm/plain-agent 1.12.1 → 1.13.1

package/README.md

@@ -1,10 +1,8 @@
 # Plain Agent
 
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/iinm/plain-agent)
-[![npm version](https://img.shields.io/npm/v/@iinm/plain-agent)](https://www.npmjs.com/package/@iinm/plain-agent)
-[![install size](https://packagephobia.com/badge?p=@iinm/plain-agent)](https://packagephobia.com/result?p=@iinm/plain-agent)
-[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.12.1)](https://socket.dev/npm/package/@iinm/plain-agent)
 [![CodeQL](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/iinm/plain-agent/actions/workflows/github-code-scanning/codeql)
+[![Socket Badge](https://badge.socket.dev/npm/package/@iinm/plain-agent/1.13.1)](https://socket.dev/npm/package/@iinm/plain-agent)
+[![install size](https://packagephobia.com/badge?p=@iinm/plain-agent)](https://packagephobia.com/result?p=@iinm/plain-agent)
 
 A lightweight terminal-based coding agent focused on safety and low token cost
 
@@ -189,9 +187,8 @@ A Docker-based wrapper called `plain-sandbox` is included, but the interface is
 {
   "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"],
+    "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--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": "--",
@@ -544,6 +541,17 @@ plain resume --list
 plain resume 2026-05-10-0803-a7k
 ```
 
+Launch the sandbox command using the app config's sandbox settings.
+Arguments before `--` are flags for the `plain` CLI itself (e.g. `-c` to load a
+config file). Arguments after `--` are passed through to the sandbox command as-is.
+
+```sh
+plain sandbox -- --tty zsh
+
+# Or specify a config file explicitly
+plain sandbox -c .plain-agent/config.sandbox.json -- --tty zsh
+```
+
 ## Configuration
 
 Files are loaded in the following order. Settings in later files override earlier ones.
@@ -618,9 +626,8 @@ 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", "--mount-readonly", ".plain-agent/config.json", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--keep-alive", "30"],
     // ↑ --mount-readonly: prevents the agent from overwriting its own config
     "separator": "--"
   }
@@ -691,9 +698,8 @@ 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", "--mount-readonly", ".plain-agent/config.json", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--mount-readonly", ".plain-agent/config.json", "--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": "--",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.12.1",
+  "version": "1.13.1",
   "description": "A lightweight terminal-based coding agent focused on safety and low token cost",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
     "!src/**/*.test.mjs",
     "!src/**/*.test.*.mjs",
     "!src/**/*.playground.mjs",
+    "!src/test-reporter.mjs",
     "!src/**/test/"
   ],
   "engines": {
@@ -33,9 +34,9 @@
   },
   "scripts": {
     "check": "npm run lint && tsc && npm run test && npm run test:e2e && npm run test:predefined-approval",
-    "test": "node --test 'src/**/*.test.mjs'",
-    "test:e2e": "node --test --test-timeout=30000 'e2e/**/*.test.mjs'",
-    "coverage": "c8 --exclude='src/**/*.test.mjs' --exclude='e2e/**' node --test --test-force-exit 'src/**/*.test.mjs' 'e2e/**/*.test.mjs'",
+    "test": "node --test --test-reporter=./src/test-reporter.mjs 'src/**/*.test.mjs'",
+    "test:e2e": "node --test --test-reporter=./src/test-reporter.mjs --test-timeout=30000 'e2e/**/*.test.mjs'",
+    "coverage": "c8 --exclude='src/**/*.test.mjs' --exclude='e2e/**' node --test --test-reporter=./src/test-reporter.mjs --test-force-exit 'src/**/*.test.mjs' 'e2e/**/*.test.mjs'",
     "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",

package/sandbox/bin/plain-sandbox

@@ -23,7 +23,7 @@ Usage: $SCRIPT_NAME [--dockerfile FILE]
            [--publish [HOST_ADDRESS:]HOST_PORT:CONTAINER_PORT]
            [--tty]
            [--no-cache]
-           [--skip-build]
+           [--rebuild]
            [--verbose] [--dry-run]
            [--keep-alive SECONDS]
            COMMAND
@@ -69,8 +69,8 @@ Options:
                             If no host address is given, ports bind to 127.0.0.1 by default.
 
   --tty                     Allocate a pseudo-TTY for the container.
-  --no-cache                Disables cache when building the image.
-  --skip-build              Skips building the image; assumes it already exists.
+  --no-cache                Disables cache when building the image (forces rebuild).
+  --rebuild                 Rebuild the image even if it already exists (cache is still used).
   --verbose                 Output verbose logs to stderr.
   --dry-run                 Does not execute the command; just prints it to stdout.
   --keep-alive SECONDS      Keep the container running after COMMAND finishes, so it can be reused.
@@ -151,7 +151,7 @@ main() {
   local env_file=""
   local allocate_tty="no"
   local no_cache="no"
-  local skip_build="no"
+  local rebuild="no"
   local platform=""
   local keep_alive_seconds="0"
  
@@ -199,7 +199,7 @@ main() {
       --env-file   ) env_file="$2"; shift 2 ;;
       --tty        ) allocate_tty="yes"; shift ;;
       --no-cache   ) no_cache="yes"; shift ;;
-      --skip-build ) skip_build="yes"; shift ;;
+      --rebuild    ) rebuild="yes"; shift ;;
       --verbose    ) VERBOSE="yes"; shift ;;
       --dry-run    ) DRY_RUN="yes"; shift ;;
       --keep-alive ) keep_alive_seconds="$2"; shift 2 ;;
@@ -504,9 +504,14 @@ EOF
  
   trap 'on_exit' EXIT
 
-  if test "$skip_build" = "yes"; then
-    log "Skip building docker image: $IMAGE_NAME"
-  else
+  local should_build="yes"
+  if test "$no_cache" = "yes" -o "$rebuild" = "yes"; then
+    should_build="yes"
+  elif test "$DRY_RUN" = "no" && docker image inspect "${IMAGE_NAME}:${image_tag}" &> /dev/null; then
+    should_build="no"
+  fi
+
+  if test "$should_build" = "yes"; then
     log "Building docker image: $IMAGE_NAME"
     if test -n "$dockerfile"; then
       run docker build "${docker_build_opts[@]}" "$docker_build_context"
@@ -514,9 +519,11 @@ EOF
       run docker build "${docker_build_opts[@]}" - \
         < <("$SCRIPT_PATH" print_preset_dockerfile)
     fi
+  else
+    log "Image already exists, skipping build: $IMAGE_NAME"
   fi
 
-  if test "$skip_build" = "yes" -a "$(docker inspect --type container "$container_name" --format "{{ .State.Running }}" 2> /dev/null)" = "true"; then
+  if test "$DRY_RUN" = "no" && test "$(docker inspect --type container "$container_name" --format "{{ .State.Running }}" 2> /dev/null)" = "true"; then
     log "Container is already running. Reusing $container_name"
   else
     log "Stopping any existing container: $container_name"

package/src/agentLoop.mjs

@@ -206,6 +206,13 @@ export function createAgentLoop({
         break;
       }
 
+      // Ctrl-C during model call: skip execution and ask for approval
+      if (pauseSignal.isPaused()) {
+        pauseSignal.reset();
+        agentEventEmitter.emit("toolUseRequest", toolUseParts.length);
+        break;
+      }
+
       const executionResult = await toolExecutor.executeBatch(toolUseParts);
 
       if (!executionResult.success) {

package/src/cli/args.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand | ResumeSubcommand | TestApprovalSubcommand} Subcommand
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand | ResumeSubcommand | TestApprovalSubcommand | SandboxSubcommand} Subcommand
  */
 
 /**
@@ -37,6 +37,12 @@
  * @typedef {{ type: 'resume', sessionId: string | null, list: boolean, config: string[] }} ResumeSubcommand
  */
 
+/**
+ * Launch the sandbox command using the app config's sandbox settings.
+ * Arguments after `--` are passed through to the sandbox command as-is.
+ * @typedef {{ type: 'sandbox', config: string[], passthroughArgs: string[] }} SandboxSubcommand
+ */
+
 /**
  * @typedef {Object} CliArgs
  * @property {Subcommand} subcommand - The subcommand to execute
@@ -172,6 +178,31 @@ export function parseCliArgs(argv) {
     };
   }
 
+  if (subcommandName === "sandbox") {
+    const sandboxArgs = args.slice(1);
+    /** @type {string[]} */
+    const config = [];
+    /** @type {string[]} */
+    const passthroughArgs = [];
+
+    for (let i = 0; i < sandboxArgs.length; i++) {
+      if (sandboxArgs[i] === "--") {
+        passthroughArgs.push(...sandboxArgs.slice(i + 1));
+        break;
+      }
+      if (sandboxArgs[i] === "-c" || sandboxArgs[i] === "--config") {
+        if (sandboxArgs[i + 1]) {
+          config.push(sandboxArgs[i + 1]);
+          i++;
+        }
+      }
+    }
+
+    return {
+      subcommand: { type: "sandbox", config, passthroughArgs },
+    };
+  }
+
   if (subcommandName === "cost") {
     const costArgs = args.slice(1);
     let from = null;
@@ -208,6 +239,7 @@ export function printHelp(exitCode = 0) {
 Usage: plain [options]
        plain batch [options] <task>
        plain resume [<sessionId>] [--list]
+       plain sandbox [-c <file>...] -- [sandbox args...]
        plain cost [--from YYYY-MM-DD] [--to YYYY-MM-DD]
        plain list-models
        plain install-claude-code-plugins
@@ -227,6 +259,9 @@ Subcommands:
                                see resumable sessions. Switching models is
                                not supported (-m is rejected).
   test-approval                Run auto-approval rule tests defined in config.
+  sandbox                      Launch the sandbox command using the app
+                               config's sandbox settings. Arguments after --
+                               are passed through to the sandbox command as-is.
   cost                         Show aggregated token cost per day for a period.
                                Defaults to the first day of the current month
                                through today.

package/src/cli/interactive.mjs

@@ -188,7 +188,7 @@ export function startInteractiveSession({
       console.error(
         styleText(
           "yellow",
-          "\n\n⚠️ Ctrl-C: Auto-approve paused. Finishing current tool...\nPress Ctrl-D twice to exit.\n",
+          "\n\n⚠️ Ctrl-C: Auto-approve paused.\nPress Ctrl-D twice to exit.\n",
         ),
       );
       return;

package/src/main.mjs

@@ -3,6 +3,7 @@
  * @import { SessionState } from "./sessionStore.mjs";
  */
 
+import { spawn } from "node:child_process";
 import { randomInt } from "node:crypto";
 import { styleText } from "node:util";
 import { createAgent } from "./agent.mjs";
@@ -90,6 +91,32 @@ export async function main(argv = process.argv) {
     process.exit(exitCode);
   }
 
+  if (cliArgs.subcommand.type === "sandbox") {
+    const { appConfig } = await loadAppConfig({
+      configFiles: cliArgs.subcommand.config,
+    });
+    if (!appConfig.sandbox) {
+      console.error(
+        "sandbox setting not found in config. Define a sandbox section in your config or specify one with -c.",
+      );
+      process.exit(1);
+    }
+    const sandbox = appConfig.sandbox;
+    const argsToRun = [
+      ...(sandbox.args || []),
+      ...cliArgs.subcommand.passthroughArgs,
+    ];
+    const child = spawn(sandbox.command, argsToRun, { stdio: "inherit" });
+    child.on("error", (err) => {
+      console.error(`Failed to start sandbox: ${err.message}`);
+      process.exit(1);
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+    });
+    return;
+  }
+
   if (cliArgs.subcommand.type === "resume" && cliArgs.subcommand.list) {
     const sessions = await listSessions();
     if (sessions.length === 0) {