@xingular/harness 0.1.7 → 2.0.0

package/src/terminal/tui/commands.ts

@@ -5,17 +5,22 @@ import { isAbsolute, join, relative, resolve } from 'node:path'
 import { promisify } from 'node:util'
 import { ModelSelectorComponent, TreeSelectorComponent, SessionManager, type AgentSession, type ExtensionUIContext } from '@earendil-works/pi-coding-agent'
 import { SettingsPanel, type TerminalSettingItem } from './settings'
+import { DialogPanel, SearchableSelect } from './dialogs'
+import { TrajectoryPanel } from './trajectoryPanel'
+import { expandSkillInvocation, type SkillEntry } from './skillInvocation'
 import manifest from '../../../package.json'
 import type { TerminalRuntime } from './runtime'
+import type { TerminalTrajectoryRun, TerminalTrajectorySnapshot } from '../trajectory'
 
 export interface TerminalCommandHost {
   session(): AgentSession
   /** Navigation is scope checked by the Harness runtime adapter. */
-  runtime(): Pick<TerminalRuntime, 'newSession' | 'switchSession' | 'fork' | 'importFromJsonl' | 'reload' | 'navigateTree' | 'installationDeviceId'>
+  runtime(): Pick<TerminalRuntime, 'newSession' | 'switchSession' | 'fork' | 'importFromJsonl' | 'reload' | 'navigateTree' | 'installationDeviceId' | 'permissions' | 'setFullPermission' | 'setGlobalTool'>
   ui: ExtensionUIContext
   cwd(): string
   sessionDirectory(): string
   refresh(): void
+  changed(): void
   shutdown(): void
   setEditorText(text: string): void
   copyText(text: string): Promise<void>
@@ -24,6 +29,10 @@ export interface TerminalCommandHost {
   suspend?(): Promise<void>
   hotkeys?(): string
   changelog?(): Promise<string>
+  trajectory: {
+    list(): Promise<TerminalTrajectoryRun[]>
+    read(runId: string, afterSequence?: number): Promise<TerminalTrajectorySnapshot>
+  }
 }
 
 export interface TerminalCommandCompletion { name: string; description?: string }
@@ -35,12 +44,14 @@ const BUILTINS: TerminalCommandCompletion[] = [
   { name: 'tree', description: 'Navigate the session tree' },
   { name: 'fork', description: 'Fork from a user message' },
   { name: 'model', description: 'Choose a model' },
-  { name: 'thinking', description: 'Choose thinking effort' },
+  { name: 'effort', description: 'Choose thinking effort' },
   { name: 'clone', description: 'Clone the current branch to a new session' },
   { name: 'scoped-models', description: 'Choose models for cycling' },
   { name: 'settings', description: 'Session and terminal settings' },
+  { name: 'permissions', description: 'Review and change terminal approval permissions' },
   { name: 'name', description: 'Name the current session' },
   { name: 'session', description: 'Current session statistics' },
+  { name: 'trajectory', description: 'Inspect recorded runs for this native session' },
   { name: 'compact', description: 'Compact the current context' },
   { name: 'reload', description: 'Reload trusted resources and keyboard bindings' },
   { name: 'trust', description: 'Review plugin code and project trust' },
@@ -72,11 +83,16 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     for (const prompt of session.resourceLoader.getPrompts().prompts) {
       if (!commands.has(prompt.name)) commands.set(prompt.name, { name: prompt.name, description: prompt.description })
     }
-    if (session.settingsManager.getEnableSkillCommands()) {
-      for (const skill of session.resourceLoader.getSkills().skills) commands.set(`skill:${skill.name}`, { name: `skill:${skill.name}`, description: skill.description })
-    }
     return [...commands.values()]
   }
+  /** The skills this session may be asked to use, each invoked as `$name`. Off with the "Skill commands" setting. */
+  const skills = (): SkillEntry[] => {
+    const session = host.session()
+    if (!session.settingsManager.getEnableSkillCommands()) return []
+    return session.resourceLoader.getSkills().skills.map((skill) => ({ name: skill.name, description: skill.description }))
+  }
+  /** The text to send: a leading `$name` of a loaded skill becomes the `/skill:name` form Pi expands. */
+  const expandSkill = (text: string): string => expandSkillInvocation(text, new Set(skills().map((skill) => skill.name)))
 
   async function settings() {
     const session = host.session()
@@ -192,6 +208,68 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     } finally { await rm(directory, { recursive: true, force: true }) }
   }
 
+  async function trajectory(runId: string) {
+    const runs = await host.trajectory.list()
+    if (!runs.length) { notify('No runs recorded for this native session yet'); return }
+    const initialIndex = runId ? runs.findIndex(run => run.id === runId) : 0
+    if (initialIndex < 0) throw new Error('Run not found in this native session')
+    const initial = await host.trajectory.read(runs[initialIndex]!.id)
+    await host.ui.custom<void>((tui, theme, _keys, done) => {
+      const content = new TrajectoryPanel({
+        tui, theme, runs, initialIndex, initial,
+        read: host.trajectory.read,
+        copy: host.copyText,
+        close: () => done(undefined),
+        changed: host.changed,
+        notify: (message, type) => host.ui.notify(message, type === 'error' || type === 'warning' ? type : 'info')
+      })
+      const dialog = new DialogPanel('Trajectory', content, () => theme, '←/→ runs · ↑/↓ events · PgUp/PgDn details · C copy · Esc close')
+      return Object.assign(dialog, { dispose: () => content.dispose() })
+    }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '90%' } })
+  }
+
+  async function permissions() {
+    for (;;) {
+      const runtime = host.runtime()
+      const state = await runtime.permissions()
+      const activeTools = host.session().getActiveToolNames()
+      const granted = new Set(state.globalTools)
+      const toolNames = [...new Set([...activeTools, ...granted])].sort((a, b) => a.localeCompare(b))
+      const entries = [
+        { id: 'full', label: `Full Permission: ${state.full ? 'on' : 'off'}` },
+        ...toolNames.map(tool => ({ id: `tool:${tool}`, label: `${tool}: allow everywhere ${granted.has(tool) ? 'on' : 'off'}` })),
+        { id: 'done', label: 'Done' }
+      ]
+      const description = [
+        'Permissions apply to future Pi terminal approvals using this local Harness state.',
+        'A tool grant allows every call with that tool name, regardless of its arguments.',
+        'Full Permission approves every eligible future request. Hard denials and disabled tools still apply; human-only requests stay manual unless the host explicitly opts them in.',
+        'Existing pending requests are never approved by changing these settings.'
+      ].join('\n')
+      const selected = await host.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+        const list = new SearchableSelect(entries.map(entry => entry.label), tui, () => theme,
+          index => done(entries[index]?.id), () => done(undefined))
+        return new DialogPanel('Permissions', list, () => theme, 'Enter change · Type to search · Esc close', description)
+      }, { overlay: true, overlayOptions: { width: '100%', maxHeight: '90%' } })
+      if (!selected || selected === 'done') return
+      if (selected === 'full') {
+        const desired = !state.full
+        const latest = await runtime.permissions()
+        if (latest.full !== desired) {
+          if (!desired || await host.ui.confirm('Enable Full Permission?', 'Automatically approve eligible future requests in every Pi terminal session sharing this local Harness state. Hard denials and disabled tools still apply; human-only requests stay manual unless the host explicitly opts them in.')) {
+            await runtime.setFullPermission(desired)
+          }
+        }
+        continue
+      }
+      const tool = selected.slice('tool:'.length)
+      if (!tool) continue
+      const desired = !granted.has(tool)
+      const latest = await runtime.permissions()
+      if (latest.globalTools.includes(tool) !== desired) await runtime.setGlobalTool(tool, desired)
+    }
+  }
+
   async function execute(text: string): Promise<boolean> {
     const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(text.trim())
     if (!match) return false
@@ -199,6 +277,8 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     const argument = match[2]?.trim() ?? ''
     if (!BUILTINS.some(item => item.name === name)) {
       if (completions().some(item => item.name === name)) return false
+      // A skill is offered as $name; the typed /skill:name form still reaches the SDK, which expands it.
+      if (skills().some(skill => `skill:${skill.name}` === name)) return false
       host.ui.notify(`Unknown command: /${name}. Use /help to list commands.`, 'error')
       return true
     }
@@ -256,7 +336,7 @@ export function createTerminalCommands(host: TerminalCommandHost) {
           }
           break
         }
-        case 'thinking': {
+        case 'effort': {
           const levels = session.getAvailableThinkingLevels()
           const level = argument || await host.ui.select('Thinking effort', levels)
           if (!level) break
@@ -292,12 +372,14 @@ export function createTerminalCommands(host: TerminalCommandHost) {
           break
         }
         case 'settings': await settings(); break
+        case 'permissions': await permissions(); break
         case 'name': {
           const name = argument || await host.ui.input('Session name', session.sessionName)
           if (name !== undefined) session.setSessionName(name)
           break
         }
         case 'session': notify(JSON.stringify(session.getSessionStats(), null, 2)); break
+        case 'trajectory': await trajectory(argument); break
         case 'compact': await session.compact(argument || undefined); break
         case 'reload': await host.runtime().reload(); notify('Trusted resources reloaded'); break
         case 'trust': {
@@ -357,5 +439,5 @@ export function createTerminalCommands(host: TerminalCommandHost) {
     } catch (error) { host.ui.notify(error instanceof Error ? error.message : String(error), 'error') }
     return true
   }
-  return { execute, completions }
+  return { execute, completions, skills, expandSkill }
 }

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

@@ -1,50 +1,65 @@
 import { getSelectListTheme, initTheme, type KeybindingsManager, Theme } from '@earendil-works/pi-coding-agent'
-import { CURSOR_MARKER, KeybindingsManager as TuiKeybindingsManager, stripTerminalSequences, type TUI, TUI_KEYBINDINGS, visibleWidth } from '@earendil-works/pi-tui'
+import { CURSOR_MARKER, KeybindingsManager as TuiKeybindingsManager, renderFakeCursor, stripTerminalSequences, type TUI, type TuiMouseEvent, TUI_KEYBINDINGS, visibleWidth } from '@earendil-works/pi-tui'
 import { describe, expect, it } from 'vitest'
 
-import { HarnessEditor } from './editor'
+import { COMPOSER_SUGGESTIONS, type ComposerView, HarnessEditor } from './editor'
 import { createHarnessTheme } from './theme'
 
 initTheme('dark', false)
 const theme = createHarnessTheme({ getColorMode: () => 'truecolor' } as Theme)
-function setup() {
+const bandText = (width: number) => '[band]'.padEnd(width)
+function setup(view: Partial<ComposerView> = {}) {
   const editor = new HarnessEditor({ terminal: { rows: 30 }, requestRender() {} } as unknown as TUI,
     { borderColor: (text) => text, selectList: getSelectListTheme() }, new TuiKeybindingsManager(TUI_KEYBINDINGS) as KeybindingsManager, {
-      band: (width, above, below) => `${above}:${below}`.padEnd(width, '─'),
-      theme: () => theme, showHint: () => true, thinkingKey: '⇧⇥'
+      band: (width) => bandText(width),
+      theme: () => theme, placeholder: () => undefined, ...view
     })
   editor.focused = true
   return editor
 }
 
-describe('band composer over the native Pi editor', () => {
-  it('uses exactly a band and a curved prompt row, preserving the real cursor beside the hint', () => {
+describe('Claude-style composer frame over the native Pi editor', () => {
+  it('frames the prompt between two full-width rules, with the band below', () => {
     const editor = setup()
-    const rows = editor.render(80)
-    expect(rows).toHaveLength(2)
-    expect(stripTerminalSequences(rows[1])).toMatch(/^╰─ .*⇧⇥ to change thinking effort$/)
+    const rows = editor.render(40)
+    expect(rows).toHaveLength(4)
+    expect(stripTerminalSequences(rows[0])).toBe('─'.repeat(40))
+    expect(rows[0]).toContain('38;2;136;136;136')
+    expect(stripTerminalSequences(rows[1])).toMatch(/^❯ /)
     expect(rows[1]).toContain(CURSOR_MARKER)
-    expect(rows.every((row) => visibleWidth(row) <= 80)).toBe(true)
+    expect(stripTerminalSequences(rows[2])).toBe('─'.repeat(40))
+    expect(stripTerminalSequences(rows[3]).trimEnd()).toBe('[band]')
+    expect(rows.every((row) => visibleWidth(row) <= 40)).toBe(true)
     expect(editor.getText()).toBe('')
   })
 
-  it('closes the fake cursor before the hint, so the rest of the row is not reverse video', () => {
-    const editor = setup()
-    // Mirrors pi-tui's resolveFakeCursors: the cursor opens reverse video and its end marker closes it.
-    const resolved = editor.render(80)[1].replace(/\x1b_pi:fc\x07/g, '\x1b[7m').replace(/\x1b_pi:\/fc\x07/g, '\x1b[27m')
-    const reverseOn = resolved.indexOf('\x1b[7m')
-    const reverseOff = resolved.indexOf('\x1b[27m')
-    expect(reverseOn).toBeGreaterThan(-1)
-    expect(reverseOff).toBeGreaterThan(reverseOn)
-    expect(reverseOff).toBeLessThan(resolved.indexOf('⇧⇥'))
+  it('shows the suggestion as a fake cursor on its first character, only while focused', () => {
+    const editor = setup({ placeholder: () => COMPOSER_SUGGESTIONS[0] })
+    const rows = editor.render(60)
+    expect(stripTerminalSequences(rows[1])).toContain('Try "fix the failing test"')
+    expect(rows[1]).toContain(CURSOR_MARKER + renderFakeCursor('T'))
+    editor.focused = false
+    const idle = editor.render(60)[1]
+    expect(idle).not.toContain(CURSOR_MARKER)
+    expect(stripTerminalSequences(idle)).toContain('Try "fix the failing test"')
+  })
+
+  it('drops the suggestion as soon as there is a draft', () => {
+    const editor = setup({ placeholder: () => 'fix the failing test' })
+    editor.handleInput('h')
+    const rows = editor.render(60)
+    expect(editor.getText()).toBe('h')
+    expect(stripTerminalSequences(rows[1])).toMatch(/^❯ h/)
+    expect(stripTerminalSequences(rows[1])).not.toContain('Try')
   })
 
-  it('closes the cursor cell so the hint is not painted in reverse video', () => {
+  it('does not render a shortcuts or thinking hint row', () => {
     const editor = setup()
-    // Why: pi-tui paints its fake cursor as reverse video when it resolves a frame.
-    const prompt = editor.render(80)[1].replace(/\x1b_pi:fc\x07/g, '\x1b[7m').replace(/\x1b_pi:\/fc\x07/g, '\x1b[27m')
-    expect(prompt.split('\x1b[7m')).toHaveLength(prompt.split('\x1b[27m').length)
-    expect(prompt.indexOf('to change')).toBeGreaterThan(prompt.lastIndexOf('\x1b[27m'))
+    const rows = editor.render(80).map(stripTerminalSequences)
+    expect(rows.join('\n')).not.toContain('? for shortcuts')
+    expect(rows.join('\n')).not.toContain('to change thinking effort')
+    editor.handleInput('x')
+    expect(editor.render(80).map(stripTerminalSequences).join('\n')).not.toContain('to clear')
   })
 
   it('preserves editing, multiline wrapping, history, and cursor markers across resizes', () => {
@@ -67,7 +82,7 @@ describe('band composer over the native Pi editor', () => {
     expect(editor.getText()).toBe('previous prompt')
   })
 
-  it('retains autocomplete rows and selection without mistaking them for the removed bottom border', async () => {
+  it('lists autocomplete above the composer with matching orange dividers and accepts a selection', async () => {
     const editor = setup()
     editor.setAutocompleteProvider({
       getSuggestions: async () => ({ items: [{ value: '/accounts', label: '/accounts' }, { value: '/plugins', label: '/plugins' }], prefix: '/' }),
@@ -76,9 +91,23 @@ describe('band composer over the native Pi editor', () => {
     editor.handleInput('/')
     await new Promise((resolve) => setTimeout(resolve, 30))
     const rows = editor.render(50)
-    expect(rows.some((row) => stripTerminalSequences(row).includes('/accounts'))).toBe(true)
+    const band = rows.findIndex((row) => stripTerminalSequences(row).startsWith('[band]'))
+    const completion = rows.findIndex((row) => stripTerminalSequences(row).includes('/accounts'))
+    const composerDivider = rows.findIndex((row, index) => index > completion && stripTerminalSequences(row) === '─'.repeat(50))
+    expect(rows[0]).toContain('38;2;255;179;71')
+    expect(rows[composerDivider]).toContain('38;2;136;136;136')
+    expect(completion).toBeGreaterThan(0)
+    expect(composerDivider).toBeGreaterThan(completion)
+    expect(band).toBeGreaterThan(composerDivider)
     expect(rows.every((row) => visibleWidth(row) <= 50)).toBe(true)
     editor.handleInput('\t')
     expect(editor.getText()).toContain('/accounts')
   })
+
+  it('does not hand the band row to the editor as its own', () => {
+    const editor = setup()
+    editor.render(40)
+    const at = (y: number) => ({ x: 5, y, width: 40, height: 5 }) as TuiMouseEvent
+    expect(editor.handleMouse(at(3))).toBeUndefined()
+  })
 })

package/src/terminal/tui/editor.ts

@@ -1,21 +1,32 @@
 // Harness owns composer geometry and actions; Pi provides the editing primitive.
 import { CustomEditor, type KeybindingsManager, type Theme } from '@earendil-works/pi-coding-agent'
-import { CURSOR_MARKER, type EditorTheme, type TUI, type TuiMouseEvent, sliceByColumn, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
+import { CURSOR_MARKER, type EditorTheme, type TUI, type TuiMouseEvent, parseColor, renderFakeCursor, truncateToWidth } from '@earendil-works/pi-tui'
+
+import { autocompleteRuleColor, composerRuleColor } from './theme'
 
 const BOTTOM = '\u0000harness-composer-bottom'
 
+// Generic on purpose: the placeholder names no file, project or product.
+export const COMPOSER_SUGGESTIONS = [
+  'fix the failing test',
+  'explain how this project is laid out',
+  'find where the configuration is loaded',
+  'summarize what changed since the last commit',
+  'write a test for the next change'
+]
+
 export interface ComposerView {
   band(width: number, hiddenAbove: number, hiddenBelow: number): string
   theme(): Theme
-  showHint(): boolean
-  thinkingKey: string
+  placeholder(): string | undefined
 }
 
 export class HarnessEditor extends CustomEditor {
   private hiddenAbove = 0
   private hiddenBelow = 0
   private contentRows = 1
-  private gutterWidth = 3
+  private completionRows = 0
+  private gutterWidth = 2
 
   constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, private readonly view: ComposerView) {
     super(tui, theme, keybindings, { paddingX: 0 })
@@ -37,7 +48,7 @@ export class HarnessEditor extends CustomEditor {
 
   override render(width: number): string[] {
     if (width < 1) return []
-    this.gutterWidth = Math.min(3, Math.max(0, width - 1))
+    this.gutterWidth = Math.min(2, Math.max(0, width - 1))
     const innerWidth = Math.max(1, width - this.gutterWidth)
     // Pi 1.2 cannot lay out a two-cell grapheme in a one-cell text area.
     // Lay out safely, then clip the presentation without changing the draft.
@@ -46,33 +57,52 @@ export class HarnessEditor extends CustomEditor {
     const content = rows.slice(1, bottom)
     this.contentRows = content.length
     const theme = this.view.theme()
+    const placeholder = this.getText() === '' ? this.view.placeholder() : undefined
     const prompt = content.map((line, index) => {
-      const cue = index === 0 ? '╰─ '.slice(0, this.gutterWidth) : ' '.repeat(this.gutterWidth)
-      let text = line
-      if (index === 0 && this.getText() === '' && this.view.showHint()) {
-        const hint = theme.fg('accent', this.view.thinkingKey) + ' ' + theme.italic(theme.fg('dim', 'to change thinking effort'))
-        // Why: a one-cell slice cuts off the fake cursor's closing marker, so pi-tui
-        // paints the rest of the row in reverse video. Two cells keep the marker.
-        const prefix = sliceByColumn(line, 0, 2)
-        const gap = innerWidth - visibleWidth(prefix) - visibleWidth(hint)
-        if (gap >= 1) text = prefix + ' '.repeat(gap) + hint
-      }
-      return theme.fg('borderMuted', cue) + text
+      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 completions = rows.slice(bottom + 1).map((line) => ' '.repeat(this.gutterWidth) + line)
-    const result = [this.view.band(width, this.hiddenAbove, this.hiddenBelow), ...prompt, ...completions].map((line) => truncateToWidth(line, width, ''))
+    this.completionRows = completions.length
+    const completionDivider = completions.length > 0 ? [this.rule(width, theme, autocompleteRuleColor(theme))] : []
+    const result = [
+      ...completionDivider, ...completions,
+      this.rule(width, theme), ...prompt, this.rule(width, theme), this.view.band(width, this.hiddenAbove, this.hiddenBelow)
+    ].map((line) => truncateToWidth(line, width, ''))
     if (this.focused && !result.some((line) => line.includes(CURSOR_MARKER))) {
-      const index = Math.max(1, Math.min(result.length - 1, prompt.length))
+      const composerOffset = completions.length > 0 ? completions.length + 1 : 0
+      const index = composerOffset + Math.max(1, Math.min(result.length - composerOffset - 1, prompt.length))
       result[index] = truncateToWidth(result[index], Math.max(0, width - 1), '') + CURSOR_MARKER + ' '
     }
     return result
   }
 
+  private rule(width: number, theme: Theme, color = composerRuleColor(theme)): string {
+    return theme.style('─'.repeat(width), { fg: parseColor(color) })
+  }
+
+  private placeholderRow(suggestion: string, innerWidth: number, theme: Theme): string {
+    const text = truncateToWidth(`Try "${suggestion}"`, innerWidth, '')
+    if (!this.focused) return theme.fg('dim', text)
+    // The first character is the fake cursor, so an empty prompt reads as the caret it will type into.
+    const [first = '', ...rest] = Array.from(text)
+    return CURSOR_MARKER + renderFakeCursor(first) + theme.fg('dim', rest.join(''))
+  }
+
   override handleMouse(event: TuiMouseEvent) {
+    // Pi sees its own rows; the suggestion divider and status band are presentation rows.
+    const composerOffset = this.completionRows > 0 ? this.completionRows + 1 : 0
+    const band = composerOffset + this.contentRows + 2
+    if (event.y === band) return undefined
+    if (this.completionRows > 0 && event.y === 0) return undefined
+    const y = this.completionRows > 0 && event.y <= this.completionRows
+      ? this.contentRows + 1 + event.y
+      : event.y - composerOffset
     return super.handleMouse({
       ...event,
       x: event.x - this.gutterWidth,
-      y: event.y > this.contentRows ? event.y + 1 : event.y,
+      y,
       width: Math.max(1, event.width - this.gutterWidth)
     })
   }

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

@@ -4,6 +4,14 @@ 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', () => {
+  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)
+})
+
 it('reloads edited isolated keybindings on the existing public manager', () => {
   const root = mkdtempSync(join(tmpdir(), 'harness-keybindings-'))
   try {

package/src/terminal/tui/keybindings.ts

@@ -3,11 +3,20 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { KeybindingsManager, TUI_KEYBINDINGS, type KeybindingDefinitions, type KeybindingsConfig } from '@earendil-works/pi-tui'
 
+declare module '@earendil-works/pi-tui' {
+  interface Keybindings {
+    'app.thinking.increase': true
+    'app.thinking.decrease': true
+    'app.plan.toggle': true
+  }
+}
+
 // Harness owns application actions. Editing and selection retain Pi's reusable bindings.
 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': 'shift+tab', 'app.thinking.save': 'ctrl+s',
+  'app.thinking.cycle': [], 'app.thinking.save': 'ctrl+s', 'app.plan.toggle': 'shift+tab',
+  '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',
   'app.editor.external': 'ctrl+g', 'app.message.copy': 'ctrl+x',

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

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest'
+
+import { planModeTools } from './planMode'
+
+describe('plan mode tools', () => {
+  it('keeps read-only inspection, questions and recall, and withdraws changes, commands and delegation', () => {
+    const normal = ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'ask_user', 'ask_user_question', 'wiki_search', 'memory_append', 'spawn_subagent', 'app_tool', 'history_read']
+    expect(planModeTools(normal)).toEqual(['read', 'grep', 'find', 'ls', 'ask_user', 'ask_user_question', 'wiki_search', 'history_read'])
+  })
+})

package/src/terminal/tui/planMode.ts

@@ -0,0 +1,12 @@
+import { ASK_USER } from '../../tools/askUser'
+
+// Read-only inspection, questions and recall. Everything else is withdrawn in plan mode: file changes, commands,
+// memory writes, delegation and connected apps, since none of them can be judged read-only from their names.
+const READ_ONLY_TOOLS = new Set([
+  'read', 'grep', 'find', 'ls', ASK_USER, 'ask_user_question',
+  'history_search', 'history_read', 'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts'
+])
+
+export function planModeTools(normal: readonly string[]): string[] {
+  return normal.filter(name => READ_ONLY_TOOLS.has(name))
+}

package/src/terminal/tui/runtime.socket.test.ts

@@ -1,5 +1,5 @@
 import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
-import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -7,7 +7,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createHarness, type Harness } from '../../harness'
 import { memorySecretStore } from '../../accounts/secrets'
 import { connectionFromEnv, socketCall, terminalCall } from '../client'
+import type { TerminalPrepareInput } from '../terminals'
 import { controlCall } from '../control'
+import { readAllRuns } from '../../sessions/runIndex'
 import { createTerminalRuntime, type TerminalRuntime } from './runtime'
 
 const opened: Array<{ harness: Harness; runtime?: TerminalRuntime; root: string }> = []
@@ -21,7 +23,7 @@ afterEach(async () => {
   vi.unstubAllEnvs()
 })
 
-async function setup() {
+async function setup(input: Partial<TerminalPrepareInput> = {}) {
   const root = mkdtempSync(join(tmpdir(), 'harness-sdk-socket-'))
   const cwd = join(root, 'project')
   mkdirSync(cwd)
@@ -30,7 +32,7 @@ async function setup() {
   opened.push(entry)
   await harness.ready
   const account = harness.accounts.create('Offline test', 'apiKey').accounts[0]
-  const launch = await harness.terminals.prepare({ sessionId: 'offline-sdk', cwd, accountId: account.id, sessionFolder: join(root, 'history') })
+  const launch = await harness.terminals.prepare({ sessionId: 'offline-sdk', cwd, accountId: account.id, sessionFolder: join(root, 'history'), ...input })
   for (const [name, value] of Object.entries(launch.env)) vi.stubEnv(name, value === null ? undefined : value)
   vi.spyOn(process, 'cwd').mockReturnValue(cwd)
   const ui = { select: vi.fn(async () => undefined), confirm: vi.fn(async () => false), notify: vi.fn(), getEditorText: () => '' } as unknown as ExtensionUIContext
@@ -40,6 +42,78 @@ async function setup() {
 }
 
 describe('a native SDK runtime on the actual Harness terminal socket', () => {
+  it('reads and changes shared terminal permissions only through the claimed private control key', async () => {
+    const { runtime } = await setup()
+    await expect(socketCall(connectionFromEnv(), 'terminal.permissions.get')).rejects.toThrow('Only a person')
+    expect(await runtime.permissions()).toEqual({ full: false, globalTools: [] })
+    await runtime.setGlobalTool('bash', true)
+    await runtime.setFullPermission(true)
+    expect(await runtime.permissions()).toEqual({ full: true, globalTools: ['bash'] })
+    await runtime.setGlobalTool('bash', false)
+    await runtime.setFullPermission(false)
+    expect(await runtime.permissions()).toEqual({ full: false, globalTools: [] })
+  })
+
+  it('runs asynchronous children through the protected bridge and joins their results before settling', async () => {
+    const { harness, runtime } = await setup()
+    const ai = await import('@earendil-works/pi-ai')
+    const faux = ai.fauxProvider()
+    runtime.services.modelRuntime.registerNativeProvider(faux.provider)
+    harness.accounts.runtime = async () => runtime.services.modelRuntime
+    await runtime.session.setModel(faux.getModel())
+    const route = (context: { messages: Array<{ role: string; content: unknown }> }) => {
+      const users = context.messages.filter(message => message.role === 'user').map(message => typeof message.content === 'string' ? message.content : (message.content as Array<{ text?: string }>).map(part => part.text ?? '').join(''))
+      if (users.includes('terminal-native-child')) return ai.fauxAssistantMessage('TERMINAL_CHILD_EVIDENCE')
+      if (JSON.stringify(context.messages).includes('TERMINAL_CHILD_EVIDENCE')) return ai.fauxAssistantMessage('Final with TERMINAL_CHILD_EVIDENCE')
+      if (!context.messages.some(message => message.role === 'toolResult')) return ai.fauxAssistantMessage([ai.fauxToolCall('spawn_subagent', { brief: 'terminal-native-child' })], { stopReason: 'toolUse' })
+      return ai.fauxAssistantMessage('Draft before joining')
+    }
+    faux.setResponses(Array(8).fill(route) as never)
+    await expect(socketCall(connectionFromEnv(), 'terminal.subagents.tools')).rejects.toThrow('Only a person')
+    await runtime.session.prompt('Terminal parent')
+    const runs = readAllRuns(harness.env.root)
+    const parent = runs.find(run => run.sessionId === 'offline-sdk')!
+    const child = runs.find(run => run.relation === 'subagent')!
+    expect(parent.status).toBe('completed')
+    expect(child).toMatchObject({ parentRunId: parent.id, accountId: parent.accountId, status: 'completed' })
+    expect(harness.runs.activeRunIds()).toEqual([])
+    const entries = readFileSync(runtime.session.sessionFile!, 'utf8').trim().split('\n').map(line => JSON.parse(line))
+    const receipts = entries.filter(entry => entry.customType === 'xingular-subagent-results')
+    expect(receipts).toHaveLength(1)
+    expect(receipts[0].content).toContain('TERMINAL_CHILD_EVIDENCE')
+    expect(harness.terminals.state('offline-sdk').active).toBe(false)
+  })
+
+  it('routes a child approval to its original run through the terminal decision controls', async () => {
+    const { harness, runtime } = await setup()
+    await terminalCall('begin', { text: 'Parent fixture' })
+    await controlCall('terminal.subagents.register', { tools: ['read', 'bash', 'spawn_subagent', 'wait_subagents'], history: { owners: [], receipts: [] } })
+    const parentId = harness.runs.activeForSession('offline-sdk')!.runId
+    const { loadRun, saveRun } = await import('../../sessions/runStore')
+    const parent = loadRun(harness.env.root, parentId)
+    saveRun(harness.env.root, { ...parent, id: 'approval-child', sessionId: 'opaque-child', parentRunId: parentId, relation: 'subagent', status: 'queued', endedAt: null })
+    const active = harness.runs.start('opaque-child', 'approval-child')
+    const answer = active.requestApproval({ target: 'bash', action: 'fixture', rememberable: false })
+    let pending: Awaited<ReturnType<typeof runtime.pending>> = []
+    await vi.waitFor(async () => { pending = await runtime.pending(); expect(pending).toHaveLength(1) })
+    await runtime.approve(pending[0].requestId, 'denied')
+    await expect(answer).resolves.toBe('denied')
+    expect(await runtime.pending()).toEqual([])
+    active.finish('interrupted')
+  })
+
+  it('offers native tools without connected apps and preserves a read-only child ceiling', async () => {
+    const { harness, runtime } = await setup({ connections: false, readOnly: true })
+    expect(runtime.session.getToolDefinition('spawn_subagent')).toBeDefined()
+    await terminalCall('begin', { text: 'Read-only parent' })
+    await controlCall('terminal.subagents.register', { tools: ['read', 'write', 'bash', 'spawn_subagent', 'wait_subagents'], history: { owners: [], receipts: [] } })
+    const parentRunId = harness.runs.activeForSession('offline-sdk')!.runId
+    await expect(harness.subagents.spawn({ parentRunId, brief: 'Cannot widen', tools: ['write'] })).rejects.toThrow('cannot have tools')
+    const { loadRun } = await import('../../capabilities/runSnapshot')
+    expect(loadRun(harness.env.root, parentRunId)?.tools).toEqual(['read', 'spawn_subagent', 'wait_subagents'])
+    await runtime.interrupt()
+  })
+
   it('keeps the same account, command control and readiness after new/reload with no provider request', async () => {
     const { harness, runtime, ui } = await setup()
     expect(harness.terminals.state('offline-sdk')).toEqual({ ready: true, dirty: false, active: false })

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

@@ -187,6 +187,16 @@ describe('the persistent terminal SDK adapter', () => {
     expect(runtime.session.sessionFile).toBe(join(realpathSync(history), 'external.jsonl'))
   })
 
+  it('starts a new conversation when the recorded history file was never written', async () => {
+    // Pi writes a session file only after its first message, so a restart before that has nothing to resume.
+    const f = fixture()
+    const unwritten = join(f.history, 'not-written-yet.jsonl')
+    const runtime = await createTerminalRuntime([...f.args, '--session', unwritten], f.host)
+    runtimes.push(runtime)
+    expect(runtime.session.sessionFile?.startsWith(realpathSync(f.history))).toBe(true)
+    expect(runtime.session.sessionFile).not.toBe(unwritten)
+  })
+
   it('requires the prepared isolated account and refuses malformed session headers', async () => {
     const f = fixture()
     vi.stubEnv('PI_CODING_AGENT_DIR', '')