pi-code 1.0.29 → 1.0.31

package/extensions/hooks/config.ts

@@ -44,6 +44,11 @@ export interface HookCommand {
   /** 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
@@ -76,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'))
@@ -88,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

package/extensions/hooks/decisions.ts

@@ -19,9 +19,14 @@ export interface HookDecision {
   ask?: boolean
 }
 
+/** Claude's stdout shape rule: only output that starts with `{` and ends with `}`
+ * (ignoring surrounding whitespace) is read as JSON output; a JSON array, a quoted
+ * string, or a bare number is plain text. Multi-line output whose lines each parse
+ * as JSON on their own with no output field set is plain text too (that case
+ * arrives here as a parse failure and hookJsonError sorts it from a real error). */
 export function tryParseJson(text: string):
   | {
-      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown }
+      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string; additionalContext?: string; updatedInput?: unknown; suppressOriginalPrompt?: boolean }
       decision?: string
       reason?: string
       continue?: boolean
@@ -32,13 +37,58 @@ export function tryParseJson(text: string):
       ok?: boolean
     }
   | undefined {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return undefined
   try {
-    return JSON.parse(text)
+    const parsed: unknown = JSON.parse(trimmed)
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? (parsed as ReturnType<typeof tryParseJson>) : undefined
   } catch {
     return undefined
   }
 }
 
+/** Top-level JSON output fields; a multi-line output where a line sets one of
+ * these is a parse failure rather than plain text, as Claude documents. */
+const OUTPUT_FIELDS = new Set(['decision', 'reason', 'continue', 'stopReason', 'systemMessage', 'suppressOutput', 'hookSpecificOutput', 'updatedToolOutput', 'updatedMCPToolOutput', 'ok'])
+
+/** Claude reports a `<hook> hook error` notice when {..}-shaped stdout cannot be
+ * read as JSON output, and does not treat that stdout as plain text. Returns the
+ * error message for that case; undefined for valid JSON output and for output the
+ * shape rule already reads as plain text (including the multi-line case). */
+export function hookJsonError(text: string): string | undefined {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) return undefined
+  let parseError: string
+  try {
+    JSON.parse(trimmed)
+    return undefined
+  } catch (error) {
+    parseError = error instanceof Error ? error.message : String(error)
+  }
+  const lines = trimmed
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+  if (lines.length >= 2 && !multiLineSetsOutputField(lines)) return undefined
+  return `invalid JSON output: ${parseError}`
+}
+
+/** Whether every line parses as JSON and at least one sets an output field; a
+ * non-JSON line means the multi-line rule does not apply (still a parse error). */
+function multiLineSetsOutputField(lines: string[]): boolean {
+  let setsField = false
+  for (const line of lines) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(line)
+    } catch {
+      return true // not all-JSON: the whole output is a parse failure
+    }
+    if (parsed !== null && typeof parsed === 'object' && Object.keys(parsed).some((key) => OUTPUT_FIELDS.has(key))) setsField = true
+  }
+  return setsField
+}
+
 /** The reason a JSON body's blocking decision carries, whichever spelling made it. */
 function jsonBlockingReason(parsed: ReturnType<typeof tryParseJson>): string | undefined {
   if (parsed?.hookSpecificOutput?.permissionDecision === 'deny') return parsed.hookSpecificOutput.permissionDecisionReason
@@ -94,6 +144,10 @@ function surfaceHookFailures(commands: HookCommand[], results: HookRunResult[],
   if (!notify) return
   for (const [i, result] of results.entries()) {
     if (result.spawnFailed) notify(`Hook failed to run: ${commands[i].command}: ${result.stderr.trim() || 'unknown error'}`)
+    // Claude shows a `<hook> hook error` notice when {..}-shaped stdout cannot be
+    // read as JSON output (exit 2 still blocks and reads its own channels).
+    const jsonError = result.code === 2 ? undefined : hookJsonError(result.stdout)
+    if (jsonError !== undefined) notify(`${commands[i].command} hook error: ${jsonError}`)
   }
 }
 
@@ -196,6 +250,8 @@ export interface PromptDecision {
   block: boolean
   reason?: string
   context: string
+  /** Claude's suppressOriginalPrompt: the hook's context replaces the prompt. */
+  suppress?: boolean
 }
 
 /** Additional context a UserPromptSubmit hook contributes: an explicit
@@ -203,6 +259,8 @@ export interface PromptDecision {
 export function promptContext(stdout: string): string {
   const parsed = tryParseJson(stdout)
   if (parsed) return parsed.hookSpecificOutput?.additionalContext ?? ''
+  // Malformed JSON output is an error, not plain text: no context is added.
+  if (hookJsonError(stdout) !== undefined) return ''
   return stdout.trim()
 }
 
@@ -221,13 +279,17 @@ export async function runUserPromptSubmit(config: HooksConfig, prompt: string, r
   }
   if (onSystemMessage) surfaceSystemMessages(results, onSystemMessage)
   const contexts: string[] = []
+  let suppress = false
   for (const result of results) {
     const decision = interpretHookResult(result.code, result.stdout, result.stderr)
     if (decision.block) return { block: true, reason: decision.reason, context: '' }
+    // Claude's suppressOriginalPrompt: any hook setting it hides the original
+    // prompt, and the collected context is what reaches the model.
+    if (tryParseJson(result.stdout)?.hookSpecificOutput?.suppressOriginalPrompt === true) suppress = true
     const context = promptContext(result.stdout)
     if (context) contexts.push(context)
   }
-  return { block: false, context: contexts.join('\n') }
+  return { block: false, context: contexts.join('\n'), suppress }
 }
 
 /** The feedback lines one PostToolUse/PostToolUseFailure result appends next to the

package/extensions/hooks/index.ts

@@ -73,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
@@ -90,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'
@@ -184,6 +187,9 @@ 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
+  /** Tool start times per call id, for Claude's duration_ms on PostToolUse: the
+   * clock starts after PreToolUse hooks and any confirm dialog resolve. */
+  const toolStartTimes = new Map<string, number>()
   /** 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. */
@@ -257,7 +263,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
@@ -274,6 +287,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>()
@@ -345,15 +367,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)
@@ -390,13 +420,18 @@ export default function hooksExtension(pi: ExtensionAPI) {
       // additionalContext is delivered alongside the tool result, so stash it for
       // this call's tool_result to append.
       if (decision.context && decision.context.length > 0) pendingToolContext.set(event.toolCallId, decision.context)
+      // Claude's duration_ms excludes PreToolUse hook time, so the clock starts here.
+      toolStartTimes.set(event.toolCallId, Date.now())
       return undefined
     }
     // Claude's "ask": prompt the user and let the call through if they approve.
     // With no UI (headless) the block stands, which is the safe default.
     if (decision.ask && ctx.hasUI) {
       const approved = await ctx.ui.confirm(`Allow ${event.toolName}?`, decision.reason ?? 'A hook asks you to confirm this tool call.')
-      return approved ? undefined : blockedToolCall(decision.reason)
+      if (!approved) return blockedToolCall(decision.reason)
+      // Claude's duration_ms also excludes time in permission prompts.
+      toolStartTimes.set(event.toolCallId, Date.now())
+      return undefined
     }
     return blockedToolCall(decision.reason)
   })
@@ -424,7 +459,9 @@ export default function hooksExtension(pi: ExtensionAPI) {
     if (commands.length === 0 && pending.length === 0) return
     const translatedInput = alias === undefined ? claudeToolInput(event.toolName, event.input, ctx.cwd) : undefined
     const response = (alias === undefined && !event.isError ? claudeToolResponse(event.toolName, event.input, textContent(event.content), event.isError, ctx.cwd) : undefined) ?? { content: event.content, details: event.details, isError: event.isError }
-    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response }
+    const startedAt = toolStartTimes.get(event.toolCallId)
+    toolStartTimes.delete(event.toolCallId)
+    const payload = { hook_event_name: eventName, tool_name: translatedName ?? event.toolName, tool_input: translatedInput ?? event.input, tool_response: response, ...(startedAt === undefined ? {} : { duration_ms: Date.now() - startedAt }) }
     const run = boundRunner(ctx, { tool_use_id: event.toolCallId })
     const results = await Promise.all(commands.map((command) => run(command, payload, timeoutMs(command))))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
@@ -488,8 +525,10 @@ export default function hooksExtension(pi: ExtensionAPI) {
       return { action: 'handled' }
     }
     // Claude injects a UserPromptSubmit hook's context ahead of the prompt; transform is
-    // pi's seam for rewriting the submitted text.
-    if (decision.context) return { action: 'transform', text: `${decision.context}\n\n${event.text}` }
+    // pi's seam for rewriting the submitted text. With suppressOriginalPrompt the
+    // context replaces the prompt entirely (honored only when context exists, since
+    // an empty submission would be no turn at all).
+    if (decision.context) return { action: 'transform', text: decision.suppress ? decision.context : `${decision.context}\n\n${event.text}` }
     return { action: 'continue' }
   })
 
@@ -582,13 +621,19 @@ export default function hooksExtension(pi: ExtensionAPI) {
 
   pi.on('session_before_compact', async (event, ctx) => {
     const trigger = claudeSpelling(PRECOMPACT_TRIGGER, event.reason)
-    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), { hook_event_name: 'PreCompact', trigger: trigger.value }, boundRunner(ctx))
+    // Claude's custom_instructions: the /compact arguments on a manual run, empty
+    // on an automatic one; pi carries them on the event directly.
+    const payload = { hook_event_name: 'PreCompact', trigger: trigger.value, custom_instructions: event.customInstructions ?? '' }
+    const results = await runNotifyHooks(matchingCommands(config.PreCompact, trigger.names), payload, boundRunner(ctx))
     surfaceSystemMessages(results, (message) => ctx.ui.notify(message, 'warning'))
   })
 
   pi.on('session_compact', async (event, ctx) => {
     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))
+    // Claude's compact_summary: the summary that replaced the compacted history.
+    const summary = (event as { compactionEntry?: { summary?: unknown } }).compactionEntry?.summary
+    const payload = { hook_event_name: 'PostCompact', trigger: trigger.value, ...(typeof summary === 'string' ? { compact_summary: summary } : {}) }
+    const results = await runNotifyHooks(matchingCommands(config.PostCompact, trigger.names), payload, 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,
@@ -639,7 +684,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,6 +120,8 @@ 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; a
       // plugin's or skill's copy of the same handler stays separate, and http

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.29",
+  "version": "1.0.31",
   "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",