@xingular/harness 2.0.0 → 2.1.1

package/src/sessions/planMode.ts

@@ -0,0 +1,57 @@
+// Plan mode: a run that may only look, ask and recall, and ends with a proposed plan. The tool list
+// the model sees is unchanged, so switching the mode does not change the cached prompt prefix; the
+// gate refuses everything else, and the instruction arrives as a context update.
+import { deliveredSnapshot, type HostSection } from '../prompt/compile'
+import { ASK_USER } from '../tools/askUser'
+
+/**
+ * Read-only inspection, questions and recall. Everything else is refused in plan mode: file
+ * changes, commands, memory writes, delegation and connected apps, since none of them can be
+ * judged read-only from their names. A provider marks its own read-only tools with `readOnly`.
+ */
+export const PLAN_READ_ONLY_TOOLS: ReadonlySet<string> = 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'
+])
+
+export const PLAN_SECTION_ID = 'plan'
+/** Between the application's role and the memory blocks. */
+export const PLAN_SECTION_ORDER = 25
+export const PLAN_OPEN_TAG = '<proposed_plan>'
+export const PLAN_CLOSE_TAG = '</proposed_plan>'
+
+export const 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.`
+
+/** The tools a plan-mode run may call: the read-only set and the provider tools marked read-only. */
+export function planModeTools(normal: readonly string[], readOnly: Iterable<string> = []): string[] {
+  const allowed = new Set([...PLAN_READ_ONLY_TOOLS, ...readOnly])
+  return normal.filter((name) => allowed.has(name))
+}
+
+/** Why a plan-mode run may not call this tool, or null when it may. */
+export function planRefusal(tool: string, readOnly: ReadonlySet<string>): string | null {
+  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.`
+}
+
+/**
+ * The plan section for this request. While plan mode is on it carries the instructions; on the
+ * first request after it, the empty slot withdraws the earlier instructions from the conversation.
+ * Otherwise there is no section, so a conversation that never planned is delivered exactly as before.
+ */
+export function planSection(plan: boolean, historyFile: string | null): HostSection | null {
+  if (plan) return { id: PLAN_SECTION_ID, title: 'Plan mode', body: PLAN_INSTRUCTIONS, budget: 2000, order: PLAN_SECTION_ORDER, dynamic: true }
+  const delivered = historyFile ? deliveredSnapshot(historyFile) : null
+  return delivered?.some((entry) => entry.id === PLAN_SECTION_ID)
+    ? { id: PLAN_SECTION_ID, title: 'Plan mode', body: null, budget: 2000, order: PLAN_SECTION_ORDER, dynamic: true }
+    : null
+}

package/src/sessions/sessions.test.ts

@@ -400,6 +400,29 @@ describe('session turns on Pi', () => {
     expect(contexts).toEqual([policyContext])
   })
 
+  it('refuses non-read-only calls in plan mode and delivers its instructions without changing the system prompt', async () => {
+    const seen: { system: string; update: string | null; reasons: (string | null)[] }[] = []
+    const { run, harness } = setup(async ({ gate, params }) => fakeSession(async () => {
+      const reasons = [await gate.check('bash', {}), await gate.check('write', {}), await gate.check('memory_append', {}), await gate.check('lookup', {}), await gate.check('change', {})]
+      seen.push({ system: params.system, update: params.update?.content ?? null, reasons })
+    }, gate))
+    harness.approvals.setAuto('chat', true)
+    harness.sessions.provide(() => [
+      { name: 'lookup', label: 'Lookup', description: 'Reads', readOnly: true, parameters: (Type) => Type.Object({}), execute: async () => 'ok' },
+      { name: 'change', label: 'Change', description: 'Writes', parameters: (Type) => Type.Object({}), execute: async () => 'ok' }
+    ])
+    await run('plan-run', { plan: true, tools: { allow: ['read', 'bash', 'write', 'lookup', 'change'] } })
+    await tick()
+    await run('normal-run', { tools: { allow: ['read', 'bash', 'write', 'lookup', 'change'] } })
+    await tick()
+    const [planned, normal] = seen
+    expect(planned.reasons.map((reason) => reason?.startsWith('Plan mode is read-only') ?? null)).toEqual([true, true, true, null, true])
+    expect(normal.reasons).toEqual([null, null, null, null, null])
+    expect(planned.system).toBe(normal.system)
+    expect(planned.update).toContain('<proposed_plan>')
+    expect(normal.update ?? '').not.toContain('Plan mode is on')
+  })
+
   it('aborts the Pi session on interrupt', async () => {
     let session: (PiSessionLike & { aborted: boolean }) | null = null
     const { events, run, harness } = setup(async ({ gate }) => (session = fakeSession(() => new Promise((resolve) => setTimeout(resolve, 50)), gate)))

package/src/sessions/sessions.ts

@@ -34,6 +34,7 @@ import type { ToolPolicy } from './policy'
 import type { ActiveRun, RunRegistry } from './registry'
 import { piSessionFactory, runTurn, summarize, type Effort, type PiSessionLike, type SessionFactory, type ToolGate, type TurnParams } from './runner'
 import { loadRun, runDir, saveRun, updateRun } from './runStore'
+import { planRefusal, planSection } from './planMode'
 
 /** The fields of a run record the caller decides; the harness fills in the rest. */
 export type RunFields = Pick<RunRecord, 'id' | 'sessionId'> & Partial<Pick<RunRecord, 'mode' | 'harness' | 'sessionType' | 'projectId' | 'agentId' | 'trigger' | 'goal' | 'attachmentCount' | 'resumedFromRunId' | 'parentRunId' | 'relation' | 'worktreeId' | 'handoffId'>>
@@ -73,6 +74,11 @@ export interface SessionRunInput {
   subagents?: SubagentOptions | null
   /** Ask the application's tool providers for tools (the default). False runs with the harness's own tools only. */
   providers?: boolean
+  /**
+   * Plan mode: the run may only read, search, recall and ask, and is told to end with a
+   * `<proposed_plan>` block. Other calls are refused at the gate; the tool list is unchanged.
+   */
+  plan?: boolean
 }
 
 /** The connected-apps broker, as a session sees it. */
@@ -240,8 +246,10 @@ export class Sessions {
     try {
       if (!existsSync(input.sessionDir)) mkdirSync(input.sessionDir, { recursive: true })
       const launch = input.launch ?? {}
+      const plan = planSection(input.plan === true, historyFile)
       const effectiveLaunch = {
         ...launch,
+        sections: plan ? [...(launch.sections ?? []).filter((section) => section.id !== plan.id), plan] : launch.sections,
         tools: capabilities.tools,
         connectionTools: (launch.connectionTools ?? []).filter((name) => capabilities.tools.includes(name)),
         toolGroups: launch.toolGroups?.map((group) => ({ ...group, tools: group.tools.filter((name) => capabilities.tools.includes(name)) })).filter((group) => group.tools.length > 0)
@@ -269,6 +277,7 @@ export class Sessions {
         ...subagentTools(this.options.subagents, runId).filter(tool => allow.includes(tool.name))
       ]
       if (input.providers !== false) for (const provider of this.providers) tools.push(...(await provider(session)))
+      const readOnly = new Set(tools.filter((tool) => tool.readOnly).map((tool) => tool.name))
       const params: TurnParams = {
         runId,
         restrictTools: input.run.relation === 'subagent',
@@ -294,7 +303,14 @@ export class Sessions {
         allow,
         gate: (() => {
           const gate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))))
-          return { ...gate, check: (name: string, args: unknown) => input.run.relation === 'subagent' && !capabilities.tools.includes(name) ? Promise.resolve('This tool is outside the child capability snapshot.') : gate.check(name, args) }
+          return {
+            ...gate,
+            check: (name: string, args: unknown) => {
+              if (input.run.relation === 'subagent' && !capabilities.tools.includes(name)) return Promise.resolve('This tool is outside the child capability snapshot.')
+              const refusal = input.plan ? planRefusal(name, readOnly) : null
+              return refusal ? Promise.resolve(refusal) : gate.check(name, args)
+            }
+          }
         })(),
         tools,
         runtime: () => this.options.accounts.runtime(context),

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,6 +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 } from './commands'
 import type { TerminalDecision } from './runtime'
 import { terminalKeybindings } from './keybindings'
 import { autocompleteRuleColor, createHarnessTheme } from './theme'
@@ -21,8 +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: { execute: ReturnType<typeof vi.fn> }
+    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
@@ -49,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: {
@@ -223,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')
@@ -234,17 +235,33 @@ describe('the owned terminal application', () => {
     await application.shutdown()
   })
 
-  it('toggles plan mode on Shift+Tab, narrowing to read-only tools and leaving thinking alone', 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 })
-    expect(app.dispatchInput('\x1b[Z')).toEqual({ consume: true })
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'grep'])
-    expect(app.dispatchInput('\x1b[Z')).toEqual({ consume: true })
-    expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'bash', 'edit', 'write', 'grep', 'spawn_subagent'])
-    expect(cycleThinkingLevel).not.toHaveBeenCalled()
+    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.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,6 +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) },
+        plan: brief => this.enqueuePlan(brief),
         copyText: copyToClipboard, openExternal,
         changed: this.change,
         trajectory: {
@@ -201,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)
@@ -306,19 +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 togglePlanMode(): void {
-    if (!this.runtime) 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 = !this.planMode
-    this.notify(this.planMode ? 'Plan mode: only read-only tools are available. Shift+Tab returns 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 }> {
@@ -395,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) : []
@@ -425,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 }
     })
   }
@@ -446,7 +485,6 @@ export class TerminalApplication {
       else void this.shutdown()
     } else if (is('app.exit') && this.editor.getText() === '') void this.shutdown()
     else if (is('app.thinking.cycle')) this.session.cycleThinkingLevel()
-    else if (is('app.plan.toggle')) this.togglePlanMode()
     else if (is('app.thinking.increase') || is('app.thinking.decrease')) this.stepThinking(is('app.thinking.increase') ? 1 : -1)
     else if (is('app.thinking.save')) this.session.setThinkingLevel(this.session.thinkingLevel, { persist: true })
     else if (is('app.model.cycleForward') || is('app.model.cycleBackward')) this.attempt(() => this.session.cycleModel(is('app.model.cycleBackward') ? 'backward' : 'forward'))
@@ -454,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())
@@ -497,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') }
@@ -513,12 +559,20 @@ export class TerminalApplication {
       const text = typeof message.content === 'string' ? message.content : message.content.filter(part => part.type === 'text').map(part => part.text).join('\n')
       if (text) this.editor.addToHistory?.(text)
     }
-    this.baseAutocomplete = skillCompletions(new CombinedAutocompleteProvider(this.commands.completions(), this.runtime.cwd), this.commands.skills)
+    const commands = this.commands.completions()
+    if (this.editor instanceof HarnessEditor) {
+      this.editor.setValidCommands([
+        ...commands.map(command => command.name),
+        ...this.commands.skills().map(skill => 'skill:' + skill.name)
+      ])
+    }
+    this.baseAutocomplete = skillCompletions(new CombinedAutocompleteProvider(commands, this.runtime.cwd), this.commands.skills)
     this.editor.setAutocompleteProvider?.(this.ui.wrapAutocomplete(this.baseAutocomplete))
     this.change()
   }
   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,6 +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 () => {}),
+    plan: vi.fn(),
     hotkeys: () => 'Escape: interrupt', changelog: async () => 'Harness release notes',
     trajectory: {
       list: vi.fn(async () => [trajectoryRun]),
@@ -64,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,6 +21,7 @@ export interface TerminalCommandHost {
   sessionDirectory(): string
   refresh(): void
   changed(): void
+  plan(brief: string): void
   shutdown(): void
   setEditorText(text: string): void
   copyText(text: string): Promise<void>
@@ -39,6 +40,7 @@ export interface TerminalCommandCompletion { name: string; description?: string
 
 const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'help', description: 'Available terminal commands' },
+  { 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' },
@@ -286,6 +288,11 @@ export function createTerminalCommands(host: TerminalCommandHost) {
       const session = host.session()
       switch (name) {
         case 'help': notify(completions().map(item => `/${item.name}  ${item.description ?? ''}`).join('\n')); break
+        case 'plan': {
+          if (!argument || ['on', 'off', 'toggle'].includes(argument.toLowerCase())) throw new Error('Use /plan <plan brief>.')
+          host.plan(argument)
+          break
+        }
         case 'quit': host.shutdown(); break
         case 'new': await host.runtime().newSession(); break
         case 'resume': {

package/src/terminal/tui/editor.ts

@@ -15,6 +15,12 @@ export const COMPOSER_SUGGESTIONS = [
   'write a test for the next change'
 ]
 
+function leadingSlashCommand(text: string, validCommands: ReadonlySet<string>): string | null {
+  const match = /^\s*\/([^\s/]+)(?=\s|$)/u.exec(text)
+  if (!match || !validCommands.has(match[1]!)) return null
+  return '/' + match[1]
+}
+
 export interface ComposerView {
   band(width: number, hiddenAbove: number, hiddenBelow: number): string
   theme(): Theme
@@ -27,11 +33,17 @@ export class HarnessEditor extends CustomEditor {
   private contentRows = 1
   private completionRows = 0
   private gutterWidth = 2
+  private validCommands = new Set<string>()
 
   constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, private readonly view: ComposerView) {
     super(tui, theme, keybindings, { paddingX: 0 })
   }
 
+  setValidCommands(commands: readonly string[]): void {
+    this.validCommands = new Set(commands)
+    this.tui.requestRender()
+  }
+
   override setPaddingX(_padding: number): void {
     super.setPaddingX(0)
   }
@@ -58,10 +70,13 @@ export class HarnessEditor extends CustomEditor {
     this.contentRows = content.length
     const theme = this.view.theme()
     const placeholder = this.getText() === '' ? this.view.placeholder() : undefined
+    const command = leadingSlashCommand(this.getText(), this.validCommands)
+    const commandLine = command ? content.findIndex(line => line.includes(command)) : -1
     const prompt = content.map((line, index) => {
       const cue = theme.fg('dim', index === 0 ? '❯ '.slice(0, this.gutterWidth) : ' '.repeat(this.gutterWidth))
       if (index === 0 && placeholder) return cue + this.placeholderRow(placeholder, innerWidth, theme)
-      return cue + line
+      const renderedLine = index === commandLine && command ? line.replace(command, theme.fg('mdLink', command)) : line
+      return cue + renderedLine
     })
     const completions = rows.slice(bottom + 1).map((line) => ' '.repeat(this.gutterWidth) + line)
     this.completionRows = completions.length

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

@@ -4,11 +4,10 @@ import { join } from 'node:path'
 import { expect, it } from 'vitest'
 import { terminalKeybindings } from './keybindings'
 
-it('steps thinking effort on shift arrows and gives shift+tab to plan mode', () => {
+it('steps thinking effort on shift arrows', () => {
   const manager = terminalKeybindings('/unused/isolated-account')
   expect(manager.matches('\x1b[1;2A', 'app.thinking.increase')).toBe(true)
   expect(manager.matches('\x1b[1;2B', 'app.thinking.decrease')).toBe(true)
-  expect(manager.matches('\x1b[Z', 'app.plan.toggle')).toBe(true)
   expect(manager.matches('\x1b[Z', 'app.thinking.cycle')).toBe(false)
 })
 

package/src/terminal/tui/keybindings.ts

@@ -7,7 +7,6 @@ declare module '@earendil-works/pi-tui' {
   interface Keybindings {
     'app.thinking.increase': true
     'app.thinking.decrease': true
-    'app.plan.toggle': true
   }
 }
 
@@ -15,7 +14,7 @@ declare module '@earendil-works/pi-tui' {
 const actions: Record<string, string | string[]> = {
   'app.interrupt': 'escape', 'app.clear': 'ctrl+c', 'app.exit': 'ctrl+d',
   'app.suspend': process.platform === 'win32' ? [] : 'ctrl+z',
-  'app.thinking.cycle': [], 'app.thinking.save': 'ctrl+s', 'app.plan.toggle': 'shift+tab',
+  'app.thinking.cycle': [], 'app.thinking.save': 'ctrl+s',
   'app.thinking.increase': 'shift+up', 'app.thinking.decrease': 'shift+down',
   'app.model.cycleForward': 'ctrl+p', 'app.model.cycleBackward': 'alt+p',
   'app.model.select': 'ctrl+l', 'app.tools.expand': 'ctrl+o', 'app.thinking.toggle': 'ctrl+t',