@iinm/plain-agent 1.7.13 → 1.7.15

package/README.md

@@ -46,7 +46,7 @@ Create the configuration.
 // ~/.config/plain-agent/config.local.json
 {
   "model": "gpt-5.4+thinking-high",
-  // "model": "claude-sonnet-4-6+thinking-16k",
+  // "model": "claude-sonnet-4-6+thinking-high",
 
   // Configure the providers you want to use
   "platforms": [
@@ -191,7 +191,7 @@ Create the configuration.
     },
     {
       "name": "claude-sonnet-4-6",
-      "variant": "thinking-16k-bedrock-jp",
+      "variant": "thinking-high-bedrock-jp",
       "platform": {
         "name": "bedrock",
         "variant": "jp"
@@ -201,7 +201,8 @@ Create the configuration.
         "config": {
           "model": "jp.anthropic.claude-sonnet-4-6",
           "max_tokens": 32768,
-          "thinking": { "type": "enabled", "budget_tokens": 16384 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "high" }
         }
       },
       "cost": {
@@ -239,6 +240,18 @@ plain
 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
+```
+
+After the agent finishes, run the generated setup script once to build the sandbox image and install dependencies.
+
+```sh
+./.plain-agent/setup.sh
+```
+
 Run in batch mode (non-interactive).
 In batch mode, config files are not loaded automatically. Only the files specified with `--config` are loaded.
 
@@ -271,6 +284,7 @@ The agent can use the following tools to assist with tasks:
 - **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.
 
 ## Directory Structure
 
@@ -331,7 +345,7 @@ The agent loads configuration files in the following order. Settings in later fi
   },
   "sandbox": {
     "command": "plain-sandbox",
-    "args": ["--dockerfile", ".plain-agent/sandbox/Dockerfile", "--allow-write", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--skip-build", "--keep-alive", "30"],
     "separator": "--",
     "rules": [
       {
@@ -394,7 +408,7 @@ The agent loads configuration files in the following order. Settings in later fi
   // https://github.com/iinm/plain-agent/tree/main/sandbox
   "sandbox": {
     "command": "plain-sandbox",
-    "args": ["--dockerfile", ".plain-agent/sandbox/Dockerfile", "--allow-write", "--skip-build", "--keep-alive", "30"],
+    "args": ["--allow-write", "--skip-build", "--keep-alive", "30"],
     // separator is inserted between sandbox flags and the user command to prevent bypasses
     "separator": "--",
 

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

@@ -1,8 +1,8 @@
 ---
-description: Analyzes the project and builds sandbox configuration files (Dockerfile, run.sh, env, setup.sh) tailored to the project's needs.
+description: Analyzes the project and generates sandbox configuration files (run.sh, setup.sh) tailored to the project's needs.
 ---
 
-You are a sandbox builder. You analyze the project and generate sandbox configuration files so that commands run in an isolated Docker container.
+You are a sandbox builder. You analyze the project and generate sandbox configuration files so that commands run in an isolated Docker container using the `plain-sandbox` preset image.
 
 ## Overview
 
@@ -19,48 +19,40 @@ Before generating anything, analyze the project to determine:
 
 ### 1a. Runtime & Tools
 
-Detect the project type and determine which runtimes to install via mise:
+Detect the project type and determine which runtimes to install via mise. Use the runtime's bundled package managers instead of installing them separately via mise (e.g. Node.js ships with npm; use `corepack enable` for yarn/pnpm).
 
-| File found | mise install commands |
-|---|---|
-| `package.json` | `mise use node@<version>` (check `.nvmrc` or `.node-version`, else use LTS) |
-| `package.json` + `package-lock.json` | Add `mise use npm@latest` |
-| `package.json` + `yarn.lock` | Add `mise use yarn@latest` |
-| `package.json` + `pnpm-lock.yaml` | Add `mise use pnpm@latest` |
-| `requirements.txt` or `pyproject.toml` | `mise use python@<version>` (check `.python-version`, else 3.12) |
-| `go.mod` | `mise use go@<version>` (check `go.mod` for version directive) |
-| `Cargo.toml` | `mise use rust@latest` |
-| Multiple of the above | All detected runtimes |
+| File found | mise install commands | Version source |
+|---|---|---|
+| `package.json` | `mise use node@<version>` | `.nvmrc` / `.node-version` / `package.json` (`engines.node`) |
+| `requirements.txt` or `pyproject.toml` | `mise use python@<version>` | `.python-version` / `pyproject.toml` (`requires-python`) |
 
 Also check for common dev tools:
-- `terraform/` directory or `*.tf` files → `mise use terraform@<version>`
-- `.terraform-version` → `mise use terraform@<version>`
+- `*.tf` files or `.terraform-version` → `mise use terraform@<version>` (version source: `.terraform-version`)
+
+If a version cannot be determined from the files above, **ask the user which version to use** rather than falling back to a default.
 
 ### 1b. Volume Candidates
 
-Detect directories that should use Docker volumes (for performance with large directories):
+Detect directories that should use Docker volumes. A Docker volume is preferred over a host bind mount for `node_modules` because:
+
+- `node_modules` contains many thousands of small files, and bind-mounting it into the container is slow on macOS/Windows (file sync overhead).
+- Native modules compiled for the host OS/arch can be incompatible with the Linux container, so keeping container-side `node_modules` isolated avoids conflicts.
 
 | Project type | Cache volumes | Dependency volumes |
 |---|---|---|
-| Node.js | `plain-sandbox--global--home-npm:/home/sandbox/.npm` | `node_modules` (per package.json dir if monorepo) |
+| Node.js | `plain-sandbox--global--home-npm:/home/sandbox/.npm` | `node_modules` (per `package.json` dir if monorepo) |
 | Python | `plain-sandbox--global--home-pip:/home/sandbox/.cache/pip` | — |
-| Go | `plain-sandbox--global--home-go-pkg:/home/sandbox/go/pkg/mod` | — |
-| Rust | `plain-sandbox--global--home-cargo:/home/sandbox/.cargo/registry` | — |
 
-For monorepo detection: if multiple `package.json` files exist (excluding `node_modules`), treat as monorepo and create a volume per `node_modules` directory.
+For monorepo detection: if multiple `package.json` files exist (excluding `node_modules`), treat as a monorepo and create a volume per `node_modules` directory.
 
 ### 1c. Setup Install Commands
 
 | Project type | Install command |
 |---|---|
 | Node.js (npm) | `npm ci` (or `npm install` if no lockfile) |
-| Node.js (yarn) | `yarn install --frozen-lockfile` |
-| Node.js (pnpm) | `pnpm install --frozen-lockfile` |
+| Node.js (yarn) | `corepack enable && yarn install --frozen-lockfile` |
+| Node.js (pnpm) | `corepack enable && pnpm install --frozen-lockfile` |
 | Python | `pip install -r requirements.txt` or `pip install .` |
-| Go | `go mod download` |
-| Rust | `cargo build` |
-
-If multiple project types, include all relevant commands.
 
 ## Step 2: Confirm with User
 
@@ -77,45 +69,7 @@ Ask only one additional question:
 
 ## Step 3: Generate run.sh
 
-Generate `.plain-agent/sandbox/run.sh`. The structure varies by project type.
-
-### Monorepo handling:
-
-If multiple `package.json` files exist, dynamically create volumes for each `node_modules`:
-
-```bash
-# Create volumes for each node_modules directory
-for path in $(fd package.json --max-depth 3 | sed -E 's,package.json$,node_modules,'); do
-  mkdir -p "$path"
-  options+=("--volume" "$path")
-done
-```
-
-### Git worktree handling:
-
-Always include this block after the options array, before `plain-sandbox`:
-
-```bash
-# Mount main worktree if using git worktrees
-git_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
-if test -n "$git_root" && test -f "$git_root/.git"; then
-  main_worktree_path=$(sed -E 's,^gitdir: (.+)/.git/.+,\1,' < "$git_root/.git")
-  options+=("--mount-writable" "$main_worktree_path:$main_worktree_path")
-fi
-```
-
-### gitconfig handling:
-
-Include this block only if the user confirmed:
-
-```bash
-# Mount gitconfig
-if test -f "$HOME/.gitconfig"; then
-  options+=("--mount-readonly" "$HOME/.gitconfig:/home/sandbox/.gitconfig")
-fi
-```
-
-### Complete run.sh example (Node.js project):
+Generate `.plain-agent/sandbox/run.sh`. Use the following Node.js example as the template and adapt volumes for other runtimes from the table in Step 1b.
 
 ```bash
 #!/usr/bin/env bash
@@ -128,6 +82,13 @@ options=(
   --volume node_modules
 )
 
+# Monorepo: create a volume for each node_modules directory.
+# Include only when multiple package.json files exist.
+# for path in $(fd package.json --max-depth 3 | sed -E 's,package.json$,node_modules,'); do
+#   mkdir -p "$path"
+#   options+=("--volume" "$path")
+# done
+
 # Mount main worktree if using git worktrees
 git_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
 if test -n "$git_root" && test -f "$git_root/.git"; then
@@ -135,7 +96,7 @@ if test -n "$git_root" && test -f "$git_root/.git"; then
   options+=("--mount-writable" "$main_worktree_path:$main_worktree_path")
 fi
 
-# Mount gitconfig
+# Mount gitconfig (include only if the user confirmed)
 if test -f "$HOME/.gitconfig"; then
   options+=("--mount-readonly" "$HOME/.gitconfig:/home/sandbox/.gitconfig")
 fi
@@ -145,7 +106,7 @@ plain-sandbox "${options[@]}" "$@"
 
 ## Step 4: Generate setup.sh
 
-Generate `.plain-agent/setup.sh`:
+Generate `.plain-agent/setup.sh`. Use the following Node.js example and replace `node@lts` / `npm ci` with the commands chosen in Step 1.
 
 ```bash
 #!/usr/bin/env bash
@@ -154,24 +115,31 @@ set -eu -o pipefail
 
 this_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Setup sandbox (install dependencies inside container with full network access)
+# 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
 
-# Setup host (install dependencies on host)
+# Setup host
 npm ci
 ```
 
-The `--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.
+`--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
 
-After generating all files, display the following example and instruct the user to add it to their `.plain-agent/config.json`:
-
-```
-Add the following to your .plain-agent/config.json:
+After generating all files, instruct the user to add the following to their `.plain-agent/config.json`:
 
+```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"],
@@ -186,7 +154,7 @@ Add the following to your .plain-agent/config.json:
 }
 ```
 
-If the project already has a `.plain-agent/config.json`, show only the `sandbox` key that should be added/merged. Remind the user:
+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
-- `rules` for `gh` and `docker` should typically run unsandboxed (host access needed)
+- `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.

package/config/config.predefined.json

@@ -181,7 +181,7 @@
     },
     {
       "name": "claude-sonnet-4-6",
-      "variant": "thinking-16k",
+      "variant": "thinking-high",
       "platform": {
         "name": "anthropic",
         "variant": "default",
@@ -192,7 +192,8 @@
         "config": {
           "model": "claude-sonnet-4-6",
           "max_tokens": 32768,
-          "thinking": { "type": "enabled", "budget_tokens": 16384 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "high" }
         }
       },
       "cost": {
@@ -208,7 +209,7 @@
     },
     {
       "name": "claude-sonnet-4-6",
-      "variant": "thinking-32k",
+      "variant": "thinking-max",
       "platform": {
         "name": "anthropic",
         "variant": "default",
@@ -219,7 +220,8 @@
         "config": {
           "model": "claude-sonnet-4-6",
           "max_tokens": 64000,
-          "thinking": { "type": "enabled", "budget_tokens": 32768 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "max" }
         }
       },
       "cost": {
@@ -234,8 +236,8 @@
       }
     },
     {
-      "name": "claude-opus-4-6",
-      "variant": "thinking-16k",
+      "name": "claude-opus-4-7",
+      "variant": "thinking-high",
       "platform": {
         "name": "anthropic",
         "variant": "default",
@@ -244,9 +246,10 @@
       "model": {
         "format": "anthropic",
         "config": {
-          "model": "claude-opus-4-6",
+          "model": "claude-opus-4-7",
           "max_tokens": 32768,
-          "thinking": { "type": "enabled", "budget_tokens": 16384 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "high" }
         }
       },
       "cost": {
@@ -261,8 +264,8 @@
       }
     },
     {
-      "name": "claude-opus-4-6",
-      "variant": "thinking-32k",
+      "name": "claude-opus-4-7",
+      "variant": "thinking-max",
       "platform": {
         "name": "anthropic",
         "variant": "default",
@@ -271,9 +274,10 @@
       "model": {
         "format": "anthropic",
         "config": {
-          "model": "claude-opus-4-6",
+          "model": "claude-opus-4-7",
           "max_tokens": 64000,
-          "thinking": { "type": "enabled", "budget_tokens": 32768 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "max" }
         }
       },
       "cost": {
@@ -342,7 +346,7 @@
     },
     {
       "name": "claude-sonnet-4-6",
-      "variant": "thinking-16k-bedrock",
+      "variant": "thinking-high-bedrock",
       "platform": {
         "name": "bedrock",
         "variant": "default"
@@ -352,7 +356,8 @@
         "config": {
           "model": "global.anthropic.claude-sonnet-4-6",
           "max_tokens": 32768,
-          "thinking": { "type": "enabled", "budget_tokens": 16384 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "high" }
         }
       },
       "cost": {
@@ -368,7 +373,7 @@
     },
     {
       "name": "claude-sonnet-4-6",
-      "variant": "thinking-32k-bedrock",
+      "variant": "thinking-max-bedrock",
       "platform": {
         "name": "bedrock",
         "variant": "default"
@@ -378,7 +383,8 @@
         "config": {
           "model": "global.anthropic.claude-sonnet-4-6",
           "max_tokens": 64000,
-          "thinking": { "type": "enabled", "budget_tokens": 32768 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "max" }
         }
       },
       "cost": {
@@ -393,8 +399,8 @@
       }
     },
     {
-      "name": "claude-opus-4-6",
-      "variant": "thinking-16k-bedrock",
+      "name": "claude-opus-4-7",
+      "variant": "thinking-high-bedrock",
       "platform": {
         "name": "bedrock",
         "variant": "default"
@@ -402,9 +408,10 @@
       "model": {
         "format": "anthropic",
         "config": {
-          "model": "global.anthropic.claude-opus-4-6-v1",
+          "model": "global.anthropic.claude-opus-4-7",
           "max_tokens": 32768,
-          "thinking": { "type": "enabled", "budget_tokens": 16384 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "high" }
         }
       },
       "cost": {
@@ -419,8 +426,8 @@
       }
     },
     {
-      "name": "claude-opus-4-6",
-      "variant": "thinking-32k-bedrock",
+      "name": "claude-opus-4-7",
+      "variant": "thinking-max-bedrock",
       "platform": {
         "name": "bedrock",
         "variant": "default"
@@ -428,9 +435,10 @@
       "model": {
         "format": "anthropic",
         "config": {
-          "model": "global.anthropic.claude-opus-4-6-v1",
+          "model": "global.anthropic.claude-opus-4-7",
           "max_tokens": 64000,
-          "thinking": { "type": "enabled", "budget_tokens": 32768 }
+          "thinking": { "type": "adaptive" },
+          "output_config": { "effort": "max" }
         }
       },
       "cost": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.13",
+  "version": "1.7.15",
   "description": "A lightweight CLI-based coding agent",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@aws-crypto/sha256-js": "^5.2.0",
-    "@aws-sdk/credential-providers": "^3.1026.0",
+    "@aws-sdk/credential-providers": "^3.1030.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "^2.0.0-alpha.2",
     "@smithy/protocol-http": "^5.3.13",
@@ -45,7 +45,7 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.4.12",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.19.17",
     "typescript": "^5.9.3"

package/src/agent.mjs

@@ -1,6 +1,7 @@
 /**
  * @import { Agent, AgentConfig, AgentEventEmitter, UserEventEmitter } from "./agent"
  * @import { Tool, ToolDefinition } from "./tool"
+ * @import { CompactContextInput } from "./tools/compactContext"
  * @import { DelegateToSubagentInput } from "./tools/delegateToSubagent"
  * @import { ReportAsSubagentInput } from "./tools/reportAsSubagent"
  */
@@ -13,6 +14,10 @@ import { createCostTracker } from "./costTracker.mjs";
 import { MESSAGES_DUMP_FILE_PATH } from "./env.mjs";
 import { createSubagentManager } from "./subagent.mjs";
 import { createToolExecutor } from "./toolExecutor.mjs";
+import {
+  compactContextToolName,
+  readMemoryForCompaction,
+} from "./tools/compactContext.mjs";
 import { delegateToSubagentToolName } from "./tools/delegateToSubagent.mjs";
 import { reportAsSubagentToolName } from "./tools/reportAsSubagent.mjs";
 
@@ -89,6 +94,20 @@ export function createAgent({
     return result.memoryContent;
   };
 
+  /**
+   * @param {Record<string, unknown>} rawInput
+   */
+  const compactContextImpl = async (rawInput) => {
+    if (subagentManager.isSubagentActive()) {
+      return new Error(
+        "compact_context cannot be used while running as a subagent. " +
+          "Call report_as_subagent to return to the main agent first.",
+      );
+    }
+    const input = /** @type {CompactContextInput} */ (rawInput);
+    return await readMemoryForCompaction(input);
+  };
+
   /** @type {Map<string, Tool>} */
   const toolByName = new Map();
   for (const tool of tools) {
@@ -98,6 +117,9 @@ export function createAgent({
     if (tool.def.name === reportAsSubagentToolName && tool.injectImpl) {
       tool.injectImpl(reportAsSubagentImpl);
     }
+    if (tool.def.name === compactContextToolName && tool.injectImpl) {
+      tool.injectImpl(compactContextImpl);
+    }
     toolByName.set(tool.def.name, tool);
   }
 

package/src/agentLoop.mjs

@@ -7,6 +7,37 @@
  */
 
 import { styleText } from "node:util";
+import { compactContextToolName } from "./tools/compactContext.mjs";
+
+/**
+ * If compact_context was called successfully, discard the prior conversation
+ * (keeping only the system prompt) and append the tool result as a standard
+ * user message so the model can resume from the reloaded memory file.
+ * @param {StateManager} stateManager
+ * @param {MessageContentToolUse[]} toolUseParts
+ * @param {MessageContentToolResult[]} toolResults
+ * @returns {boolean} true if compact was applied
+ */
+function applyCompactContextIfCalled(stateManager, toolUseParts, toolResults) {
+  const compactToolUse = toolUseParts.find(
+    (t) => t.toolName === compactContextToolName,
+  );
+  if (!compactToolUse) return false;
+
+  const compactResult = toolResults.find(
+    (r) => r.toolUseId === compactToolUse.toolUseId,
+  );
+  if (!compactResult || compactResult.isError) return false;
+
+  const systemMessage = stateManager.getMessageAt(0);
+  if (!systemMessage) return false;
+
+  stateManager.setMessages([systemMessage]);
+  stateManager.appendMessages([
+    { role: "user", content: compactResult.content },
+  ]);
+  return true;
+}
 
 /**
  * @typedef {Object} PauseSignal
@@ -200,6 +231,12 @@ export function createAgentLoop({
 
       const toolResults = executionResult.results;
 
+      if (
+        applyCompactContextIfCalled(stateManager, toolUseParts, toolResults)
+      ) {
+        continue;
+      }
+
       const result = subagentManager.processToolResults(
         toolUseParts,
         toolResults,
@@ -300,6 +337,13 @@ export function createInputHandler(context) {
       }
 
       const toolResults = executionResult.results;
+
+      if (
+        applyCompactContextIfCalled(stateManager, toolUseParts, toolResults)
+      ) {
+        return;
+      }
+
       const result = subagentManager.processToolResults(
         toolUseParts,
         toolResults,

package/src/cliCommands.mjs

@@ -149,6 +149,19 @@ export function createCommandHandler({
       return "prompt";
     }
 
+    // /compact
+    if (inputTrimmed.toLowerCase() === "/compact") {
+      const message = [
+        'System: This prompt was invoked as "/compact".',
+        "",
+        "Compact the conversation context:",
+        "1. Update the memory file for the current task so it fully captures the task overview, progress, decisions, and next steps in a self-contained way.",
+        '2. Then call the "compact_context" tool alone with that memory file path and a brief reason.',
+      ].join("\n");
+      userEventEmitter.emit("userInput", [{ type: "text", text: message }]);
+      return "continue";
+    }
+
     // /agents or /agents:id
     if (inputTrimmed === "/agents") {
       const agentRoles = await loadAgentRoles(claudeCodePlugins);

package/src/cliCompleter.mjs

@@ -34,6 +34,11 @@ export const SLASH_COMMANDS = [
   { name: "/dump", description: "Save current messages to a JSON file" },
   { name: "/load", description: "Load messages from a JSON file" },
   { name: "/cost", description: "Display session cost and token usage" },
+  {
+    name: "/compact",
+    description:
+      "Ask the agent to compact the context by reloading from a memory file",
+  },
 ];
 
 /**

package/src/cliFormatter.mjs

@@ -1,5 +1,6 @@
 /**
  * @import { Message, MessageContentToolUse, MessageContentToolResult, ProviderTokenUsage } from "./model"
+ * @import { CompactContextInput } from "./tools/compactContext"
  * @import { ExecCommandInput } from "./tools/execCommand"
  * @import { PatchFileInput } from "./tools/patchFile"
  * @import { WriteFileInput } from "./tools/writeFile"
@@ -95,6 +96,16 @@ export function formatToolUse(toolUse) {
     ].join("\n");
   }
 
+  if (toolName === "compact_context") {
+    /** @type {Partial<CompactContextInput>} */
+    const compactContextInput = input;
+    return [
+      `tool: ${toolName}`,
+      `memoryPath: ${compactContextInput.memoryPath}`,
+      `reason: ${compactContextInput.reason}`,
+    ].join("\n");
+  }
+
   if (toolName === "report_as_subagent") {
     /** @type {Partial<import("./tools/reportAsSubagent").ReportAsSubagentInput>} */
     const reportAsSubagentInput = input;

package/src/cliInteractive.mjs

@@ -12,10 +12,8 @@ import {
   formatProviderTokenUsage,
   printMessage,
 } from "./cliFormatter.mjs";
-import {
-  createPasteTransform,
-  resolvePastePlaceholders,
-} from "./cliPasteTransform.mjs";
+import { createInterruptTransform } from "./cliInterruptTransform.mjs";
+import { createPasteHandler } from "./cliPasteTransform.mjs";
 import { notify } from "./utils/notify.mjs";
 
 const HELP_MESSAGE = [
@@ -82,7 +80,7 @@ export function startInteractiveSession({
     subagentName: "",
   };
 
-  const getCliPrompt = (subagentName = "") =>
+  const getCliPrompt = (subagentName = "", flashMessage = "") =>
     [
       "",
       styleText(
@@ -92,6 +90,7 @@ export function startInteractiveSession({
           `session: ${sessionId} | model: ${modelName} | sandbox: ${sandbox ? "on" : "off"}`,
         ].join(" "),
       ),
+      ...(flashMessage ? [flashMessage] : []),
       "> ",
     ].join("\n");
 
@@ -116,37 +115,91 @@ export function startInteractiveSession({
     process.exit(0);
   };
 
-  // Double-press exit confirmation
-  let lastExitAttempt = 0;
+  // Double-press Ctrl-D exit confirmation
+  let lastCtrlDAttempt = 0;
   const EXIT_CONFIRM_TIMEOUT = 1500;
 
+  /** @type {import("node:readline").Interface} */
+  let cli;
+
+  /**
+   * Clear the current readline input line and redraw the prompt.
+   * Also aborts multi-line input mode if active.
+   */
+  const resetInput = () => {
+    if (state.multiLineBuffer !== null) {
+      state.multiLineBuffer = null;
+      cli.setPrompt(currentCliPrompt);
+    }
+    cli.write(null, { ctrl: true, name: "a" }); // move to line start
+    cli.write(null, { ctrl: true, name: "k" }); // delete to line end
+    cli.prompt();
+  };
+
   const handleCtrlC = () => {
-    // If agent is running, pause auto-approve instead of exiting
+    // Agent turn: pause auto-approve; do not clear input.
     if (!state.turn) {
       agentCommands.pauseAutoApprove();
       console.log(
         styleText(
           "yellow",
-          "\n⚠ Ctrl-C: Auto-approve paused. Finishing current tool...",
+          "\n\n⚠️ Ctrl-C: Auto-approve paused. Finishing current tool...\nPress Ctrl-D twice to exit.\n",
+        ),
+      );
+      return;
+    }
+
+    // User turn: clear current input. On empty input, show exit hint.
+    const hasInput = cli.line.length > 0 || state.multiLineBuffer !== null;
+    if (hasInput) {
+      resetInput();
+    } else {
+      cli.setPrompt(
+        getCliPrompt(
+          state.subagentName,
+          styleText("yellow", "Press Ctrl-D twice to exit"),
         ),
       );
+      cli.prompt();
+    }
+    // Reset Ctrl-D confirmation when Ctrl-C is pressed
+    lastCtrlDAttempt = 0;
+  };
+
+  const handleCtrlD = () => {
+    // User turn with non-empty input: ignore Ctrl-D entirely.
+    if (state.turn && (cli.line.length > 0 || state.multiLineBuffer !== null)) {
       return;
     }
 
     const now = Date.now();
-    if (now - lastExitAttempt < EXIT_CONFIRM_TIMEOUT) {
+    if (now - lastCtrlDAttempt < EXIT_CONFIRM_TIMEOUT) {
       handleExit();
       return;
     }
-    lastExitAttempt = now;
-    console.log(styleText("yellow", "\nPress Ctrl-C or Ctrl-D again to exit."));
+    lastCtrlDAttempt = now;
+    if (state.turn) {
+      cli.setPrompt(
+        getCliPrompt(
+          state.subagentName,
+          styleText("yellow", "Press Ctrl-D again to exit."),
+        ),
+      );
+      cli.prompt();
+    } else {
+      console.log(styleText("yellow", "\n\n⚠️ Press Ctrl-D again to exit.\n"));
+    }
   };
 
-  // Create a transform stream to handle bracketed paste before readline
-  const pasteTransform = createPasteTransform(handleCtrlC);
+  // Pre-readline pipeline:
+  //   stdin -> interrupt (Ctrl-C / Ctrl-D) -> paste (bracketed paste) -> readline
+  const interrupt = createInterruptTransform({
+    onCtrlC: handleCtrlC,
+    onCtrlD: handleCtrlD,
+  });
+  const paste = createPasteHandler();
 
-  // Set up transformed stdin for readline
-  process.stdin.pipe(pasteTransform);
+  process.stdin.pipe(interrupt).pipe(paste.transform);
 
   // Enable bracketed paste mode
   if (process.stdout.isTTY) {
@@ -154,9 +207,8 @@ export function startInteractiveSession({
   }
 
   let currentCliPrompt = getCliPrompt();
-  /** @type {import("node:readline").Interface} */
-  const cli = readline.createInterface({
-    input: pasteTransform,
+  cli = readline.createInterface({
+    input: paste.transform,
     output: process.stdout,
     prompt: currentCliPrompt,
     completer: createCompleter(() => cli, claudeCodePlugins),
@@ -199,7 +251,7 @@ export function startInteractiveSession({
     state.turn = false;
 
     // Resolve paste placeholders to original content
-    const resolvedInput = resolvePastePlaceholders(input);
+    const resolvedInput = paste.resolvePlaceholders(input);
     const inputTrimmed = resolvedInput.trim();
 
     if (inputTrimmed.length === 0) {
@@ -281,13 +333,13 @@ export function startInteractiveSession({
 
   agentEventEmitter.on("toolUseRequest", () => {
     cli.setPrompt(
-      [
+      getCliPrompt(
+        state.subagentName,
         styleText(
           "yellow",
-          "\nApprove tool calls? (y = allow once, Y = allow in this session, or feedback)",
+          "Approve tool calls? (y = allow once, Y = allow in this session, or feedback)",
         ),
-        currentCliPrompt,
-      ].join("\n"),
+      ),
     );
   });
 

package/src/cliInterruptTransform.mjs

@@ -0,0 +1,34 @@
+import { Transform } from "node:stream";
+
+/**
+ * Create a Transform that intercepts Ctrl-C (0x03) and Ctrl-D (0x04). When
+ * either byte is seen anywhere in a chunk, the corresponding callback is
+ * invoked and the entire chunk is dropped so that downstream consumers (e.g.
+ * readline) never observe it. All other input flows through unchanged.
+ *
+ * If both bytes appear in the same chunk, Ctrl-C is handled first.
+ *
+ * @param {object} handlers
+ * @param {() => void} handlers.onCtrlC - Called when Ctrl-C is detected
+ * @param {() => void} handlers.onCtrlD - Called when Ctrl-D is detected
+ * @returns {Transform}
+ */
+export function createInterruptTransform({ onCtrlC, onCtrlD }) {
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      const data = chunk.toString("utf8");
+      if (data.includes("\x03")) {
+        onCtrlC();
+        callback();
+        return;
+      }
+      if (data.includes("\x04")) {
+        onCtrlD();
+        callback();
+        return;
+      }
+      this.push(chunk);
+      callback();
+    },
+  });
+}

package/src/cliPasteTransform.mjs

@@ -4,11 +4,21 @@ import { Transform } from "node:stream";
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
 
-// Store for pasted content
-const pastedContentStore = new Map();
+// Time to wait for a continuation paste chunk before flushing the paste buffer.
+// Some terminals split large pastes into multiple bracketed paste sequences
+// (e.g. `\x1b[200~...\x1b[201~\x1b[200~...\x1b[201~`) that arrive back-to-back.
+// Holding the paste briefly lets us merge them into a single placeholder.
+const PASTE_MERGE_WINDOW_MS = 20;
+
+// Paste state machine:
+//   IDLE    - normal passthrough
+//   PASTE   - inside a BRACKETED_PASTE_START ... BRACKETED_PASTE_END sequence
+//   PENDING - just saw an END; waiting to see if the next data continues the
+//             paste (another START immediately follows) or not.
+/** @typedef {"IDLE" | "PASTE" | "PENDING"} PasteState */
 
 /**
- * Generate a short hash for paste reference
+ * Generate a short hash for paste reference.
  * @param {string} content
  * @returns {string}
  */
@@ -23,107 +33,151 @@ function generatePasteHash(content) {
 }
 
 /**
- * Resolve paste placeholders and append context tags
- * @param {string} input
- * @returns {string}
+ * @typedef {object} PasteHandler
+ * @property {Transform} transform
+ *   Transform stream to pipe stdin through. Emits placeholders for multi-line
+ *   pastes and raw text for single-line pastes / typed input.
+ * @property {(input: string) => string} resolvePlaceholders
+ *   Given a string containing placeholders produced by `transform`, append a
+ *   `<context id="pasted#HASH">...</context>` block for each referenced paste
+ *   and consume the stored content. Unknown placeholders are left untouched.
  */
-export function resolvePastePlaceholders(input) {
-  /** @type {string[]} */
-  const contexts = [];
-
-  // Collect paste content for context tags while keeping placeholders
-  const text = input.replace(
-    /\[Pasted text #([a-f0-9]{6}),/g,
-    (match, hash) => {
-      const content = pastedContentStore.get(hash);
-      if (content !== undefined) {
-        pastedContentStore.delete(hash); // Clean up after use
-        contexts.push(`<context id="pasted#${hash}">\n${content}\n</context>`);
-      }
-      return match; // Keep placeholder in text
-    },
-  );
-
-  // Append contexts to the end of input
-  if (contexts.length > 0) {
-    return [text, ...contexts].join("\n\n");
-  }
-
-  return text;
-}
 
 /**
- * Create a Transform stream to handle bracketed paste before readline.
- * @param {() => void} onCtrlC - Called when Ctrl-C or Ctrl-D is detected
- * @returns {Transform}
+ * Create a bracketed-paste handler. The handler owns its own content store so
+ * pastes from one handler instance cannot interfere with another (and state
+ * does not leak across tests).
+ *
+ * @returns {PasteHandler}
  */
-export function createPasteTransform(onCtrlC) {
-  let inPasteMode = false;
+export function createPasteHandler() {
+  /** @type {Map<string, string>} */
+  const pastedContentStore = new Map();
+
+  /** @type {PasteState} */
+  let state = "IDLE";
   let pasteBuffer = "";
+  /** @type {NodeJS.Timeout | null} */
+  let mergeTimer = null;
+  /** @type {Transform} */
+  let transform;
 
-  return new Transform({
+  const clearMergeTimer = () => {
+    if (mergeTimer) {
+      clearTimeout(mergeTimer);
+      mergeTimer = null;
+    }
+  };
+
+  const flushPasteBuffer = () => {
+    clearMergeTimer();
+    if (pasteBuffer) {
+      // Strip a trailing newline so a paste like "foo\n" is treated as single-line.
+      const trimmed = pasteBuffer.replace(/\n$/, "");
+      if (trimmed.includes("\n")) {
+        // Multi-line: emit a placeholder and stash the content for later.
+        const hash = generatePasteHash(pasteBuffer);
+        pastedContentStore.set(hash, pasteBuffer);
+        const lineCount = pasteBuffer.split("\n").length;
+        transform.push(`[Pasted text #${hash}, ${lineCount} lines]`);
+      } else {
+        transform.push(trimmed);
+      }
+    }
+    pasteBuffer = "";
+    state = "IDLE";
+  };
+
+  transform = new Transform({
     transform(chunk, _encoding, callback) {
       /** @type {string} */
       let data = chunk.toString("utf8");
 
-      // Handle Ctrl-C and Ctrl-D
-      if (data.includes("\x03") || data.includes("\x04")) {
-        onCtrlC();
-        callback();
-        return;
-      }
-
       while (data.length > 0) {
-        if (inPasteMode) {
+        if (state === "PASTE") {
           const endIdx = data.indexOf(BRACKETED_PASTE_END);
-          if (endIdx !== -1) {
-            // End of paste
+          if (endIdx === -1) {
+            pasteBuffer += data;
+            data = "";
+          } else {
+            // End of (this chunk of) paste. Hold briefly in case another paste
+            // chunk follows immediately and should be merged.
             pasteBuffer += data.slice(0, endIdx);
             data = data.slice(endIdx + BRACKETED_PASTE_END.length);
-            inPasteMode = false;
-
-            // Handle paste content
-            if (pasteBuffer) {
-              // Remove trailing newline for single-line paste detection
-              const trimmedPaste = pasteBuffer.replace(/\n$/, "");
-
-              // For single-line paste, insert directly without placeholder
-              if (!trimmedPaste.includes("\n")) {
-                this.push(trimmedPaste);
-              } else {
-                // For multi-line paste, use placeholder
-                const hash = generatePasteHash(pasteBuffer);
-                pastedContentStore.set(hash, pasteBuffer);
-                const lines = pasteBuffer.split("\n");
-                this.push(`[Pasted text #${hash}, ${lines.length} lines]`);
-              }
-            }
-            pasteBuffer = "";
+            state = "PENDING";
+          }
+        } else if (state === "PENDING") {
+          if (data.startsWith(BRACKETED_PASTE_START)) {
+            // Continuation of the previous paste; keep appending to pasteBuffer.
+            data = data.slice(BRACKETED_PASTE_START.length);
+            clearMergeTimer();
+            state = "PASTE";
           } else {
-            // Still in paste mode
-            pasteBuffer += data;
-            break;
+            // Not a continuation; flush, then re-process this data as IDLE.
+            flushPasteBuffer();
           }
         } else {
+          // IDLE
           const startIdx = data.indexOf(BRACKETED_PASTE_START);
-          if (startIdx !== -1) {
-            // Start of paste
-            // Output any data before the paste
-            if (startIdx > 0) {
-              this.push(data.slice(0, startIdx));
-            }
-            data = data.slice(startIdx + BRACKETED_PASTE_START.length);
-            inPasteMode = true;
-            pasteBuffer = "";
-          } else {
-            // Normal data
+          if (startIdx === -1) {
             this.push(data);
-            break;
+            data = "";
+          } else {
+            this.push(data.slice(0, startIdx));
+            data = data.slice(startIdx + BRACKETED_PASTE_START.length);
+            state = "PASTE";
           }
         }
       }
 
+      // If the chunk ended while still waiting for a possible continuation,
+      // schedule a short timer to flush the pending paste if nothing arrives.
+      if (state === "PENDING" && !mergeTimer) {
+        mergeTimer = setTimeout(() => {
+          mergeTimer = null;
+          flushPasteBuffer();
+        }, PASTE_MERGE_WINDOW_MS);
+      }
+
+      callback();
+    },
+
+    flush(callback) {
+      if (state === "PENDING") {
+        flushPasteBuffer();
+      }
       callback();
     },
   });
+
+  /**
+   * @param {string} input
+   * @returns {string}
+   */
+  const resolvePlaceholders = (input) => {
+    /** @type {string[]} */
+    const contexts = [];
+
+    // Collect paste content for context tags while keeping placeholders.
+    const text = input.replace(
+      /\[Pasted text #([a-f0-9]{6}),/g,
+      (match, hash) => {
+        const content = pastedContentStore.get(hash);
+        if (content !== undefined) {
+          pastedContentStore.delete(hash); // Clean up after use
+          contexts.push(
+            `<context id="pasted#${hash}">\n${content}\n</context>`,
+          );
+        }
+        return match; // Keep placeholder in text
+      },
+    );
+
+    if (contexts.length > 0) {
+      return [text, ...contexts].join("\n\n");
+    }
+    return text;
+  };
+
+  return { transform, resolvePlaceholders };
 }

package/src/main.mjs

@@ -24,6 +24,7 @@ import { createModelCaller } from "./modelCaller.mjs";
 import { createPrompt } from "./prompt.mjs";
 import { createAskURLTool } from "./tools/askURL.mjs";
 import { createAskWebTool } from "./tools/askWeb.mjs";
+import { createCompactContextTool } from "./tools/compactContext.mjs";
 import { createDelegateToSubagentTool } from "./tools/delegateToSubagent.mjs";
 import { createExecCommandTool } from "./tools/execCommand.mjs";
 import { createPatchFileTool } from "./tools/patchFile.mjs";
@@ -164,6 +165,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
     writeFileTool,
     createPatchFileTool(),
     createTmuxCommandTool({ sandbox: appConfig.sandbox }),
+    createCompactContextTool(),
     createDelegateToSubagentTool(),
     createReportAsSubagentTool(),
   ];

package/src/subagent.mjs

@@ -246,9 +246,18 @@ export function createSubagentManager(agentRoles, handlers) {
     return { messages: truncatedMessages, newMessage };
   }
 
+  /**
+   * Whether the main agent is currently running as a subagent.
+   * @returns {boolean}
+   */
+  function isSubagentActive() {
+    return subagents.length > 0;
+  }
+
   return {
     delegateToSubagent,
     reportAsSubagent,
     processToolResults,
+    isSubagentActive,
   };
 }

package/src/tools/compactContext.d.ts

@@ -0,0 +1,4 @@
+export type CompactContextInput = {
+  memoryPath: string;
+  reason: string;
+};

package/src/tools/compactContext.mjs

@@ -0,0 +1,87 @@
+/**
+ * @import { Tool, ToolImplementation } from '../tool'
+ * @import { CompactContextInput } from './compactContext'
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { AGENT_MEMORY_DIR } from "../env.mjs";
+import { noThrow } from "../utils/noThrow.mjs";
+
+export const compactContextToolName = "compact_context";
+
+/** @returns {Tool} */
+export function createCompactContextTool() {
+  /** @type {ToolImplementation} */
+  let impl = async () => {
+    throw new Error("Not implemented");
+  };
+
+  /** @type {Tool} */
+  const tool = {
+    def: {
+      name: compactContextToolName,
+      description:
+        "Discard prior messages and reload task state from a memory file.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          memoryPath: {
+            type: "string",
+            description: `Path to the memory file under ${AGENT_MEMORY_DIR}/.`,
+          },
+          reason: {
+            type: "string",
+            description: "The reason for compacting the context.",
+          },
+        },
+        required: ["memoryPath", "reason"],
+      },
+    },
+
+    // Implementation is injected by the agent so it can access subagent
+    // state (compact_context is not allowed during subagent execution).
+    get impl() {
+      return impl;
+    },
+
+    injectImpl(fn) {
+      impl = fn;
+    },
+  };
+
+  return tool;
+}
+
+/**
+ * Read a memory file and return the compact_context tool result string.
+ * Validates that the memoryPath is within the project memory directory.
+ * @param {CompactContextInput} input
+ * @returns {Promise<string | Error>}
+ */
+export async function readMemoryForCompaction(input) {
+  return await noThrow(async () => {
+    const absolutePath = path.resolve(input.memoryPath);
+    const memoryDir = path.resolve(AGENT_MEMORY_DIR);
+    const relativePath = path.relative(memoryDir, absolutePath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+      return new Error(
+        `Access denied: memoryPath must be within ${AGENT_MEMORY_DIR}`,
+      );
+    }
+
+    const memoryContent = await fs.readFile(absolutePath, {
+      encoding: "utf-8",
+    });
+
+    return [
+      "Context compacted. Prior conversation has been discarded.",
+      `Reason: ${input.reason}`,
+      `Memory file: ${input.memoryPath}`,
+      "",
+      "Resume the task using the memory file contents below.",
+      "",
+      memoryContent,
+    ].join("\n");
+  });
+}