@iinm/plain-agent 1.9.3 → 1.9.4

package/README.md

@@ -62,7 +62,6 @@ A lightweight, capable coding agent for the terminal.
 ## Limitations
 
 - **Path validation only covers tool arguments** — Path validation restricts only paths explicitly passed as tool-use arguments; it cannot control file access inside arbitrary scripts. Always use sandboxed execution when allowing arbitrary script execution.
-- **No session persistence** — Sessions are not persisted. Start a fresh session and use memory files (`.plain-agent/memory/`) instead.
 - **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.
@@ -338,6 +337,21 @@ plain cost
 plain cost --from 2026-04-01 --to 2026-04-30
 ```
 
+Resume a previously interrupted interactive session. Sessions are
+auto-saved to `.plain-agent/sessions/` and can be removed with `rm` when
+no longer needed. Without an argument, the most recently updated session
+is resumed. Use `--list` to see resumable sessions. Switching models is
+not supported (`-m` is rejected).
+
+```sh
+plain resume
+```
+
+```
+plain resume --list
+plain resume 2026-05-10-0803-a7k
+```
+
 Configure plain-agent for your project.
 
 ```
@@ -591,10 +605,14 @@ The agent searches for subagent definitions in the following directories:
 
 ```md
 ---
-description: Simplifies and refines code for clarity and maintainability
+description: Fetches a web page and answers questions about its content
 ---
 
-You are a code simplifier. Your role is to refactor code while preserving its functionality.
+You are a web content reader and analyzer. Given a URL and a question, you:
+
+1. Fetch the page content using `w3m -dump <URL>`.
+2. Read and understand the fetched content.
+3. Answer the user's question based on the content.
 ```
 
 ## Claude Code Plugin Support

package/package.json

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

package/src/agent.d.ts

@@ -9,6 +9,7 @@ import type {
   PartialMessageContent,
   ProviderTokenUsage,
 } from "./model";
+import type { SessionState } from "./sessionStore.mjs";
 import type { Tool, ToolUseApprover } from "./tool";
 
 export type Agent = {
@@ -18,10 +19,12 @@ export type Agent = {
 };
 
 export type AgentCommands = {
-  dumpMessages: () => Promise<void>;
-  loadMessages: () => Promise<void>;
   getCostSummary: () => CostSummary;
   pauseAutoApprove: () => void;
+  /** Subagent currently active for this session, or null. */
+  getActiveSubagent: () => { name: string } | null;
+  /** Wait for any pending session-state writes to flush to disk. */
+  flushSessionPersistence: () => Promise<void>;
 };
 
 type UserEventMap = {
@@ -49,4 +52,13 @@ export type AgentConfig = {
   toolUseApprover: ToolUseApprover;
   agentRoles: Map<string, AgentRole>;
   modelCostConfig?: CostConfig;
+  /** Metadata used when persisting session state. */
+  sessionMetadata: {
+    sessionId: string;
+    modelName: string;
+    workingDir: string;
+    startTime: Date;
+  };
+  /** When provided, the agent restores its state from this snapshot. */
+  initialState?: SessionState | null;
 };

package/src/agent.mjs

@@ -7,11 +7,11 @@
  */
 
 import { EventEmitter } from "node:events";
-import fs from "node:fs/promises";
+import { styleText } from "node:util";
 import { createAgentLoop } from "./agentLoop.mjs";
 import { createStateManager } from "./agentState.mjs";
 import { createCostTracker } from "./costTracker.mjs";
-import { MESSAGES_DUMP_FILE_PATH } from "./env.mjs";
+import { SESSION_FILE_VERSION, saveSession } from "./sessionStore.mjs";
 import { createSubagentManager } from "./subagent.mjs";
 import { createToolExecutor } from "./toolExecutor.mjs";
 import {
@@ -32,6 +32,8 @@ export function createAgent({
   toolUseApprover,
   agentRoles,
   modelCostConfig,
+  sessionMetadata,
+  initialState,
 }) {
   /** @type {UserEventEmitter} */
   const userEventEmitter = new EventEmitter();
@@ -44,23 +46,27 @@ export function createAgent({
     costTracker.recordUsage(usage);
   });
 
-  const stateManager = createStateManager(
-    [
-      {
-        role: "system",
-        content: [{ type: "text", text: prompt }],
-      },
-    ],
-    {
-      onMessagesAppended: (newMessages) => {
-        const lastMessage = newMessages.at(-1);
-        if (!lastMessage) {
-          return;
-        }
+  // Build the initial message list. When resuming, replace messages[0] with
+  // the freshly built system prompt (today/agent roles/skills may have
+  // changed) but keep the rest of the saved conversation verbatim.
+  /** @type {import("./model").SystemMessage} */
+  const systemMessage = {
+    role: "system",
+    content: [{ type: "text", text: prompt }],
+  };
+  const baseMessages = initialState?.messages?.length
+    ? [systemMessage, ...initialState.messages.slice(1)]
+    : [systemMessage];
+
+  const stateManager = createStateManager(baseMessages, {
+    onMessagesAppended: (newMessages) => {
+      const lastMessage = newMessages.at(-1);
+      if (lastMessage) {
         agentEventEmitter.emit("message", lastMessage);
-      },
+      }
+      schedulePersist();
     },
-  );
+  });
 
   const subagentManager = createSubagentManager(agentRoles, {
     onSubagentSwitched: (subagent) => {
@@ -68,6 +74,46 @@ export function createAgent({
     },
   });
 
+  // Restore the rest of the session state. Subagent restoration is silent
+  // (no event), since CLI listeners aren't attached yet — the CLI consults
+  // getActiveSubagent() at startup instead.
+  if (initialState) {
+    subagentManager.restoreState(initialState.subagentState);
+    toolUseApprover.restoreAllowedToolUseInSession(
+      initialState.allowedToolUseInSession,
+    );
+    costTracker.restoreUsageHistory(initialState.tokenUsageHistory);
+  }
+
+  /** @type {Promise<void>} */
+  let persistChain = Promise.resolve();
+  function schedulePersist() {
+    persistChain = persistChain.then(async () => {
+      try {
+        await saveSession({
+          version: SESSION_FILE_VERSION,
+          sessionId: sessionMetadata.sessionId,
+          modelName: sessionMetadata.modelName,
+          workingDir: sessionMetadata.workingDir,
+          startTime: sessionMetadata.startTime.toISOString(),
+          lastUpdatedAt: new Date().toISOString(),
+          messages: stateManager.getMessages(),
+          subagentState: subagentManager.getState(),
+          allowedToolUseInSession: toolUseApprover.getAllowedToolUseInSession(),
+          tokenUsageHistory: costTracker.getUsageHistory(),
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(
+          styleText(
+            "yellow",
+            `Warning: failed to persist session state: ${message}`,
+          ),
+        );
+      }
+    });
+  }
+
   /**
    * @param {SwitchToSubagentInput} input
    */
@@ -130,42 +176,6 @@ export function createAgent({
     exclusiveToolNames: [switchToSubagentToolName, switchToMainAgentToolName],
   });
 
-  async function dumpMessages() {
-    const filePath = MESSAGES_DUMP_FILE_PATH;
-    try {
-      await fs.writeFile(
-        filePath,
-        JSON.stringify(stateManager.getMessages(), null, 2),
-      );
-      console.log(`Messages dumped to ${filePath}`);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.error(`Error dumping messages: ${message}`);
-    }
-  }
-
-  async function loadMessages() {
-    const filePath = MESSAGES_DUMP_FILE_PATH;
-    try {
-      const data = await fs.readFile(filePath, "utf-8");
-      const loadedMessages = JSON.parse(data);
-      if (Array.isArray(loadedMessages)) {
-        // Keep the system message (index 0) and replace the rest
-        stateManager.setMessages([
-          stateManager.getMessageAt(0),
-          ...loadedMessages.slice(1),
-        ]);
-        console.log(`Messages loaded from ${filePath}`);
-      } else {
-        console.error("Error loading messages: Invalid format in file.");
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        console.error(`Error loading messages: ${error.message}`);
-      }
-    }
-  }
-
   // Pause signal: set by Ctrl-C during agent execution, checked after each tool batch completes
   let paused = false;
   /** @type {import("./agentLoop.mjs").PauseSignal} */
@@ -193,12 +203,14 @@ export function createAgent({
     userEventEmitter,
     agentEventEmitter,
     agentCommands: {
-      dumpMessages,
-      loadMessages,
       getCostSummary: () => costTracker.calculateCost(),
       pauseAutoApprove: () => {
         paused = true;
       },
+      getActiveSubagent: () => subagentManager.getActiveSubagent(),
+      flushSessionPersistence: async () => {
+        await persistChain;
+      },
     },
   };
 }

package/src/cliArgs.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand} Subcommand
+ * @typedef {HelpSubcommand | InteractiveSubcommand | BatchSubcommand | ListModelsSubcommand | InstallClaudeCodePluginsSubcommand | CostSubcommand | ResumeSubcommand} Subcommand
  */
 
 /**
@@ -26,6 +26,13 @@
  * @typedef {{ type: 'cost', from: string | null, to: string | null }} CostSubcommand
  */
 
+/**
+ * Resume a previously interrupted interactive session.
+ * - `sessionId === null` and `list === false`: resume the most recently updated session.
+ * - `list === true`: print the resumable sessions and exit.
+ * @typedef {{ type: 'resume', sessionId: string | null, list: boolean, config: string[] }} ResumeSubcommand
+ */
+
 /**
  * @typedef {Object} CliArgs
  * @property {Subcommand} subcommand - The subcommand to execute
@@ -110,6 +117,38 @@ export function parseCliArgs(argv) {
     };
   }
 
+  if (subcommandName === "resume") {
+    const resumeArgs = args.slice(1);
+    /** @type {string | null} */
+    let sessionId = null;
+    let list = false;
+    /** @type {string[]} */
+    const config = [];
+
+    for (let i = 0; i < resumeArgs.length; i++) {
+      const arg = resumeArgs[i];
+      if (arg === "--list") {
+        list = true;
+      } else if (arg === "-c" || arg === "--config") {
+        if (resumeArgs[i + 1]) {
+          config.push(resumeArgs[i + 1]);
+          i++;
+        }
+      } else if (arg === "-m" || arg === "--model") {
+        // Switching models on resume is not supported by design.
+        return {
+          subcommand: { type: "help" },
+        };
+      } else if (!arg.startsWith("-") && sessionId === null) {
+        sessionId = arg;
+      }
+    }
+
+    return {
+      subcommand: { type: "resume", sessionId, list, config },
+    };
+  }
+
   if (subcommandName === "cost") {
     const costArgs = args.slice(1);
     let from = null;
@@ -145,6 +184,7 @@ export function printHelp(exitCode = 0) {
   console.log(`
 Usage: plain [options]
        plain batch [options] <task>
+       plain resume [<sessionId>] [--list] [-c <file>]
        plain cost [--from YYYY-MM-DD] [--to YYYY-MM-DD]
        plain list-models
        plain install-claude-code-plugins
@@ -158,6 +198,11 @@ Subcommands:
   batch <task>                 Run in batch mode with the given task instruction.
                                Config files are NOT auto-loaded in batch mode;
                                use -c to specify config files explicitly.
+  resume                       Resume an interactive session that was
+                               interrupted. With no sessionId, resumes the
+                               most recently updated session. Use --list to
+                               see resumable sessions. Switching models is
+                               not supported (-m is rejected).
   cost                         Show aggregated token cost per day for a period.
                                Defaults to the first day of the current month
                                through today.

package/src/cliBatch.mjs

@@ -71,6 +71,7 @@ export async function startBatchSession({
         });
       }
 
+      await agentCommands.flushSessionPersistence();
       await onStop();
       resolve();
     });

package/src/cliCommands.mjs

@@ -131,18 +131,6 @@ export function createCommandHandler({
       return "continue";
     }
 
-    // /dump
-    if (inputTrimmed.toLowerCase() === "/dump") {
-      await agentCommands.dumpMessages();
-      return "prompt";
-    }
-
-    // /load
-    if (inputTrimmed.toLowerCase() === "/load") {
-      await agentCommands.loadMessages();
-      return "prompt";
-    }
-
     // /cost
     if (inputTrimmed.toLowerCase() === "/cost") {
       const summary = agentCommands.getCostSummary();

package/src/cliCompleter.mjs

@@ -32,8 +32,6 @@ export const SLASH_COMMANDS = [
     name: "/resume",
     description: "Resume conversation after an LLM provider error",
   },
-  { 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",

package/src/cliInteractive.mjs

@@ -112,7 +112,7 @@ export function startInteractiveSession({
   const state = {
     turn: true,
     multiLineBuffer: null,
-    subagentName: "",
+    subagentName: agentCommands.getActiveSubagent()?.name ?? "",
   };
 
   /**
@@ -157,6 +157,7 @@ export function startInteractiveSession({
     console.log();
     console.log(formatCostSummary(summary));
     await persistUsage(summary, { sessionId, modelName, startTime });
+    await agentCommands.flushSessionPersistence();
     await onStop();
     process.exit(0);
   };
@@ -351,7 +352,7 @@ export function startInteractiveSession({
     process.stdout.write("\x1b[?2004h");
   }
 
-  let currentCliPrompt = getCliPrompt();
+  let currentCliPrompt = getCliPrompt(state.subagentName);
   cli = readline.createInterface({
     input: paste.transform,
     output: process.stdout,

package/src/costTracker.mjs

@@ -29,6 +29,8 @@
  * @property {() => Record<string, number>} getAggregatedUsage - Get aggregated usage
  * @property {() => CostSummary} calculateCost - Calculate cost summary
  * @property {() => boolean} hasUsage - Check if any usage recorded
+ * @property {() => ProviderTokenUsage[]} getUsageHistory - Get a snapshot of the raw usage history
+ * @property {(history: ProviderTokenUsage[]) => void} restoreUsageHistory - Replace the usage history (used when resuming a saved session)
  */
 
 /**
@@ -110,11 +112,38 @@ export function createCostTracker(costConfig) {
     return usageHistory.length > 0;
   }
 
+  /**
+   * Get a snapshot copy of the raw usage history.
+   * @returns {ProviderTokenUsage[]}
+   */
+  function getUsageHistory() {
+    return usageHistory.map((u) => u);
+  }
+
+  /**
+   * Replace the usage history. Used when resuming a saved session.
+   * @param {ProviderTokenUsage[]} history
+   */
+  function restoreUsageHistory(history) {
+    if (!Array.isArray(history)) {
+      throw new TypeError("history must be an array");
+    }
+    usageHistory.length = 0;
+    for (const usage of history) {
+      if (typeof usage !== "object" || usage === null) {
+        throw new TypeError("each usage entry must be a non-null object");
+      }
+      usageHistory.push(usage);
+    }
+  }
+
   return Object.freeze({
     recordUsage,
     getAggregatedUsage,
     calculateCost,
     hasUsage,
+    getUsageHistory,
+    restoreUsageHistory,
   });
 }
 

package/src/env.mjs

@@ -30,15 +30,11 @@ export const AGENT_PROJECT_METADATA_DIR = ".plain-agent";
 
 export const AGENT_MEMORY_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "memory");
 export const AGENT_TMP_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "tmp");
+export const SESSIONS_DIR = path.join(AGENT_PROJECT_METADATA_DIR, "sessions");
 
 export const CLAUDE_CODE_PLUGIN_DIR = path.join(
   AGENT_PROJECT_METADATA_DIR,
   "claude-code-plugins",
 );
 
-export const MESSAGES_DUMP_FILE_PATH = path.join(
-  AGENT_PROJECT_METADATA_DIR,
-  "messages.json",
-);
-
 export const USER_NAME = process.env.USER || "unknown";

package/src/main.mjs

@@ -1,7 +1,9 @@
 /**
  * @import { Tool } from "./tool";
+ * @import { SessionState } from "./sessionStore.mjs";
  */
 
+import { randomInt } from "node:crypto";
 import { styleText } from "node:util";
 import { createAgent } from "./agent.mjs";
 import {
@@ -19,6 +21,7 @@ import { AGENT_PROJECT_METADATA_DIR, USER_NAME } from "./env.mjs";
 import { setupMCPServer } from "./mcpIntegration.mjs";
 import { createModelCaller } from "./modelCaller.mjs";
 import { createPrompt } from "./prompt.mjs";
+import { listSessions, loadSession } from "./sessionStore.mjs";
 import { createAskURLTool } from "./tools/askURL.mjs";
 import { createAskWebTool } from "./tools/askWeb.mjs";
 import { createCompactContextTool } from "./tools/compactContext.mjs";
@@ -70,19 +73,74 @@ if (cliArgs.subcommand.type === "cost") {
   }
 }
 
+if (cliArgs.subcommand.type === "resume" && cliArgs.subcommand.list) {
+  const sessions = await listSessions();
+  if (sessions.length === 0) {
+    console.log("No resumable sessions in .plain-agent/sessions/.");
+    process.exit(0);
+  }
+  console.log("Resumable sessions (most recently updated first):\n");
+  for (const s of sessions) {
+    console.log(
+      `  ${s.sessionId}  ${s.modelName}  (updated ${formatLocalDateTime(s.lastUpdatedAt)}, ${s.messageCount} messages)`,
+    );
+    if (s.workingDir !== process.cwd()) {
+      console.log(`    workingDir: ${s.workingDir}`);
+    }
+  }
+  process.exit(0);
+}
+
 (async () => {
-  const startTime = new Date();
-  const sessionId = [
-    `${startTime.getFullYear()}-${`0${startTime.getMonth() + 1}`.slice(-2)}-${`0${startTime.getDate()}`.slice(-2)}`,
-    `0${startTime.getHours()}`.slice(-2) +
-      `0${startTime.getMinutes()}`.slice(-2),
-  ].join("-");
+  /** @type {SessionState | null} */
+  let resumedState = null;
+
+  if (cliArgs.subcommand.type === "resume") {
+    const requestedId = cliArgs.subcommand.sessionId;
+    if (requestedId) {
+      resumedState = await loadSession(requestedId);
+      if (!resumedState) {
+        console.error(
+          styleText("red", `No saved session found for id: ${requestedId}`),
+        );
+        process.exit(1);
+      }
+    } else {
+      const sessions = await listSessions();
+      if (sessions.length === 0) {
+        console.error(
+          styleText(
+            "red",
+            "No resumable sessions found in .plain-agent/sessions/.",
+          ),
+        );
+        process.exit(1);
+      }
+      resumedState = await loadSession(sessions[0].sessionId);
+      if (!resumedState) {
+        console.error(
+          styleText(
+            "red",
+            `Failed to load latest session: ${sessions[0].sessionId}`,
+          ),
+        );
+        process.exit(1);
+      }
+    }
+  }
+
+  const startTime = resumedState
+    ? new Date(resumedState.startTime)
+    : new Date();
+  const sessionId = resumedState ? resumedState.sessionId : generateSessionId();
   const tmuxSessionId = `agent-${sessionId}`;
 
   const isBatchMode = cliArgs.subcommand.type === "batch";
+  /** @type {string[]} */
   const configFiles =
     cliArgs.subcommand.type === "batch" ||
-    cliArgs.subcommand.type === "interactive"
+    cliArgs.subcommand.type === "interactive" ||
+    cliArgs.subcommand.type === "resume"
       ? cliArgs.subcommand.config
       : [];
 
@@ -109,6 +167,23 @@ if (cliArgs.subcommand.type === "cost") {
     } else {
       console.log(styleText("yellow", "\n📦 Sandbox: off"));
     }
+
+    if (resumedState) {
+      console.log(
+        styleText("green", `\n⏯  Resuming session: ${resumedState.sessionId}`),
+      );
+      console.log(
+        `  ⤷ ${resumedState.messages.length} messages, last updated ${formatLocalDateTime(resumedState.lastUpdatedAt)}`,
+      );
+      if (resumedState.workingDir !== process.cwd()) {
+        console.log(
+          styleText(
+            "yellow",
+            `  ⚠ workingDir differs (saved: ${resumedState.workingDir}, current: ${process.cwd()})`,
+          ),
+        );
+      }
+    }
   }
 
   /** @type {(() => Promise<void>)[]} */
@@ -156,7 +231,30 @@ if (cliArgs.subcommand.type === "cost") {
     cliArgs.subcommand.type === "interactive"
       ? cliArgs.subcommand.model
       : null;
-  const modelNameWithVariant = modelFromArgs || modelFromConfig;
+  let modelNameWithVariant = modelFromArgs || modelFromConfig;
+
+  if (resumedState) {
+    // Switching models on resume is not supported. The model from the saved
+    // session always wins. If config disagrees, fail loudly.
+    if (
+      modelNameWithVariant &&
+      modelNameWithVariant !== resumedState.modelName
+    ) {
+      console.error(
+        styleText(
+          "red",
+          [
+            `Cannot resume session ${resumedState.sessionId}: model mismatch.`,
+            `  saved model:   ${resumedState.modelName}`,
+            `  current model: ${modelNameWithVariant}`,
+            "Resume must use the same model the session was started with.",
+          ].join("\n"),
+        ),
+      );
+      process.exit(1);
+    }
+    modelNameWithVariant = resumedState.modelName;
+  }
 
   const pluginPaths = resolvePluginPaths(appConfig.claudeCodePlugins ?? []);
   const [prompts, agentRoles] = await Promise.all([
@@ -243,6 +341,13 @@ if (cliArgs.subcommand.type === "cost") {
     toolUseApprover,
     agentRoles,
     modelCostConfig: modelDef.cost,
+    sessionMetadata: {
+      sessionId,
+      modelName: modelNameWithVariant,
+      workingDir: process.cwd(),
+      startTime,
+    },
+    initialState: resumedState,
   });
 
   const sessionOptions = {
@@ -281,3 +386,41 @@ if (cliArgs.subcommand.type === "cost") {
   console.error(err);
   process.exit(1);
 });
+
+/**
+ * Generate a session id of the form `YYYY-MM-DD-HHMM-<3 random base36 chars>`.
+ * The random suffix avoids collisions when multiple `plain` processes start
+ * within the same minute. `randomInt` is uniform over `[0, 36 ** 3)`, so
+ * each suffix character is unbiased.
+ *
+ * @param {Date} [now]
+ * @returns {string}
+ */
+function generateSessionId(now = new Date()) {
+  const date = [
+    `${now.getFullYear()}-${`0${now.getMonth() + 1}`.slice(-2)}-${`0${now.getDate()}`.slice(-2)}`,
+    `0${now.getHours()}`.slice(-2) + `0${now.getMinutes()}`.slice(-2),
+  ].join("-");
+  const suffix = randomInt(36 ** 3)
+    .toString(36)
+    .padStart(3, "0");
+  return `${date}-${suffix}`;
+}
+
+/**
+ * Format an ISO 8601 timestamp as `YYYY-MM-DD HH:MM:SS` in the local timezone.
+ *
+ * @param {string} iso
+ * @returns {string}
+ */
+function formatLocalDateTime(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  const y = d.getFullYear();
+  const mo = `${d.getMonth() + 1}`.padStart(2, "0");
+  const da = `${d.getDate()}`.padStart(2, "0");
+  const h = `${d.getHours()}`.padStart(2, "0");
+  const mi = `${d.getMinutes()}`.padStart(2, "0");
+  const s = `${d.getSeconds()}`.padStart(2, "0");
+  return `${y}-${mo}-${da} ${h}:${mi}:${s}`;
+}

package/src/sessionStore.mjs

@@ -0,0 +1,164 @@
+/**
+ * @import { Message, ProviderTokenUsage } from "./model"
+ * @import { ToolUsePattern } from "./tool"
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SESSIONS_DIR } from "./env.mjs";
+
+/** Current on-disk format version. Bump on breaking changes. */
+export const SESSION_FILE_VERSION = 1;
+
+/**
+ * @typedef {Object} SubagentSerializedState
+ * @property {{name: string, goal: string, switchMessageIndex: number}[]} subagents
+ * @property {number} subagentCount
+ */
+
+/**
+ * @typedef {Object} SessionState
+ * @property {number} version
+ * @property {string} sessionId
+ * @property {string} modelName
+ * @property {string} workingDir
+ * @property {string} startTime - ISO 8601
+ * @property {string} lastUpdatedAt - ISO 8601
+ * @property {Message[]} messages
+ * @property {SubagentSerializedState} subagentState
+ * @property {ToolUsePattern[]} allowedToolUseInSession
+ * @property {ProviderTokenUsage[]} tokenUsageHistory
+ */
+
+/**
+ * @typedef {Object} SessionSummary
+ * @property {string} sessionId
+ * @property {string} modelName
+ * @property {string} workingDir
+ * @property {string} startTime
+ * @property {string} lastUpdatedAt
+ * @property {number} messageCount
+ */
+
+/**
+ * Resolve the path to a session file.
+ * @param {string} sessionId
+ * @param {{ dir?: string }} [options]
+ */
+export function sessionFilePath(sessionId, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  return path.join(dir, `${sessionId}.json`);
+}
+
+/**
+ * Persist a session state atomically.
+ *
+ * Writes to a process-unique temp file in the same directory, then renames
+ * it over the target path. Same-directory rename is atomic on POSIX, so a
+ * crash during write leaves either the previous file or the new one — never
+ * a half-written file.
+ *
+ * @param {SessionState} state
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<void>}
+ */
+export async function saveSession(state, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  await fs.mkdir(dir, { recursive: true });
+  const target = path.join(dir, `${state.sessionId}.json`);
+  const tmp = `${target}.tmp.${process.pid}`;
+  const json = JSON.stringify(state, null, 2);
+  await fs.writeFile(tmp, json, "utf8");
+  await fs.rename(tmp, target);
+}
+
+/**
+ * Load a session by id. Returns null when the file does not exist.
+ * Throws on parse errors or unsupported versions.
+ *
+ * @param {string} sessionId
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<SessionState | null>}
+ */
+export async function loadSession(sessionId, options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  const target = path.join(dir, `${sessionId}.json`);
+  /** @type {string} */
+  let raw;
+  try {
+    raw = await fs.readFile(target, "utf8");
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw err;
+  }
+
+  const parsed = JSON.parse(raw);
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    typeof parsed.version !== "number"
+  ) {
+    throw new Error(`Invalid session file: ${target}`);
+  }
+  if (parsed.version !== SESSION_FILE_VERSION) {
+    throw new Error(
+      `Unsupported session file version ${parsed.version} at ${target} (expected ${SESSION_FILE_VERSION})`,
+    );
+  }
+  return /** @type {SessionState} */ (parsed);
+}
+
+/**
+ * List sessions in the sessions directory, sorted by lastUpdatedAt descending.
+ * Malformed files are silently skipped.
+ *
+ * @param {{ dir?: string }} [options]
+ * @returns {Promise<SessionSummary[]>}
+ */
+export async function listSessions(options = {}) {
+  const dir = options.dir ?? SESSIONS_DIR;
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT"
+    ) {
+      return [];
+    }
+    throw err;
+  }
+
+  /** @type {SessionSummary[]} */
+  const summaries = [];
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    if (name.includes(".tmp.")) continue;
+    const sessionId = name.slice(0, -".json".length);
+    try {
+      const state = await loadSession(sessionId, { dir });
+      if (!state) continue;
+      summaries.push({
+        sessionId: state.sessionId,
+        modelName: state.modelName,
+        workingDir: state.workingDir,
+        startTime: state.startTime,
+        lastUpdatedAt: state.lastUpdatedAt,
+        messageCount: state.messages.length,
+      });
+    } catch {
+      // Skip malformed or version-mismatched files so a single bad file
+      // doesn't break listing.
+    }
+  }
+
+  summaries.sort((a, b) => b.lastUpdatedAt.localeCompare(a.lastUpdatedAt));
+  return summaries;
+}

package/src/subagent.mjs

@@ -256,10 +256,66 @@ export function createSubagentManager(agentRoles, handlers) {
     return subagents.length > 0;
   }
 
+  /**
+   * Get the most recently activated subagent, or null if none is active.
+   * @returns {{name: string} | null}
+   */
+  function getActiveSubagent() {
+    const top = subagents.at(-1);
+    return top ? { name: top.name } : null;
+  }
+
+  /**
+   * @typedef {Object} SubagentSerializedState
+   * @property {{name: string, goal: string, switchMessageIndex: number}[]} subagents
+   * @property {number} subagentCount
+   */
+
+  /**
+   * Snapshot the subagent stack for persistence.
+   * @returns {SubagentSerializedState}
+   */
+  function getState() {
+    return {
+      subagents: subagents.map((s) => ({ ...s })),
+      subagentCount,
+    };
+  }
+
+  /**
+   * Restore the subagent stack from a previously saved snapshot.
+   * Does NOT fire onSubagentSwitched; the caller is responsible for
+   * syncing any UI state (since listeners may not be attached yet).
+   * @param {SubagentSerializedState} state
+   */
+  function restoreState(state) {
+    if (typeof state !== "object" || state === null) {
+      throw new TypeError("state must be a non-null object");
+    }
+    if (!Array.isArray(state.subagents)) {
+      throw new TypeError("state.subagents must be an array");
+    }
+    if (typeof state.subagentCount !== "number") {
+      throw new TypeError("state.subagentCount must be a number");
+    }
+    subagents.length = 0;
+    for (const s of state.subagents) {
+      subagents.push({
+        name: s.name,
+        goal: s.goal,
+        switchMessageIndex: s.switchMessageIndex,
+      });
+    }
+    subagentCount = state.subagentCount;
+  }
+
   return {
     switchToSubagent,
     switchToMainAgent,
     processToolResults,
     isSubagentActive,
+    getActiveSubagent,
+    getState,
+    restoreState,
   };
 }

package/src/tool.d.ts

@@ -59,6 +59,8 @@ export type ToolUseApprover = {
   isAllowedToolUse: (toolUse: MessageContentToolUse) => ToolUseDecision;
   allowToolUse: (toolUse: MessageContentToolUse) => void;
   resetApprovalCount: () => void;
+  getAllowedToolUseInSession: () => ToolUsePattern[];
+  restoreAllowedToolUseInSession: (patterns: ToolUsePattern[]) => void;
 };
 
 export type ToolUsePattern = {

package/src/toolUseApprover.mjs

@@ -91,9 +91,34 @@ export function createToolUseApprover({
     });
   }
 
+  /**
+   * Snapshot the tool-use patterns the user explicitly allowed during this
+   * session. Used to persist resumable session state.
+   * @returns {ToolUsePattern[]}
+   */
+  function getAllowedToolUseInSession() {
+    return state.allowedToolUseInSession.map((p) => ({ ...p }));
+  }
+
+  /**
+   * Replace the in-session allow-list with a previously saved snapshot.
+   * @param {ToolUsePattern[]} patterns
+   */
+  function restoreAllowedToolUseInSession(patterns) {
+    if (!Array.isArray(patterns)) {
+      throw new TypeError("patterns must be an array");
+    }
+    state.allowedToolUseInSession.length = 0;
+    for (const p of patterns) {
+      state.allowedToolUseInSession.push({ ...p });
+    }
+  }
+
   return {
     isAllowedToolUse,
     allowToolUse,
     resetApprovalCount,
+    getAllowedToolUseInSession,
+    restoreAllowedToolUseInSession,
   };
 }

package/src/tools/execCommand.mjs

@@ -84,6 +84,7 @@ export function createExecCommandTool(config) {
                 PWD: process.env.PWD,
                 PATH: process.env.PATH,
                 HOME: process.env.HOME,
+                LANG: process.env.LANG,
               },
               timeout: 5 * 60 * 1000,
             },