@xingular/harness 2.0.0 → 2.1.0

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -59,10 +59,12 @@ recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async d
 receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
 terminal socket, private controls, native execution and child decision routing. RPC and App host
 regressions cover protocol shapes and ancestry. Tests use disposable storage without external
-model requests. These are working-tree changes, not a publication or live-provider acceptance claim.
+model requests. These changes shipped in `@xingular/harness` 2.0.0 (commit `44471bc`); release does not imply live-provider acceptance.
 
 Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
 build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
 and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
 pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
 user-data-root testing was performed.
+
+Release verification on 2026-10-18: npm 10 clean install, typecheck, 515 tests (two skipped), build and standalone proof passed. GitHub CI passed on Ubuntu and macOS, and the npm publish workflow released version 2.0.0 with provenance. No live provider requests were made during release verification.

package/docs/terminal-tui.md

@@ -87,16 +87,22 @@ The decision and its consequences are recorded in
 
 ## Plan mode and thinking keys
 
-Shift+Tab switches the terminal 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`),
+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.
 
-The model is not yet told about the mode through the prompt; it only sees the narrower tool set. That
-instruction belongs in the prompt compiler, the one place model instructions are built. Shift+Up and
-Shift+Down step the thinking level within the levels the model supports, and do not wrap.
+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.
 
 ## Reference and reproduced presentation
 
@@ -302,9 +308,9 @@ The [live report and capture](evidence/terminal-2026-10-17-followup/live-codex/R
 this quota failure explicitly. Successful live streaming/tool acceptance remains open until
 account capacity is available. GitHub gist publication, actual OS clipboard/image transfer,
 Windows behavior and every terminal emulator remain unverified. Rich image/diff rendering and clipboard adapters have
-focused compatibility tests; that does not establish OS interaction. These working-tree changes
-are not a published release and the complete plan's acceptance remains open while required
-integration/provider evidence is outstanding.
+focused compatibility tests; that does not establish OS interaction. These changes shipped in
+`@xingular/harness` 2.0.0 (commit `44471bc`), while the complete plan's acceptance remains
+open pending the required integration and provider evidence.
 
 To reproduce the controlled scenario after building:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "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/hub/hub.test.ts

@@ -40,6 +40,8 @@ describe('Hub installation', () => {
     expect(existsSync(join(root, 'config', 'plugin-attachments.json'))).toBe(false)
     writeFileSync(join(root, 'hub', 'documents', receipt.document!), '{"edited":true}')
     expect(() => hub.readDocument('example/review', '1.0.0')).toThrow('differs')
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'changed' })
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('Uninstall it before installing')
   })
   it('imports complete skills disabled and refuses overwriting local files', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
@@ -90,12 +92,58 @@ describe('Hub installation', () => {
     expect(preview.delivery.kind !== 'pi-package' && preview.delivery.bundled).toContain('data only')
     expect(existsSync(join(root, 'hub'))).toBe(false)
   })
+  it('returns bounded UTF-8-safe preview pages and reuses the verified download for install', async () => {
+    const content = `"${'é'.repeat(20_000)}"`
+    const item = entry('document', content)
+    if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const fetcher = vi.fn(async () => new Response(content)) as typeof fetch
+    const { hub, root } = fixture([item], fetcher)
+    const pages = []
+    let offset = 0
+    while (true) {
+      const page = await hub.preview(item.id, item.version, offset)
+      expect(Buffer.byteLength(page.content)).toBeLessThanOrEqual(16 * 1024)
+      pages.push(page.content)
+      if (page.done) break
+      offset = page.nextOffset
+    }
+    expect(pages.join('')).toBe(content)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    await hub.install(item.id, item.version)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    expect(existsSync(join(root, 'hub', 'documents'))).toBe(true)
+  })
+  it('uninstalls only its receipt-owned document, including local edits', async () => {
+    const first = entry()
+    const second = { ...entry(), id: 'example/second', title: 'Second' }
+    const { hub, root } = fixture([first, second])
+    const owned = await hub.install(first.id, first.version)
+    const other = await hub.install(second.id, second.version)
+    writeFileSync(join(root, 'hub', 'documents', owned.document!), '{"local":true}')
+    await hub.uninstall(first.id, first.version)
+    expect(existsSync(join(root, 'hub', 'documents', owned.document!))).toBe(false)
+    expect(existsSync(join(root, 'hub', 'documents', other.document!))).toBe(true)
+    expect((await hub.list()).installed.map((receipt) => receipt.entry.id)).toEqual([second.id])
+  })
+  it('uninstalls only receipt-owned registry resources and leaves unrelated files', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    const receipt = await hub.install('example/review', '1.0.0')
+    const unrelated = join(root, 'registry', 'skills', 'unrelated', 'SKILL.md')
+    mkdirSync(join(root, 'registry', 'skills', 'unrelated'), { recursive: true })
+    writeFileSync(unrelated, '---\nname: unrelated\ndescription: Local.\n---\n')
+    await hub.uninstall('example/review', '1.0.0')
+    expect(existsSync(join(root, 'registry', 'skills', 'review'))).toBe(false)
+    expect(readFileSync(unrelated, 'utf8')).toContain('unrelated')
+    expect((await hub.list()).installed).toEqual([])
+    expect(receipt.resourceIds).toEqual(['skills/review'])
+  })
   it('can reinstall deleted resources and clears stale attachment grants', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
     await hub.install('example/review', '1.0.0')
     registry.setEnabled(root, null, ['skills/review'])
     rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
-    expect((await hub.list()).installed).toEqual([])
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'incomplete' })
+    await hub.uninstall('example/review', '1.0.0')
     await hub.install('example/review', '1.0.0')
     expect(registry.enabledFor(root, null)).toEqual([])
     expect((await hub.list()).installed).toHaveLength(1)

package/src/hub/hub.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { watch } from 'node:fs'
 
@@ -12,7 +12,7 @@ import * as registry from '../skills/registry'
 import * as attachments from '../plugins/attachments'
 import { version as harnessVersion } from '../../package.json'
 import bundled from './catalog.json'
-import { HUB_CATALOG_URL, HUB_MAX_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, HUB_PREVIEW_PAGE_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
 
 export interface HubOptions {
   catalogUrl?: string
@@ -60,6 +60,7 @@ export class Hub {
   private watcher: ReturnType<typeof watch> | null = null
   private refresh: Promise<HubOverview> | null = null
   private installing = false
+  private cachedPayload: { key: string; bytes: Buffer; expiresAt: number } | null = null
   get busy(): boolean { return this.installing }
 
   constructor(private readonly harness: Harness, options: HubOptions = {}) {
@@ -80,12 +81,25 @@ export class Hub {
     const cached = readJsonOr<{ catalog: unknown; at: string } | null>(join(this.harness.stateDir, 'hub', 'catalog.json'), null)
     const parsed = hubCatalogSchema.safeParse(cached?.catalog)
     const catalog = parsed.success ? parsed.data : this.fallback
-    const installed = this.receipts().filter((receipt) => this.present(receipt))
+    const installed = this.receipts().map((receipt) => ({ ...receipt, state: this.receiptState(receipt) }))
     const entries = new Map(catalog.entries.map((entry) => [`${entry.id}@${entry.version}`, entry]))
     for (const receipt of installed) if (!entries.has(`${receipt.entry.id}@${receipt.entry.version}`)) entries.set(`${receipt.entry.id}@${receipt.entry.version}`, receipt.entry)
     return { entries: [...entries.values()], installed, origin: parsed.success ? 'cached' : 'bundled', refreshedAt: parsed.success ? cached!.at : null, error: null, dataRoot: this.harness.dataRoot, stateDir: this.harness.stateDir }
   }
 
+  private receiptState(receipt: HubReceipt): 'installed' | 'changed' | 'incomplete' {
+    if (receipt.document && receipt.entry.delivery.kind === 'document') {
+      if (receipt.document !== `${receiptName(receipt.entry)}.json`) return 'incomplete'
+      try {
+        const path = join(this.harness.dataRoot!, 'hub', 'documents', receipt.document)
+        const stat = lstatSync(path)
+        if (!stat.isFile() || stat.size > HUB_MAX_BYTES) return 'incomplete'
+        return digest(readFileSync(path)) === receipt.entry.delivery.sha256 ? 'installed' : 'changed'
+      } catch { return 'incomplete' }
+    }
+    return this.present(receipt) ? 'installed' : 'incomplete'
+  }
+
   private present(receipt: HubReceipt): boolean {
     const root = this.harness.dataRoot
     if (!root) return false
@@ -169,6 +183,28 @@ export class Hub {
     return { ...entry, delivery: { ...entry.delivery, bundled: this.decode(bytes) } }
   }
 
+  private async verifiedPayload(entry: HubEntry): Promise<Buffer> {
+    if (entry.delivery.kind === 'pi-package') throw invalid('Packages do not have a JSON payload preview.')
+    const key = `${entry.id}@${entry.version}`
+    if (this.cachedPayload?.key === key && this.cachedPayload.expiresAt > Date.now()) return this.cachedPayload.bytes
+    const bytes = entry.delivery.bundled === undefined ? await this.bytes(entry.delivery.url) : Buffer.from(entry.delivery.bundled)
+    if (digest(bytes) !== entry.delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+    this.decode(bytes)
+    this.cachedPayload = { key, bytes, expiresAt: Date.now() + 5 * 60 * 1000 }
+    return bytes
+  }
+
+  async preview(id: string, version: string, offset = 0) {
+    if (!Number.isSafeInteger(offset) || offset < 0) throw invalid('Preview offset must be a non-negative byte position.')
+    const entry = this.find(id, version)
+    const bytes = await this.verifiedPayload(entry)
+    if (offset > bytes.length || offset < bytes.length && (bytes[offset] & 0xc0) === 0x80) throw invalid('Preview offset is outside the payload or splits a UTF-8 character.')
+    let end = Math.min(offset + HUB_PREVIEW_PAGE_BYTES, bytes.length)
+    while (end > offset && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end -= 1
+    const content = this.decode(bytes.subarray(offset, end))
+    return { entry, content, offset, nextOffset: end, totalBytes: bytes.length, done: end >= bytes.length }
+  }
+
   async install(id: string, version: string): Promise<HubReceipt> {
     const root = this.harness.env.root
     const entry = hubEntrySchema.parse(this.find(id, version))
@@ -181,6 +217,7 @@ export class Hub {
       const records = this.receipts()
       const existing = records.find((receipt) => receipt.entry.id === id && receipt.entry.version === version)
       if (existing && this.present(existing)) return existing
+      if (existing) throw invalid('This Hub receipt is changed or incomplete. Uninstall it before installing this version again.')
       const remaining = records.filter((record) => record !== existing)
       const receipt: HubReceipt = { entry, installedAt: now(), resourceIds: [], document: null }
       const choicesBefore = attachments.load(root)
@@ -195,13 +232,14 @@ export class Hub {
         if (!receipt.resourceIds.length) throw invalid('The package did not add an installable plugin. No hub installation was recorded.')
       } else {
         const delivery = entry.delivery
-        const bytes = delivery.bundled === undefined ? await this.bytes(delivery.url) : Buffer.from(delivery.bundled)
-        if (digest(bytes) !== delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+        const bytes = await this.verifiedPayload(entry)
         const text = this.decode(bytes)
         if (delivery.kind === 'document') {
           JSON.parse(text)
           receipt.document = `${receiptName(entry)}.json`
-          atomicWrite(join(root, 'hub', 'documents', receipt.document), bytes)
+          const documentPath = join(root, 'hub', 'documents', receipt.document)
+          try { lstatSync(documentPath); throw invalid('A file already exists at the Hub document path. Review or remove it before installing.') } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          atomicWrite(documentPath, bytes)
         } else {
           const payload = JSON.parse(text)
           const previous = new Set(registry.list(root).map((item) => item.id))
@@ -232,6 +270,84 @@ export class Hub {
     } finally { this.installing = false; releaseData?.(); releaseState() }
   }
 
+  async uninstall(id: string, version: string): Promise<HubReceipt> {
+    const root = this.harness.env.root
+    const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'))
+    this.installing = true
+    let releaseData: (() => void) | null = null
+    try {
+      releaseData = acquire(join(root, 'hub', 'install.lock'))
+      const records = this.receipts()
+      const receipt = records.find((item) => item.entry.id === id && item.entry.version === version)
+      if (!receipt) throw invalid('This Hub installation receipt no longer exists.')
+      const staged = mkdtempSync(join(root, 'hub', '.uninstall-'))
+      const moves: Array<{ source: string; staged: string }> = []
+      let choicesBefore: ReturnType<typeof attachments.load> | null = null
+      let committed = false
+      let rollbackComplete = true
+      try {
+        const ownedPaths: string[] = []
+        if (receipt.document) {
+          if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('The Hub receipt has an invalid document path.')
+          const path = join(root, 'hub', 'documents', receipt.document)
+          try {
+            const stat = lstatSync(path)
+            if (!stat.isFile()) throw invalid('The receipt-owned document path is not a regular file; it was left untouched.')
+            ownedPaths.push(path)
+          } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+        }
+        if (receipt.entry.delivery.kind === 'registry') {
+          const expectedKind = receipt.entry.delivery.registryKind
+          for (const id of receipt.resourceIds) {
+            if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id)) throw invalid('The Hub receipt contains an invalid registry resource path.')
+            const [kind, name] = id.split('/')
+            if (kind !== expectedKind) throw invalid('The Hub receipt contains a resource outside its registry kind.')
+            const path = join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`)
+            try { lstatSync(path); ownedPaths.push(path) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          }
+          choicesBefore = attachments.load(root)
+          const choices = structuredClone(choicesBefore)
+          const owned = new Set(receipt.resourceIds)
+          for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((value) => !owned.has(value))
+            scope.off = scope.off.filter((value) => !owned.has(value))
+          }
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+          attachments.save(root, choices)
+        } else {
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+        }
+        if (receipt.entry.delivery.kind === 'pi-package') for (const pluginId of receipt.resourceIds) await packages.remove(this.harness, { pluginId })
+        writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt))
+        committed = true
+        try { rmSync(staged, { recursive: true, force: true }) } catch { /* The receipt is removed; leave the staged copy for disk recovery. */ }
+        this.cachedPayload = this.cachedPayload?.key === `${id}@${version}` ? null : this.cachedPayload
+        this.harness.bus.emit({ type: 'hub.changed' })
+        this.harness.bus.emit({ type: 'plugins.changed' })
+        return receipt
+      } catch (error) {
+        if (!committed) {
+          if (choicesBefore) try { attachments.save(root, choicesBefore) } catch { /* Preserve the original failure and restore the owned files below. */ }
+          for (const move of moves.reverse()) {
+            try { lstatSync(move.staged); renameSync(move.staged, move.source) } catch { rollbackComplete = false }
+          }
+          if (rollbackComplete) try { rmSync(staged, { recursive: true, force: true }) } catch { /* Keep the staging directory for recovery. */ }
+        }
+        throw error
+      }
+    } finally { this.installing = false; releaseData?.(); releaseState() }
+  }
+
   readDocument(id: string, version: string): { entry: HubEntry; content: string } {
     const receipt = this.receipts().find((item) => item.entry.id === id && item.entry.version === version)
     if (!receipt?.document || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('Install this document before opening it.')

package/src/hub/schema.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 
 export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
 export const HUB_MAX_BYTES = 16 * 1024 * 1024
+export const HUB_PREVIEW_PAGE_BYTES = 16 * 1024
 
 const httpsUrl = z.string().max(2000).url().refine((value) => {
   const url = new URL(value)
@@ -53,7 +54,17 @@ export const hubReceiptSchema = z.object({
   entry: hubEntrySchema,
   installedAt: z.string(),
   resourceIds: z.array(z.string()),
-  document: z.string().nullable()
+  document: z.string().nullable(),
+  state: z.enum(['installed', 'changed', 'incomplete']).optional()
+}).strict()
+
+export const hubPreviewPageSchema = z.object({
+  entry: hubEntrySchema,
+  content: z.string(),
+  offset: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative(),
+  totalBytes: z.number().int().nonnegative(),
+  done: z.boolean()
 }).strict()
 
 export const hubOverviewSchema = z.object({
@@ -69,6 +80,7 @@ export const hubOverviewSchema = z.object({
 export type HubEntry = z.infer<typeof hubEntrySchema>
 export type HubCatalog = z.infer<typeof hubCatalogSchema>
 export type HubReceipt = z.infer<typeof hubReceiptSchema>
+export type HubPreviewPage = z.infer<typeof hubPreviewPageSchema>
 export type HubOverview = z.infer<typeof hubOverviewSchema>
 
 export function meetsMinimum(actual: string, minimum: string): boolean {

package/src/server/methods.ts

@@ -83,6 +83,8 @@ export function methods(harness: Harness): Record<string, Handler> {
     'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
     'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
     'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+    'hub.preview': (params: Params) => harness.hub.preview(text(params, 'id'), text(params, 'version'), typeof params.offset === 'number' ? params.offset : 0),
+    'hub.uninstall': (params: Params) => harness.hub.uninstall(text(params, 'id'), text(params, 'version')),
     'hub.readDocument': (params: Params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version')),
 
     // ---- Accounts --------------------------------------------------------------------------------

package/src/sessions/planMode.test.ts

@@ -0,0 +1,40 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from '../prompt/compile'
+import { PLAN_INSTRUCTIONS, PLAN_SECTION_ID, planModeTools, planRefusal, planSection } from './planMode'
+
+function history(sectionIds: string[]): string {
+  const file = join(mkdtempSync(join(tmpdir(), 'plan-history-')), 'session.jsonl')
+  const snapshot = sectionIds.map((id) => ({ id, title: id, body: 'x', sources: [], budget: 100, size: 1, cut: false }))
+  writeFileSync(file, [
+    JSON.stringify({ type: 'session', id: 'session' }),
+    JSON.stringify({ type: 'custom_message', id: 'c1', parentId: null, customType: CONTEXT_MESSAGE_TYPE, details: { [CONTEXT_SNAPSHOT_KEY]: snapshot } })
+  ].join('\n'))
+  return file
+}
+
+describe('plan mode', () => {
+  it('keeps read-only inspection, questions and recall, plus provider tools marked read-only', () => {
+    const normal = ['read', 'bash', 'edit', 'write', 'grep', 'ask_user', 'wiki_search', 'memory_append', 'spawn_subagent', 'files_read', 'files_write', 'skill_load']
+    expect(planModeTools(normal, ['files_read'])).toEqual(['read', 'grep', 'ask_user', 'wiki_search', 'files_read', 'skill_load'])
+  })
+
+  it('refuses changes, commands, memory writes and delegation with a reason the model can act on', () => {
+    const readOnly = new Set(['files_read'])
+    for (const tool of ['read', 'grep', 'wiki_read', 'files_read', 'ask_user']) expect(planRefusal(tool, readOnly), tool).toBeNull()
+    for (const tool of ['bash', 'write', 'edit', 'memory_append', 'wiki_propose', 'spawn_subagent', 'mcp_call_tool', 'files_write']) {
+      expect(planRefusal(tool, readOnly), tool).toContain('Plan mode is read-only')
+    }
+  })
+
+  it('adds its instructions while on, withdraws them once after, and is absent otherwise', () => {
+    expect(planSection(true, null)).toMatchObject({ id: PLAN_SECTION_ID, body: PLAN_INSTRUCTIONS, dynamic: true })
+    expect(PLAN_INSTRUCTIONS).toContain('<proposed_plan>')
+    expect(planSection(false, null)).toBeNull()
+    expect(planSection(false, history(['blocks']))).toBeNull()
+    expect(planSection(false, history(['blocks', PLAN_SECTION_ID]))).toMatchObject({ id: PLAN_SECTION_ID, body: null, dynamic: true })
+  })
+})

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/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, type TerminalCommandHost } from './commands'
 import type { TerminalDecision } from './runtime'
 import { terminalKeybindings } from './keybindings'
 import { autocompleteRuleColor, createHarnessTheme } from './theme'
@@ -22,7 +23,9 @@ 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> }
+    commands: ReturnType<typeof createTerminalCommands> | { execute: ReturnType<typeof vi.fn> }
+    planMode: boolean
+    setPlanMode(enabled: boolean): void
     masthead: { render(width: number): string[] }
     header?: { render(width: number): string[]; invalidate(): void }
     branch: string | null
@@ -234,15 +237,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('toggles plan mode with /plan, narrowing to read-only tools', 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 })
+    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']
+    })
+    app.mountEditor()
+    app.submit('/plan')
+    await vi.waitFor(() => expect(setActiveToolsByName).toHaveBeenCalledWith(['read', 'grep']))
     expect(setActiveToolsByName).toHaveBeenLastCalledWith(['read', 'grep'])
-    expect(app.dispatchInput('\x1b[Z')).toEqual({ consume: true })
+    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()
     await application.shutdown()