pi-code 1.0.29 → 1.0.30

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/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'
@@ -257,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
@@ -274,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>()
@@ -345,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)
@@ -639,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,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.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",