pi-code 1.0.3 → 1.0.5

package/extensions/memory.ts

@@ -15,6 +15,8 @@ import { StringEnum } from '@earendil-works/pi-ai'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Type } from 'typebox'
 import { capForContext } from './internal/output-guard.js'
+import { isProjectApprovedSilently } from './internal/project-approval.js'
+import { findNearestFile, repoRoot } from './internal/project-root.js'
 
 const INDEX_FILE = 'MEMORY.md'
 
@@ -45,21 +47,79 @@ function legacySlug(cwd: string): string {
     .replace(/^-+/, '-')
 }
 
+/** The project a memory store belongs to: the repository root, so subdirectory
+ * sessions share one store, matching Claude ("derived from the git repository, so
+ * all worktrees and subdirectories within the same repo share one auto memory
+ * directory. Outside a git repo, the project root is used instead."). Falls back
+ * to cwd when there is no project marker. */
+function memoryProject(cwd: string): string {
+  return repoRoot(cwd) ?? cwd
+}
+
 export function memoryDir(cwd: string): string {
-  return path.join(os.homedir(), '.pi', 'agent', 'memory', projectSlug(cwd))
+  return path.join(os.homedir(), '.pi', 'agent', 'memory', projectSlug(memoryProject(cwd)))
 }
 
-/** Move a store written under the pre-digest slug to the current one, once. Without
- * this the slug change would silently orphan every memory a user already has. */
+/** The store location, honoring an `autoMemoryDirectory` override. Claude requires
+ * it to be absolute or start with `~/`; a relative value is ignored, falling back
+ * to the default per-project directory. */
+export function resolveMemoryDir(cwd: string, override?: string): string {
+  const trimmed = override?.trim()
+  if (trimmed?.startsWith('~/')) return path.join(os.homedir(), trimmed.slice(2))
+  if (trimmed && path.isAbsolute(trimmed)) return trimmed
+  return memoryDir(cwd)
+}
+
+/** Whether auto memory runs: on by default, off when `CLAUDE_CODE_DISABLE_AUTO_MEMORY`
+ * is `1`/`true` or a settings scope sets `autoMemoryEnabled: false`. */
+export function autoMemoryEnabled(setting: unknown, env: NodeJS.ProcessEnv): boolean {
+  const disable = (env.CLAUDE_CODE_DISABLE_AUTO_MEMORY ?? '').trim().toLowerCase()
+  if (disable === '1' || disable === 'true') return false
+  return setting !== false
+}
+
+/** Set or replace the ISO 8601 `modified:` field inside a memory's YAML frontmatter.
+ * Files without frontmatter are returned untouched: Claude never adds frontmatter to
+ * a file that has none. */
+export function stampModified(content: string, iso: string): string {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)
+  if (!match) return content
+  const inner = match[1]
+  const rest = content.slice(match[0].length)
+  const withoutModified = inner
+    .split('\n')
+    .filter((line) => !/^\s*modified\s*:/.test(line))
+    .join('\n')
+  const body = withoutModified.length > 0 ? `${withoutModified}\n` : ''
+  return `---\n${body}modified: ${iso}\n---${rest}`
+}
+
+/** The index content that actually loads: YAML frontmatter and block-level HTML
+ * comments are stripped, so they neither show in the prompt nor count toward the
+ * 200-line / 25KB read limits, matching Claude Code. */
+export function stripNonLoaded(text: string): string {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').replace(/<!--[\s\S]*?-->\r?\n?/g, '')
+}
+
+/** Move a store written under an older slug to the current one, once. Two earlier
+ * formats can orphan a user's memories on upgrade: the released digest-of-cwd slug
+ * (before the store was anchored on the repository root, so a subdirectory session
+ * resolved to a different dir), and the pre-digest slug. Newest format first. */
 export function migrateLegacyStore(cwd: string): void {
   const current = memoryDir(cwd)
   if (fs.existsSync(current)) return
-  const legacy = path.join(os.homedir(), '.pi', 'agent', 'memory', legacySlug(cwd))
-  if (!fs.existsSync(legacy)) return
-  try {
-    fs.renameSync(legacy, current)
-  } catch {
-    // A failed migration must not take down session start; the store stays legacy.
+  const base = path.join(os.homedir(), '.pi', 'agent', 'memory')
+  // projectSlug(cwd) differs from current only for a subdirectory session (current is
+  // keyed on the repo root); for a repo-root session it equals current and is skipped.
+  const candidates = [path.join(base, projectSlug(cwd)), path.join(base, legacySlug(cwd))]
+  for (const legacy of candidates) {
+    if (legacy === current || !fs.existsSync(legacy)) continue
+    try {
+      fs.renameSync(legacy, current)
+    } catch {
+      // A failed migration must not take down session start; the store stays put.
+    }
+    return
   }
 }
 
@@ -73,12 +133,13 @@ export function indexWouldOverflow(index: string, name: string, description: str
   // since the injected index is capped at read time.
   const isUpdate = index.split('\n').some((entry) => entry.startsWith(entryPrefix(name)))
   if (isUpdate) return false
-  const next = upsertIndexLine(index, name, description)
+  // Only the loaded content counts: frontmatter and comments are stripped first.
+  const next = stripNonLoaded(upsertIndexLine(index, name, description))
   return next.split('\n').length > INDEX_MAX_LINES || Buffer.byteLength(next, 'utf-8') > INDEX_MAX_BYTES
 }
 
 /** Write a memory and its index line, or say why it cannot be written. */
-export function saveMemory(dir: string, indexPath: string, name: string | undefined, description: string | undefined, content: string | undefined): { content: Array<{ type: 'text'; text: string }>; details: Record<string, never> } {
+export function saveMemory(dir: string, indexPath: string, name: string | undefined, description: string | undefined, content: string | undefined, now: string = new Date().toISOString()): { content: Array<{ type: 'text'; text: string }>; details: Record<string, never> } {
   if (!name || !description || !content) {
     return { content: [{ type: 'text', text: 'save requires name, description, and content.' }], details: {} }
   }
@@ -92,22 +153,24 @@ export function saveMemory(dir: string, indexPath: string, name: string | undefi
     }
   }
   fs.mkdirSync(dir, { recursive: true })
-  fs.writeFileSync(path.join(dir, `${name}.md`), content)
-  fs.writeFileSync(indexPath, upsertIndexLine(index, name, description))
+  // A memory with frontmatter records its write time; one without is left as-is.
+  fs.writeFileSync(path.join(dir, `${name}.md`), stampModified(content, now))
+  writeIndex(indexPath, upsertIndexLine(index, name, description))
   return { content: [{ type: 'text', text: `Saved memory ${name}.` }], details: {} }
 }
 
 /** The index as injected into the prompt, bounded like Claude's startup load. */
 export function capIndexForPrompt(index: string): string {
-  const withinLines = index.split('\n').slice(0, INDEX_MAX_LINES)
-  let dropped = index.split('\n').length - withinLines.length
+  const loaded = stripNonLoaded(index)
+  const withinLines = loaded.split('\n').slice(0, INDEX_MAX_LINES)
+  let dropped = loaded.split('\n').length - withinLines.length
   let text = withinLines.join('\n')
   while (Buffer.byteLength(text, 'utf-8') > INDEX_MAX_BYTES && withinLines.length > 1) {
     withinLines.pop()
     dropped++
     text = withinLines.join('\n')
   }
-  if (dropped <= 0) return index
+  if (dropped <= 0) return loaded
   return `${text}\n(${dropped} more memories not shown; use the memory tool with action "list")`
 }
 
@@ -150,25 +213,89 @@ const MemoryParams = Type.Object({
 function readIndex(dir: string): string {
   try {
     return fs.readFileSync(path.join(dir, INDEX_FILE), 'utf-8')
+  } catch (error) {
+    // Only a missing file means an empty index. Treating any other failure as empty
+    // lets the next read-modify-write clobber every existing entry.
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+}
+
+/** For display paths, where a transiently unreadable index should not break the
+ * session; the mutating paths go through readIndex and refuse instead. */
+function readIndexQuietly(dir: string): string {
+  try {
+    return readIndex(dir)
   } catch {
     return ''
   }
 }
 
+/** Replace the index through a rename so a crash mid-write cannot truncate it. */
+function writeIndex(indexPath: string, content: string): void {
+  const tmp = `${indexPath}.${process.pid}.tmp`
+  fs.writeFileSync(tmp, content)
+  fs.renameSync(tmp, indexPath)
+}
+
+/** The settings chain that decides `autoMemoryEnabled` and `autoMemoryDirectory`:
+ * user settings always, then project settings (nearest at or above cwd) only when
+ * approved, since a project's `autoMemoryDirectory` is honored under the same trust
+ * rule as hooks in settings files. Later files win. */
+export function memorySettingsFiles(cwd: string, home: string, approved: boolean): string[] {
+  const files = [path.join(home, '.claude', 'settings.json')]
+  if (!approved) return files
+  for (const name of ['settings.json', 'settings.local.json']) {
+    files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
+  }
+  return files
+}
+
+/** Merge the two memory settings across the chain, later files winning per key. */
+export function readMemorySettings(files: string[]): { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } {
+  const merged: { autoMemoryEnabled?: unknown; autoMemoryDirectory?: unknown } = {}
+  for (const file of files) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      if (settings === null || typeof settings !== 'object') continue
+      if ('autoMemoryEnabled' in settings) merged.autoMemoryEnabled = settings.autoMemoryEnabled
+      if ('autoMemoryDirectory' in settings) merged.autoMemoryDirectory = settings.autoMemoryDirectory
+    } catch {
+      // missing or invalid settings file: skip
+    }
+  }
+  return merged
+}
+
 export default function memoryExtension(pi: ExtensionAPI) {
   let dir = memoryDir(process.cwd())
+  let enabled = true
+
+  // These extensions also load inside spawned subagent processes, which carry the
+  // PI_CODE_SUBAGENT marker. Claude does not load the main conversation's auto memory
+  // into subagents (they get their own store through the agent `memory:` field), so
+  // everything here no-ops there: no index injection, no notify, and the tool never
+  // touches the parent store. Read per call so tests can flip the env var.
+  const inSubagent = (): boolean => Boolean(process.env.PI_CODE_SUBAGENT)
 
   pi.on('session_start', async (_event, ctx) => {
+    if (inSubagent()) return
     migrateLegacyStore(ctx.cwd)
-    dir = memoryDir(ctx.cwd)
-    const count = readIndex(dir)
+    const approved = isProjectApprovedSilently(ctx)
+    const settings = readMemorySettings(memorySettingsFiles(ctx.cwd, os.homedir(), approved))
+    enabled = autoMemoryEnabled(settings.autoMemoryEnabled, process.env)
+    const override = typeof settings.autoMemoryDirectory === 'string' ? settings.autoMemoryDirectory : undefined
+    dir = enabled ? resolveMemoryDir(ctx.cwd, override) : memoryDir(ctx.cwd)
+    if (!enabled) return
+    const count = readIndexQuietly(dir)
       .split('\n')
       .filter((l) => l.startsWith('- ')).length
     if (count > 0) ctx.ui.notify(`Memory: ${count} memories loaded`, 'info')
   })
 
   pi.on('before_agent_start', async (event) => {
-    const index = readIndex(dir)
+    if (inSubagent() || !enabled) return
+    const index = readIndexQuietly(dir)
     if (!index.trim()) return
     return {
       systemPrompt: `${event.systemPrompt}\n\n## Memory\n\nPersistent memories from earlier sessions (index):\n\n${capIndexForPrompt(index)}\nUse the memory tool with action "read" to load a memory's full content when relevant.`,
@@ -181,11 +308,21 @@ export default function memoryExtension(pi: ExtensionAPI) {
     description: 'Persistent memory across sessions. Save durable facts, user preferences, corrections, and project decisions that are not derivable from the code. Actions: save (name + description + content), read (name), delete (name), list.',
     parameters: MemoryParams,
     async execute(_id, params) {
+      if (inSubagent()) {
+        return { content: [{ type: 'text' as const, text: 'The memory tool is unavailable in a subagent; auto memory belongs to the main conversation. Use your agent memory directory instead if one was provided.' }], details: {} }
+      }
+      if (!enabled) {
+        return { content: [{ type: 'text' as const, text: 'Auto memory is disabled (autoMemoryEnabled is false or CLAUDE_CODE_DISABLE_AUTO_MEMORY is set). No memory was read or written.' }], details: {} }
+      }
       const name = params.name ? slugifyName(params.name) : undefined
       const indexPath = path.join(dir, INDEX_FILE)
 
       if (params.action === 'save') {
-        return saveMemory(dir, indexPath, name, params.description, params.content)
+        try {
+          return saveMemory(dir, indexPath, name, params.description, params.content)
+        } catch (error) {
+          return { content: [{ type: 'text' as const, text: `Memory save failed: ${error instanceof Error ? error.message : String(error)}. The index was left untouched.` }], details: {} }
+        }
       }
 
       if (params.action === 'read') {
@@ -200,14 +337,22 @@ export default function memoryExtension(pi: ExtensionAPI) {
 
       if (params.action === 'delete') {
         if (!name) return { content: [{ type: 'text' as const, text: 'delete requires name.' }], details: {} }
+        // The index is read before anything is removed: refusing on a failed read
+        // must leave both the memory file and the index as they were.
+        let index: string
+        try {
+          index = readIndex(dir)
+        } catch (error) {
+          return { content: [{ type: 'text' as const, text: `Memory delete failed: ${error instanceof Error ? error.message : String(error)}. Nothing was deleted.` }], details: {} }
+        }
         fs.rmSync(path.join(dir, `${name}.md`), { force: true })
-        const remaining = removeIndexLine(readIndex(dir), name)
-        if (remaining) fs.writeFileSync(indexPath, remaining)
+        const remaining = removeIndexLine(index, name)
+        if (remaining) writeIndex(indexPath, remaining)
         else fs.rmSync(indexPath, { force: true })
         return { content: [{ type: 'text' as const, text: `Deleted memory ${name}.` }], details: {} }
       }
 
-      const index = readIndex(dir)
+      const index = readIndexQuietly(dir)
       return { content: [{ type: 'text' as const, text: index.trim() || 'No memories saved for this project yet.' }], details: {} }
     },
   })

package/extensions/notify.ts

@@ -6,10 +6,62 @@
  * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
  * - OSC 99: Kitty
  * - Windows toast: Windows Terminal (WSL)
+ *
+ * Honors Claude Code's `preferredNotifChannel` (user settings): `terminal_bell`
+ * rings the bell, `notifications_disabled` stays silent, `iterm2_with_bell` does
+ * both, anything else sends the desktop notification. Like Claude, a notification
+ * fires only when you "appear to be away": pi exposes no terminal-focus signal, so
+ * a turn is treated as away when it ran at least AWAY_AFTER_MS, or when no prompt
+ * was submitted since session start.
  */
 
+import { execFile } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+/** How a finished turn is announced, from Claude's `preferredNotifChannel`. */
+export type NotifChannel = 'desktop' | 'bell' | 'both' | 'off'
+
+/** Map Claude's `preferredNotifChannel` to what we emit. Unknown or unset means the
+ * default desktop notification; `iterm2_with_bell` both notifies and rings. */
+export function resolveNotifChannel(setting: unknown): NotifChannel {
+  switch (typeof setting === 'string' ? setting : '') {
+    case 'notifications_disabled':
+      return 'off'
+    case 'terminal_bell':
+      return 'bell'
+    case 'iterm2_with_bell':
+      return 'both'
+    default:
+      return 'desktop'
+  }
+}
+
+/** How long a turn must run before its end is worth a notification. Claude only
+ * notifies when you "appear to be away"; pi exposes no terminal-focus signal, so a
+ * turn that ran at least this long is the best available proxy for having stepped
+ * away. A turn with no recorded start (none since session start) always notifies. */
+export const AWAY_AFTER_MS = 30_000
+
+export function isAway(lastInputAt: number | undefined, now: number, thresholdMs: number): boolean {
+  if (lastInputAt === undefined) return true
+  return now - lastInputAt >= thresholdMs
+}
+
+/** The `preferredNotifChannel` from the user's settings. This is a personal terminal
+ * preference, so only user scope is read; a checked-out repo does not get to silence
+ * or change your notifications. */
+function readPreferredNotifChannel(home: string): unknown {
+  try {
+    const settings = JSON.parse(fs.readFileSync(path.join(home, '.claude', 'settings.json'), 'utf-8'))
+    return settings?.preferredNotifChannel
+  } catch {
+    return undefined
+  }
+}
+
 function windowsToastScript(title: string, body: string): string {
   const type = 'Windows.UI.Notifications'
   const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`
@@ -29,7 +81,6 @@ function notifyOSC99(title: string, body: string): void {
 }
 
 function notifyWindows(title: string, body: string): void {
-  const { execFile } = require('node:child_process')
   // Resolve powershell from a fixed system path rather than through PATH, and let the callback
   // capture a spawn failure instead of an unhandled 'error' event crashing the host.
   const root = process.env.SystemRoot ?? String.raw`C:\Windows`
@@ -37,9 +88,7 @@ function notifyWindows(title: string, body: string): void {
   execFile(powershell, ['-NoProfile', '-Command', windowsToastScript(title, body)], () => {})
 }
 
-function notify(title: string, body: string): void {
-  // Piped or headless stdout (pi -p, CI) must not receive raw escape bytes.
-  if (!process.stdout.isTTY) return
+function notifyDesktop(title: string, body: string): void {
   if (process.env.WT_SESSION) {
     notifyWindows(title, body)
   } else if (process.env.KITTY_WINDOW_ID) {
@@ -50,7 +99,31 @@ function notify(title: string, body: string): void {
 }
 
 export default function notifyExtension(pi: ExtensionAPI) {
+  let channel: NotifChannel = 'desktop'
+  // When the user last submitted a prompt, so a turn's duration can stand in for
+  // Claude's "appear to be away" check. Undefined until the first prompt this session.
+  let lastInputAt: number | undefined
+
+  pi.on('session_start', async (_event, ctx) => {
+    channel = resolveNotifChannel(readPreferredNotifChannel(os.homedir()))
+    lastInputAt = undefined
+    void ctx
+  })
+
+  pi.on('input', async () => {
+    lastInputAt = Date.now()
+  })
+
   pi.on('agent_end', async () => {
-    notify('Pi', 'Ready for input')
+    if (channel === 'off') return
+    // Piped or headless stdout (pi -p, CI) must not receive raw escape bytes.
+    if (!process.stdout.isTTY) return
+    if (!isAway(lastInputAt, Date.now(), AWAY_AFTER_MS)) return
+    if (channel === 'bell') {
+      process.stdout.write('\x07')
+      return
+    }
+    notifyDesktop('Pi', 'Ready for input')
+    if (channel === 'both') process.stdout.write('\x07')
   })
 }

package/extensions/output-styles.ts

@@ -2,7 +2,9 @@
  * Output Styles Extension
  *
  * Bridges Claude Code's output styles into pi. It discovers `.claude/output-styles/*.md`
- * (user then project), honors the active style recorded as `outputStyle` in
+ * (user then project) plus styles shipped by enabled plugins (manifest `outputStyles`,
+ * default `output-styles/`, ranked below the user's and project's own), honors the
+ * active style recorded as `outputStyle` in
  * `.claude/settings.json` (user, project, then settings.local.json, last wins),
  * and appends that style's body to the system prompt so the agent adopts its
  * tone and role. `/output-style` lists the styles and persists a choice to the
@@ -22,7 +24,9 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { installedPlugins } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
+import { findNearestDir, findNearestFile } from './internal/project-root.js'
 
 export interface OutputStyle {
   name: string
@@ -79,10 +83,24 @@ function isDirectory(target: string): boolean {
  */
 export function styleDirs(cwd: string, home: string, trusted: boolean): string[] {
   const dirs = [path.join(home, '.claude', 'output-styles')]
-  if (trusted) dirs.push(path.join(cwd, '.claude', 'output-styles'))
+  if (trusted) dirs.push(findNearestDir(cwd, path.join('.claude', 'output-styles')) ?? path.join(cwd, '.claude', 'output-styles'))
   return dirs.filter((dir) => isDirectory(dir))
 }
 
+/**
+ * Output-style directories of every enabled plugin: `output-styles/` unless the
+ * manifest's `outputStyles` points elsewhere, in which case it replaces the
+ * default scan (Claude Code semantics). Plugins are user-installed, so user scope
+ * alone decides; they rank below the user's and project's own styles.
+ */
+export function pluginStyleDirs(home: string): string[] {
+  return installedPlugins(home).flatMap((plugin) => {
+    const declared = plugin.manifest.outputStyles
+    const dirs = Array.isArray(declared) ? declared : [typeof declared === 'string' ? declared : 'output-styles']
+    return dirs.map((dir) => path.resolve(plugin.root, String(dir)))
+  })
+}
+
 /** All output styles, project entries overriding user entries of the same name. */
 export function loadStyles(dirs: string[]): OutputStyle[] {
   const byName = new Map<string, OutputStyle>()
@@ -108,10 +126,14 @@ export function loadStyles(dirs: string[]): OutputStyle[] {
   return [...byName.values()]
 }
 
-/** Settings files that carry `outputStyle`. Project settings apply only when trusted. */
+/** Settings files that carry `outputStyle`. Project settings apply only when trusted,
+ * each the nearest of its name at or above cwd, as the hooks settings chain reads. */
 export function settingsFiles(cwd: string, home: string, trusted: boolean): string[] {
   const files = [path.join(home, '.claude', 'settings.json')]
-  if (trusted) files.push(path.join(cwd, '.claude', 'settings.json'), path.join(cwd, '.claude', 'settings.local.json'))
+  if (!trusted) return files
+  for (const name of ['settings.json', 'settings.local.json']) {
+    files.push(findNearestFile(cwd, path.join('.claude', name)) ?? path.join(cwd, '.claude', name))
+  }
   return files
 }
 
@@ -156,8 +178,14 @@ export default function outputStylesExtension(pi: ExtensionAPI) {
     // project styles / selection once the project is approved. isProjectTrusted alone
     // is true for a repo pi never asked about; see project-approval.
     const trusted = await isProjectApproved(ctx)
-    styles = loadStyles([BUILTIN_STYLES_DIR, ...styleDirs(ctx.cwd, home, trusted)])
-    localSettingsPath = path.join(ctx.cwd, '.claude', 'settings.local.json')
+    // Precedence low to high: builtin, plugin, then the user's and project's own
+    // dirs, so a same-named user or project style overrides a plugin's.
+    styles = loadStyles([BUILTIN_STYLES_DIR, ...pluginStyleDirs(home), ...styleDirs(ctx.cwd, home, trusted)])
+    // Persist the choice where the read chain will find it again: the nearest local
+    // settings file, else inside the nearest .claude directory, else at cwd.
+    const nearestLocal = findNearestFile(ctx.cwd, path.join('.claude', 'settings.local.json'))
+    const claudeDir = findNearestDir(ctx.cwd, '.claude') ?? path.join(ctx.cwd, '.claude')
+    localSettingsPath = nearestLocal ?? path.join(claudeDir, 'settings.local.json')
     activeName = readActiveStyleName(settingsFiles(ctx.cwd, home, trusted))
     const active = styleForName(styles, activeName)
     if (active) ctx.ui.notify(`Output style: ${active.name}`, 'info')

package/extensions/plan-mode/index.ts

@@ -24,6 +24,10 @@ import { extractTodoItems, isSafeCommand, markCompletedSteps, planToTodos, type
 // Tools
 const PLAN_MODE_TOOLS = ['read', 'bash', 'grep', 'find', 'ls', 'question', 'plan_mode_complete']
 
+/** Agent runs in execution mode with no [DONE:n] progress before execution ends on
+ * its own. Kept small: each stalled run re-injects the stale plan into the turn. */
+const STALLED_RUN_LIMIT = 2
+
 // Type guard for assistant messages
 function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
   return m.role === 'assistant' && Array.isArray(m.content)
@@ -60,6 +64,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
   let todoItems: TodoItem[] = []
   let planFromTool = false
   let savedTools: string[] = []
+  let stalledRuns = 0
+  let runProgress = false
 
   function enterPlanTools(): void {
     savedTools = pi.getActiveTools()
@@ -113,6 +119,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     executionMode = false
     todoItems = []
     planFromTool = false
+    stalledRuns = 0
+    runProgress = false
 
     if (planModeEnabled) {
       enterPlanTools()
@@ -140,11 +148,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     })
   }
 
-  // Announce completion and reset once every step is done
-  function finalizeCompletedExecution(ctx: ExtensionContext): void {
-    if (!todoItems.every((t) => t.completed)) return
-    const completedList = todoItems.map((t) => `~~${t.text}~~`).join('\n')
-    pi.sendMessage({ customType: 'plan-complete', content: `**Plan Complete!** ✓\n\n${completedList}`, display: true }, { triggerTurn: false })
+  function endExecution(ctx: ExtensionContext, content: string): void {
+    pi.sendMessage({ customType: 'plan-complete', content, display: true }, { triggerTurn: false })
     executionMode = false
     todoItems = []
     restoreTools()
@@ -152,6 +157,23 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     persistState() // Save cleared state so resume doesn't restore old execution mode
   }
 
+  // Announce completion and reset once every step is done
+  function finalizeCompletedExecution(ctx: ExtensionContext): void {
+    if (!todoItems.every((t) => t.completed)) return
+    const completedList = todoItems.map((t) => `~~${t.text}~~`).join('\n')
+    endExecution(ctx, `**Plan Complete!** ✓\n\n${completedList}`)
+  }
+
+  /** Models regularly drop or renumber a [DONE:n] marker; without a bounded exit the
+   * stale plan would be injected into every later turn until the user finds /plan. */
+  function endStalledExecution(ctx: ExtensionContext): void {
+    const remaining = todoItems
+      .filter((t) => !t.completed)
+      .map((t) => `${t.step}. ${t.text}`)
+      .join('\n')
+    endExecution(ctx, `**Plan execution ended** after ${STALLED_RUN_LIMIT} turns without step progress. Unfinished steps:\n\n${remaining}`)
+  }
+
   // Fall back to extracting a plan from the last assistant message's prose
   function deriveTodosFromProse(messages: AgentMessage[]): void {
     const lastAssistant = [...messages].reverse().find(isAssistantMessage)
@@ -170,6 +192,8 @@ export default function planModeExtension(pi: ExtensionAPI): void {
       planModeEnabled = false
       executionMode = todoItems.length > 0
       planFromTool = false
+      stalledRuns = 0
+      runProgress = false
       restoreTools()
       publishPlanState()
       updateStatus(ctx)
@@ -241,9 +265,19 @@ export default function planModeExtension(pi: ExtensionAPI): void {
     handler: async (ctx) => togglePlanMode(ctx),
   })
 
-  // Block destructive bash commands in plan mode
+  // Enforce plan mode at call time, not only through the active-tool set: pi
+  // activates tools registered after the restriction was applied (an MCP server
+  // connecting during session_start, or a mid-session list_changed refresh), so the
+  // set alone leaks write-capable tools into plan mode.
   pi.on('tool_call', async (event) => {
-    if (!planModeEnabled || event.toolName !== 'bash') return
+    if (!planModeEnabled) return
+    if (!PLAN_MODE_TOOLS.includes(event.toolName)) {
+      return {
+        block: true,
+        reason: `Plan mode: tool blocked (read-only mode). Use /plan to disable plan mode first.\nTool: ${event.toolName}`,
+      }
+    }
+    if (event.toolName !== 'bash') return
 
     const command = event.input.command as string
     if (!isSafeCommand(command)) {
@@ -332,6 +366,7 @@ After completing a step, include a [DONE:n] tag in your response.`,
 
     const text = getTextContent(event.message)
     if (markCompletedSteps(text, todoItems) > 0) {
+      runProgress = true
       updateStatus(ctx)
     }
     persistState()
@@ -339,9 +374,18 @@ After completing a step, include a [DONE:n] tag in your response.`,
 
   // Handle plan completion and plan mode UI
   pi.on('agent_end', async (event, ctx) => {
-    // Check if execution is complete
+    // Check if execution is complete, or has stalled without marker progress
     if (executionMode && todoItems.length > 0) {
-      finalizeCompletedExecution(ctx)
+      if (todoItems.every((t) => t.completed)) {
+        finalizeCompletedExecution(ctx)
+        stalledRuns = 0
+      } else if (runProgress) {
+        stalledRuns = 0
+      } else {
+        stalledRuns++
+        if (stalledRuns >= STALLED_RUN_LIMIT) endStalledExecution(ctx)
+      }
+      runProgress = false
       return
     }
 
@@ -376,6 +420,8 @@ After completing a step, include a [DONE:n] tag in your response.`,
     executionMode = false
     todoItems = []
     planFromTool = false
+    stalledRuns = 0
+    runProgress = false
 
     if (pi.getFlag('plan') === true) {
       planModeEnabled = true