pi-code 1.0.54 → 1.0.56

package/README.md

@@ -13,7 +13,7 @@
 
 Claude Code experience for the [pi](https://pi.dev) coding agent, in one package. Point pi at a project that already has a `.claude/` directory and it reads your existing config: rules, commands, skills, hooks, output styles, MCP servers, and agents. It also adds the Claude Code features pi lacks: a todo overlay, checkpoints, memory, web search, subagents, and goals.
 
-What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes.
+What a repository ships is treated as untrusted until you approve it: project MCP servers, hooks, agents, rules, output styles, commands and skills load only once you say yes. A headless run (`pi -p`) cannot ask, so an undecided project loads none of them there, which is stricter than Claude, where a headless run uses them without showing the dialog.
 
 ![pi-code demo](demos/hero.gif)
 
@@ -45,7 +45,7 @@ Each topic links to its own doc with the full contract and any divergences from
 - **[MCP servers](docs/mcp.md)** — every Claude config scope, all four transports, OAuth, managed policy, timeouts, prompts, and resources.
 - **[Custom slash commands](docs/commands.md)** — `.claude/commands` with arguments, bash spans, `@file` inlining, frontmatter, and model invocation.
 - **[Skills](docs/skills.md)** — `.claude/skills` discovery plus the same dynamic content commands get.
-- **[Subagents / Task](docs/subagents.md)** — built-in and custom agents, background runs, per-agent memory, worktree isolation.
+- **[Subagents](docs/subagents.md)** — built-in and custom agents, background runs, per-agent memory, worktree isolation.
 - **[CLAUDE.md, @imports, and rules](docs/claude-md.md)** — the context files and path-scoped rules pi does not load natively.
 - **[Settings `env`](docs/settings-env.md)** — env blocks from every settings scope, exported with Claude's precedence.
 - **[Output styles](docs/output-styles.md)** — replace semantics, bundled built-ins, `/output-style`.

package/extensions/commands.ts

@@ -325,7 +325,11 @@ export default function commandsExtension(pi: ExtensionAPI) {
     // escape as unhandled; surface it as a no-op instead of leaving the session silently
     // on the command's override model.
     set: (model) => {
-      void pi.setModel(model as Parameters<typeof pi.setModel>[0]).catch(() => {})
+      // A refused switch leaves the turn on the session model rather than the one the
+      // command named, and the reply gives no sign of it, so the refusal is reported.
+      void pi.setModel(model as Parameters<typeof pi.setModel>[0]).catch((error: unknown) => {
+        console.warn(`pi-code-commands: could not switch to ${typeof model === 'object' && model !== null && 'id' in model ? String((model as { id: unknown }).id) : String(model)}: ${error instanceof Error ? error.message : String(error)}`)
+      })
     },
   })
   /** The thinking level to restore after a command's `effort:` override drove its run,
@@ -505,8 +509,12 @@ export default function commandsExtension(pi: ExtensionAPI) {
       let parsed: ParsedCommand
       try {
         parsed = parseCommandFile(fs.readFileSync(command.filePath, 'utf-8'))
-      } catch {
-        continue // an unreadable command file must not take down session start
+      } catch (error) {
+        // An unreadable file must not take down session start, but the command is then
+        // absent from /help and unresolvable by the model, which looks like one that was
+        // never written.
+        console.warn(`pi-code-commands: ignoring ${command.filePath}: ${error instanceof Error ? error.message : String(error)}`)
+        continue
       }
       discovered.set(command.name, command)
       // A user-only command stays off the tool description; it is still in the

package/extensions/hooks/config.ts

@@ -200,7 +200,10 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
   let parsed: { hooks?: HooksConfig }
   try {
     parsed = JSON.parse(raw)
-  } catch {
+  } catch (error) {
+    // Every hook this source declares is now absent, a policy hook among them, so the
+    // failure is named rather than left to look like a file with no hooks in it.
+    console.warn(`pi-code-hooks: ignoring the hooks in ${source}: ${error instanceof Error ? error.message : String(error)}`)
     return
   }
   for (const [event, matchers] of Object.entries(parsed?.hooks ?? {})) {

package/extensions/hooks/matcher.ts

@@ -59,8 +59,10 @@ function compileMatcher(matcher: string): CompiledMatcher {
   } else {
     try {
       compiled = { regex: new RegExp(matcher, 'i') }
-    } catch {
-      // An invalid regex matcher falls back to exact-name matching, as before.
+    } catch (error) {
+      // The fallback matches the literal text, which almost never matches a tool name, so
+      // the hook simply never fires. Say so: the matcher reads as merely wrong otherwise.
+      console.warn(`pi-code-hooks: matcher ${matcher} is not a valid regular expression (${error instanceof Error ? error.message : String(error)}); it will only match a tool of that exact name`)
       compiled = { tokens: exactTokens(matcher) }
     }
   }

package/extensions/hooks/runners.ts

@@ -224,7 +224,11 @@ export async function runHttpHook(hook: { type?: string; command: string; url?:
     }
     return { code: 0, stdout: body, stderr: '', timedOut: false }
   } catch (error) {
-    return { code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: false }
+    // A timeout is the abort that AbortSignal.timeout raises. Mark it as one so a gated
+    // event fails closed on it, exactly as a command hook that ran out of time does: the
+    // hook never answered, whichever transport it used.
+    const name = error instanceof Error ? error.name : ''
+    return { code: 1, stdout: '', stderr: error instanceof Error ? error.message : String(error), timedOut: name === 'TimeoutError' || name === 'AbortError' }
   }
 }
 
@@ -319,7 +323,8 @@ export async function runMcpToolHook(hook: HookCommand, payload: unknown, timeou
   const input = hook.input && typeof hook.input === 'object' ? (substituteInputPaths(hook.input, payload) as Record<string, unknown>) : {}
   let timer: ReturnType<typeof setTimeout> | undefined
   const deadline = new Promise<HookRunResult>((resolve) => {
-    timer = setTimeout(() => resolve({ code: 1, stdout: '', stderr: `mcp_tool hook timed out after ${timeoutMs}ms`, timedOut: false }), timeoutMs)
+    // Marked as a timeout so a gated event fails closed on it, like a command hook.
+    timer = setTimeout(() => resolve({ code: 1, stdout: '', stderr: `mcp_tool hook timed out after ${timeoutMs}ms`, timedOut: true }), timeoutMs)
   })
   const call = callMcpTool(hook.server, hook.tool, input)
     .then((result): HookRunResult => ({ code: result.isError ? 1 : 0, stdout: result.text, stderr: '', timedOut: false }))

package/extensions/internal/plugins.ts

@@ -31,10 +31,19 @@ export interface InstalledPlugin {
 }
 
 function readJson(file: string): Record<string, unknown> {
+  let raw: string
   try {
-    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
-    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+    raw = fs.readFileSync(file, 'utf-8')
   } catch {
+    return {} // no such file: nothing to read, and most callers expect that
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch (error) {
+    // A manifest that does not parse leaves the plugin with no components at all, and
+    // settings that do not parse drop the enablement or configuration they carried.
+    console.warn(`pi-code-plugins: ignoring ${file}: ${error instanceof Error ? error.message : String(error)}`)
     return {}
   }
 }

package/extensions/mcp/transport.ts

@@ -345,8 +345,20 @@ export function runHeadersHelper(command: string, env: NodeJS.ProcessEnv, resolv
       resolve({})
       return
     }
+    const server = env.CLAUDE_CODE_MCP_SERVER_NAME ?? 'the server'
     execFile(shell.file, shell.argsFor(command), { timeout: 10_000, env }, (error, stdout) => {
-      resolve(error ? {} : parseHelperHeaders(stdout))
+      if (error) {
+        // The connect proceeds unauthenticated and the server answers 401, which reads as
+        // a login problem rather than a helper that never produced a header.
+        console.warn(`pi-code-mcp: the headersHelper for ${server} failed: ${error.message}; connecting without the headers it would have supplied`)
+        resolve({})
+        return
+      }
+      const headers = parseHelperHeaders(stdout)
+      if (Object.keys(headers).length === 0 && stdout.trim().length > 0) {
+        console.warn(`pi-code-mcp: the headersHelper for ${server} produced no usable headers; it must print a JSON object of header names to string values`)
+      }
+      resolve(headers)
     })
   })
 }

package/extensions/memory.ts

@@ -149,8 +149,10 @@ export function migrateLegacyStore(cwd: string): void {
     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.
+    } catch (error) {
+      // A failed migration must not take down session start, but the session then has no
+      // memories while they sit under the old slug, which reads as having lost them.
+      console.warn(`pi-code-memory: could not move ${legacy} to ${current}: ${error instanceof Error ? error.message : String(error)}; this session starts without those memories`)
     }
     return
   }
@@ -230,7 +232,12 @@ function readMemory(dir: string, name: string): MemoryToolResult {
   try {
     const body = fs.readFileSync(path.join(dir, `${name}.md`), 'utf-8')
     return { content: [{ type: 'text', text: capForContext(body) }], details: {} }
-  } catch {
+  } catch (error) {
+    // Only a missing file is "no such memory"; anything else (a directory in its place, a
+    // permission problem) sends the model hunting for a name that is actually there.
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      return { content: [{ type: 'text', text: `Memory ${name} could not be read: ${error instanceof Error ? error.message : String(error)}` }], details: {} }
+    }
     return { content: [{ type: 'text', text: `No memory named ${name}.` }], details: {} }
   }
 }

package/extensions/subagent/README.md

@@ -39,7 +39,7 @@ This tool executes a separate `pi` subprocess with a delegated system prompt and
 
 **Default behavior:** Loads the bundled builtin agents (Explore, Plan, general-purpose) plus **user-level agents** from `~/.claude/agents` and `~/.pi/agent/agents`. A user or project agent with the same name overrides a builtin. Discovered agents and their descriptions are listed in the system prompt each turn, so the model can pick one itself; project agent descriptions appear only once the project is approved.
 
-To enable project-local agents (`.claude/agents`, `.pi/agents`), pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+Project-local agents (`.claude/agents`, `.pi/agents`) load once the project is approved: a default call resolves `agentScope` to `"both"` for an approved project and `"user"` otherwise, and an explicit `agentScope` still narrows or widens it. Every invocation passes the project-agent gate either way.
 
 When running interactively, the tool prompts for confirmation before running project-local agents. `confirmProjectAgents: false` skips that prompt for a project you have already approved; an unapproved project is still asked about.
 
@@ -134,9 +134,9 @@ enforces per call.
 
 **Locations:**
 - `~/.claude/agents/*.md`, `~/.pi/agent/agents/*.md` - User-level (always loaded; `~/.pi` wins a name conflict)
-- `.claude/agents/*.md`, `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`; `.pi` wins a name conflict)
+- `.claude/agents/*.md`, `.pi/agents/*.md` - Project-level (an approved project, or an explicit `agentScope` of `"project"`/`"both"`; `.pi` wins a name conflict)
 
-Project agents override user agents with the same name when `agentScope: "both"`.
+Project agents override user agents with the same name when both scopes are in play.
 
 ## Builtin Agents
 

package/extensions/subagent/agents.ts

@@ -177,8 +177,11 @@ function parseAgentFile(content: string, source: AgentSource, filePath: string,
   let parsed: { frontmatter: Record<string, unknown>; body: string }
   try {
     parsed = parseFrontmatter<Record<string, unknown>>(content)
-  } catch {
-    return null // malformed YAML must not abort discovery for the whole directory
+  } 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)})`)
+    return null
   }
   const { frontmatter, body } = parsed
   const name = agentName(frontmatter, filePath, pluginName)

package/extensions/subagent/background.ts

@@ -204,7 +204,7 @@ export function resumeBackgroundRun(id: string, task: string, onComplete: (run:
   if (!fs.existsSync(run.spawn.cwd)) return 'cwd-gone'
   // Persisted so the rebuild happens once: rebuilding per resume leaked one temp
   // prompt dir every follow-up.
-  const rebuilt = withRebuiltPrompt(run.spawn)
+  const rebuilt = withRebuiltPrompt(run.spawn, run.agent)
   run.spawn = { ...run.spawn, args: rebuilt.args }
   if (rebuilt.dir) run.rebuiltPromptDir = rebuilt.dir
   // The task prompt is always the final argument: both spawn paths push it last and the
@@ -228,7 +228,7 @@ export function resumeBackgroundRun(id: string, task: string, onComplete: (run:
 
 /** Re-point --system-prompt at a fresh file when the original is gone; `dir` is the
  * temp dir created for it, which the run then owns. */
-function withRebuiltPrompt(spawnSpec: BackgroundSpawn): { args: string[]; dir?: string } {
+function withRebuiltPrompt(spawnSpec: BackgroundSpawn, agent: string): { args: string[]; dir?: string } {
   const flag = spawnSpec.args.indexOf('--system-prompt')
   if (flag === -1 || !spawnSpec.promptBody) return { args: spawnSpec.args }
   const current = spawnSpec.args[flag + 1]
@@ -240,9 +240,12 @@ function withRebuiltPrompt(spawnSpec: BackgroundSpawn): { args: string[]; dir?:
     const rebuilt = [...spawnSpec.args]
     rebuilt[flag + 1] = file
     return { args: rebuilt, dir }
-  } catch {
+  } catch (error) {
     // Cannot rewrite it: drop the pair rather than hand pi a path it will treat as
-    // prompt text, which would replace the agent persona with a temp path.
+    // 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)}`)
     return { args: spawnSpec.args.filter((_arg, i) => i !== flag && i !== flag + 1) }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.54",
+  "version": "1.0.56",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, subagents, and goals",
   "keywords": [
     "pi",