pi-code 1.0.61 → 1.0.62

package/README.md

@@ -60,6 +60,8 @@ Slash commands: `/init`, `/context`, `/goal`, `/memory`, `/todos`, `/rewind`, `/
 
 pi has no general permission system, so most of what Claude routes through a permission prompt maps to hard behavior here: `allowed-tools` restricts the turn's tool set instead of pre-approving calls, and a hook that times out on PreToolUse or UserPromptSubmit fails closed. A hook's `permissionDecision: "ask"` is the exception: it shows a confirm dialog and lets the call through when you approve (a headless run has no dialog, so it blocks). Where a Claude restriction cannot be expressed at all (an argument-scoped grant in an agent's `tools:`), the definition is rejected rather than widened.
 
+Trust is the other place pi-code is deliberately stricter. Claude states that "a `claude -p` run never shows the trust dialog" and loads the project's hooks, MCP servers, agents, commands, skills and rules anyway. pi-code refuses instead: with no stored decision and no UI to ask, a headless run in a project you have not already trusted loads none of them. A repository would otherwise get to run its own hooks and MCP servers in any CI job that checks it out, with nobody present to decline.
+
 `CLAUDE.md` itself needs no extension: pi loads `CLAUDE.md` / `AGENTS.md` context files natively (global + walking cwd to root). `context-imports.ts` only adds the `@import` resolution pi's loader lacks, appending the imported files without re-injecting the base. Setting `CLAUDE_CONFIG_DIR` relocates the entire home config scope (settings, commands, agents, skills, plugins, output styles, memory, and the user `CLAUDE.md`); a project's own `.claude/` is a separate scope and is unaffected.
 
 [`extensions/internal/`](extensions/internal) holds the shared modules pi's loader must not treat as extensions (each file's header says what it owns); only `internal/` keeps them out of pi's extension scan.

package/extensions/commands.ts

@@ -10,8 +10,8 @@
  * `allowed-tools`, `argument-hint` and `model` frontmatter (`model` switches the
  * session model for the command's run via `pi.setModel`, restored on agent_end).
  * `shell: powershell` runs a command's injected spans through PowerShell when a
- * pwsh binary is installed, falling back to /bin/sh so the command still works
- * without one.
+ * pwsh binary is installed, falling back to the default shell path so the command
+ * still works without one: /bin/sh on POSIX, Git Bash on Windows.
  *
  * Commands are also exposed to the model through a `slash_command` tool
  * (Claude's SlashCommand tool), listing every discovered command whose file
@@ -33,7 +33,7 @@
  * A project command body is repository-controlled text that can run shell
  * commands and read files, so project commands load only once the project is
  * approved. That closes the "skills / commands are not trust-gated" limitation
- * for commands; skills remain pi-loader territory.
+ * for commands; skills.ts gates project skills on the same approval.
  *
  * Docs: https://code.claude.com/docs/en/slash-commands.md
  */
@@ -54,6 +54,7 @@ import { matchesPathRules } from './internal/path-rules.js'
 import { type InstalledPlugin, installedPlugins, pluginComponentPath } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
 import { ancestorDirs, repoRoot } from './internal/project-root.js'
+import { agentNamesIn, matchesAgentRules, matchesDomainRules, matchesSkillRules } from './internal/scope-rules.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
 import { createTurnOverride } from './internal/turn-override.js'
 import { errorMessage, isDirectory } from './internal/values.js'
@@ -85,6 +86,15 @@ function substitutePathRule(rule: string, vars: Record<string, string | undefine
   return rule.trimStart().startsWith('${CLAUDE_') && path.isAbsolute(substituted) ? `/${substituted}` : substituted
 }
 
+/** One scalar argument scope checked against one call: undefined when the tool is
+ * unscoped for this run or the call matches, otherwise a block naming the rules in
+ * force and the value that failed them. */
+function scopeVerdict(rules: string[] | undefined, tool: string, subjectLabel: string, subject: string, matches: (rules: string[]) => boolean): { block: true; reason: string } | undefined {
+  if (!rules) return undefined
+  if (matches(rules)) return undefined
+  return { block: true, reason: `allowed-tools: ${tool} is scoped for this command.\nAllowed: ${rules.join(', ')}\n${subjectLabel}: ${subject}` }
+}
+
 /** The path rules that survive an allowed-tools intersection: only the tools the
  * grant kept get their scopes, each rule ${CLAUDE_*}-substituted like the body. */
 function scopedPathRules(pathRules: Partial<Record<PathRuleTool, string[]>>, granted: string[], vars: Record<string, string | undefined>): Partial<Record<PathRuleTool, string[]>> {
@@ -310,6 +320,12 @@ export default function commandsExtension(pi: ExtensionAPI) {
   let pendingRestore: string[] | undefined
   /** `Bash(...)` scopes enforced while that run lasts; lifted with the restriction. */
   let pendingBashRules: string[] | undefined
+  /** `WebFetch(domain:...)` scopes enforced the same way. */
+  let pendingDomainRules: string[] | undefined
+  /** `Agent(...)`/`Task(...)` agent-name scopes enforced the same way. */
+  let pendingAgentRules: string[] | undefined
+  /** `Skill(...)` name-pattern scopes enforced the same way. */
+  let pendingSkillRules: string[] | undefined
   /** Read/Edit path scopes enforced the same way, per pi file tool. */
   let pendingPathRules: Partial<Record<PathRuleTool, string[]>> | undefined
   /** The session model to restore after a command's `model:` override drove its run,
@@ -342,6 +358,9 @@ export default function commandsExtension(pi: ExtensionAPI) {
   // continuation remains, which is the grant's true clearing point.
   pi.on('agent_settled', async () => {
     pendingBashRules = undefined
+    pendingDomainRules = undefined
+    pendingAgentRules = undefined
+    pendingSkillRules = undefined
     pendingPathRules = undefined
     modelOverride.settle()
     effortOverride.settle()
@@ -354,18 +373,27 @@ export default function commandsExtension(pi: ExtensionAPI) {
   // The active-tool set has no argument dimension, so a scoped grant hands the turn
   // the whole tool; the scope is enforced here instead, when the call arrives. Same
   // steering-not-sandbox caveat as plan mode's guard.
+  //
+  // PAIRED WITH hooks/matcher.ts's matchesToolPattern, which dispatches the same tools
+  // to the same matchers for hook `if` filters. Deliberately not merged: bash differs
+  // (here every segment of a compound command must match a rule; there the filter is
+  // best effort and errs toward running the hook). A new scoped tool must be added in
+  // both; the shared roster is ARG_RULE_TOOLS in internal/command-file.ts.
   pi.on('tool_call', async (event, ctx) => {
-    if (pendingBashRules && event.toolName === 'bash') {
-      const command = typeof event.input.command === 'string' ? event.input.command : ''
-      if (matchesBashRules(command, pendingBashRules)) return
-      return {
-        block: true,
-        reason: `allowed-tools: bash is scoped for this command.\nAllowed: ${pendingBashRules.join(', ')}\nCommand: ${command}`,
-      }
+    const input = event.input as Record<string, unknown>
+    const text = (value: unknown): string => (typeof value === 'string' ? value : '')
+    // The four scalar-scope tools share one shape: rules in force, the part of the call
+    // they judge, and the sentence naming both when it blocks. One helper keeps the arms
+    // from drifting; only the subject and the matcher differ.
+    if (event.toolName === 'bash') return scopeVerdict(pendingBashRules, 'bash', 'Command', text(input.command), (rules) => matchesBashRules(text(input.command), rules))
+    if (event.toolName === 'web_fetch') return scopeVerdict(pendingDomainRules, 'web_fetch', 'Url', text(input.url), (rules) => matchesDomainRules(text(input.url), rules))
+    if (event.toolName === 'subagent') {
+      const names = agentNamesIn(input)
+      return scopeVerdict(pendingAgentRules, 'subagent', 'Agents', names.join(', '), (rules) => matchesAgentRules(names, rules))
     }
+    if (event.toolName === 'slash_command') return scopeVerdict(pendingSkillRules, 'slash_command', 'Command', text(input.command), (rules) => matchesSkillRules(text(input.command), rules))
     const rules = pendingPathRules?.[event.toolName as PathRuleTool]
     if (!rules) return
-    const input = event.input as Record<string, unknown>
     const filePath = typeof input.path === 'string' ? input.path : ''
     const anchors = { cwd: ctx.cwd, projectRoot: repoRoot(ctx.cwd) ?? ctx.cwd, home: os.homedir() }
     if (filePath && matchesPathRules(filePath, rules, anchors)) return
@@ -403,6 +431,9 @@ export default function commandsExtension(pi: ExtensionAPI) {
     // the same ${CLAUDE_*} substitution as the body, so a rule can name a bundled
     // script by its real path, as the skills docs show.
     pendingBashRules = granted.includes('bash') ? parsed.bashRules?.map((rule) => substituteVars(rule, vars)) : undefined
+    pendingDomainRules = granted.includes('web_fetch') ? parsed.domainRules : undefined
+    pendingAgentRules = granted.includes('subagent') ? parsed.agentRules : undefined
+    pendingSkillRules = granted.includes('slash_command') ? parsed.skillRules : undefined
     pendingPathRules = parsed.pathRules ? scopedPathRules(parsed.pathRules, granted, vars) : undefined
   }
 
@@ -482,6 +513,9 @@ export default function commandsExtension(pi: ExtensionAPI) {
     // no setActiveTools/setModel/setThinkingLevel, since the new session owns its own state.
     pendingRestore = undefined
     pendingBashRules = undefined
+    pendingDomainRules = undefined
+    pendingAgentRules = undefined
+    pendingSkillRules = undefined
     pendingPathRules = undefined
     modelOverride.reset()
     effortOverride.reset()

package/extensions/env-settings.ts

@@ -40,6 +40,7 @@ import { claudeConfigDir } from './internal/config-dir.js'
 import { readManagedSettings } from './internal/managed-settings.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { claudeSettingsChain } from './internal/settings-chain.js'
+import { watchSettingsFiles } from './internal/settings-watch.js'
 import { isRecord } from './internal/values.js'
 
 /** The `env` object of one settings scope, coerced to string values. A string is kept
@@ -145,6 +146,8 @@ function projectEnv(cwd: string, home: string): Record<string, string> {
 
 export default function envSettingsExtension(pi: ExtensionAPI) {
   const owned = new Map<string, string | undefined>()
+  /** Stops the watcher of the previous session, as the hooks extension does. */
+  let disposeWatch: () => void = () => {}
 
   const apply = (home: string, project: Record<string, string>): void => {
     applyEnvSettings(mergeEnvScopes(envFromSettings(readManagedSettings()), userEnv(home), project), process.env, owned)
@@ -155,6 +158,21 @@ export default function envSettingsExtension(pi: ExtensionAPI) {
   apply(os.homedir(), {})
 
   pi.on('session_start', async (_event, ctx: ExtensionContext) => {
-    apply(os.homedir(), isProjectApprovedSilently(ctx) ? projectEnv(ctx.cwd, os.homedir()) : {})
+    const home = os.homedir()
+    const approved = isProjectApprovedSilently(ctx)
+    const reapply = (): void => apply(home, approved ? projectEnv(ctx.cwd, home) : {})
+    reapply()
+    // Claude: "Claude Code watches your settings files and reloads them when they change,
+    // so it applies most edits to the running session without a restart." `env` is not
+    // one of the restart-only keys (model, effortLevel/modelSettings, outputStyle), so an
+    // edit has to reach process.env now rather than at the next session. applyEnvSettings
+    // tracks what it owns, so a key removed from the file is restored, not left behind.
+    disposeWatch()
+    disposeWatch = watchSettingsFiles(claudeSettingsChain(ctx.cwd, home, approved), reapply)
+  })
+
+  pi.on('session_shutdown', async () => {
+    disposeWatch()
+    disposeWatch = () => {}
   })
 }

package/extensions/hooks/claude-tools.ts

@@ -10,6 +10,14 @@
  * node_modules/@earendil-works/pi-coding-agent/dist/core/tools and Claude's hooks
  * reference (per-tool input tables, PostToolUse response shapes).
  *
+ * NAMES and SHAPES cover different sets on purpose. Names come from
+ * internal/claude-tool-names.ts and cover every pi tool the tools reference has a
+ * counterpart for, because a hook matcher written in Claude's vocabulary has to fire.
+ * Shapes are translated only for the file and shell tools below, because those are
+ * the only tools the hooks reference gives a per-tool input table for; for the rest
+ * there is no documented Claude shape to conform to, so the pi input passes through
+ * unchanged and a hook reads the fields pi's own schema defines.
+ *
  * Translation choices the shapes force, each documented on its function:
  * - pi's multi-entry `edits[]` maps to Claude's single Edit with the first entry in
  *   `old_string`/`new_string` and the full array carried alongside as `edits`.
@@ -21,13 +29,7 @@
 import * as os from 'node:os'
 import * as path from 'node:path'
 
-/** pi built-in -> Claude tool name for hook payloads and matchers. MCP tools ride
- * the alias bus instead; pi tools with no Claude counterpart (ls) stay untranslated. */
-const CLAUDE_NAMES: Record<string, string> = { bash: 'Bash', edit: 'Edit', write: 'Write', read: 'Read', grep: 'Grep', find: 'Glob' }
-
-export function claudeToolName(piName: string): string | undefined {
-  return CLAUDE_NAMES[piName]
-}
+export { claudeToolName } from '../internal/claude-tool-names.js'
 
 /** Claude file-tool paths are always absolute with `~` expanded before hooks run,
  * so a path guard cannot be bypassed by a relative or `~` spelling of the same path. */

package/extensions/hooks/config.ts

@@ -33,6 +33,11 @@ export interface HookCommand {
   /** Claude's permission-rule filter (`"Bash(git *)"`, `"Edit(*.ts)"`): evaluated only
    * on tool events; on any other event a hook carrying `if` never runs. */
   if?: string
+  /** The declaring plugin's paths, exported to the hook process. Claude: "All three
+   * are exported as environment variables to hook processes and to MCP and LSP server
+   * subprocesses", so a script can read them instead of relying on inline substitution. */
+  pluginRoot?: string
+  pluginDataDir?: string
   /** http entries: the endpoint POSTed to; `command` mirrors it for dedup and display. */
   url?: string
   headers?: Record<string, string>
@@ -181,7 +186,18 @@ function stampOrigin(entries: HookMatcher[], origin: string): void {
   }
 }
 
-function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>, origin?: string): void {
+/** Stamp the declaring plugin's paths onto every hook it contributes, so the runner
+ * can export them without re-deriving which plugin a hook came from. */
+function stampPluginPaths(entries: HookMatcher[], plugin: { root: string; dataDir: string }): void {
+  for (const entry of entries) {
+    for (const hook of entry.hooks ?? []) {
+      hook.pluginRoot = plugin.root
+      hook.pluginDataDir = plugin.dataDir
+    }
+  }
+}
+
+function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>, origin?: string, plugin?: { root: string; dataDir: string }): void {
   let parsed: { hooks?: HooksConfig }
   try {
     parsed = JSON.parse(raw)
@@ -200,6 +216,7 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
     const usable = matchers.filter((entry) => isUsableMatcher(entry, source, event))
     if (usable.length === 0) continue
     if (origin !== undefined) stampOrigin(usable, origin)
+    if (plugin !== undefined) stampPluginPaths(usable, plugin)
     config[event] = [...(config[event] ?? []), ...usable]
     // Each parse produces fresh entry objects, so object identity keys the /hooks
     // viewer's source attribution without touching the entries themselves.
@@ -261,13 +278,13 @@ export function loadPluginHooks(config: HooksConfig, plugins: InstalledPlugin[],
     // silently registering nothing.
     if (declared !== null && typeof declared === 'object' && !Array.isArray(declared)) {
       const inlineSource = `${plugin.name} (plugin.json)`
-      mergeHooksJson(config, substitutePluginVars(withoutUserConfigShellCommands(JSON.stringify({ hooks: declared }), inlineSource), plugin, jsonEscape), inlineSource, sources, `plugin:${plugin.name}`)
+      mergeHooksJson(config, substitutePluginVars(withoutUserConfigShellCommands(JSON.stringify({ hooks: declared }), inlineSource), plugin, jsonEscape), inlineSource, sources, `plugin:${plugin.name}`, plugin)
       continue
     }
     const file = pluginComponentPath(plugin, typeof declared === 'string' ? declared : path.join('hooks', 'hooks.json'))
     if (file === undefined) continue
     try {
-      mergeHooksJson(config, substitutePluginVars(withoutUserConfigShellCommands(fs.readFileSync(file, 'utf-8'), file), plugin, jsonEscape), file, sources, `plugin:${plugin.name}`)
+      mergeHooksJson(config, substitutePluginVars(withoutUserConfigShellCommands(fs.readFileSync(file, 'utf-8'), file), plugin, jsonEscape), file, sources, `plugin:${plugin.name}`, plugin)
     } catch {
       // a plugin without hooks contributes nothing
     }

package/extensions/hooks/index.ts

@@ -102,7 +102,7 @@ import { readManagedSettings } from '../internal/managed-settings.js'
 import { isMcpToolAliases, MCP_TOOLS_CHANNEL } from '../internal/mcp-alias.js'
 import { resolveModelOverride } from '../internal/model-lookup.js'
 import { isPlanModeState, PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
-import { installedPlugins } from '../internal/plugins.js'
+import { installedPlugins, managedForceEnabled } from '../internal/plugins.js'
 import { isProjectApproved } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
 import { watchSettingsFiles } from '../internal/settings-watch.js'
@@ -283,7 +283,7 @@ export default function hooksExtension(pi: ExtensionAPI) {
         if (hook.type === 'prompt') return runPromptHook(hook, merged, resolveHookModel(ctx, hook.model), ms)
         if (hook.type === 'agent') return runAgentHook(hook, merged, ms, (ctx.model as { id?: string } | undefined)?.id)
         if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
-        return runHookCommand(hook.command, merged, ms, projectDir, hook.args, onChild, hook.shell)
+        return runHookCommand(hook.command, merged, ms, { projectDir, args: hook.args, onChild, shell: hook.shell, plugin: hook.pluginRoot !== undefined && hook.pluginDataDir !== undefined ? { root: hook.pluginRoot, dataDir: hook.pluginDataDir } : undefined })
       }
       // Claude's `once` (skill-frontmatter hooks only): removed after the first
       // successful run; a failure, block, or timeout leaves it in place.
@@ -414,7 +414,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // Claude's allowManagedHooksOnly: user, project, local, plugin, and skill
     // hooks are blocked; only the managed set runs.
     managedHooksOnly = managedSettings.allowManagedHooksOnly === true
-    if (managedHooksOnly || readSettingsDisableAllHooks(files)) return
+    // The escape hatch is checked FIRST, and deliberately: a settings-level
+    // disableAllHooks turns off every non-managed hook, and a plugin's hooks are
+    // non-managed however the plugin came to be enabled. Only the managed policy hooks
+    // loaded above survive it. Putting the force-enable exemption ahead of this let an
+    // administrator's enabledPlugins entry defeat the user's own escape hatch.
+    if (readSettingsDisableAllHooks(files)) return
+    if (managedHooksOnly) {
+      // Claude: "Hooks from plugins force-enabled in managed settings `enabledPlugins`
+      // are exempt." That exemption is from allowManagedHooksOnly, not from the hatch.
+      loadPluginHooks(config, managedForceEnabled(installedPlugins(os.homedir())), hookSources)
+      return
+    }
     for (const [eventName, matchers] of Object.entries(loadHooks(files, hookSources))) config[eventName] = [...(config[eventName] ?? []), ...matchers]
     // Plugins are user-installed and enabled by user settings (see installedPlugins),
     // so a checked-out repo cannot toggle which code-bearing plugin hooks run.

package/extensions/hooks/matcher.ts

@@ -5,7 +5,9 @@
  */
 
 import { matchesBashIfFilter } from '../internal/bash-rules.js'
+import { CLAUDE_TOOL_MAP } from '../internal/claude-tool-names.js'
 import { matchesPathRules, type PathAnchors } from '../internal/path-rules.js'
+import { agentNamesIn, matchesAgentRules, matchesDomainRules, matchesSkillRules } from '../internal/scope-rules.js'
 import { errorMessage } from '../internal/values.js'
 import type { HookCommand, HookMatcher } from './config.js'
 
@@ -179,13 +181,39 @@ export function passesIfFilter(hook: HookCommand, target: IfFilterTarget | undef
   if (!toolMatches) return false
   const pattern = parsed[2]
   if (pattern === undefined) return true
-  const input = target.input as Record<string, unknown> | null
-  if (fold(target.piName) === 'bash' || (target.claudeName !== undefined && fold(target.claudeName) === 'bash')) {
-    const command = typeof input?.command === 'string' ? input.command : ''
-    return command.length > 0 && matchesBashIfFilter(command, pattern)
+  // Either spelling can arrive; normalize to the pi name the specifier engines take.
+  const tool = CLAUDE_TOOL_MAP[fold(target.piName)] ?? CLAUDE_TOOL_MAP[fold(target.claudeName ?? '')] ?? fold(target.piName)
+  return matchesToolPattern(tool, target.input as Record<string, unknown> | null, pattern, target.anchors)
+}
+
+/** One `if` pattern against a call's arguments. Claude evaluates the rule "against
+ * the tool name and arguments together" in permission-rule syntax, so each tool uses
+ * the same specifier engine its permission rules use:
+ *
+ * PAIRED WITH commands.ts's tool_call guard, which dispatches the same tools to the
+ * same matchers for `allowed-tools` scopes. The two are deliberately NOT merged: bash
+ * differs on purpose (an allow scope requires every segment to match, an `if` filter is
+ * best effort and errs toward running the hook), and merging would hide that. They are
+ * two lists that must agree, so a new scoped tool has to be added in both places; the
+ * shared roster is ARG_RULE_TOOLS in internal/command-file.ts.
+ * a command pattern for Bash, a
+ * `domain:` host for WebFetch, an agent name for Agent, a skill name for Skill, and a
+ * path rule for the file tools. A tool with no specifier syntax matches nothing,
+ * which is also what an unparseable rule does. */
+function matchesToolPattern(piName: string, input: Record<string, unknown> | null, pattern: string, anchors: PathAnchors): boolean {
+  const str = (value: unknown): string => (typeof value === 'string' ? value : '')
+  switch (piName) {
+    case 'bash':
+      return str(input?.command).length > 0 && matchesBashIfFilter(str(input?.command), pattern)
+    case 'web_fetch':
+      return matchesDomainRules(str(input?.url), [pattern])
+    case 'subagent':
+      return matchesAgentRules(agentNamesIn(input), [pattern])
+    case 'slash_command':
+      return matchesSkillRules(str(input?.command), [pattern])
+    default: {
+      const filePath = str(input?.path) || str(input?.file_path)
+      return filePath.length > 0 && matchesPathRules(filePath, [pattern], anchors)
+    }
   }
-  let filePath = ''
-  if (typeof input?.path === 'string') filePath = input.path
-  else if (typeof input?.file_path === 'string') filePath = input.file_path
-  return filePath.length > 0 && matchesPathRules(filePath, [pattern], target.anchors)
 }

package/extensions/hooks/runners.ts

@@ -5,6 +5,7 @@
  */
 
 import { type ChildProcess, spawn } from 'node:child_process'
+import * as fs from 'node:fs'
 import * as path from 'node:path'
 import type { Api, Model } from '@earendil-works/pi-ai'
 import { runAgent } from '../internal/agent-run.js'
@@ -44,7 +45,20 @@ export type HookRunner = (hook: HookCommand, payload: unknown, timeoutMs: number
  * `args` array it becomes the exec path: `command` is spawned directly with those args.
  * `onChild` hands the caller a kill for the spawned tree, so a background hook that is
  * still running at session end can be reaped (Claude kills async hooks at teardown). */
-export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, projectDir?: string, args?: string[], onChild?: (kill: () => void) => void, shell?: string) => Promise<HookRunResult>
+/** How one command hook is spawned, beyond the payload and its budget. Grouped rather
+ * than trailing off the parameter list: the exec form, the shell choice and the
+ * declaring plugin are all per-hook fields that arrive together from one HookCommand. */
+export interface HookSpawnOptions {
+  projectDir?: string
+  /** exec-form argv; shell-form when absent. */
+  args?: string[]
+  onChild?: (kill: () => void) => void
+  shell?: string
+  /** The declaring plugin's paths, exported to the child. */
+  plugin?: { root: string; dataDir: string }
+}
+
+export type HookCommandRunner = (command: string, payload: unknown, timeoutMs: number, options?: HookSpawnOptions) => Promise<HookRunResult>
 
 /** Above 2^31-1 ms Node clamps a timer to 1ms, which would kill the hook instantly. */
 const MAX_TIMEOUT_S = 2_147_483
@@ -104,6 +118,17 @@ function killTree(child: ChildProcess): void {
   child.kill('SIGKILL')
 }
 
+/** Create the plugin data directory the moment its path is handed to a child. Claude
+ * describes it as "created on first reference"; a best-effort mkdir, since a hook whose
+ * data dir cannot be created should still run. */
+function ensureDir(dir: string): void {
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+  } catch {
+    // The hook runs anyway; a script that needs the directory reports its own failure.
+  }
+}
+
 /** The shell invocation for a shell-form command, or undefined when this machine has no
  * shell for it (Windows with neither Git Bash nor PowerShell). */
 function shellInvocation(command: string, shell: string | undefined): { file: string; spawnArgs: string[] } | undefined {
@@ -111,7 +136,7 @@ function shellInvocation(command: string, shell: string | undefined): { file: st
   return resolved ? { file: resolved.file, spawnArgs: resolved.argsFor(command) } : undefined
 }
 
-export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, projectDir, args, onChild, shell) =>
+export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, { projectDir, args, onChild, shell, plugin } = {}) =>
   new Promise((resolve) => {
     // /bin/sh by absolute path off Windows, so the shell can't be resolved through an
     // attacker-controlled PATH; on Windows the resolver follows Claude's documented Git
@@ -125,6 +150,15 @@ export const runHookCommand: HookCommandRunner = (command, payload, timeoutMs, p
     // detection cannot see the captured terminal.
     const env: NodeJS.ProcessEnv = { ...process.env, CLAUDECODE: '1', CLAUDE_CODE_CHILD_SESSION: '1' }
     if (projectDir) env.CLAUDE_PROJECT_DIR = projectDir
+    // Claude: "All three are exported as environment variables to hook processes and to
+    // MCP and LSP server subprocesses", so a plugin script can read them rather than
+    // depend on inline substitution. The data directory is "created on first reference",
+    // and exporting the path is that reference: a script should not have to mkdir it.
+    if (plugin) {
+      env.CLAUDE_PLUGIN_ROOT = plugin.root
+      env.CLAUDE_PLUGIN_DATA = plugin.dataDir
+      ensureDir(plugin.dataDir)
+    }
     if (process.stdout.columns) env.COLUMNS = String(process.stdout.columns)
     if (process.stdout.rows) env.LINES = String(process.stdout.rows)
     // An exec-form hook (an `args` array) spawns the executable directly with those args

package/extensions/internal/claude-tool-names.ts

@@ -0,0 +1,70 @@
+/**
+ * The one place pi tool names and Claude tool names are paired.
+ *
+ * Two independent tables used to encode this: a Claude->pi map for resolving
+ * `allowed-tools` entries, and a pi->Claude map for hook payloads and matchers.
+ * They disagreed. The second one listed six tools, so a hook matcher written in
+ * Claude's vocabulary never fired for `web_fetch`, `subagent`, `question`, `todo`,
+ * `slash_command`, `web_search` or `plan_mode_complete`, even though the first table
+ * had known those pairings all along. Both directions now derive from this list, so
+ * a tool cannot be nameable in one direction and invisible in the other.
+ *
+ * Canonical names are the tools reference's own spellings. `claude: null` marks a pi
+ * tool the reference has no counterpart for: it stays untranslated in payloads, and
+ * no Claude name resolves to it beyond its own spelling.
+ *
+ * Input SHAPES are a separate question and deliberately not driven from here. The
+ * hooks reference documents per-tool input tables only for the file and shell tools,
+ * so those are the only ones claude-tools.ts translates; for the rest there is no
+ * documented Claude shape to conform to and the pi input is passed through.
+ */
+
+interface ToolNamePair {
+  /** Canonical Claude tool name, or null when the reference has no such tool. */
+  claude: string | null
+  /** pi's registered tool name. */
+  pi: string
+  /** Further Claude spellings accepted when reading a grant: renamed tools and
+   * secondary tools that share one pi implementation. Never used for payloads. */
+  aliases?: string[]
+}
+
+const TOOL_NAMES: ToolNamePair[] = [
+  { claude: 'Read', pi: 'read' },
+  { claude: 'Write', pi: 'write' },
+  { claude: 'Edit', pi: 'edit' },
+  { claude: 'Bash', pi: 'bash' },
+  { claude: 'Grep', pi: 'grep' },
+  { claude: 'Glob', pi: 'find' },
+  { claude: 'WebFetch', pi: 'web_fetch' },
+  { claude: 'WebSearch', pi: 'web_search' },
+  // `Task` was renamed `Agent`; both spellings resolve, the payload reports `Agent`.
+  { claude: 'Agent', pi: 'subagent', aliases: ['Task'] },
+  { claude: 'AskUserQuestion', pi: 'question' },
+  { claude: 'ExitPlanMode', pi: 'plan_mode_complete' },
+  // Custom commands were folded into skills and the reference no longer lists a
+  // SlashCommand tool, so `Skill` is canonical and `SlashCommand` is the legacy name.
+  { claude: 'Skill', pi: 'slash_command', aliases: ['SlashCommand'] },
+  // pi's single todo tool serves Claude's whole todo/task-list family. Claude now
+  // prefers TaskCreate/TaskGet/TaskList/TaskUpdate over TodoWrite/TodoRead; every
+  // spelling resolves so an allowed-tools entry naming the current tools still grants
+  // something, and TodoWrite stays the name a payload reports.
+  { claude: 'TodoWrite', pi: 'todo', aliases: ['TodoRead', 'TaskCreate', 'TaskGet', 'TaskList', 'TaskUpdate'] },
+  // pi tools the tools reference has no entry for.
+  { claude: null, pi: 'ls', aliases: ['LS'] },
+]
+
+const fold = (name: string): string => name.trim().toLowerCase()
+
+/** Every Claude spelling -> pi tool name, for reading a grant list. Includes each
+ * pi name itself so a list written in pi's own vocabulary still resolves. */
+export const CLAUDE_TOOL_MAP: Record<string, string> = Object.fromEntries(TOOL_NAMES.flatMap(({ claude, pi, aliases }) => [...(claude === null ? [] : [[fold(claude), pi]]), ...(aliases ?? []).map((alias) => [fold(alias), pi]), [fold(pi), pi]]))
+
+const PI_TO_CLAUDE: Record<string, string> = Object.fromEntries(TOOL_NAMES.filter((pair): pair is ToolNamePair & { claude: string } => pair.claude !== null).map(({ claude, pi }) => [pi, claude]))
+
+/** pi built-in -> canonical Claude tool name for hook payloads and matchers, or
+ * undefined for a pi tool the reference has no counterpart for. MCP tools ride the
+ * alias bus instead and never reach here. */
+export function claudeToolName(piName: string): string | undefined {
+  return PI_TO_CLAUDE[piName]
+}