@iinm/plain-agent 1.7.14 → 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": [
@@ -284,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iinm/plain-agent",
-  "version": "1.7.14",
+  "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,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";
@@ -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");
+  });
+}