pi-code 1.0.56 → 1.0.57

package/extensions/plan-mode/utils.ts

@@ -120,6 +120,37 @@ export interface TodoItem {
   completed: boolean
 }
 
+/** The plan state persisted in a session entry, once each field has been checked.
+ * A field the restore cannot recognize is simply absent, so the caller keeps its
+ * current value. */
+export interface RestoredPlanState {
+  enabled?: boolean
+  todos?: TodoItem[]
+  executing?: boolean
+  savedTools?: string[]
+}
+
+const isTodoItem = (value: unknown): value is TodoItem => {
+  if (value === null || typeof value !== 'object') return false
+  const item = value as Record<string, unknown>
+  return typeof item.step === 'number' && typeof item.text === 'string' && typeof item.completed === 'boolean'
+}
+
+/** Read a persisted plan-mode entry, keeping only fields of the expected shape.
+ * The session file is data on disk, and `savedTools` feeds the active tool set: a
+ * string there would be spread character by character into the tool gating, and a
+ * non-array `todos` throws on the first restore that iterates it. */
+export function restoredPlanState(data: unknown): RestoredPlanState {
+  if (data === null || typeof data !== 'object') return {}
+  const raw = data as Record<string, unknown>
+  const state: RestoredPlanState = {}
+  if (typeof raw.enabled === 'boolean') state.enabled = raw.enabled
+  if (typeof raw.executing === 'boolean') state.executing = raw.executing
+  if (Array.isArray(raw.todos) && raw.todos.every(isTodoItem)) state.todos = raw.todos
+  if (Array.isArray(raw.savedTools) && raw.savedTools.every((tool) => typeof tool === 'string')) state.savedTools = raw.savedTools
+  return state
+}
+
 function cleanStepText(text: string): string {
   let cleaned = text
     .replace(/\*{1,2}([^*]+)\*{1,2}/g, '$1') // Remove bold/italic

package/extensions/session-title.ts

@@ -21,6 +21,7 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 
 import { completeText } from './internal/model-complete.js'
+import { contentText } from './internal/values.js'
 
 const TITLE_SYSTEM = 'You name a coding session from its first user message. Reply with a terse 3 to 6 word title in Title Case that captures the task. No quotes, no surrounding punctuation, no trailing period. Output the title only, nothing else.'
 /** A title is a few words; a tight cap keeps the extra call cheap and stops a runaway reply. */
@@ -29,23 +30,12 @@ const TITLE_MAX_TOKENS = 24
  * bounded prompt keeps the input cost of the extra call small. */
 const MAX_PROMPT_CHARS = 1000
 
-/** Join the text of a message's content, mirroring git-checkpoint's extraction: content is
- * either a plain string or an array of parts, of which only text parts carry a title's worth. */
-function extractText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (!Array.isArray(content)) return ''
-  return content
-    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
-    .map((part) => part.text)
-    .join(' ')
-}
-
 /** Text of the first user message in the branch, or empty when the run carried no user text
  * (for example a slash-command-only turn), in which case there is nothing to title from. */
 export function firstUserText(ctx: ExtensionContext): string {
   for (const entry of ctx.sessionManager.getBranch()) {
     if (entry?.type === 'message' && entry.message.role === 'user') {
-      return extractText(entry.message.content).trim()
+      return contentText(entry.message.content, ' ').trim()
     }
   }
   return ''

package/extensions/skills.ts

@@ -23,7 +23,6 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { type ExtensionAPI, type ExtensionContext, parseFrontmatter } from '@earendil-works/pi-coding-agent'
-
 import { expandCommand, shellExecutionDisabled } from './commands.js'
 import { runAgent } from './internal/agent-run.js'
 import { parseCommandFile } from './internal/command-file.js'
@@ -32,16 +31,9 @@ import { managedSettingsFile } from './internal/managed-settings.js'
 import { installedPlugins, pluginComponentPath } from './internal/plugins.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorDirs } from './internal/project-root.js'
-import { claudeSettingsChain } from './internal/settings-chain.js'
+import { claudeSettingsChain, readSettingsChain } from './internal/settings-chain.js'
 import { SKILL_HOOKS_CHANNEL } from './internal/skill-hooks.js'
-
-function isDirectory(target: string): boolean {
-  try {
-    return fs.statSync(target).isDirectory()
-  } catch {
-    return false
-  }
-}
+import { errorMessage, isDirectory, isRecord } from './internal/values.js'
 
 /** Existing `.claude/skills` directories, user first then project. The project
  * directory is included only for approved projects: pi's loader surfaces every skill's
@@ -136,13 +128,9 @@ export default function skillsExtension(pi: ExtensionAPI) {
  * (a pi-loader surface, noted in docs). */
 function skillOverrideFor(name: string, cwd: string, trusted: boolean): string | undefined {
   let value: string | undefined
-  for (const file of claudeSettingsChain(cwd, os.homedir(), trusted)) {
-    try {
-      const overrides = JSON.parse(fs.readFileSync(file, 'utf-8')).skillOverrides
-      if (overrides !== null && typeof overrides === 'object' && typeof overrides[name] === 'string') value = overrides[name]
-    } catch {
-      // missing or invalid file: skip
-    }
+  for (const settings of readSettingsChain(claudeSettingsChain(cwd, os.homedir(), trusted))) {
+    const overrides = settings.skillOverrides
+    if (isRecord(overrides) && typeof overrides[name] === 'string') value = overrides[name]
   }
   return value
 }
@@ -165,7 +153,7 @@ async function runForkedSkill(name: string, filePath: string, expanded: string,
     const output = await runAgent({ prompt: expanded, fullTools: true, ...(agentName ? { agent: agentName } : {}) })
     return { action: 'transform', text: `<skill name="${name}" location="${filePath}">\nThe skill ran in a forked subagent (no conversation history shared). Its result:\n\n${output}\n</skill>` }
   } catch (error) {
-    return { action: 'transform', text: `<skill name="${name}">\nThe forked subagent run failed: ${error instanceof Error ? error.message : String(error)}\n</skill>` }
+    return { action: 'transform', text: `<skill name="${name}">\nThe forked subagent run failed: ${errorMessage(error)}\n</skill>` }
   }
 }
 

package/extensions/status-line.ts

@@ -36,6 +36,7 @@ import { claudeEffortLevel } from './internal/effort.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isPlanModeState, PLAN_MODE_CHANNEL } from './internal/plan-mode-state.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
+import { readSettingsChain } from './internal/settings-chain.js'
 import { watchSettingsFiles } from './internal/settings-watch.js'
 import { readActiveStyleName, settingsFiles } from './output-styles.js'
 
@@ -178,14 +179,7 @@ export function readStatusLineConfig(files: string[], managed: Record<string, un
   if (managedConfig) return managedConfig
   if (managed.allowManagedHooksOnly === true) return undefined
   let found: StatusLineConfig | undefined
-  for (const file of files) {
-    try {
-      const settings = JSON.parse(fs.readFileSync(file, 'utf-8'))
-      found = parseStatusLineEntry(settings.statusLine) ?? found
-    } catch {
-      // missing or invalid file: skip
-    }
-  }
+  for (const settings of readSettingsChain(files)) found = parseStatusLineEntry(settings.statusLine) ?? found
   return found
 }
 

package/extensions/subagent/README.md

@@ -18,9 +18,19 @@ Delegate tasks to specialized subagents with isolated context windows.
 ```
 subagent/
 ├── README.md            # This file
-├── index.ts             # The extension (entry point)
-├── agents.ts            # Agent discovery logic
+├── index.ts             # The extension: tool schema, dispatch, session hooks
+├── agents.ts            # Agent discovery and frontmatter
+├── child.ts             # How a child is configured before it is spawned
+├── run.ts               # Spawning one child and parsing its event stream
+├── modes.ts             # Single, parallel, chain, background, and the project-agent gate
 ├── background.ts        # Background run registry and spawning
+├── worktree.ts          # isolation: worktree setup and teardown
+├── params.ts            # The tool schema and the types derived from it
+├── types.ts             # Result shapes shared by the tool and its renderers
+├── concurrency.ts       # Parallel-run caps and the bounded worker pool
+├── registry-text.ts     # Text for /tasks, /agents and completion notices
+├── render.ts            # Transcript formatting shared with the parent
+├── render-result.ts     # How a call and its results are drawn
 ├── agents/              # Bundled builtin agents, always available (lowest precedence)
 │   ├── explore.md       # Explore: fast read-only codebase exploration
 │   ├── plan.md          # Plan: read-only implementation planning

package/extensions/subagent/agents.ts

@@ -6,7 +6,6 @@ import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
 import { getAgentDir, parseFrontmatter, stripFrontmatter } from '@earendil-works/pi-coding-agent'
-
 // The same mapping a command's `allowed-tools` gets: an agent's `tools:` is the same
 // Claude field, and `--tools` is an exact-name allowlist, so a name pi has no tool for
 // is not merely ignored, it narrows the child's registry.
@@ -14,6 +13,7 @@ import { parseToolGrants } from '../internal/command-file.js'
 import { claudeConfigDir } from '../internal/config-dir.js'
 import { installedPlugins, pluginComponentPath } from '../internal/plugins.js'
 import { ancestorDirs, findNearestDir } from '../internal/project-root.js'
+import { errorMessage } from '../internal/values.js'
 
 /**
  * `tools:` may be a comma-separated string (the Claude Code format) or a YAML block
@@ -180,7 +180,7 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string,
   } catch (error) {
     // Malformed YAML must not abort discovery for the whole directory, but a silent drop
     // reads as "that agent does not exist", so it is named like the other rejections here.
-    console.warn(`pi-code-subagent: ignoring agent ${filePath}: its frontmatter could not be parsed (${error instanceof Error ? error.message : String(error)})`)
+    console.warn(`pi-code-subagent: ignoring agent ${filePath}: its frontmatter could not be parsed (${errorMessage(error)})`)
     return null
   }
   const { frontmatter, body } = parsed

package/extensions/subagent/background.ts

@@ -11,6 +11,7 @@ import { randomUUID } from 'node:crypto'
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
+import { errorMessage } from '../internal/values.js'
 
 export interface BackgroundRun {
   id: string
@@ -245,7 +246,7 @@ function withRebuiltPrompt(spawnSpec: BackgroundSpawn, agent: string): { args: s
     // prompt text, which would replace the agent persona with a temp path. The child then
     // runs as a plain assistant instead of the agent asked for, and nothing in its output
     // says so, hence the notice.
-    console.warn(`pi-code-subagent: resuming ${agent} without its agent prompt: ${error instanceof Error ? error.message : String(error)}`)
+    console.warn(`pi-code-subagent: resuming ${agent} without its agent prompt: ${errorMessage(error)}`)
     return { args: spawnSpec.args.filter((_arg, i) => i !== flag && i !== flag + 1) }
   }
 }

package/extensions/subagent/child.ts

@@ -0,0 +1,197 @@
+/**
+ * How a child agent is configured before it is spawned: its system prompt, its own
+ * memory store, the tools it resolves to, its CLI arguments and its hook environment.
+ *
+ * Separate from the runner so the shape of a child can be asserted without spawning
+ * one, and from the extension body so the factory keeps only schema and dispatch.
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import type { AgentRunRequest } from '../internal/agent-run.js'
+import { claudeConfigDir } from '../internal/config-dir.js'
+import { repoRoot } from '../internal/project-root.js'
+import { autoMemoryEnabled, capIndexForPrompt, INDEX_MAX_BYTES, INDEX_MAX_LINES, memorySettingsFiles, readMemorySettings } from '../memory.js'
+import { type AgentConfig, type AgentMemoryScope, expandMcpToolPatterns, withPreloadedSkills } from './agents.js'
+/** The system prompt for Claude's experimental `type: "agent"` hooks: the subagent
+ * inspects with read-only tools and returns the same JSON decision a command hook's
+ * stdout carries. A hook-supplied `systemPrompt` is appended after it. */
+export const AGENT_HOOK_SYSTEM = [
+  'You are a Claude Code agent hook verifying whether an action should proceed.',
+  'Use the Read, Grep, and Glob tools to inspect files as needed before deciding.',
+  'When done, respond with ONLY a JSON object and nothing else:',
+  '{"hookSpecificOutput":{"permissionDecision":"allow"|"deny"|"ask","permissionDecisionReason":"<short reason>"}}',
+  'Use "allow" to let the action proceed, "deny" to block it, "ask" to require the user to confirm.',
+].join('\n')
+
+/** A throwaway agent config for one agent-hook run: read-only inspection tools, the
+ * hook's model (a fast default when unset), and the decision-returning system prompt. */
+/** The agent a context: fork skill runs as when it names none: full toolset, no
+ * extra system prompt (the child keeps pi's default), the skill content as the
+ * task. */
+export function forkAgent(request: Pick<AgentRunRequest, 'model' | 'systemPrompt'>): AgentConfig {
+  return {
+    name: 'fork',
+    description: 'forked skill run',
+    systemPrompt: request.systemPrompt ?? '',
+    ...(request.model ? { model: request.model } : {}),
+    source: 'builtin',
+    filePath: '',
+  }
+}
+
+export function buildHookAgent(request: Pick<AgentRunRequest, 'model' | 'systemPrompt'>): AgentConfig {
+  return {
+    name: 'agent-hook',
+    description: 'Verifies a hook condition using read-only inspection tools.',
+    tools: ['read', 'grep', 'find'],
+    model: request.model,
+    systemPrompt: request.systemPrompt ? `${AGENT_HOOK_SYSTEM}\n\n${request.systemPrompt}` : AGENT_HOOK_SYSTEM,
+    source: 'builtin',
+    filePath: '',
+  }
+}
+
+/** The file-management tools a memory-enabled child needs for its store. */
+const MEMORY_TOOLS = ['read', 'write', 'edit']
+
+/** Where an agent's own persistent memory lives, per its `memory:` scope (Claude:
+ * user -> ~/.claude/agent-memory/<name>, project -> <root>/.claude/agent-memory/<name>,
+ * local -> <root>/.claude/agent-memory-local/<name>). The name comes from frontmatter
+ * a repository can control, so it is sanitized before becoming a path segment. */
+export function agentMemoryDir(scope: AgentMemoryScope, name: string, cwd: string, home: string): string {
+  const sanitized = name.replace(/[^\w.-]+/g, '_')
+  // A name of only dots ('.', '..') survives the character filter but still traverses.
+  const segment = /^\.+$/.test(sanitized) ? '_' : sanitized
+  if (scope === 'user') return path.join(claudeConfigDir(home), 'agent-memory', segment)
+  const root = repoRoot(cwd) ?? cwd
+  return path.join(root, '.claude', scope === 'project' ? 'agent-memory' : 'agent-memory-local', segment)
+}
+
+/** The prompt section giving a memory-enabled child its own persistent store: the
+ * directory, read/write/curation instructions, and its MEMORY.md capped like the
+ * parent's index load (first 200 lines or 25KB, whichever comes first). */
+export function agentMemorySection(dir: string, memoryMd: string): string {
+  const indexPath = path.join(dir, 'MEMORY.md')
+  const capped = capIndexForPrompt(memoryMd)
+  const current = capped.trim() ? `Current ${indexPath}:\n\n${capped}` : `${indexPath} does not exist yet; create it once you have something worth keeping.`
+  return [
+    '## Agent memory',
+    '',
+    `You have a persistent memory directory at ${dir} that survives across sessions.`,
+    'Use the read, write, and edit tools to record durable insights, project patterns, and lessons learned there, and consult them when relevant.',
+    `Only the first ${INDEX_MAX_LINES} lines or ${INDEX_MAX_BYTES} bytes of ${indexPath} are loaded at startup, so keep it a concise, curated index and move details into separate files in the directory.`,
+    '',
+    current,
+  ].join('\n')
+}
+
+/** The memory section for one run, or undefined when the agent declares no memory,
+ * auto memory is off, or a repo-scoped store is not approved. Subagent memory is part
+ * of auto memory, so the same settings chain and env kill switch gate it. */
+export function agentMemoryPromptSection(agent: Pick<AgentConfig, 'memory' | 'name'>, cwd: string, projectApproved: boolean): string | undefined {
+  if (!agent.memory) return undefined
+  // project and local stores live under the repository's .claude, a repo-controlled
+  // path; like rules, they are only read once the project is approved.
+  if (agent.memory !== 'user' && !projectApproved) return undefined
+  const settings = readMemorySettings(memorySettingsFiles(cwd, os.homedir(), projectApproved))
+  if (!autoMemoryEnabled(settings.autoMemoryEnabled, process.env)) return undefined
+  const dir = agentMemoryDir(agent.memory, agent.name, cwd, os.homedir())
+  let memoryMd = ''
+  try {
+    memoryMd = fs.readFileSync(path.join(dir, 'MEMORY.md'), 'utf-8')
+  } catch {
+    // no store yet: the section still tells the child where to create one
+  }
+  return agentMemorySection(dir, memoryMd)
+}
+
+/** Widen a restricted agent's allowlist so it can manage its memory files. An
+ * unrestricted agent (no allowlist) already has every tool. */
+export function withMemoryTools(tools: string[] | undefined): string[] | undefined {
+  if (!tools || tools.length === 0) return tools
+  return [...tools, ...MEMORY_TOOLS.filter((tool) => !tools.includes(tool))]
+}
+
+/** The child's --append-system-prompt body: the skills-preloaded prompt plus the
+ * agent memory section, without a stray separator when either part is empty. */
+export function childPromptBody(agent: AgentConfig, skillRoots: string[], memorySection: string | undefined): string {
+  const prompt = withPreloadedSkills(agent.systemPrompt, agent.skills, skillRoots)
+  if (!memorySection) return prompt
+  return [prompt, memorySection].filter((part) => part.trim()).join('\n\n')
+}
+
+/** The parent's MCP tool aliases, published by the mcp extension on the shared bus;
+ * the module-level seam matches setMcpToolCaller's. Children read the same MCP config
+ * files, so the parent's roster is the translation table for server-level patterns. */
+let knownMcpAliases: ReadonlyArray<{ pi: string; claude: string }> = []
+
+export function setKnownMcpAliases(aliases: ReadonlyArray<{ pi: string; claude: string }>): void {
+  knownMcpAliases = aliases
+}
+
+/** pi's built-in ToolName union (core/tools/index.d.ts; the package's export map
+ * does not expose allToolNames, so this mirrors it) plus the tools pi-code's own
+ * extensions register in a child. Claude's capitalized spellings fold onto these. */
+const CHILD_TOOL_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'web_fetch', 'web_search', 'list_mcp_resources', 'read_mcp_resource', 'todo', 'question', 'memory', 'slash_command', 'plan_mode_complete'])
+
+/** Claude: when no entry in a `tools` list resolves to a tool, the subagent fails
+ * to launch with an error naming the entries, instead of running tool-less. */
+export function unresolvedToolsError(agent: AgentConfig): string | undefined {
+  if (!agent.tools || agent.tools.length === 0) return undefined
+  const fold = (name: string): string => name.toLowerCase().replaceAll('-', '_')
+  const known = new Set(knownMcpAliases.map((alias) => fold(alias.pi)))
+  const resolves = expandMcpToolPatterns(agent.tools, knownMcpAliases).some((entry) => CHILD_TOOL_NAMES.has(fold(entry)) || known.has(fold(entry)))
+  if (resolves) return undefined
+  return `Agent "${agent.name}" would launch with zero tools: no entry in [${agent.tools.join(', ')}] resolves to a tool.`
+}
+
+/** CLI args shared by foreground and background children, from the agent's config. */
+export function agentInvocationArgs(agent: AgentConfig, aliasModel?: string): string[] {
+  const args: string[] = ['--mode', 'json', '-p', '--no-session']
+  // A concrete model wins; otherwise a Claude tier alias resolved against the models
+  // this user can actually run; then CLAUDE_CODE_SUBAGENT_MODEL, per Claude's model
+  // order (invocation model, frontmatter model, this variable, the session model).
+  // pi reads a thinking level from the model pattern's :suffix when a model is
+  // pinned, and from --thinking otherwise.
+  // Claude exempts the two built-ins from the environment variable: "Setting
+  // CLAUDE_CODE_SUBAGENT_MODEL by itself doesn't change the model the built-in Explore and
+  // Plan subagents run on." A model they name themselves, or one the invocation names,
+  // still applies.
+  const exemptFromEnvModel = agent.source === 'builtin' && (agent.name === 'Explore' || agent.name === 'Plan')
+  const model = agent.model ?? aliasModel ?? (exemptFromEnvModel ? undefined : process.env.CLAUDE_CODE_SUBAGENT_MODEL)
+  if (model) args.push('--model', agent.effort ? `${model}:${agent.effort}` : model)
+  else if (agent.effort) args.push('--thinking', agent.effort)
+  // Claude's mcp__<server> / mcp__* patterns expand against the parent's MCP roster;
+  // without this a server-level deny removed nothing (fail open) and a server-level
+  // grant granted nothing.
+  if (agent.tools && agent.tools.length > 0) args.push('--tools', expandMcpToolPatterns(agent.tools, knownMcpAliases).join(','))
+  if (agent.disallowedTools && agent.disallowedTools.length > 0) args.push('--exclude-tools', expandMcpToolPatterns(agent.disallowedTools, knownMcpAliases).join(','))
+  // Claude: "Explore and Plan are the only subagents that omit CLAUDE.md" (and no
+  // field or setting changes which agents skip them), to keep research fast.
+  if (agent.source === 'builtin' && (agent.name === 'Explore' || agent.name === 'Plan')) args.push('--no-context-files')
+  return args
+}
+
+/** Claude's agent-frontmatter hooks ride to the child as env; the child's hooks
+ * extension merges them for the run only (they die with the process, matching
+ * "only while that subagent is running"). Stop converts to SubagentStop, the
+ * event the child fires when it completes, as Claude documents. */
+export function agentHooksEnv(agent: AgentConfig, agentId: string): Record<string, string> {
+  if (!agent.hooks) return {}
+  const hooks: Record<string, unknown> = { ...agent.hooks }
+  const stop = hooks.Stop
+  delete hooks.Stop
+  if (Array.isArray(stop)) hooks.SubagentStop = [...(Array.isArray(hooks.SubagentStop) ? (hooks.SubagentStop as unknown[]) : []), ...stop]
+  return { PI_CODE_AGENT_HOOKS: JSON.stringify({ agent: agent.name, id: agentId, hooks }) }
+}
+
+/** The task argument with any SubagentStart hook context ahead of it, per Claude:
+ * "added to the subagent's context at the start of its conversation, before its
+ * first prompt". */
+export function taskWithStartContext(task: string, contexts: string[]): string {
+  const context = contexts.filter(Boolean).join('\n')
+  return context ? `${context}\n\nTask: ${task}` : `Task: ${task}`
+}

package/extensions/subagent/concurrency.ts

@@ -0,0 +1,23 @@
+/**
+ * Bounded fan-out for parallel subagent runs: the caps the tool advertises and the
+ * worker pool that honours them.
+ */
+
+export const MAX_PARALLEL_TASKS = 8
+export const MAX_CONCURRENCY = 4
+
+export async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: number, fn: (item: TIn, index: number) => Promise<TOut>): Promise<TOut[]> {
+  if (items.length === 0) return []
+  const limit = Math.max(1, Math.min(concurrency, items.length))
+  const results: TOut[] = new Array(items.length)
+  let nextIndex = 0
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const current = nextIndex++
+      if (current >= items.length) return
+      results[current] = await fn(items[current], current)
+    }
+  })
+  await Promise.all(workers)
+  return results
+}