pi-code 1.0.28 → 1.0.30

package/extensions/hooks/config.ts

@@ -41,6 +41,14 @@ export interface HookCommand {
   /** prompt/agent entries: an optional model override; agent adds a system prompt. */
   model?: string
   systemPrompt?: string
+  /** Dedup scope: unset for settings files (identical handlers collapse across
+   * them); a plugin's or skill's copy carries its origin and stays separate. */
+  origin?: string
+  /** Claude's `once`: remove after the first successful run. Honored only for
+   * skill-frontmatter hooks; ignored in settings files and agent frontmatter. */
+  once?: boolean
+  /** Set after a once-hook's first successful run; collection skips spent hooks. */
+  spent?: boolean
 }
 export interface HookMatcher {
   matcher?: string
@@ -73,7 +81,13 @@ export function hookFiles(cwd: string, home: string, trusted: boolean): string[]
  * disabled in their own settings would defeat the escape hatch. The chain itself
  * already gates project files on trust (see hookFiles). */
 export function readDisableAllHooks(files: string[], managed: Record<string, unknown> = readManagedSettings()): boolean {
-  if (managed.disableAllHooks === true) return true
+  return managed.disableAllHooks === true || readSettingsDisableAllHooks(files)
+}
+
+/** The settings-chain half of disableAllHooks alone. Claude: user/project/local
+ * disableAllHooks cannot disable hooks configured through managed policy settings,
+ * so the caller keeps managed hooks running when only this half is set. */
+export function readSettingsDisableAllHooks(files: string[]): boolean {
   for (const file of files) {
     try {
       const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'))
@@ -85,6 +99,22 @@ export function readDisableAllHooks(files: string[], managed: Record<string, unk
   return false
 }
 
+/** Hooks from managed policy settings, one of Claude's hook locations. They run
+ * even when user/project/local disableAllHooks is set; only the managed level's
+ * own disableAllHooks turns them off (the caller checks that tier). */
+export function loadManagedHooks(sources?: Map<HookMatcher, string>, managed: Record<string, unknown> = readManagedSettings()): HooksConfig {
+  const config: HooksConfig = {}
+  if (isRecord(managed.hooks)) mergeHooksJson(config, JSON.stringify({ hooks: managed.hooks }), 'managed settings', sources)
+  return config
+}
+
+/** Hooks a skill's frontmatter declares, registered when the skill is invoked and
+ * kept for the rest of the session, as Claude documents. They carry a skill origin
+ * so dedup keeps them separate from settings copies and `once` is honored. */
+export function mergeSkillHooks(config: HooksConfig, skillName: string, hooks: unknown, sources?: Map<HookMatcher, string>): void {
+  mergeHooksJson(config, JSON.stringify({ hooks }), `${skillName} (skill)`, sources, `skill:${skillName}`)
+}
+
 /** Claude's `allowedHttpHookUrls` setting: URL patterns http hooks may target, with
  * `*` as a wildcard. Per Claude's documentation: undefined (no source sets the key)
  * means no restrictions, an empty array blocks every http hook, and arrays merge
@@ -135,7 +165,15 @@ export function loadHooks(files: string[], sources?: Map<HookMatcher, string>):
   return config
 }
 
-function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>): void {
+/** Claude dedups identical handlers across settings files only; a plugin's copy
+ * stays separate, so plugin entries carry their origin into the dedup key. */
+function stampOrigin(entries: HookMatcher[], origin: string): void {
+  for (const entry of entries) {
+    for (const hook of entry.hooks ?? []) hook.origin = origin
+  }
+}
+
+function mergeHooksJson(config: HooksConfig, raw: string, source: string, sources?: Map<HookMatcher, string>, origin?: string): void {
   let parsed: { hooks?: HooksConfig }
   try {
     parsed = JSON.parse(raw)
@@ -150,6 +188,7 @@ function mergeHooksJson(config: HooksConfig, raw: string, source: string, source
     // call for the rest of the session failed with an opaque type error.
     const usable = matchers.filter((entry) => isUsableMatcher(entry, source, event))
     if (usable.length === 0) continue
+    if (origin !== undefined) stampOrigin(usable, origin)
     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.
@@ -167,12 +206,12 @@ export function loadPluginHooks(config: HooksConfig, plugins: InstalledPlugin[],
     // numeric event keys), so it falls through to the default path rather than
     // silently registering nothing.
     if (declared !== null && typeof declared === 'object' && !Array.isArray(declared)) {
-      mergeHooksJson(config, substitutePluginVars(JSON.stringify({ hooks: declared }), plugin), `${plugin.name} (plugin.json)`, sources)
+      mergeHooksJson(config, substitutePluginVars(JSON.stringify({ hooks: declared }), plugin), `${plugin.name} (plugin.json)`, sources, `plugin:${plugin.name}`)
       continue
     }
     const file = path.resolve(plugin.root, typeof declared === 'string' ? declared : path.join('hooks', 'hooks.json'))
     try {
-      mergeHooksJson(config, substitutePluginVars(fs.readFileSync(file, 'utf-8'), plugin), file, sources)
+      mergeHooksJson(config, substitutePluginVars(fs.readFileSync(file, 'utf-8'), plugin), file, sources, `plugin:${plugin.name}`)
     } catch {
       // a plugin without hooks contributes nothing
     }

package/extensions/hooks/index.ts

@@ -20,7 +20,12 @@
  * - Stop            -> pi `agent_end` (a block feeds its reason back as a new turn,
  *                      with stop_hook_active as the loop guard)
  * - PreCompact      -> pi `session_before_compact` (fire-and-forget)
- * - PostCompact     -> pi `session_compact` (fire-and-forget)
+ * - PostCompact     -> pi `session_compact` (fire-and-forget); the same event also
+ *                      fires SessionStart with source "compact", as Claude does
+ *                      when a session continues after compaction
+ * - PostModelSwitch -> pi `model_select` (after the change, matched against the new
+ *                      model id; stdout context rides the next agent start;
+ *                      PreModelSwitch stays unbridged, pi has no veto seam)
  * - PostToolUseFailure -> pi `tool_result` error branch (stderr/additionalContext
  *                      appended to the failed result; it cannot block, the tool failed)
  * - SessionEnd      -> pi `session_shutdown` (fire-and-forget)
@@ -68,12 +73,13 @@
  * `{"hookSpecificOutput": {"permissionDecision": "deny", ...}}` (or the older
  * `{"decision": "block"}`).
  *
- * Config is merged from ~/.claude/settings.json (always) plus the project's
- * .claude/settings.json and settings.local.json (only when the project is
- * trusted, since hooks execute arbitrary shell). Claude's `disableAllHooks`
- * setting (managed settings or any honored file in that chain) short-circuits
- * the load entirely, so no event fires any hook; /hooks prints the resolved
- * chain per event with each entry's source settings file. Matchers follow Claude's rule:
+ * Config is merged from managed policy settings, ~/.claude/settings.json (always),
+ * the project's .claude/settings.json and settings.local.json (only when the
+ * project is trusted, since hooks execute arbitrary shell), plugins, and invoked
+ * skills' frontmatter. Claude's `disableAllHooks` is tiered: at the managed level
+ * it turns everything off; in any honored settings file it disables the
+ * non-managed hooks while managed policy hooks keep running. /hooks prints the
+ * resolved chain per event with each entry's source. Matchers follow Claude's rule:
  * `*`/empty match all, plain names are exact (with `|`/`,` list separators), and
  * anything with other regex characters is an unanchored regex. Claude matchers
  * are PascalCase (`Bash`); pi tool names are lowercase (`bash`), so comparison
@@ -85,14 +91,16 @@
 import * as os from 'node:os'
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { INSTRUCTIONS_CHANNEL, isInstructionLoadEvent } from '../internal/instruction-events.js'
+import { readManagedSettings } from '../internal/managed-settings.js'
 import { isMcpToolAliases, MCP_TOOLS_CHANNEL } from '../internal/mcp-alias.js'
 import { isPlanModeState, PLAN_MODE_CHANNEL } from '../internal/plan-mode-state.js'
 import { installedPlugins } from '../internal/plugins.js'
 import { isProjectApproved } from '../internal/project-approval.js'
 import { repoRoot } from '../internal/project-root.js'
+import { isSkillHooksEvent, SKILL_HOOKS_CHANNEL } from '../internal/skill-hooks.js'
 import { isSubagentPhaseEvent, SUBAGENT_CHANNEL } from '../internal/subagent-events.js'
 import { claudeToolInput, claudeToolName, claudeToolResponse, piToolOutput } from './claude-tools.js'
-import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadPluginHooks, readAllowedHttpHookUrls, readDisableAllHooks } from './config.js'
+import { formatHooksSummary, type HookCommand, type HookMatcher, type HooksConfig, hookFiles, isBackgroundHook, loadHooks, loadManagedHooks, loadPluginHooks, mergeSkillHooks, readAllowedHttpHookUrls, readDisableAllHooks, readSettingsDisableAllHooks } from './config.js'
 import { blockedToolCall, jsonBlockVerdict, postToolFeedback, promptContext, runPreToolUse, runUserPromptSubmit, surfaceSystemMessages, tryParseJson } from './decisions.js'
 import { allCommands, matchingCommands, passesIfFilter } from './matcher.js'
 import { type HookRunner, type HookRunResult, runAgentHook, runHookCommand, runHttpHook, runMcpToolHook, runPromptHook, sessionEndTimeoutMs, timeoutMs } from './runners.js'
@@ -160,6 +168,15 @@ function claudeSpelling(map: Record<string, string>, raw: string): { names: stri
   return { names: value === raw ? [raw] : [raw, value], value }
 }
 
+/** Claude: idle_prompt fires when "Claude finished responding about 60 seconds ago
+ * and you haven't typed since". */
+const IDLE_PROMPT_DELAY_MS = 60_000
+
+/** pi's model_select sources in Claude's PostModelSwitch vocabulary: an explicit
+ * set is a command-style request, cycling is the picker, and restore is the model
+ * Claude Code restores on resume. */
+const MODEL_SELECT_SOURCE: Record<string, string> = { set: 'command', cycle: 'picker', restore: 'resume' }
+
 export default function hooksExtension(pi: ExtensionAPI) {
   let config: HooksConfig = {}
   let projectDir = ''
@@ -170,6 +187,14 @@ export default function hooksExtension(pi: ExtensionAPI) {
   /** Consecutive Stop-hook blocks with no user progress between them. Reset on user input
    * and on a non-blocking Stop; at the cap the continuation is suppressed and the turn ends. */
   let stopHookBlockCount = 0
+  /** The pending idle_prompt notification: Claude fires it when the turn ended about
+   * 60 seconds ago and the user hasn't typed since, so it arms on agent_end and is
+   * canceled by input or the next turn. */
+  let idlePromptTimer: ReturnType<typeof setTimeout> | undefined
+  const cancelIdlePrompt = (): void => {
+    clearTimeout(idlePromptTimer)
+    idlePromptTimer = undefined
+  }
   let sessionCtx: ExtensionContext | undefined
   /** Claude's disableAllHooks escape hatch was set somewhere in the honored chain. */
   let hooksDisabled = false
@@ -235,7 +260,14 @@ export default function hooksExtension(pi: ExtensionAPI) {
         if (hook.type === 'mcp_tool') return runMcpToolHook(hook, merged, ms)
         return runHookCommand(hook.command, merged, ms, projectDir, hook.args, onChild)
       }
-      if (!isBackgroundHook(hook)) return dispatch()
+      // Claude's `once` (skill-frontmatter hooks only): removed after the first
+      // successful run; a failure, block, or timeout leaves it in place.
+      const markOnce = async (run: Promise<HookRunResult>): Promise<HookRunResult> => {
+        const result = await run
+        if (hook.once === true && hook.origin?.startsWith('skill:') === true && result.code === 0 && !result.timedOut) hook.spent = true
+        return result
+      }
+      if (!isBackgroundHook(hook)) return markOnce(dispatch())
       let kill: (() => void) | undefined
       void dispatch((registered) => {
         kill = registered
@@ -252,6 +284,15 @@ export default function hooksExtension(pi: ExtensionAPI) {
         })
       return Promise.resolve({ code: 0, stdout: '', stderr: '', timedOut: false })
     }
+  // Hooks a skill's frontmatter declares arrive over the shared bus when the skill
+  // is invoked (see skills.ts) and stay registered for the rest of the session, as
+  // Claude documents; a session restart reloads config and drops them.
+  pi.events.on(SKILL_HOOKS_CHANNEL, (data) => {
+    if (!isSkillHooksEvent(data)) return
+    if (hooksDisabled) return
+    mergeSkillHooks(config, data.skillName, data.hooks, hookSources)
+  })
+
   // Claude matchers name MCP tools mcp__<server>__<tool>; pi-code registers them as
   // <server>_<tool>. The mcp extension publishes the mapping on pi's shared bus.
   const mcpAliases = new Map<string, string>()
@@ -323,15 +364,23 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const files = hookFiles(ctx.cwd, os.homedir(), trusted)
     hookSources.clear()
     allowedHttpHookUrls = readAllowedHttpHookUrls(files)
-    // The disableAllHooks escape hatch, checked before any config loads: with no
-    // config resolved, no event, plugin hooks included, can fire a hook.
-    hooksDisabled = readDisableAllHooks(files)
-    if (hooksDisabled) {
+    // The disableAllHooks escape hatch, checked before any config loads. The tiers
+    // differ, as Claude documents: managed-level disableAllHooks turns everything
+    // off, while a settings-level one cannot disable the hooks an administrator
+    // configured through managed policy settings.
+    const managedSettings = readManagedSettings()
+    hooksDisabled = readDisableAllHooks(files, managedSettings)
+    if (managedSettings.disableAllHooks === true) {
       config = {}
       pendingSessionContext = []
       return
     }
-    config = loadHooks(files, hookSources)
+    config = loadManagedHooks(hookSources, managedSettings)
+    if (readSettingsDisableAllHooks(files)) {
+      pendingSessionContext = []
+      return
+    }
+    for (const [event, matchers] of Object.entries(loadHooks(files, hookSources))) config[event] = [...(config[event] ?? []), ...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.
     loadPluginHooks(config, installedPlugins(os.homedir()), hookSources)
@@ -353,6 +402,8 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // over the bus from context-imports, which owns claudeMdExcludes; announcing
   // the raw contextFiles here would fire for a file the exclusion removed.
   pi.on('before_agent_start', async () => {
+    // A new turn is beginning, so the session is no longer idle.
+    cancelIdlePrompt()
     if (pendingSessionContext.length === 0) return
     const content = pendingSessionContext.join('\n')
     pendingSessionContext = []
@@ -452,6 +503,8 @@ export default function hooksExtension(pi: ExtensionAPI) {
     // Only genuine user input; extension-injected messages (plan-mode, subagent) are not
     // prompts the user submitted.
     if (event.source === 'extension') return { action: 'continue' }
+    // The user typed, so the pending idle_prompt no longer applies.
+    cancelIdlePrompt()
     // Genuine user input is progress, so it breaks a Stop-hook continuation streak: the
     // block cap counts only consecutive blocks with nothing from the user in between.
     stopHookBlockCount = 0
@@ -479,11 +532,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
   // automatic retry or compaction; that is the better tradeoff.
   pi.on('agent_end', async (event, ctx) => {
     // Claude's Notification event, for the one type pi can honestly source: the
-    // agent finished and is waiting for input (idle_prompt). Observational only;
-    // exit codes and JSON output are ignored, as Claude documents for this event.
+    // agent finished and is waiting for input. Per Claude, idle_prompt fires when
+    // the turn ended about 60 seconds ago and the user hasn't typed since, so it
+    // arms here and input or the next turn cancels it. Observational only; exit
+    // codes and JSON output are ignored, as Claude documents for this event.
+    cancelIdlePrompt()
     const notifyCommands = matchingCommands(config.Notification, ['idle_prompt'])
     if (notifyCommands.length > 0) {
-      void runNotifyHooks(notifyCommands, { hook_event_name: 'Notification', notification_type: 'idle_prompt', message: 'pi is waiting for your input' }, boundRunner(ctx)).catch(() => {})
+      const runner = boundRunner(ctx)
+      idlePromptTimer = setTimeout(() => {
+        void runNotifyHooks(notifyCommands, { hook_event_name: 'Notification', notification_type: 'idle_prompt', message: 'pi is waiting for your input' }, runner).catch(() => {})
+      }, IDLE_PROMPT_DELAY_MS)
+      idlePromptTimer.unref?.()
     }
 
     // Stop has no matcher support (a stray matcher is ignored, as Claude documents)
@@ -557,6 +617,33 @@ export default function hooksExtension(pi: ExtensionAPI) {
     const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
     const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), { hook_event_name: 'PostCompact', trigger: trigger.value }, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    // Claude also fires SessionStart with source "compact" when the session
+    // continues after compaction; its stdout context rides the next agent start,
+    // the same as any other SessionStart context.
+    const sessionStart = matchingCommands(config.SessionStart, 'compact')
+    if (sessionStart.length > 0) {
+      const startResults = await runNotifyHooks(sessionStart, { hook_event_name: 'SessionStart', source: 'compact' }, boundRunner(ctx))
+      surfaceSystemMessages(startResults, (message) => ctx.ui.notify(message, 'warning'))
+      pendingSessionContext.push(...startResults.map((result) => promptContext(result.stdout)).filter(Boolean))
+    }
+  })
+
+  pi.on('model_select', async (event, ctx) => {
+    // Claude's PostModelSwitch: runs after the session's model changes, matched
+    // against the model switched to; it can't block. PreModelSwitch stays
+    // unbridged: pi's model_select has no veto seam, and a "Pre" hook whose block
+    // decision is silently ignored would be worse than an absent event.
+    const { model, previousModel, source } = event as { model: { id: string }; previousModel?: { id: string }; source: string }
+    if (!previousModel || previousModel.id === model.id) return
+    const commands = matchingCommands(config.PostModelSwitch, model.id)
+    if (commands.length === 0) return
+    // requested_model is null: pi does not carry the alias the request named.
+    const payload = { hook_event_name: 'PostModelSwitch', from_model: previousModel.id, to_model: model.id, requested_model: null, source: MODEL_SELECT_SOURCE[source] ?? 'command' }
+    const results = await runNotifyHooks(commands, payload, boundRunner(ctx))
+    surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
+    // Claude delivers the hook's stdout (or additionalContext) to Claude with the
+    // next request after the switch; pi's seam for that is the next agent start.
+    pendingSessionContext.push(...results.map((result) => promptContext(result.stdout)).filter(Boolean))
   })
 
   pi.on('session_shutdown', async (event, ctx) => {
@@ -579,7 +666,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
   pi.registerCommand('hooks', {
     description: 'Show the hook configuration resolved from settings',
     handler: async (_args, ctx) => {
-      if (hooksDisabled) {
+      // With a settings-level disable, managed policy hooks stay active and the
+      // viewer still shows them; only a fully empty config reports disabled.
+      if (hooksDisabled && Object.keys(config).length === 0) {
         ctx.ui.notify('All hooks are disabled by the disableAllHooks setting.', 'info')
         return
       }

package/extensions/hooks/matcher.ts

@@ -104,8 +104,14 @@ function syntheticCommand(hook: HookCommand): string | undefined {
 /** A matched entry with its `command` filled in: mirroring the synthetic identity into
  * `command` keeps dedup, timeout messages and display working for non-shell hooks. */
 function withCommand(raw: HookCommand): HookCommand {
-  const identity = syntheticCommand(raw)
-  return identity !== undefined && typeof raw.command !== 'string' ? { ...raw, command: identity } : raw
+  // Fill the identity onto the config entry itself rather than a clone: the runner
+  // must receive the same object collection reads, so a once-hook marked spent
+  // after a successful run is the object the next collection filters out.
+  if (typeof raw.command !== 'string') {
+    const identity = syntheticCommand(raw)
+    if (identity !== undefined) raw.command = identity
+  }
+  return raw
 }
 
 function collectCommands(matchers: HookMatcher[] | undefined, applies: (entry: HookMatcher) => boolean): HookCommand[] {
@@ -114,10 +120,15 @@ function collectCommands(matchers: HookMatcher[] | undefined, applies: (entry: H
   for (const entry of matchers ?? []) {
     if (!applies(entry)) continue
     for (const raw of (entry.hooks ?? []).filter(isRunnableHook)) {
+      // A once-hook that already ran successfully is removed, as Claude documents.
+      if (raw.spent === true) continue
       const hook = withCommand(raw)
-      // Claude runs a handler defined in more than one settings file once.
-      if (seen.has(hook.command)) continue
-      seen.add(hook.command)
+      // Claude runs a handler defined in more than one settings file once; a
+      // plugin's or skill's copy of the same handler stays separate, and http
+      // handlers with the same URL but different headers are distinct.
+      const key = `${hook.origin ?? 'settings'}\n${hook.command}\n${hook.headers ? JSON.stringify(hook.headers) : ''}`
+      if (seen.has(key)) continue
+      seen.add(key)
       result.push(hook)
     }
   }

package/extensions/hooks/runners.ts

@@ -247,6 +247,33 @@ export async function runPromptHook(hook: HookCommand, payload: unknown, model:
   }
 }
 
+/** A dotted path into the hook's JSON input, or undefined when any step is missing. */
+function lookupPath(payload: unknown, dotted: string): unknown {
+  let current: unknown = payload
+  for (const key of dotted.split('.')) {
+    if (current === null || typeof current !== 'object') return undefined
+    current = (current as Record<string, unknown>)[key]
+  }
+  return current
+}
+
+/** Claude's ${path} substitution for mcp_tool input: string values may reference the
+ * hook's JSON input, such as ${tool_input.file_path}. Arrays and nested objects are
+ * walked; an unresolvable path stays literal; non-string looked-up values are
+ * JSON-encoded into the string. */
+function substituteInputPaths(value: unknown, payload: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.replace(/\$\{([\w.]+)\}/g, (matchText, dotted: string) => {
+      const found = lookupPath(payload, dotted)
+      if (found === undefined) return matchText
+      return typeof found === 'string' ? found : JSON.stringify(found)
+    })
+  }
+  if (Array.isArray(value)) return value.map((entry) => substituteInputPaths(entry, payload))
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, substituteInputPaths(entry, payload)]))
+  return value
+}
+
 /**
  * Claude's `type: "mcp_tool"` hook: call a tool on an already-connected MCP server
  * and treat its text output like command stdout. pi reaches the server through the
@@ -255,7 +282,9 @@ export async function runPromptHook(hook: HookCommand, payload: unknown, model:
  */
 export async function runMcpToolHook(hook: HookCommand, payload: unknown, timeoutMs: number): Promise<HookRunResult> {
   if (!hook.server || !hook.tool) return { code: 1, stdout: '', stderr: 'mcp_tool hook needs server and tool', timedOut: false }
-  const input = hook.input && typeof hook.input === 'object' ? hook.input : (payload as Record<string, unknown>)
+  // Claude: `input` is the arguments passed to the tool; without it the tool is
+  // called with no arguments, never handed the whole event payload.
+  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)

package/extensions/internal/skill-hooks.ts

@@ -0,0 +1,19 @@
+/**
+ * The bus channel skills.ts publishes frontmatter hooks on. Claude registers a
+ * skill's hooks when the skill is invoked and keeps them for the rest of the
+ * session; the hooks extension owns running them, so the skill side only
+ * announces the declaration.
+ */
+
+export const SKILL_HOOKS_CHANNEL = 'pi-code:skill-hooks'
+
+export interface SkillHooksEvent {
+  skillName: string
+  hooks: Record<string, unknown>
+}
+
+export function isSkillHooksEvent(data: unknown): data is SkillHooksEvent {
+  if (typeof data !== 'object' || data === null) return false
+  const event = data as { skillName?: unknown; hooks?: unknown }
+  return typeof event.skillName === 'string' && typeof event.hooks === 'object' && event.hooks !== null && !Array.isArray(event.hooks)
+}

package/extensions/skills.ts

@@ -30,6 +30,7 @@ import { claudeConfigDir } from './internal/config-dir.js'
 import { installedPlugins } from './internal/plugins.js'
 import { isProjectApprovedSilently } from './internal/project-approval.js'
 import { ancestorDirs } from './internal/project-root.js'
+import { SKILL_HOOKS_CHANNEL } from './internal/skill-hooks.js'
 
 function isDirectory(target: string): boolean {
   try {
@@ -139,14 +140,23 @@ async function expandSkillInvocation(pi: ExtensionAPI, rawText: string, ctx: Ext
   const found = findClaudeSkill(name, skillDirs(ctx.cwd, os.homedir(), trusted))
   if (!found) return
   let parsed: ReturnType<typeof parseCommandFile>
+  let content: string
   try {
-    parsed = parseCommandFile(fs.readFileSync(found.filePath, 'utf-8'))
+    content = fs.readFileSync(found.filePath, 'utf-8')
+    parsed = parseCommandFile(content)
   } catch {
     // Unreadable, or malformed frontmatter: pass through to pi's plain expansion
     // (the loader registered the skill and delivers the raw body), rather than
     // failing the invocation over the dynamic features it cannot have.
     return
   }
+  // Claude registers hooks a skill's frontmatter declares when the skill is
+  // invoked, for the rest of the session; the hooks extension owns running them,
+  // so the declaration is announced over the shared bus.
+  const declaredHooks = parseFrontmatter<Record<string, unknown>>(content).frontmatter.hooks
+  if (declaredHooks !== null && typeof declaredHooks === 'object' && !Array.isArray(declaredHooks)) {
+    pi.events?.emit(SKILL_HOOKS_CHANNEL, { skillName: name, hooks: declaredHooks })
+  }
   const expanded = await expandCommand(pi, parsed, args, { cwd: ctx.cwd }, found.filePath, undefined, { allowShell: !shellExecutionDisabled(ctx.cwd, os.homedir(), trusted) })
   return { action: 'transform', text: `<skill name="${name}" location="${found.filePath}">\nReferences are relative to ${found.baseDir}.\n\n${expanded}\n</skill>` }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "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, and subagents",
   "keywords": [
     "pi",