@iinm/plain-agent 1.7.14 → 1.7.16

package/README.md

@@ -4,21 +4,28 @@
 
 # Plain Agent
 
-A lightweight CLI-based coding agent.
+A lightweight CLI-based coding agent with zero framework dependencies.
 
-- **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** — Reuse Claude Code plugins, agents, commands, and skills
+## Why Plain Agent?
 
-## Safety Controls
+- **Multi-provider** — Use Claude, GPT, Gemini, or any OpenAI-compatible model.
+  Switch providers without changing your workflow.
+- **Fine-grained approval rules** — Auto-approve commands by name, arguments,
+  and file paths using regex patterns
+  ([`config.predefined.json`](https://github.com/iinm/plain-agent/blob/main/config/config.predefined.json)).
+- **Path validation** — File paths must stay within the working directory
+  and git-ignored files (`.env`, etc.) are blocked.
+- **Sandboxed execution** — Run the agent's shell commands inside a Docker
+  container with network access restricted to allowlisted destinations
+  (e.g., `registry.npmjs.org` only for `npm install`).
+- **Extensible** — Define prompts and subagents in Markdown.
+  Connect MCP servers. Reuse Claude Code plugins.
 
-**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).
+## Limitations
 
-**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.
+- **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.
 
 ## Requirements
 
@@ -46,7 +53,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": [
@@ -67,32 +74,11 @@ Create the configuration.
       "variant": "default",
       "apiKey": "FIXME"
     },
-    {
-      // Requires Azure CLI to get access token
-      "name": "azure",
-      "variant": "openai",
-      "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": {
+    // askWeb: Searches the web to answer questions requiring up-to-date information or external sources.
     "askWeb": {
       "provider": "gemini",
       "apiKey": "FIXME",
@@ -108,6 +94,8 @@ Create the configuration.
       // "account": "<service_account_email>"
     },
 
+    // askURL: Answers questions based on provided URL content.
+    //         Directly injecting URL content into context is not supported to prevent prompt injection.
     "askURL": {
       "provider": "gemini",
       "apiKey": "FIXME"
@@ -129,7 +117,40 @@ Create the configuration.
 ```
 
 <details>
-<summary><b>Other provider examples</b></summary>
+<summary><b>Azure / Bedrock / Vertex AI provider examples</b></summary>
+
+```js
+{
+  "platforms": [
+    {
+      // Requires Azure CLI to get access token
+      "name": "azure",
+      "variant": "openai",
+      "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>"
+    }
+  ]
+}
+```
+</details>
+
+<details>
+<summary><b>OpenAI compatible provider examples</b></summary>
 
 ```js
 {
@@ -284,6 +305,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.14",
+  "version": "1.7.16",
   "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"
@@ -10,6 +11,49 @@
 import { styleText } from "node:util";
 import { createPatch } from "diff";
 
+/** Length above which a single-line arg forces block-form rendering. */
+const ARG_BLOCK_LENGTH_THRESHOLD = 60;
+
+/**
+ * Format an args array for display.
+ * Uses compact JSON for short single-line args; switches to a YAML-style
+ * block form when any arg contains newlines or exceeds
+ * {@link ARG_BLOCK_LENGTH_THRESHOLD} characters so that long scripts passed
+ * to `bash -c`, `python -c`, `node -e`, etc. stay readable.
+ * @param {unknown} args
+ * @returns {string}
+ */
+export function formatArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    return `args: ${JSON.stringify(args ?? [])}`;
+  }
+
+  const needsBlock = args.some(
+    (a) =>
+      typeof a === "string" &&
+      (a.includes("\n") || a.length > ARG_BLOCK_LENGTH_THRESHOLD),
+  );
+  if (!needsBlock) {
+    return `args: ${JSON.stringify(args)}`;
+  }
+
+  const lines = ["args:"];
+  for (const arg of args) {
+    if (
+      typeof arg === "string" &&
+      (arg.includes("\n") || arg.length > ARG_BLOCK_LENGTH_THRESHOLD)
+    ) {
+      lines.push("  - |");
+      for (const line of arg.split("\n")) {
+        lines.push(`      ${line}`);
+      }
+    } else {
+      lines.push(`  - ${JSON.stringify(arg)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 /**
  * Format tool use for display.
  * @param {MessageContentToolUse} toolUse
@@ -24,7 +68,7 @@ export function formatToolUse(toolUse) {
     return [
       `tool: ${toolName}`,
       `command: ${JSON.stringify(execCommandInput.command)}`,
-      `args: ${JSON.stringify(execCommandInput.args)}`,
+      formatArgs(execCommandInput.args),
     ].join("\n");
   }
 
@@ -81,7 +125,7 @@ export function formatToolUse(toolUse) {
     return [
       `tool: ${toolName}`,
       `command: ${tmuxCommandInput.command}`,
-      `args: ${JSON.stringify(tmuxCommandInput.args)}`,
+      formatArgs(tmuxCommandInput.args),
     ].join("\n");
   }
 
@@ -95,6 +139,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,52 +33,30 @@ 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;
-}
-
-// 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;
 
 /**
- * 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 = "";
-  // True when a paste just ended and we are waiting to see if the next data
-  // continues it (i.e. starts with another BRACKETED_PASTE_START).
-  let awaitingMerge = false;
   /** @type {NodeJS.Timeout | null} */
   let mergeTimer = null;
   /** @type {Transform} */
@@ -81,25 +69,23 @@ export function createPasteTransform(onCtrlC) {
     }
   };
 
-  const flushPaste = () => {
+  const flushPasteBuffer = () => {
     clearMergeTimer();
-    awaitingMerge = false;
     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")) {
-        transform.push(trimmedPaste);
-      } else {
-        // For multi-line paste, use placeholder
+      // 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 lines = pasteBuffer.split("\n");
-        transform.push(`[Pasted text #${hash}, ${lines.length} lines]`);
+        const lineCount = pasteBuffer.split("\n").length;
+        transform.push(`[Pasted text #${hash}, ${lineCount} lines]`);
+      } else {
+        transform.push(trimmed);
       }
     }
     pasteBuffer = "";
+    state = "IDLE";
   };
 
   transform = new Transform({
@@ -107,65 +93,49 @@ export function createPasteTransform(onCtrlC) {
       /** @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 (this chunk of) paste. Hold the buffer 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;
-            awaitingMerge = true;
-          } else {
-            // Still in paste mode
+          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);
+            state = "PENDING";
           }
-        } else if (awaitingMerge) {
-          // If the next data starts with another paste start marker, treat it
-          // as a continuation of the previous paste and merge.
+        } 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);
-            inPasteMode = true;
-            awaitingMerge = false;
             clearMergeTimer();
+            state = "PASTE";
           } else {
-            // Not a continuation; flush pending paste, then process this data.
-            flushPaste();
+            // 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);
             data = "";
+          } else {
+            this.push(data.slice(0, startIdx));
+            data = data.slice(startIdx + BRACKETED_PASTE_START.length);
+            state = "PASTE";
           }
         }
       }
 
-      // If the chunk ended while still awaiting a continuation, schedule a
-      // short timer to flush the pending paste if nothing else arrives.
-      if (awaitingMerge && !mergeTimer) {
+      // 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;
-          flushPaste();
+          flushPasteBuffer();
         }, PASTE_MERGE_WINDOW_MS);
       }
 
@@ -173,12 +143,41 @@ export function createPasteTransform(onCtrlC) {
     },
 
     flush(callback) {
-      if (awaitingMerge) {
-        flushPaste();
+      if (state === "PENDING") {
+        flushPasteBuffer();
       }
       callback();
     },
   });
 
-  return transform;
+  /**
+   * @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";
@@ -122,7 +123,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
       }),
     );
 
-    for (const { serverName, tools, cleanup } of mcpResults) {
+    for (const { serverName, tools, stderrLogPath, cleanup } of mcpResults) {
       mcpTools.push(...tools);
       mcpCleanups.push(cleanup);
       if (!isBatchMode) {
@@ -132,6 +133,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
             `✅ Successfully connected to MCP server: ${serverName}`,
           ),
         );
+        console.log(`  ⤷ stderr log: ${stderrLogPath}`);
       }
     }
   }
@@ -164,6 +166,7 @@ if (cliArgs.subcommand.type === "install-claude-code-plugins") {
     writeFileTool,
     createPatchFileTool(),
     createTmuxCommandTool({ sandbox: appConfig.sandbox }),
+    createCompactContextTool(),
     createDelegateToSubagentTool(),
     createReportAsSubagentTool(),
   ];

package/src/mcp.mjs

@@ -15,6 +15,7 @@ const OUTPUT_MAX_LENGTH = 1024 * 8;
 /**
  * @typedef {Object} SetupMCPServrResult
  * @property {Tool[]} tools
+ * @property {string} stderrLogPath
  * @property {() => Promise<void>} cleanup
  */
 
@@ -26,7 +27,7 @@ const OUTPUT_MAX_LENGTH = 1024 * 8;
 export async function setupMCPServer(serverName, serverConfig) {
   const { options, ...params } = serverConfig;
 
-  const { client, cleanup } = await startMCPServer({
+  const { client, stderrLogPath, cleanup } = await startMCPServer({
     serverName,
     params,
   });
@@ -41,6 +42,7 @@ export async function setupMCPServer(serverName, serverConfig) {
 
   return {
     tools,
+    stderrLogPath,
     cleanup: async () => {
       cleanup();
       await client.close();
@@ -56,7 +58,7 @@ export async function setupMCPServer(serverName, serverConfig) {
 
 /**
  * @param {MCPClientOptions} options - The options for the client.
- * @returns {Promise<{client: Client; cleanup: () => void}>} - The MCP client and cleanup function.
+ * @returns {Promise<{client: Client; stderrLogPath: string; cleanup: () => void}>} - The MCP client, stderr log path, and cleanup function.
  */
 async function startMCPServer(options) {
   const mcpClient = await import("@modelcontextprotocol/client");
@@ -88,6 +90,7 @@ async function startMCPServer(options) {
 
   return {
     client,
+    stderrLogPath: logPath,
     cleanup: () => {
       stderrLogFile.close();
     },

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");
+  });
+}