@xingular/harness 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 2.1.1 - 2026-10-19
+
+- Change terminal `/plan` to run one isolated, read-only planning request; queue later messages until it settles and apply plan instructions only for that run.
+
 ## 2.1.0 - 2026-10-19
 
 - Add per-request plan mode to SDK session runs: instructions arrive as a dynamic context update, and the tool gate refuses calls outside the read-only set. The terminal uses `/plan`, `/plan on`, and `/plan off` to narrow its active tools.

package/dist/cli.js

@@ -3624,7 +3624,7 @@ var init_askUser = __esm({
 var version, package_default;
 var init_package = __esm({
   "package.json"() {
-    version = "2.1.0";
+    version = "2.1.1";
     package_default = {
       name: "@xingular/harness",
       version,
@@ -4920,10 +4920,8 @@ Code: ${event.userCode}`);
           notify(completions().map((item) => `/${item.name}  ${item.description ?? ""}`).join("\n"));
           break;
         case "plan": {
-          const current = host.planMode();
-          const next = !argument || argument === "toggle" ? !current : argument === "on" ? true : argument === "off" ? false : null;
-          if (next === null) throw new Error("Use /plan, /plan on, /plan off, or /plan toggle.");
-          host.setPlanMode(next);
+          if (!argument || ["on", "off", "toggle"].includes(argument.toLowerCase())) throw new Error("Use /plan <plan brief>.");
+          host.plan(argument);
           break;
         }
         case "quit":
@@ -5144,7 +5142,7 @@ var init_commands = __esm({
     init_package();
     BUILTINS = [
       { name: "help", description: "Available terminal commands" },
-      { name: "plan", description: "Toggle read-only plan mode" },
+      { name: "plan", description: "Run one read-only plan request: /plan <brief>" },
       { name: "new", description: "Start a new session" },
       { name: "resume", description: "Resume a session in this account and folder" },
       { name: "tree", description: "Navigate the session tree" },
@@ -6024,7 +6022,7 @@ async function withParentCancellation(signal, work) {
     signal?.removeEventListener("abort", stop);
   }
 }
-async function piExtension_default(pi) {
+async function piExtension_default(pi, planRun) {
   await terminalCall("startup", { phase: "Pi extension loaded" });
   let context = null;
   let nativeSubagents = false;
@@ -6149,6 +6147,10 @@ async function piExtension_default(pi) {
       await controlCall("terminal.subagents.register", { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
       subagentParent = true;
     }
+    if (planRun && event.messageType === "user") {
+      if (planRun.active) event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
+      else delete event.systemPromptOptions.sections.plan;
+    }
   });
   const deliverChildren = async (event, ctx, settle) => {
     if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
@@ -6206,6 +6208,10 @@ async function piExtension_default(pi) {
     requestStartedAt = Date.now();
   });
   pi.on("tool_call", async (event) => {
+    if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+      const reason = planRefusal(event.toolName, /* @__PURE__ */ new Set()) ?? `Plan mode is read-only: ${event.toolName} is not available in this session.`;
+      return { block: true, reason };
+    }
     try {
       const policy = await controlCall("terminal.policy", { tool: event.toolName, args: event.input });
       if (policy.requiresApproval) {
@@ -6290,6 +6296,15 @@ var init_piExtension = __esm({
     init_control();
     init_subagents();
     init_askUser();
+    init_planMode();
+  }
+});
+
+// src/terminal/tui/planMode.ts
+var init_planMode2 = __esm({
+  "src/terminal/tui/planMode.ts"() {
+    "use strict";
+    init_planMode();
   }
 });
 
@@ -6434,6 +6449,7 @@ async function createTerminalRuntime(args, host) {
     const generation = uiGeneration;
     return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration);
   };
+  const planRun = { active: false, allowedTools: /* @__PURE__ */ new Set() };
   const factory = async ({ cwd: targetCwd, sessionManager, sessionStartEvent }) => {
     if (realpathSync2(targetCwd) !== cwd) throw new Error("A native session cannot change this terminal working folder.");
     const settingsManager = SettingsManager.create(cwd, agentDir);
@@ -6451,7 +6467,7 @@ async function createTerminalRuntime(args, host) {
       additionalSkillPaths: prepared.skills,
       additionalPromptTemplatePaths: prepared.prompts,
       additionalThemePaths: prepared.themes,
-      extensionFactories: [...adapter2.builtins, { name: "harness-terminal-bridge", factory: piExtension_default, hidden: true }],
+      extensionFactories: [...adapter2.builtins, { name: "harness-terminal-bridge", factory: (pi) => piExtension_default(pi, planRun), hidden: true }],
       appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
     });
     const reloadResources = resourceLoader.reload.bind(resourceLoader);
@@ -6560,6 +6576,25 @@ async function createTerminalRuntime(args, host) {
       const input = text6.trimStart().startsWith("/") ? text6.trimStart() : text6;
       await native.session.prompt(input, native.session.isStreaming ? { streamingBehavior: followUp ? "followUp" : "steer" } : {});
     },
+    async submitPlan(text6) {
+      if (disposed) throw new Error("The terminal runtime has closed.");
+      if (changing) throw new Error("Wait for the native session change to finish before submitting.");
+      if (!text6.trim()) throw new Error("Use /plan <plan brief>.");
+      const session = native.session;
+      if (!session.isIdle) throw new Error("A plan request must wait until the current response settles.");
+      const originalTools = session.getActiveToolNames();
+      const allowedTools = planModeTools(originalTools);
+      planRun.allowedTools = new Set(allowedTools);
+      planRun.active = true;
+      try {
+        session.setActiveToolsByName(allowedTools);
+        await session.prompt(text6, { expandPromptTemplates: false });
+      } finally {
+        planRun.active = false;
+        planRun.allowedTools = /* @__PURE__ */ new Set();
+        if (!disposed && native.session === session) session.setActiveToolsByName(originalTools);
+      }
+    },
     get session() {
       return native.session;
     },
@@ -6679,6 +6714,7 @@ var init_runtime = __esm({
   "src/terminal/tui/runtime.ts"() {
     "use strict";
     init_piExtension();
+    init_planMode2();
     init_control();
     init_piAdapter();
     init_sessionUi();
@@ -6771,14 +6807,6 @@ var init_screen = __esm({
   }
 });
 
-// src/terminal/tui/planMode.ts
-var init_planMode2 = __esm({
-  "src/terminal/tui/planMode.ts"() {
-    "use strict";
-    init_planMode();
-  }
-});
-
 // src/terminal/tui/status.ts
 import { basename as basename10, sep as sep7 } from "node:path";
 import { parseColor as parseColor2, stripTerminalSequences as stripTerminalSequences4, truncateToWidth as truncateToWidth6, visibleWidth as visibleWidth3 } from "@earendil-works/pi-tui";
@@ -7671,7 +7699,6 @@ var init_application = __esm({
     init_piAdapter();
     init_runtime();
     init_screen();
-    init_planMode2();
     init_status();
     init_skillInvocation();
     init_theme();
@@ -7756,8 +7783,11 @@ var init_application = __esm({
       phase;
       viewport;
       toolsExpanded = false;
-      planMode = false;
-      normalTools;
+      deferredInputs = [];
+      planBarrierOpen = false;
+      planActive = false;
+      drainingDeferred = false;
+      activeDeferredKind;
       stopped = false;
       initialized = false;
       closing;
@@ -7875,8 +7905,7 @@ var init_application = __esm({
               this.editor.setText(text6);
               this.syncDraft(text6);
             },
-            planMode: () => this.planMode,
-            setPlanMode: (enabled) => this.setPlanMode(enabled),
+            plan: (brief) => this.enqueuePlan(brief),
             copyText: copyToClipboard2,
             openExternal,
             changed: this.change,
@@ -7906,8 +7935,6 @@ Release notes were not bundled with this installation.`;
             this.keybindings.reload();
             this.resetWorkingStatus();
             this.scrollToLatest();
-            this.planMode = false;
-            this.normalTools = void 0;
             this.refresh(true);
           }));
           this.initialized = true;
@@ -8084,20 +8111,49 @@ Release notes were not bundled with this installation.`;
         this.completionStatus = void 0;
         this.phase = void 0;
       }
-      /** Plan mode narrows the session to read-only tools; leaving it restores the set the session had before. */
-      setPlanMode(enabled) {
-        if (!this.runtime) return;
-        if (this.planMode === enabled) return;
-        if (this.planMode) {
-          this.session.setActiveToolsByName(this.normalTools ?? this.session.getActiveToolNames());
-          this.normalTools = void 0;
-        } else {
-          this.normalTools = this.session.getActiveToolNames();
-          this.session.setActiveToolsByName(planModeTools(this.normalTools));
+      enqueuePlan(brief) {
+        const text6 = brief.trim();
+        if (!text6) {
+          this.notify("Use /plan <plan brief>.", "error");
+          return;
         }
-        this.planMode = enabled;
-        this.notify(this.planMode ? "Plan mode: only read-only tools are available. Use /plan off to return to normal." : "Normal mode: all tools are available.");
+        const waiting = !this.session.isIdle;
+        this.planBarrierOpen = true;
+        this.deferredInputs.push({ kind: "plan", text: text6 });
+        this.notify(waiting ? "Plan request queued to run by itself after the current response." : "Plan request queued as an isolated run.");
         this.change();
+        this.drainDeferred();
+      }
+      drainDeferred() {
+        if (this.drainingDeferred || !this.planBarrierOpen || !this.runtime || !this.session.isIdle || !this.deferredInputs.length) return;
+        this.drainingDeferred = true;
+        void (async () => {
+          try {
+            while (this.deferredInputs.length && !this.stopped && this.runtime && this.session.isIdle) {
+              const next = this.deferredInputs.shift();
+              this.activeDeferredKind = next.kind;
+              this.change();
+              try {
+                if (next.kind === "plan") {
+                  this.planActive = true;
+                  await this.runtime.submitPlan(next.text);
+                } else {
+                  await this.runtime.submit(next.text, next.followUp);
+                }
+              } catch (error) {
+                this.notify(error instanceof Error ? error.message : String(error), "error");
+              } finally {
+                if (next.kind === "plan") this.planActive = false;
+                this.activeDeferredKind = void 0;
+              }
+            }
+          } finally {
+            this.drainingDeferred = false;
+            if (!this.deferredInputs.length && !this.planActive) this.planBarrierOpen = false;
+            this.change();
+            if (this.deferredInputs.length && this.runtime?.session.isIdle) this.drainDeferred();
+          }
+        })();
       }
       scrollToLatest() {
         this.viewport?.scrollToEnd();
@@ -8175,7 +8231,9 @@ Release notes were not bundled with this installation.`;
       queuedMessages(width) {
         if (!this.ui) return [];
         const state2 = this.runtime?.snapshot();
-        return state2 ? [...state2.queue.steering.map((text6) => `Steering: ${text6}`), ...state2.queue.followUp.map((text6) => `Follow-up: ${text6}`)].flatMap((text6) => wrapTextWithAnsi5(this.theme.fg("muted", text6), width)) : [];
+        const native = state2 ? [...state2.queue.steering.map((text6) => `Steering: ${text6}`), ...state2.queue.followUp.map((text6) => `Follow-up: ${text6}`)] : [];
+        const deferred = this.deferredInputs.map((input) => input.kind === "plan" ? `Plan: /plan ${input.text}` : `Queued: ${input.text}`);
+        return [...native, ...deferred].flatMap((text6) => wrapTextWithAnsi5(this.theme.fg("muted", text6), width));
       }
       statusLines(width) {
         return this.statuses.size ? wrapTextWithAnsi5([...this.statuses.values()].join("  "), width) : [];
@@ -8216,7 +8274,13 @@ Release notes were not bundled with this installation.`;
             if (this.stopped) return;
             if (command && await this.commands.execute(text6)) return;
             if (text6.trimStart().startsWith("!")) throw new Error("Use the bash tool so this action can be checked.");
-            await this.runtime.submit(this.commands.expandSkill(text6), followUp);
+            const expanded = this.commands.expandSkill(text6);
+            if (this.planBarrierOpen) {
+              this.deferredInputs.push({ kind: "prompt", text: expanded, followUp });
+              this.change();
+              return;
+            }
+            await this.runtime.submit(expanded, followUp);
           } finally {
             if (command) this.commandBusy = false;
           }
@@ -8256,7 +8320,10 @@ Release notes were not bundled with this installation.`;
         } else if (is("app.message.followUp")) this.submit(this.editor.getExpandedText?.() ?? this.editor.getText(), true);
         else if (is("app.message.dequeue")) {
           const pending = this.session.clearQueue();
-          this.editor.setText([...pending.steering, ...pending.followUp, this.editor.getText()].filter(Boolean).join("\n"));
+          const deferred = this.deferredInputs.map((input) => input.kind === "plan" ? `/plan ${input.text}` : input.text);
+          this.deferredInputs = [];
+          this.planBarrierOpen = this.planActive || this.activeDeferredKind === "plan";
+          this.editor.setText([...pending.steering, ...pending.followUp, ...deferred, this.editor.getText()].filter(Boolean).join("\n"));
           this.syncDraft(this.editor.getText());
         } else if (is("app.editor.external")) this.attempt(() => this.externalEditor());
         else if (is("app.message.copy")) this.attempt(() => this.commands.execute("/copy"));
@@ -8301,6 +8368,7 @@ Release notes were not bundled with this installation.`;
           this.requestStartedAt = null;
           this.phase = void 0;
           this.terminal.setProgress(false);
+          queueMicrotask(() => this.drainDeferred());
         }
         if (event.type === "compaction_start") this.phase = "Compacting context\u2026";
         if (event.type === "compaction_end") {
@@ -8338,6 +8406,10 @@ Release notes were not bundled with this installation.`;
       resetPresentation() {
         this.pendingAbort?.abort();
         this.dismissedDecisions.clear();
+        this.deferredInputs = [];
+        this.planBarrierOpen = false;
+        this.planActive = false;
+        this.activeDeferredKind = void 0;
         this.resetWorkingStatus();
         this.requestStartedAt = null;
         this.lastTokensPerSecond = null;

package/dist/terminal-pi.js

@@ -18,7 +18,7 @@ function connectionFromEnv(env = process.env) {
   if (!socket || !token) throw new SocketError("not_configured", `This command only works inside a terminal session the harness started (${SOCKET_ENV} and ${TOKEN_ENV} are not set).`);
   return { socket, token };
 }
-function request(connection, body, what, timeoutMs) {
+function request(connection, body2, what, timeoutMs) {
   return new Promise((resolve, reject) => {
     const stream = createConnection(connection.socket);
     let buffer = "";
@@ -34,7 +34,7 @@ function request(connection, body, what, timeoutMs) {
       stream.destroy();
       finish(() => reject(new SocketError("timeout", `The harness did not answer ${what}.`)));
     }, timeoutMs);
-    stream.on("connect", () => stream.write(`${JSON.stringify({ token: connection.token, ...body })}
+    stream.on("connect", () => stream.write(`${JSON.stringify({ token: connection.token, ...body2 })}
 `));
     stream.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -177,13 +177,13 @@ async function addAccount(ui, call) {
   if (await attempt(ui, () => call("accounts.create", { label: label.trim(), authKind: "subscription" }))) ui.notify("Account added. Sign in to use it.", "info");
 }
 async function accountMenu(ui, call, session, accountId) {
-  const isSession = session.accountId === accountId;
+  const isSession2 = session.accountId === accountId;
   for (; ; ) {
     const overview = await call("accounts.list");
     const account = overview.accounts.find((candidate) => candidate.id === accountId);
     if (!account) return;
     const actions = [
-      ...isSession ? [] : [USE_HERE],
+      ...isSession2 ? [] : [USE_HERE],
       ...account.isDefault ? [] : [MAKE_DEFAULT],
       RENAME,
       CHECK,
@@ -193,7 +193,7 @@ async function accountMenu(ui, call, session, accountId) {
       ...account.state.piProviders.length ? [REMOVE_PROVIDER] : [],
       SIGN_OUT,
       // The session's own account is in use, so it cannot be removed from inside the session.
-      ...isSession ? [] : [REMOVE],
+      ...isSession2 ? [] : [REMOVE],
       BACK
     ];
     const action = await ui.select(`${account.label} \xB7 ${HEALTH[account.state.health] ?? HEALTH.unknown}`, actions);
@@ -278,16 +278,16 @@ async function followLogin(ui, call, accountId, loginId) {
   const deadline = Date.now() + LOGIN_TIMEOUT_MS;
   let shownRevision = -1;
   for (; ; ) {
-    const snapshot = await call("accounts.loginStatus", { accountId });
-    if (!snapshot || snapshot.loginId !== loginId) return;
-    if (snapshot.status !== "running") return reportLogin(ui, snapshot);
-    if (snapshot.prompt) {
-      await answerPrompt(ui, call, loginId, snapshot.prompt);
+    const snapshot2 = await call("accounts.loginStatus", { accountId });
+    if (!snapshot2 || snapshot2.loginId !== loginId) return;
+    if (snapshot2.status !== "running") return reportLogin(ui, snapshot2);
+    if (snapshot2.prompt) {
+      await answerPrompt(ui, call, loginId, snapshot2.prompt);
       continue;
     }
-    const step = [...snapshot.events].reverse().map(loginStep).find((text3) => text3 !== null);
-    if (step && snapshot.revision !== shownRevision) {
-      shownRevision = snapshot.revision;
+    const step = [...snapshot2.events].reverse().map(loginStep).find((text3) => text3 !== null);
+    if (step && snapshot2.revision !== shownRevision) {
+      shownRevision = snapshot2.revision;
       const choice = await ui.select(`${step}
 
 Finish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_IN]);
@@ -306,10 +306,10 @@ Finish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_I
     await new Promise((resolve) => setTimeout(resolve, POLL_MS));
   }
 }
-function reportLogin(ui, snapshot) {
-  if (snapshot.status === "completed") ui.notify("Signed in.", "info");
-  else if (snapshot.status === "cancelled") ui.notify("Sign-in was cancelled.", "warning");
-  else ui.notify(snapshot.error ?? "Sign-in failed.", "error");
+function reportLogin(ui, snapshot2) {
+  if (snapshot2.status === "completed") ui.notify("Signed in.", "info");
+  else if (snapshot2.status === "cancelled") ui.notify("Sign-in was cancelled.", "warning");
+  else ui.notify(snapshot2.error ?? "Sign-in failed.", "error");
 }
 async function answerPrompt(ui, call, loginId, prompt) {
   const promptId = String(prompt.promptId ?? "");
@@ -838,6 +838,59 @@ function askUserTool(run2) {
   };
 }
 
+// src/core/frontmatter.ts
+import { parse as parseYaml, stringify } from "yaml";
+
+// src/memory/store.ts
+import { stringify as stringify2 } from "yaml";
+
+// src/skills/registry.ts
+var MAX_SKILL_IMPORT_BYTES = 10 * 1024 * 1024;
+
+// src/prompt/compile.ts
+var SECTION_ORDER = { blocks: 30, rules: 40, references: 50, skills: 60, knowledge: 80, tools: 90 };
+var BUILT_IN_DYNAMIC = [
+  { id: "blocks", order: SECTION_ORDER.blocks },
+  { id: "references", order: SECTION_ORDER.references },
+  { id: "knowledge", order: SECTION_ORDER.knowledge }
+];
+
+// src/sessions/planMode.ts
+var PLAN_READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "read",
+  "grep",
+  "find",
+  "ls",
+  ASK_USER,
+  "ask_user_question",
+  "history_search",
+  "history_read",
+  "trajectory_search",
+  "trajectory_read",
+  "wiki_entrypoint",
+  "wiki_search",
+  "wiki_read",
+  "wiki_list",
+  "memory_facts",
+  "skill_load",
+  "mcp_list_tools"
+]);
+var PLAN_OPEN_TAG = "<proposed_plan>";
+var PLAN_CLOSE_TAG = "</proposed_plan>";
+var PLAN_INSTRUCTIONS = `Plan mode is on for this request. Investigate and design; do not carry out the work.
+- Read, search and recall freely. When a decision belongs to the user, ask with ${ASK_USER} instead of guessing.
+- Do not change files, run commands, write memory, delegate, or call connected apps. Such calls are refused while plan mode is on.
+- When the plan is ready, end the reply with exactly one block in this form, after any other text:
+${PLAN_OPEN_TAG}
+# <Plan title>
+<Markdown: the context, the steps with the files they change, and how to verify the result>
+${PLAN_CLOSE_TAG}
+- If you need the user's input before a plan is possible, ask instead of proposing one.`;
+function planRefusal(tool, readOnly) {
+  if (PLAN_READ_ONLY_TOOLS.has(tool) || readOnly.has(tool)) return null;
+  return `Plan mode is read-only: ${tool} is not available until the user leaves plan mode. Continue investigating, or finish with a ${PLAN_OPEN_TAG} block.`;
+}
+
 // src/terminal/piExtension.ts
 function resultSize(result) {
   const content = result?.content;
@@ -857,7 +910,7 @@ async function withParentCancellation(signal, work) {
     signal?.removeEventListener("abort", stop);
   }
 }
-async function piExtension_default(pi) {
+async function piExtension_default(pi, planRun) {
   await terminalCall("startup", { phase: "Pi extension loaded" });
   let context = null;
   let nativeSubagents = false;
@@ -982,6 +1035,10 @@ async function piExtension_default(pi) {
       await controlCall("terminal.subagents.register", { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
       subagentParent = true;
     }
+    if (planRun && event.messageType === "user") {
+      if (planRun.active) event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
+      else delete event.systemPromptOptions.sections.plan;
+    }
   });
   const deliverChildren = async (event, ctx, settle) => {
     if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
@@ -1039,6 +1096,10 @@ async function piExtension_default(pi) {
     requestStartedAt = Date.now();
   });
   pi.on("tool_call", async (event) => {
+    if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+      const reason = planRefusal(event.toolName, /* @__PURE__ */ new Set()) ?? `Plan mode is read-only: ${event.toolName} is not available in this session.`;
+      return { block: true, reason };
+    }
     try {
       const policy = await controlCall("terminal.policy", { tool: event.toolName, args: event.input });
       if (policy.requiresApproval) {

package/docs/terminal-tui.md

@@ -87,22 +87,22 @@ The decision and its consequences are recorded in
 
 ## Plan mode and thinking keys
 
-Use `/plan`, `/plan on`, or `/plan off` to switch between normal and plan mode. The switch is
-announced in the transcript. Plan mode narrows the session to read-only inspection (`read`, `grep`, `find`, `ls`),
-questions (`ask_user`, `ask_user_question`) and recall (history and Wiki reads, `memory_facts`). Edits,
-writes, shell commands, memory writes, subagents and connected-app tools are withdrawn until plan mode
-is switched off, and switching back restores the tools the session had. Plan mode belongs to the open
-conversation: a new or resumed session starts in normal mode.
+Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi's native follow-up
+queue until the active response settles, then runs by itself. Later messages remain behind it, even
+when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
+(`read`, `grep`, `find`, `ls`), questions (`ask_user`, `ask_user_question`) and recall (history and
+Wiki reads, `memory_facts`); edits, writes, shell commands, memory writes, subagents and connected-app
+tools are blocked. The plan instructions arrive as a request-scoped prompt section, which the next
+ordinary request withdraws. `/plan` without a brief and the old on/off/toggle forms are rejected.
 
 While typing, a recognized leading slash command uses the selected theme's link color. This
 includes built-in commands, loaded extension and prompt commands, and enabled skill invocations
 written as `/skill:name`. Unknown slash tokens keep the normal text color.
 
-SDK session runs can receive plan instructions as a dynamic context update, leaving the stable
-system prompt unchanged; their session gate refuses calls outside the read-only set. The standalone
-terminal still narrows Pi's active tools directly and does not yet deliver plan instructions through
-the prompt. Shift+Up and Shift+Down step the thinking level within the levels the model supports,
-and do not wrap.
+SDK session runs receive plan instructions as a dynamic context update, leaving the stable system
+prompt unchanged; their session gate refuses calls outside the read-only set. The standalone
+terminal applies the same one-run instructions and tool restrictions. Shift+Up and Shift+Down step
+the thinking level within the levels the model supports, and do not wrap.
 
 ## Reference and reproduced presentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
   "repository": {

package/src/terminal/piExtension.lifecycle.test.ts

@@ -11,7 +11,8 @@ vi.mock('./client', () => ({
   terminalCall: transport.telemetry
 }))
 
-import terminalExtension from './piExtension'
+import terminalExtension, { type TerminalPlanRunState } from './piExtension'
+import { PLAN_INSTRUCTIONS } from '../sessions/planMode'
 
 function extension() {
   const handlers = new Map<string, (...args: unknown[]) => unknown>()
@@ -28,6 +29,32 @@ function extension() {
 afterEach(() => vi.useRealTimers())
 
 describe('terminal bridge lifecycle', () => {
+  it('adds plan instructions as a one-run context section and withdraws them on the next user request', async () => {
+    const state: TerminalPlanRunState = { active: true, allowedTools: new Set(['read']) }
+    const { api, ctx, handlers } = extension()
+    await terminalExtension(api, state)
+    const planned = { messageType: 'user', prompt: 'inspect this', systemPrompt: 'stable prefix', systemPromptOptions: { sections: { identity: 'identity' } } }
+    await handlers.get('before_agent_start')!(planned, ctx)
+    expect(planned.systemPromptOptions.sections).toEqual({ identity: 'identity', plan: PLAN_INSTRUCTIONS })
+    expect(planned.systemPrompt).toBe('stable prefix')
+
+    state.active = false
+    const ordinary = { messageType: 'user', prompt: 'now implement', systemPrompt: 'stable prefix', systemPromptOptions: { sections: { identity: 'identity', plan: PLAN_INSTRUCTIONS } } }
+    await handlers.get('before_agent_start')!(ordinary, ctx)
+    expect(ordinary.systemPromptOptions.sections).toEqual({ identity: 'identity' })
+    expect(ordinary.systemPrompt).toBe('stable prefix')
+  })
+
+  it('blocks tools outside the active plan allowlist before consulting terminal policy', async () => {
+    const state: TerminalPlanRunState = { active: true, allowedTools: new Set(['read']) }
+    const { api, ctx, handlers } = extension()
+    await terminalExtension(api, state)
+    const policyCalls = transport.socket.mock.calls.filter(([, call]) => call === 'terminal.policy').length
+    const result = await handlers.get('tool_call')!({ toolName: 'bash', toolCallId: 'call-1', input: { command: 'touch unsafe' } }, ctx)
+    expect(result).toMatchObject({ block: true, reason: expect.stringContaining('Plan mode is read-only') })
+    expect(transport.socket.mock.calls.filter(([, call]) => call === 'terminal.policy')).toHaveLength(policyCalls)
+  })
+
   it('keeps one private control claim while replacing native session pollers and restoring readiness', async () => {
     vi.useFakeTimers()
     const first = extension()

package/src/terminal/piExtension.ts

@@ -13,6 +13,7 @@ import { claimTerminalControl, controlCall } from './control'
 import { SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, subagentHistory, type SubagentReceipt } from '../sessions/subagents'
 import { askUserTool } from '../tools/askUser'
 import type { QuestionAnswer } from '../sessions/registry'
+import { PLAN_INSTRUCTIONS, planRefusal } from '../sessions/planMode'
 
 interface SocketTool {
   name: string
@@ -21,6 +22,11 @@ interface SocketTool {
   parameters: Record<string, unknown>
 }
 
+export interface TerminalPlanRunState {
+  active: boolean
+  allowedTools: ReadonlySet<string>
+}
+
 /** How much text a tool handed back to the model. */
 function resultSize(result: unknown): number | null {
   const content = (result as { content?: unknown } | null | undefined)?.content
@@ -35,7 +41,7 @@ async function withParentCancellation<T>(signal: AbortSignal | undefined, work:
   try { return await work() } finally { signal?.removeEventListener('abort', stop) }
 }
 
-export default async function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI, planRun?: TerminalPlanRunState) {
   await terminalCall('startup', { phase: 'Pi extension loaded' })
   let context: ExtensionContext | null = null
   let nativeSubagents = false
@@ -167,6 +173,10 @@ export default async function (pi: ExtensionAPI) {
       await controlCall('terminal.subagents.register', { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) })
       subagentParent = true
     }
+    if (planRun && event.messageType === 'user') {
+      if (planRun.active) event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS
+      else delete event.systemPromptOptions.sections.plan
+    }
   })
   const deliverChildren = async (event: any, ctx: ExtensionContext, settle: boolean) => {
     if (!nativeSubagents || (settle && event.outcome !== 'completed') || ctx.signal?.aborted) return
@@ -224,6 +234,10 @@ export default async function (pi: ExtensionAPI) {
     requestStartedAt = Date.now()
   })
   pi.on('tool_call', async (event) => {
+    if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+      const reason = planRefusal(event.toolName, new Set()) ?? `Plan mode is read-only: ${event.toolName} is not available in this session.`
+      return { block: true, reason }
+    }
     try {
       const policy = await controlCall<{ allowed: boolean; reason?: string; requiresApproval?: boolean }>('terminal.policy', { tool: event.toolName, args: event.input })
       if (policy.requiresApproval) {

package/src/terminal/tui/application.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, it, vi } from 'vitest'
 vi.mock('../control', () => ({ controlCall: vi.fn(async () => ({})) }))
 import { controlCall } from '../control'
 import { TerminalApplication } from './application'
-import { createTerminalCommands, type TerminalCommandHost } from './commands'
+import { createTerminalCommands } from './commands'
 import type { TerminalDecision } from './runtime'
 import { terminalKeybindings } from './keybindings'
 import { autocompleteRuleColor, createHarnessTheme } from './theme'
@@ -22,10 +22,8 @@ function setup() {
     }
     keybindings: ReturnType<typeof terminalKeybindings>
     editor: CustomEditor
-    runtime: { interrupt: ReturnType<typeof vi.fn>; dispose: ReturnType<typeof vi.fn>; session: object; snapshot(): { hasUserMessages: boolean; cwd?: string; model?: { name: string; reasoning: boolean; contextWindow: number }; thinkingLevel?: string; account?: { label: string } | null; context?: { percent: number | null; window: number }; costUsd?: number; subscription?: boolean } }
-    commands: ReturnType<typeof createTerminalCommands> | { execute: ReturnType<typeof vi.fn> }
-    planMode: boolean
-    setPlanMode(enabled: boolean): void
+    runtime: { interrupt: ReturnType<typeof vi.fn>; dispose: ReturnType<typeof vi.fn>; submit: ReturnType<typeof vi.fn>; submitPlan: ReturnType<typeof vi.fn>; session: object; snapshot(): { hasUserMessages: boolean; cwd?: string; model?: { name: string; reasoning: boolean; contextWindow: number }; thinkingLevel?: string; account?: { label: string } | null; context?: { percent: number | null; window: number }; costUsd?: number; subscription?: boolean } }
+    commands: ReturnType<typeof createTerminalCommands> | { execute: ReturnType<typeof vi.fn>; expandSkill(text: string): string }
     masthead: { render(width: number): string[] }
     header?: { render(width: number): string[]; invalidate(): void }
     branch: string | null
@@ -52,7 +50,7 @@ function setup() {
   app.keybindings = terminalKeybindings('/unused/isolated-account')
   app.initialized = true
   const context = {}
-  app.runtime = { interrupt: vi.fn(async () => {}), dispose: vi.fn(async () => {}), snapshot: () => ({
+  app.runtime = { interrupt: vi.fn(async () => {}), dispose: vi.fn(async () => {}), submit: vi.fn(async () => {}), submitPlan: vi.fn(async () => {}), snapshot: () => ({
     hasUserMessages: false, cwd: '/work/project', model: { name: 'Claude Sonnet 4.6', reasoning: true, contextWindow: 200_000 },
     thinkingLevel: 'high', account: { label: 'Tanny' }, context: { percent: null, window: 0 }, costUsd: 0, subscription: false
   }), session: {
@@ -226,7 +224,7 @@ describe('the owned terminal application', () => {
     const { application, app } = setup()
     app.mountEditor()
     let resolve!: (value: boolean) => void
-    app.commands = { execute: vi.fn(() => new Promise<boolean>(done => { resolve = done })) }
+    app.commands = { execute: vi.fn(() => new Promise<boolean>(done => { resolve = done })), expandSkill: text => text }
     app.submit('   /settings')
     await vi.waitFor(() => expect(app.commands.execute).toHaveBeenCalledWith('   /settings'))
     app.submit('/model')
@@ -237,35 +235,33 @@ describe('the owned terminal application', () => {
     await application.shutdown()
   })
 
-  it('toggles plan mode with /plan, narrowing to read-only tools', async () => {
+  it('keeps a queued plan isolated and sends later messages after it settles', async () => {
     const { application, app } = setup()
-    const session = app.runtime.session as { getActiveToolNames(): string[]; setActiveToolsByName(names: string[]): void; cycleThinkingLevel(): void }
-    const setActiveToolsByName = vi.fn()
-    const cycleThinkingLevel = vi.fn()
-    Object.assign(session, { getActiveToolNames: () => ['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent'], setActiveToolsByName, cycleThinkingLevel })
-    app.commands = createTerminalCommands({
-      session: () => session as never,
-      runtime: () => ({} as never),
-      ui: app.ui,
-      cwd: () => '/work/project',
-      sessionDirectory: () => '/isolated/account/history',
-      refresh: () => {},
-      changed: () => {},
-      planMode: () => app.planMode,
-      setPlanMode: enabled => app.setPlanMode(enabled),
-      shutdown: () => {},
-      setEditorText: () => {},
-      copyText: async () => {},
-      trajectory: {} as TerminalCommandHost['trajectory']
-    })
+    const session = app.runtime.session as { isIdle: boolean }
+    Object.assign(session, { isIdle: false })
+    const sent: string[] = []
+    app.runtime.submitPlan = vi.fn(async brief => { sent.push(`plan:${brief}`) })
+    app.runtime.submit = vi.fn(async text => { sent.push(`prompt:${text}`) })
+    const enqueuePlan = (application as unknown as { enqueuePlan(brief: string): void }).enqueuePlan.bind(application)
     app.mountEditor()
-    app.submit('/plan')
-    await vi.waitFor(() => expect(setActiveToolsByName).toHaveBeenCalledWith(['read', 'grep']))
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'grep'])
-    app.submit('/plan off')
-    await vi.waitFor(() => expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent']))
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent'])
-    expect(cycleThinkingLevel).not.toHaveBeenCalled()
+    app.commands = {
+      execute: vi.fn(async text => {
+        if (text.trimStart().startsWith('/plan ')) { enqueuePlan(text.trimStart().slice('/plan '.length)); return true }
+        return false
+      }),
+      expandSkill: text => text
+    }
+
+    app.submit('/plan inspect the source')
+    await vi.waitFor(() => expect(app.commandBusy).toBe(false))
+    app.submit('then implement it')
+    await vi.waitFor(() => expect((application as unknown as { deferredInputs: unknown[] }).deferredInputs).toHaveLength(2))
+    expect(sent).toEqual([])
+
+    session.isIdle = true
+    app.accept({ type: 'agent_settled' } as AgentSessionEvent)
+    await vi.waitFor(() => expect(sent).toEqual(['plan:inspect the source', 'prompt:then implement it']))
+    expect(app.runtime.submitPlan).toHaveBeenCalledOnce()
     await application.shutdown()
   })
 

package/src/terminal/tui/application.ts

@@ -16,7 +16,6 @@ import { HARNESS_KEYBINDINGS, terminalKeybindings } from './keybindings'
 import { loadPiAdapter, setPiTheme } from './piAdapter'
 import { createTerminalRuntime, type TerminalDecision, type TerminalRuntime } from './runtime'
 import { createDock, createTerminalScreen, mountTerminalLayout, readScreenPreferences, scrollbackLines, writeScrollback, type ScreenHooks, type ScreenPreferences, type TerminalScreen } from './screen'
-import { planModeTools } from './planMode'
 import { renderStatusBand, singleLine } from './status'
 import { skillCompletions } from './skillInvocation'
 import { createHarnessLightTheme, createHarnessTheme } from './theme'
@@ -30,6 +29,7 @@ import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../traje
 
 const exec = promisify(execFile)
 type Mounted = Component & { dispose?(): void }
+type DeferredTerminalInput = { kind: 'plan'; text: string } | { kind: 'prompt'; text: string; followUp: boolean }
 type EditorFactory = Parameters<ExtensionUIContext['setEditorComponent']>[0]
 type HeaderFactory = Parameters<ExtensionUIContext['setHeader']>[0]
 type FooterFactory = Parameters<ExtensionUIContext['setFooter']>[0]
@@ -102,8 +102,11 @@ export class TerminalApplication {
   private phase?: string
   private viewport?: ScrollView
   private toolsExpanded = false
-  private planMode = false
-  private normalTools?: string[]
+  private deferredInputs: DeferredTerminalInput[] = []
+  private planBarrierOpen = false
+  private planActive = false
+  private drainingDeferred = false
+  private activeDeferredKind?: DeferredTerminalInput['kind']
   private stopped = false
   private initialized = false
   private closing?: Promise<void>
@@ -184,7 +187,7 @@ export class TerminalApplication {
         session: () => this.session, runtime: () => this.runtime!, ui: this.ui,
         cwd: () => this.runtime!.cwd, sessionDirectory: () => this.runtime!.sessionDirectory,
         refresh: () => this.refresh(), shutdown: () => { void this.shutdown() }, setEditorText: text => { this.editor.setText(text); this.syncDraft(text) },
-        planMode: () => this.planMode, setPlanMode: enabled => this.setPlanMode(enabled),
+        plan: brief => this.enqueuePlan(brief),
         copyText: copyToClipboard, openExternal,
         changed: this.change,
         trajectory: {
@@ -202,7 +205,7 @@ export class TerminalApplication {
       })
       this.cleanup.push(this.runtime.subscribe(event => this.accept(event)))
       this.cleanup.push(this.runtime.onBeforeSessionChange(() => this.resetPresentation()))
-      this.cleanup.push(this.runtime.onSessionChange(() => { this.keybindings.reload(); this.resetWorkingStatus(); this.scrollToLatest(); this.planMode = false; this.normalTools = undefined; this.refresh(true) }))
+      this.cleanup.push(this.runtime.onSessionChange(() => { this.keybindings.reload(); this.resetWorkingStatus(); this.scrollToLatest(); this.refresh(true) }))
       this.initialized = true
       this.phase = undefined
       this.refresh(true)
@@ -307,20 +310,46 @@ export class TerminalApplication {
     this.completionStatus = undefined
     this.phase = undefined
   }
-  /** Plan mode narrows the session to read-only tools; leaving it restores the set the session had before. */
-  private setPlanMode(enabled: boolean): void {
-    if (!this.runtime) return
-    if (this.planMode === enabled) return
-    if (this.planMode) {
-      this.session.setActiveToolsByName(this.normalTools ?? this.session.getActiveToolNames())
-      this.normalTools = undefined
-    } else {
-      this.normalTools = this.session.getActiveToolNames()
-      this.session.setActiveToolsByName(planModeTools(this.normalTools))
-    }
-    this.planMode = enabled
-    this.notify(this.planMode ? 'Plan mode: only read-only tools are available. Use /plan off to return to normal.' : 'Normal mode: all tools are available.')
+  private enqueuePlan(brief: string): void {
+    const text = brief.trim()
+    if (!text) { this.notify('Use /plan <plan brief>.', 'error'); return }
+    const waiting = !this.session.isIdle
+    this.planBarrierOpen = true
+    this.deferredInputs.push({ kind: 'plan', text })
+    this.notify(waiting ? 'Plan request queued to run by itself after the current response.' : 'Plan request queued as an isolated run.')
     this.change()
+    this.drainDeferred()
+  }
+  private drainDeferred(): void {
+    if (this.drainingDeferred || !this.planBarrierOpen || !this.runtime || !this.session.isIdle || !this.deferredInputs.length) return
+    this.drainingDeferred = true
+    void (async () => {
+      try {
+        while (this.deferredInputs.length && !this.stopped && this.runtime && this.session.isIdle) {
+          const next = this.deferredInputs.shift()!
+          this.activeDeferredKind = next.kind
+          this.change()
+          try {
+            if (next.kind === 'plan') {
+              this.planActive = true
+              await this.runtime.submitPlan(next.text)
+            } else {
+              await this.runtime.submit(next.text, next.followUp)
+            }
+          } catch (error) {
+            this.notify(error instanceof Error ? error.message : String(error), 'error')
+          } finally {
+            if (next.kind === 'plan') this.planActive = false
+            this.activeDeferredKind = undefined
+          }
+        }
+      } finally {
+        this.drainingDeferred = false
+        if (!this.deferredInputs.length && !this.planActive) this.planBarrierOpen = false
+        this.change()
+        if (this.deferredInputs.length && this.runtime?.session.isIdle) this.drainDeferred()
+      }
+    })()
   }
   private scrollToLatest(): void { this.viewport?.scrollToEnd() }
   private async chooseApproval(request: TerminalDecision, signal: AbortSignal): Promise<{ decision: 'approved' | 'denied'; alwaysAllow: boolean }> {
@@ -397,7 +426,9 @@ export class TerminalApplication {
   private queuedMessages(width: number): string[] {
     if (!this.ui) return []
     const state = this.runtime?.snapshot()
-    return state ? [...state.queue.steering.map(text => `Steering: ${text}`), ...state.queue.followUp.map(text => `Follow-up: ${text}`)].flatMap(text => wrapTextWithAnsi(this.theme.fg('muted', text), width)) : []
+    const native = state ? [...state.queue.steering.map(text => `Steering: ${text}`), ...state.queue.followUp.map(text => `Follow-up: ${text}`)] : []
+    const deferred = this.deferredInputs.map(input => input.kind === 'plan' ? `Plan: /plan ${input.text}` : `Queued: ${input.text}`)
+    return [...native, ...deferred].flatMap(text => wrapTextWithAnsi(this.theme.fg('muted', text), width))
   }
   private statusLines(width: number): string[] {
     return this.statuses.size ? wrapTextWithAnsi([...this.statuses.values()].join('  '), width) : []
@@ -427,7 +458,13 @@ export class TerminalApplication {
         if (this.stopped) return
         if (command && await this.commands.execute(text)) return
         if (text.trimStart().startsWith('!')) throw new Error('Use the bash tool so this action can be checked.')
-        await this.runtime!.submit(this.commands.expandSkill(text), followUp)
+        const expanded = this.commands.expandSkill(text)
+        if (this.planBarrierOpen) {
+          this.deferredInputs.push({ kind: 'prompt', text: expanded, followUp })
+          this.change()
+          return
+        }
+        await this.runtime!.submit(expanded, followUp)
       } finally { if (command) this.commandBusy = false }
     })
   }
@@ -455,7 +492,14 @@ export class TerminalApplication {
     else if (is('app.tools.expand')) this.ui.setToolsExpanded(!this.toolsExpanded)
     else if (is('app.thinking.toggle')) { const hidden = !this.session.settingsManager.getHideThinkingBlock(); this.session.settingsManager.setHideThinkingBlock(hidden); this.transcript.setThinking(hidden) }
     else if (is('app.message.followUp')) this.submit(this.editor.getExpandedText?.() ?? this.editor.getText(), true)
-    else if (is('app.message.dequeue')) { const pending = this.session.clearQueue(); this.editor.setText([...pending.steering, ...pending.followUp, this.editor.getText()].filter(Boolean).join('\n')); this.syncDraft(this.editor.getText()) }
+    else if (is('app.message.dequeue')) {
+      const pending = this.session.clearQueue()
+      const deferred = this.deferredInputs.map(input => input.kind === 'plan' ? `/plan ${input.text}` : input.text)
+      this.deferredInputs = []
+      this.planBarrierOpen = this.planActive || this.activeDeferredKind === 'plan'
+      this.editor.setText([...pending.steering, ...pending.followUp, ...deferred, this.editor.getText()].filter(Boolean).join('\n'))
+      this.syncDraft(this.editor.getText())
+    }
     else if (is('app.editor.external')) this.attempt(() => this.externalEditor())
     else if (is('app.message.copy')) this.attempt(() => this.commands.execute('/copy'))
     else if (is('app.clipboard.pasteImage')) this.attempt(() => this.pasteClipboard())
@@ -498,6 +542,7 @@ export class TerminalApplication {
       this.requestStartedAt = null
       this.phase = undefined
       this.terminal.setProgress(false)
+      queueMicrotask(() => this.drainDeferred())
     }
     if (event.type === 'compaction_start') this.phase = 'Compacting context…'
     if (event.type === 'compaction_end') { this.phase = undefined; this.transcript.bind(this.session); if (event.errorMessage) this.notify(event.errorMessage, 'error') }
@@ -527,6 +572,7 @@ export class TerminalApplication {
   }
   private resetPresentation(): void {
     this.pendingAbort?.abort(); this.dismissedDecisions.clear()
+    this.deferredInputs = []; this.planBarrierOpen = false; this.planActive = false; this.activeDeferredKind = undefined
     this.resetWorkingStatus()
     this.requestStartedAt = null; this.lastTokensPerSecond = null
     this.transcript.clearSession()

package/src/terminal/tui/commands.test.ts

@@ -31,7 +31,7 @@ function setup() {
     session: () => session, runtime: () => runtime as unknown as ReturnType<TerminalCommandHost['runtime']>, ui,
     cwd: () => '/isolated/project', sessionDirectory: () => '/isolated/account/history',
     refresh: vi.fn(), changed: vi.fn(), shutdown: vi.fn(), setEditorText: vi.fn(), copyText: vi.fn(async () => {}),
-    planMode: () => false, setPlanMode: vi.fn(),
+    plan: vi.fn(),
     hotkeys: () => 'Escape: interrupt', changelog: async () => 'Harness release notes',
     trajectory: {
       list: vi.fn(async () => [trajectoryRun]),
@@ -65,6 +65,18 @@ describe('owned terminal commands', () => {
     expect(new Set(names).size).toBe(names.length)
   })
 
+  it('runs one plan request from /plan <brief> and rejects toggle syntax', async () => {
+    const { commands, host, ui } = setup()
+    expect(await commands.execute('/plan inspect the current implementation')).toBe(true)
+    expect(host.plan).toHaveBeenCalledWith('inspect the current implementation')
+    expect(await commands.execute('/plan')).toBe(true)
+    expect(await commands.execute('/plan on')).toBe(true)
+    expect(await commands.execute('/plan toggle')).toBe(true)
+    expect(host.plan).toHaveBeenCalledOnce()
+    expect(ui.notify).toHaveBeenLastCalledWith('Use /plan <plan brief>.', 'error')
+    expect(commands.completions().find(item => item.name === 'plan')?.description).toContain('/plan <brief>')
+  })
+
   it('invokes a loaded skill as $name, and leaves other text for the SDK', () => {
     const { commands, session } = setup()
     expect(commands.skills()).toEqual([{ name: 'diagnose', description: 'Diagnose a problem' }])

package/src/terminal/tui/commands.ts

@@ -21,8 +21,7 @@ export interface TerminalCommandHost {
   sessionDirectory(): string
   refresh(): void
   changed(): void
-  planMode(): boolean
-  setPlanMode(enabled: boolean): void
+  plan(brief: string): void
   shutdown(): void
   setEditorText(text: string): void
   copyText(text: string): Promise<void>
@@ -41,7 +40,7 @@ export interface TerminalCommandCompletion { name: string; description?: string
 
 const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'help', description: 'Available terminal commands' },
-  { name: 'plan', description: 'Toggle read-only plan mode' },
+  { name: 'plan', description: 'Run one read-only plan request: /plan <brief>' },
   { name: 'new', description: 'Start a new session' },
   { name: 'resume', description: 'Resume a session in this account and folder' },
   { name: 'tree', description: 'Navigate the session tree' },
@@ -290,10 +289,8 @@ export function createTerminalCommands(host: TerminalCommandHost) {
       switch (name) {
         case 'help': notify(completions().map(item => `/${item.name}  ${item.description ?? ''}`).join('\n')); break
         case 'plan': {
-          const current = host.planMode()
-          const next = !argument || argument === 'toggle' ? !current : argument === 'on' ? true : argument === 'off' ? false : null
-          if (next === null) throw new Error('Use /plan, /plan on, /plan off, or /plan toggle.')
-          host.setPlanMode(next)
+          if (!argument || ['on', 'off', 'toggle'].includes(argument.toLowerCase())) throw new Error('Use /plan <plan brief>.')
+          host.plan(argument)
           break
         }
         case 'quit': host.shutdown(); break

package/src/terminal/tui/runtime.ts

@@ -7,7 +7,8 @@ import {
 import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs'
 import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 
-import terminalExtension from '../piExtension'
+import terminalExtension, { type TerminalPlanRunState } from '../piExtension'
+import { planModeTools } from './planMode'
 import { claimTerminalControl, controlCall } from '../control'
 import { loadPiAdapter } from './piAdapter'
 import type { SessionAccount } from '../accountsMenu'
@@ -101,6 +102,7 @@ export interface TerminalRuntime {
   answerBatch(batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): Promise<void>
   snapshot(): TerminalSnapshot
   submit(text: string, followUp?: boolean): Promise<void>
+  submitPlan(text: string): Promise<void>
   readonly session: AgentSession
   readonly services: AgentSessionServices
   readonly cwd: string
@@ -200,6 +202,7 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
     const generation = uiGeneration
     return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration)
   }
+  const planRun: TerminalPlanRunState = { active: false, allowedTools: new Set() }
 
   const factory: CreateAgentSessionRuntimeFactory = async ({ cwd: targetCwd, sessionManager, sessionStartEvent }) => {
     if (realpathSync(targetCwd) !== cwd) throw new Error('A native session cannot change this terminal working folder.')
@@ -213,7 +216,7 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
       additionalExtensionPaths: prepared.extensions.slice(0, -1),
       additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
       additionalThemePaths: prepared.themes,
-      extensionFactories: [...adapter.builtins, { name: 'harness-terminal-bridge', factory: terminalExtension, hidden: true }],
+      extensionFactories: [...adapter.builtins, { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun), hidden: true }],
       appendSystemPromptOverride: (base) => [...base, ...prepared.appendSystemPrompt]
     })
     const reloadResources = resourceLoader.reload.bind(resourceLoader)
@@ -309,6 +312,25 @@ export async function createTerminalRuntime(args: string[], host: TerminalRuntim
       const input = text.trimStart().startsWith('/') ? text.trimStart() : text
       await native.session.prompt(input, native.session.isStreaming ? { streamingBehavior: followUp ? 'followUp' : 'steer' } : {})
     },
+    async submitPlan(text) {
+      if (disposed) throw new Error('The terminal runtime has closed.')
+      if (changing) throw new Error('Wait for the native session change to finish before submitting.')
+      if (!text.trim()) throw new Error('Use /plan <plan brief>.')
+      const session = native.session
+      if (!session.isIdle) throw new Error('A plan request must wait until the current response settles.')
+      const originalTools = session.getActiveToolNames()
+      const allowedTools = planModeTools(originalTools)
+      planRun.allowedTools = new Set(allowedTools)
+      planRun.active = true
+      try {
+        session.setActiveToolsByName(allowedTools)
+        await session.prompt(text, { expandPromptTemplates: false })
+      } finally {
+        planRun.active = false
+        planRun.allowedTools = new Set()
+        if (!disposed && native.session === session) session.setActiveToolsByName(originalTools)
+      }
+    },
     get session() { return native.session },
     get services() { return native.services },
     cwd, sessionDirectory,