// biome-ignore-all assist/source/organizeImports: ANT-ONLY import markers must not be reordered
/**
* Hooks are user-defined shell commands that can be executed at various points
* in Claude Code's lifecycle.
*/
import { basename } from 'path'
import { spawn, type ChildProcessWithoutNullStreams } from 'child_process'
import { pathExists } from './file.js'
import { wrapSpawn } from './ShellCommand.js'
import { TaskOutput } from './task/TaskOutput.js'
import { getCwd } from './cwd.js'
import { randomUUID } from 'crypto'
import { formatShellPrefixCommand } from './bash/shellPrefix.js'
import {
getHookEnvFilePath,
invalidateSessionEnvCache,
} from './sessionEnvironment.js'
import { subprocessEnv } from './subprocessEnv.js'
import { getPlatform } from './platform.js'
import { findGitBashPath, windowsPathToPosixPath } from './windowsPaths.js'
import { getCachedPowerShellPath } from './shell/powershellDetection.js'
import { DEFAULT_HOOK_SHELL } from './shell/shellProvider.js'
import { buildPowerShellArgs } from './shell/powershellProvider.js'
import {
loadPluginOptions,
substituteUserConfigVariables,
} from './plugins/pluginOptionsStorage.js'
import { getPluginDataDir } from './plugins/pluginDirectories.js'
import {
getSessionId,
getProjectRoot,
getIsNonInteractiveSession,
getRegisteredHooks,
getStatsStore,
addToTurnHookDuration,
getOriginalCwd,
getMainThreadAgentType,
} from '../bootstrap/state.js'
import { checkHasTrustDialogAccepted } from './config.js'
import {
getHooksConfigFromSnapshot,
shouldAllowManagedHooksOnly,
shouldDisableAllHooksIncludingManaged,
} from './hooks/hooksConfigSnapshot.js'
import {
getTranscriptPathForSession,
getAgentTranscriptPath,
} from './sessionStorage.js'
import type { AgentId } from '../types/ids.js'
import {
getSettings_DEPRECATED,
getSettingsForSource,
} from './settings/settings.js'
import {
logEvent,
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
} from 'src/services/analytics/index.js'
import { logOTelEvent } from './telemetry/events.js'
import { ALLOWED_OFFICIAL_MARKETPLACE_NAMES } from './plugins/schemas.js'
import {
startHookSpan,
endHookSpan,
isBetaTracingEnabled,
} from './telemetry/sessionTracing.js'
import {
hookJSONOutputSchema,
promptRequestSchema,
type HookCallback,
type HookCallbackMatcher,
type PromptRequest,
type PromptResponse,
isAsyncHookJSONOutput,
isSyncHookJSONOutput,
type PermissionRequestResult,
} from '../types/hooks.js'
import type {
HookEvent,
HookInput,
HookJSONOutput,
NotificationHookInput,
PostToolUseHookInput,
PostToolUseFailureHookInput,
PermissionDeniedHookInput,
PreCompactHookInput,
PostCompactHookInput,
PreToolUseHookInput,
SessionStartHookInput,
SessionEndHookInput,
SetupHookInput,
StopHookInput,
StopFailureHookInput,
SubagentStartHookInput,
SubagentStopHookInput,
TeammateIdleHookInput,
TaskCreatedHookInput,
TaskCompletedHookInput,
ConfigChangeHookInput,
CwdChangedHookInput,
FileChangedHookInput,
InstructionsLoadedHookInput,
UserPromptSubmitHookInput,
PermissionRequestHookInput,
ElicitationHookInput,
ElicitationResultHookInput,
PermissionUpdate,
ExitReason,
SyncHookJSONOutput,
AsyncHookJSONOutput,
} from 'src/entrypoints/agentSdkTypes.js'
import type { StatusLineCommandInput } from '../types/statusLine.js'
import type { ElicitResult } from '@modelcontextprotocol/sdk/types.js'
import type { FileSuggestionCommandInput } from '../types/fileSuggestion.js'
import type { HookResultMessage } from 'src/types/message.js'
import chalk from 'chalk'
import type {
HookMatcher,
HookCommand,
PluginHookMatcher,
SkillHookMatcher,
} from './settings/types.js'
import { getHookDisplayText } from './hooks/hooksSettings.js'
import { logForDebugging } from './debug.js'
import { logForDiagnosticsNoPII } from './diagLogs.js'
import { firstLineOf } from './stringUtils.js'
import {
normalizeLegacyToolName,
getLegacyToolNames,
permissionRuleValueFromString,
} from './permissions/permissionRuleParser.js'
import { logError } from './log.js'
import { createCombinedAbortSignal } from './combinedAbortSignal.js'
import type { PermissionResult } from './permissions/PermissionResult.js'
import { registerPendingAsyncHook } from './hooks/AsyncHookRegistry.js'
import { enqueuePendingNotification } from './messageQueueManager.js'
import {
extractTextContent,
getLastAssistantMessage,
wrapInSystemReminder,
} from './messages.js'
import {
emitHookStarted,
emitHookResponse,
startHookProgressInterval,
} from './hooks/hookEvents.js'
import { createAttachmentMessage } from './attachments.js'
import { all } from './generators.js'
import { findToolByName, type Tools, type ToolUseContext } from '../Tool.js'
import { execPromptHook } from './hooks/execPromptHook.js'
import type { Message, AssistantMessage } from '../types/message.js'
import { execAgentHook } from './hooks/execAgentHook.js'
import { execHttpHook } from './hooks/execHttpHook.js'
import type { ShellCommand } from './ShellCommand.js'
import {
getSessionHooks,
getSessionFunctionHooks,
getSessionHookCallback,
clearSessionHooks,
type SessionDerivedHookMatcher,
type FunctionHook,
} from './hooks/sessionHooks.js'
import type { AppState } from '../state/AppState.js'
import { jsonStringify, jsonParse } from './slowOperations.js'
import { isEnvTruthy } from './envUtils.js'
import { errorMessage, getErrnoCode } from './errors.js'
const TOOL_HOOK_EXECUTION_TIMEOUT_MS = 10 * 60 * 1000
/**
* SessionEnd hooks run during shutdown/clear and need a much tighter bound
* than TOOL_HOOK_EXECUTION_TIMEOUT_MS. This value is used by callers as both
* the per-hook default timeout AND the overall AbortSignal cap (hooks run in
* parallel, so one value suffices). Overridable via env var for users whose
* teardown scripts need more time.
*/
const SESSION_END_HOOK_TIMEOUT_MS_DEFAULT = 1500
export function getSessionEndHookTimeoutMs(): number {
const raw = process.env.CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS
const parsed = raw ? parseInt(raw, 10) : NaN
return Number.isFinite(parsed) && parsed > 0
? parsed
: SESSION_END_HOOK_TIMEOUT_MS_DEFAULT
}
function executeInBackground({
processId,
hookId,
shellCommand,
asyncResponse,
hookEvent,
hookName,
command,
asyncRewake,
pluginId,
}: {
processId: string
hookId: string
shellCommand: ShellCommand
asyncResponse: AsyncHookJSONOutput
hookEvent: HookEvent | 'StatusLine' | 'FileSuggestion'
hookName: string
command: string
asyncRewake?: boolean
pluginId?: string
}): boolean {
if (asyncRewake) {
// asyncRewake hooks bypass the registry entirely. On completion, if exit
// code 2 (blocking error), enqueue as a task-notification so it wakes the
// model via useQueueProcessor (idle) or gets injected mid-query via
// queued_command attachments (busy).
//
// NOTE: We deliberately do NOT call shellCommand.background() here, because
// it calls taskOutput.spillToDisk() which breaks in-memory stdout/stderr
// capture (getStderr() returns '' in disk mode). The StreamWrappers stay
// attached and pipe data into the in-memory TaskOutput buffers. The abort
// handler already no-ops on 'interrupt' reason (user submitted a new
// message), so the hook survives new prompts. A hard cancel (Escape) WILL
// kill the hook via the abort handler, which is the desired behavior.
void shellCommand.result.then(async result => {
// result resolves on 'exit', but stdio 'data' events may still be
// pending. Yield to I/O so the StreamWrapper data handlers drain into
// TaskOutput before we read it.
await new Promise(resolve => setImmediate(resolve))
const stdout = await shellCommand.taskOutput.getStdout()
const stderr = shellCommand.taskOutput.getStderr()
shellCommand.cleanup()
emitHookResponse({
hookId,
hookName,
hookEvent,
output: stdout + stderr,
stdout,
stderr,
exitCode: result.code,
outcome: result.code === 0 ? 'success' : 'error',
})
if (result.code === 2) {
enqueuePendingNotification({
value: wrapInSystemReminder(
`Stop hook blocking error from command "${hookName}": ${stderr || stdout}`,
),
mode: 'task-notification',
})
}
})
return true
}
// TaskOutput on the ShellCommand accumulates data — no stream listeners needed
if (!shellCommand.background(processId)) {
return false
}
registerPendingAsyncHook({
processId,
hookId,
asyncResponse,
hookEvent,
hookName,
command,
shellCommand,
pluginId,
})
return true
}
/**
* Checks if a hook should be skipped due to lack of workspace trust.
*
* ALL hooks require workspace trust because they execute arbitrary commands from
* .claude/settings.json. This is a defense-in-depth security measure.
*
* Context: Hooks are captured via captureHooksConfigSnapshot() before the trust
* dialog is shown. While most hooks won't execute until after trust is established
* through normal program flow, enforcing trust for ALL hooks prevents:
* - Future bugs where a hook might accidentally execute before trust
* - Any codepath that might trigger hooks before trust dialog
* - Security issues from hook execution in untrusted workspaces
*
* Historical vulnerabilities that prompted this check:
* - SessionEnd hooks executing when user declines trust dialog
* - SubagentStop hooks executing when subagent completes before trust
*
* @returns true if hook should be skipped, false if it should execute
*/
export function shouldSkipHookDueToTrust(): boolean {
// In non-interactive mode (SDK), trust is implicit - always execute
const isInteractive = !getIsNonInteractiveSession()
if (!isInteractive) {
return false
}
// In interactive mode, ALL hooks require trust
const hasTrust = checkHasTrustDialogAccepted()
return !hasTrust
}
/**
* Creates the base hook input that's common to all hook types
*/
export function createBaseHookInput(
permissionMode?: string,
sessionId?: string,
// Typed narrowly (not ToolUseContext) so callers can pass toolUseContext
// directly via structural typing without this function depending on Tool.ts.
agentInfo?: { agentId?: string; agentType?: string },
): {
session_id: string
transcript_path: string
cwd: string
permission_mode?: string
agent_id?: string
agent_type?: string
} {
const resolvedSessionId = sessionId ?? getSessionId()
// agent_type: subagent's type (from toolUseContext) takes precedence over
// the session's --agent flag. Hooks use agent_id presence to distinguish
// subagent calls from main-thread calls in a --agent session.
const resolvedAgentType = agentInfo?.agentType ?? getMainThreadAgentType()
return {
session_id: resolvedSessionId,
transcript_path: getTranscriptPathForSession(resolvedSessionId),
cwd: getCwd(),
permission_mode: permissionMode,
agent_id: agentInfo?.agentId,
agent_type: resolvedAgentType,
}
}
export interface HookBlockingError {
blockingError: string
command: string
}
/** Re-export ElicitResult from MCP SDK as ElicitationResponse for backward compat. */
export type ElicitationResponse = ElicitResult
export interface HookResult {
message?: HookResultMessage
systemMessage?: string
blockingError?: HookBlockingError
outcome: 'success' | 'blocking' | 'non_blocking_error' | 'cancelled'
preventContinuation?: boolean
stopReason?: string
permissionBehavior?: 'ask' | 'deny' | 'allow' | 'passthrough'
hookPermissionDecisionReason?: string
additionalContext?: string
initialUserMessage?: string
updatedInput?: Record<string, unknown>
updatedMCPToolOutput?: unknown
permissionRequestResult?: PermissionRequestResult
elicitationResponse?: ElicitationResponse
watchPaths?: string[]
elicitationResultResponse?: ElicitationResponse
retry?: boolean
hook: HookCommand | HookCallback | FunctionHook
}
export type AggregatedHookResult = {
message?: HookResultMessage
blockingError?: HookBlockingError
preventContinuation?: boolean
stopReason?: string
hookPermissionDecisionReason?: string
hookSource?: string
permissionBehavior?: PermissionResult['behavior']
additionalContexts?: string[]
initialUserMessage?: string
updatedInput?: Record<string, unknown>
updatedMCPToolOutput?: unknown
permissionRequestResult?: PermissionRequestResult
watchPaths?: string[]
elicitationResponse?: ElicitationResponse
elicitationResultResponse?: ElicitationResponse
retry?: boolean
}
/**
* Parse and validate a JSON string against the hook output Zod schema.
* Returns the validated output or formatted validation errors.
*/
function validateHookJson(
jsonString: string,
): { json: HookJSONOutput } | { validationError: string } {
const parsed = jsonParse(jsonString)
const validation = hookJSONOutputSchema().safeParse(parsed)
if (validation.success) {
logForDebugging('Successfully parsed and validated hook JSON output')
return { json: validation.data }
}
const errors = validation.error.issues
.map(err => ` - ${err.path.join('.')}: ${err.message}`)
.join('\n')
return {
validationError: `Hook JSON output validation failed:\n${errors}\n\nThe hook's output was: ${jsonStringify(parsed, null, 2)}`,
}
}
function parseHookOutput(stdout: string): {
json?: HookJSONOutput
plainText?: string
validationError?: string
} {
const trimmed = stdout.trim()
if (!trimmed.startsWith('{')) {
logForDebugging('Hook output does not start with {, treating as plain text')
return { plainText: stdout }
}
try {
const result = validateHookJson(trimmed)
if ('json' in result) {
return result
}
// For command hooks, include the schema hint in the error message
const errorMessage = `${result.validationError}\n\nExpected schema:\n${jsonStringify(
{
continue: 'boolean (optional)',
suppressOutput: 'boolean (optional)',
stopReason: 'string (optional)',
decision: '"approve" | "block" (optional)',
reason: 'string (optional)',
systemMessage: 'string (optional)',
permissionDecision: '"allow" | "deny" | "ask" (optional)',
hookSpecificOutput: {
'for PreToolUse': {
hookEventName: '"PreToolUse"',
permissionDecision: '"allow" | "deny" | "ask" (optional)',
permissionDecisionReason: 'string (optional)',
updatedInput: 'object (optional) - Modified tool input to use',
},
'for UserPromptSubmit': {
hookEventName: '"UserPromptSubmit"',
additionalContext: 'string (required)',
},
'for PostToolUse': {
hookEventName: '"PostToolUse"',
additionalContext: 'string (optional)',
},
},
},
null,
2,
)}`
logForDebugging(errorMessage)
return { plainText: stdout, validationError: errorMessage }
} catch (e) {
logForDebugging(`Failed to parse hook output as JSON: ${e}`)
return { plainText: stdout }
}
}
function parseHttpHookOutput(body: string): {
json?: HookJSONOutput
validationError?: string
} {
const trimmed = body.trim()
if (trimmed === '') {
const validation = hookJSONOutputSchema().safeParse({})
if (validation.success) {
logForDebugging(
'HTTP hook returned empty body, treating as empty JSON object',
)
return { json: validation.data }
}
}
if (!trimmed.startsWith('{')) {
const validationError = `HTTP hook must return JSON, but got non-JSON response body: ${trimmed.length > 200 ? trimmed.slice(0, 200) + '\u2026' : trimmed}`
logForDebugging(validationError)
return { validationError }
}
try {
const result = validateHookJson(trimmed)
if ('json' in result) {
return result
}
logForDebugging(result.validationError)
return result
} catch (e) {
const validationError = `HTTP hook must return valid JSON, but parsing failed: ${e}`
logForDebugging(validationError)
return { validationError }
}
}
function processHookJSONOutput({
json,
command,
hookName,
toolUseID,
hookEvent,
expectedHookEvent,
stdout,
stderr,
exitCode,
durationMs,
}: {
json: SyncHookJSONOutput
command: string
hookName: string
toolUseID: string
hookEvent: HookEvent
expectedHookEvent?: HookEvent
stdout?: string
stderr?: string
exitCode?: number
durationMs?: number
}): Partial<HookResult> {
const result: Partial<HookResult> = {}
// At this point we know it's a sync response
const syncJson = json
// Handle common elements
if (syncJson.continue === false) {
result.preventContinuation = true
if (syncJson.stopReason) {
result.stopReason = syncJson.stopReason
}
}
if (json.decision) {
switch (json.decision) {
case 'approve':
result.permissionBehavior = 'allow'
break
case 'block':
result.permissionBehavior = 'deny'
result.blockingError = {
blockingError: json.reason || 'Blocked by hook',
command,
}
break
default:
// Handle unknown decision types as errors
throw new Error(
`Unknown hook decision type: ${json.decision}. Valid types are: approve, block`,
)
}
}
// Handle systemMessage field
if (json.systemMessage) {
result.systemMessage = json.systemMessage
}
// Handle PreToolUse specific
if (
json.hookSpecificOutput?.hookEventName === 'PreToolUse' &&
json.hookSpecificOutput.permissionDecision
) {
switch (json.hookSpecificOutput.permissionDecision) {
case 'allow':
result.permissionBehavior = 'allow'
break
case 'deny':
result.permissionBehavior = 'deny'
result.blockingError = {
blockingError: json.reason || 'Blocked by hook',
command,
}
break
case 'ask':
result.permissionBehavior = 'ask'
break
default:
// Handle unknown decision types as errors
throw new Error(
`Unknown hook permissionDecision type: ${json.hookSpecificOutput.permissionDecision}. Valid types are: allow, deny, ask`,
)
}
}
if (result.permissionBehavior !== undefined && json.reason !== undefined) {
result.hookPermissionDecisionReason = json.reason
}
// Handle hookSpecificOutput
if (json.hookSpecificOutput) {
// Validate hook event name matches expected if provided
if (
expectedHookEvent &&
json.hookSpecificOutput.hookEventName !== expectedHookEvent
) {
throw new Error(
`Hook returned incorrect event name: expected '${expectedHookEvent}' but got '${json.hookSpecificOutput.hookEventName}'. Full stdout: ${jsonStringify(json, null, 2)}`,
)
}
switch (json.hookSpecificOutput.hookEventName) {
case 'PreToolUse':
// Override with more specific permission decision if provided
if (json.hookSpecificOutput.permissionDecision) {
switch (json.hookSpecificOutput.permissionDecision) {
case 'allow':
result.permissionBehavior = 'allow'
break
case 'deny':
result.permissionBehavior = 'deny'
result.blockingError = {
blockingError:
json.hookSpecificOutput.permissionDecisionReason ||
json.reason ||
'Blocked by hook',
command,
}
break
case 'ask':
result.permissionBehavior = 'ask'
break
}
}
result.hookPermissionDecisionReason =
json.hookSpecificOutput.permissionDecisionReason
// Extract updatedInput if provided
if (json.hookSpecificOutput.updatedInput) {
result.updatedInput = json.hookSpecificOutput.updatedInput
}
// Extract additionalContext if provided
result.additionalContext = json.hookSpecificOutput.additionalContext
break
case 'UserPromptSubmit':
result.additionalContext = json.hookSpecificOutput.additionalContext
break
case 'SessionStart':
result.additionalContext = json.hookSpecificOutput.additionalContext
result.initialUserMessage = json.hookSpecificOutput.initialUserMessage
if (
'watchPaths' in json.hookSpecificOutput &&
json.hookSpecificOutput.watchPaths
) {
result.watchPaths = json.hookSpecificOutput.watchPaths
}
break
case 'Setup':
result.additionalContext = json.hookSpecificOutput.additionalContext
break
case 'SubagentStart':
result.additionalContext = json.hookSpecificOutput.additionalContext
break
case 'PostToolUse':
result.additionalContext = json.hookSpecificOutput.additionalContext
// Extract updatedMCPToolOutput if provided
if (json.hookSpecificOutput.updatedMCPToolOutput) {
result.updatedMCPToolOutput =
json.hookSpecificOutput.updatedMCPToolOutput
}
break
case 'PostToolUseFailure':
result.additionalContext = json.hookSpecificOutput.additionalContext
break
case 'PermissionDenied':
result.retry = json.hookSpecificOutput.retry
break
case 'PermissionRequest':
// Extract the permission request decision
if (json.hookSpecificOutput.decision) {
result.permissionRequestResult = json.hookSpecificOutput.decision
// Also update permissionBehavior for consistency
result.permissionBehavior =
json.hookSpecificOutput.decision.behavior === 'allow'
? 'allow'
: 'deny'
if (
json.hookSpecificOutput.decision.behavior === 'allow' &&
json.hookSpecificOutput.decision.updatedInput
) {
result.updatedInput = json.hookSpecificOutput.decision.updatedInput
}
}
break
case 'Elicitation':
if (json.hookSpecificOutput.action) {
result.elicitationResponse = {
action: json.hookSpecificOutput.action,
content: json.hookSpecificOutput.content as
| ElicitationResponse['content']
| undefined,
}
if (json.hookSpecificOutput.action === 'decline') {
result.blockingError = {
blockingError: json.reason || 'Elicitation denied by hook',
command,
}
}
}
break
case 'ElicitationResult':
if (json.hookSpecificOutput.action) {
result.elicitationResultResponse = {
action: json.hookSpecificOutput.action,
content: json.hookSpecificOutput.content as
| ElicitationResponse['content']
| undefined,
}
if (json.hookSpecificOutput.action === 'decline') {
result.blockingError = {
blockingError:
json.reason || 'Elicitation result blocked by hook',
command,
}
}
}
break
}
}
return {
...result,
message: result.blockingError
? createAttachmentMessage({
type: 'hook_blocking_error',
hookName,
toolUseID,
hookEvent,
blockingError: result.blockingError,
})
: createAttachmentMessage({
type: 'hook_success',
hookName,
toolUseID,
hookEvent,
// JSON-output hooks inject context via additionalContext →
// hook_additional_context, not this field. Empty content suppresses
// the trivial "X hook success: Success" system-reminder that
// otherwise pollutes every turn (messages.ts:3577 skips on '').
content: '',
stdout,
stderr,
exitCode,
command,
durationMs,
}),
}
}
/**
* Execute a command-based hook using bash or PowerShell.
*
* Shell resolution: hook.shell → 'bash'. PowerShell hooks spawn pwsh
* with -NoProfile -NonInteractive -Command and skip bash-specific prep
* (POSIX path conversion, .sh auto-prepend, CLAUDE_CODE_SHELL_PREFIX).
* See docs/design/ps-shell-selection.md §5.1.
*/
async function execCommandHook(
hook: HookCommand & { type: 'command' },
hookEvent: HookEvent | 'StatusLine' | 'FileSuggestion',
hookName: string,
jsonInput: string,
signal: AbortSignal,
hookId: string,
hookIndex?: number,
pluginRoot?: string,
pluginId?: string,
skillRoot?: string,
forceSyncExecution?: boolean,
requestPrompt?: (request: PromptRequest) => Promise<PromptResponse>,
): Promise<{
stdout: string
stderr: string
output: string
status: number
aborted?: boolean
backgrounded?: boolean
}> {
// Gated to once-per-session events to keep diag_log volume bounded.
// started/completed live inside the try/finally so setup-path throws
// don't orphan a started marker — that'd be indistinguishable from a hang.
const shouldEmitDiag =
hookEvent === 'SessionStart' ||
hookEvent === 'Setup' ||
hookEvent === 'SessionEnd'
const diagStartMs = Date.now()
let diagExitCode: number | undefined
let diagAborted = false
const isWindows = getPlatform() === 'windows'
// --
// Per-hook shell selection (phase 1 of docs/design/ps-shell-selection.md).
// Resolution order: hook.shell → DEFAULT_HOOK_SHELL. The defaultShell
// fallback (settings.defaultShell) is phase 2 — not wired yet.
//
// The bash path is the historical default and stays unchanged. The
// PowerShell path deliberately skips the Windows-specific bash
// accommodations (cygpath conversion, .sh auto-prepend, POSIX-quoted
// SHELL_PREFIX).
const shellType = hook.shell ?? DEFAULT_HOOK_SHELL
const isPowerShell = shellType === 'powershell'
// --
// Windows bash path: hooks run via Git Bash (Cygwin), NOT cmd.exe.
//
// This means every path we put into env vars or substitute into the command
// string MUST be a POSIX path (/c/Users/foo), not a Windows path
// (C:\Users\foo or C:/Users/foo). Git Bash cannot resolve Windows paths.
//
// windowsPathToPosixPath() is pure-JS regex conversion (no cygpath shell-out):
// C:\Users\foo -> /c/Users/foo, UNC preserved, slashes flipped. Memoized
// (LRU-500) so repeated calls are cheap.
//
// PowerShell path: use native paths — skip the conversion entirely.
// PowerShell expects Windows paths on Windows (and native paths on
// Unix where pwsh is also available).
const toHookPath =
isWindows && !isPowerShell
? (p: string) => windowsPathToPosixPath(p)
: (p: string) => p
// Set CLAUDE_PROJECT_DIR to the stable project root (not the worktree path).
// getProjectRoot() is never updated when entering a worktree, so hooks that
// reference $CLAUDE_PROJECT_DIR always resolve relative to the real repo root.
const projectDir = getProjectRoot()
// Substitute ${CLAUDE_PLUGIN_ROOT} and ${user_config.X} in the command string.
// Order matches MCP/LSP (plugin vars FIRST, then user config) so a user-
// entered value containing the literal text ${CLAUDE_PLUGIN_ROOT} is treated
// as opaque — not re-interpreted as a template.
let command = hook.command
let pluginOpts: ReturnType<typeof loadPluginOptions> | undefined
if (pluginRoot) {
// Plugin directory gone (orphan GC race, concurrent session deleted it):
// throw so callers yield a non-blocking error. Running would fail — and
// `python3 <missing>.py` exits 2, the hook protocol's "block" code, which
// bricks UserPromptSubmit/Stop until restart. The pre-check is necessary
// because exit-2-from-missing-script is indistinguishable from an
// intentional block after spawn.
if (!(await pathExists(pluginRoot))) {
throw new Error(
`Plugin directory does not exist: ${pluginRoot}` +
(pluginId ? ` (${pluginId} — run /plugin to reinstall)` : ''),
)
}
// Inline both ROOT and DATA substitution instead of calling
// substitutePluginVariables(). That helper normalizes \ → / on Windows
// unconditionally — correct for bash (toHookPath already produced /c/...
// so it's a no-op) but wrong for PS where toHookPath is identity and we
// want native C:\... backslashes. Inlining also lets us use the function-
// form .replace() so paths containing $ aren't mangled by $-pattern
// interpretation (rare but possible: \\server\c$\plugin).
const rootPath = toHookPath(pluginRoot)
command = command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, () => rootPath)
if (pluginId) {
const dataPath = toHookPath(getPluginDataDir(pluginId))
command = command.replace(/\$\{CLAUDE_PLUGIN_DATA\}/g, () => dataPath)
}
if (pluginId) {
pluginOpts = loadPluginOptions(pluginId)
// Throws if a referenced key is missing — that means the hook uses a key
// that's either not declared in manifest.userConfig or not yet configured.
// Caught upstream like any other hook exec failure.
command = substituteUserConfigVariables(command, pluginOpts)
}
}
// On Windows (bash only), auto-prepend `bash` for .sh scripts so they
// execute instead of opening in the default file handler. PowerShell
// runs .ps1 files natively — no prepend needed.
if (isWindows && !isPowerShell && command.trim().match(/\.sh(\s|$|")/)) {
if (!command.trim().startsWith('bash ')) {
command = `bash ${command}`
}
}
// CLAUDE_CODE_SHELL_PREFIX wraps the command via POSIX quoting
// (formatShellPrefixCommand uses shell-quote). This makes no sense for
// PowerShell — see design §8.1. For now PS hooks ignore the prefix;
// a CLAUDE_CODE_PS_SHELL_PREFIX (or shell-aware prefix) is a follow-up.
const finalCommand =
!isPowerShell && process.env.CLAUDE_CODE_SHELL_PREFIX
? formatShellPrefixCommand(process.env.CLAUDE_CODE_SHELL_PREFIX, command)
: command
const hookTimeoutMs = hook.timeout
? hook.timeout * 1000
: TOOL_HOOK_EXECUTION_TIMEOUT_MS
// Build env vars — all paths go through toHookPath for Windows POSIX conversion
const envVars: NodeJS.ProcessEnv = {
...subprocessEnv(),
CLAUDE_PROJECT_DIR: toHookPath(projectDir),
}
// Plugin and skill hooks both set CLAUDE_PLUGIN_ROOT (skills use the same
// name for consistency — skills can migrate to plugins without code changes)
if (pluginRoot) {
envVars.CLAUDE_PLUGIN_ROOT = toHookPath(pluginRoot)
if (pluginId) {
envVars.CLAUDE_PLUGIN_DATA = toHookPath(getPluginDataDir(pluginId))
}
}
// Expose plugin options as env vars too, so hooks can read them without
// ${user_config.X} in the command string. Sensitive values included — hooks
// run the user's own code, same trust boundary as reading keychain directly.
if (pluginOpts) {
for (const [key, value] of Object.entries(pluginOpts)) {
// Sanitize non-identifier chars (bash can't ref $FOO-BAR). The schema
// at schemas.ts:611 now constrains keys to /^[A-Za-z_]\w*$/ so this is
// belt-and-suspenders, but cheap insurance if someone bypasses the schema.
const envKey = key.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()
envVars[`CLAUDE_PLUGIN_OPTION_${envKey}`] = String(value)
}
}
if (skillRoot) {
envVars.CLAUDE_PLUGIN_ROOT = toHookPath(skillRoot)
}
// CLAUDE_ENV_FILE points to a .sh file that the hook writes env var
// definitions into; getSessionEnvironmentScript() concatenates them and
// bashProvider injects the content into bash commands. A PS hook would
// naturally write PS syntax ($env:FOO = 'bar'), which bash can't parse.
// Skip for PS — consistent with how .sh prepend and SHELL_PREFIX are
// already bash-only above.
if (
!isPowerShell &&
(hookEvent === 'SessionStart' ||
hookEvent === 'Setup' ||
hookEvent === 'CwdChanged' ||
hookEvent === 'FileChanged') &&
hookIndex !== undefined
) {
envVars.CLAUDE_ENV_FILE = await getHookEnvFilePath(hookEvent, hookIndex)
}
// When agent worktrees are removed, getCwd() may return a deleted path via
// AsyncLocalStorage. Validate before spawning since spawn() emits async
// 'error' events for missing cwd rather than throwing synchronously.
const hookCwd = getCwd()
const safeCwd = (await pathExists(hookCwd)) ? hookCwd : getOriginalCwd()
if (safeCwd !== hookCwd) {
logForDebugging(
`Hooks: cwd ${hookCwd} not found, falling back to original cwd`,
{ level: 'warn' },
)
}
// --
// Spawn. Two completely separate paths:
//
// Bash: spawn(cmd, [], { shell: <gitBashPath | true> }) — the shell
// option makes Node pass the whole string to the shell for parsing.
//
// PowerShell: spawn(pwshPath, ['-NoProfile', '-NonInteractive',
// '-Command', cmd]) — explicit argv, no shell option. -NoProfile
// skips user profile scripts (faster, deterministic).
// -NonInteractive fails fast instead of prompting.
//
// The Git Bash hard-exit in findGitBashPath() is still in place for
// bash hooks. PowerShell hooks never call it, so a Windows user with
// only pwsh and shell: 'powershell' on every hook could in theory run
// without Git Bash — but init.ts still calls setShellIfWindows() on
// startup, which will exit first. Relaxing that is phase 1 of the
// design's implementation order (separate PR).
let child: ChildProcessWithoutNullStreams
if (shellType === 'powershell') {
const pwshPath = await getCachedPowerShellPath()
if (!pwshPath) {
throw new Error(
`Hook "${hook.command}" has shell: 'powershell' but no PowerShell ` +
`executable (pwsh or powershell) was found on PATH. Install ` +
`PowerShell, or remove "shell": "powershell" to use bash.`,
)
}
child = spawn(pwshPath, buildPowerShellArgs(finalCommand), {
env: envVars,
cwd: safeCwd,
// Prevent visible console window on Windows (no-op on other platforms)
windowsHide: true,
}) as ChildProcessWithoutNullStreams
} else {
// On Windows, use Git Bash explicitly (cmd.exe can't run bash syntax).
// On other platforms, shell: true uses /bin/sh.
const shell = isWindows ? findGitBashPath() : true
child = spawn(finalCommand, [], {
env: envVars,
cwd: safeCwd,
shell,
// Prevent visible console window on Windows (no-op on other platforms)
windowsHide: true,
}) as ChildProcessWithoutNullStreams
}
// Hooks use pipe mode — stdout must be streamed into JS so we can parse
// the first response line to detect async hooks ({"async": true}).
const hookTaskOutput = new TaskOutput(`hook_${child.pid}`, null)
const shellCommand = wrapSpawn(child, signal, hookTimeoutMs, hookTaskOutput)
// Track whether shellCommand ownership was transferred (e.g., to async hook registry)
let shellCommandTransferred = false
// Track whether stdin has already been written (to avoid "write after end" errors)
let stdinWritten = false
if ((hook.async || hook.asyncRewake) && !forceSyncExecution) {
const processId = `async_hook_${child.pid}`
logForDebugging(
`Hooks: Config-based async hook, backgrounding process ${processId}`,
)
// Write stdin before backgrounding so the hook receives its input.
// The trailing newline matches the sync path (L1000). Without it,
// bash `read -r line` returns exit 1 (EOF before delimiter) — the
// variable IS populated but `if read -r line; then ...` skips the
// branch. See gh-30509 / CC-161.
child.stdin.write(jsonInput + '\n', 'utf8')
child.stdin.end()
stdinWritten = true
const backgrounded = executeInBackground({
processId,
hookId,
shellCommand,
asyncResponse: { async: true, asyncTimeout: hookTimeoutMs },
hookEvent,
hookName,
command: hook.command,
asyncRewake: hook.asyncRewake,
pluginId,
})
if (backgrounded) {
return {
stdout: '',
stderr: '',
output: '',
status: 0,
backgrounded: true,
}
}
}
let stdout = ''
let stderr = ''
let output = ''
// Set up output data collection with explicit UTF-8 encoding
child.stdout.setEncoding('utf8')
child.stderr.setEncoding('utf8')
let initialResponseChecked = false
let asyncResolve:
| ((result: {
stdout: string
stderr: string
output: string
status: number
}) => void)
| null = null
const childIsAsyncPromise = new Promise<{
stdout: string
stderr: string
output: string
status: number
aborted?: boolean
}>(resolve => {
asyncResolve = resolve
})
// Track trimmed prompt-request lines we processed so we can strip them
// from final stdout by content match (no index tracking → no index drift)
const processedPromptLines = new Set<string>()
// Serialize async prompt handling so responses are sent in order
let promptChain = Promise.resolve()
// Line buffer for detecting prompt requests in streaming output
let lineBuffer = ''
child.stdout.on('data', data => {
stdout += data
output += data
// When requestPrompt is provided, parse stdout line-by-line for prompt requests
if (requestPrompt) {
lineBuffer += data
const lines = lineBuffer.split('\n')
lineBuffer = lines.pop() ?? '' // last element is an incomplete line
for (const line of lines) {
const trimmed = line.trim()
if (!trimmed) continue
try {
const parsed = jsonParse(trimmed)
const validation = promptRequestSchema().safeParse(parsed)
if (validation.success) {
processedPromptLines.add(trimmed)
logForDebugging(
`Hooks: Detected prompt request from hook: ${trimmed}`,
)
// Chain the async handling to serialize prompt responses
const promptReq = validation.data
const reqPrompt = requestPrompt
promptChain = promptChain.then(async () => {
try {
const response = await reqPrompt(promptReq)
child.stdin.write(jsonStringify(response) + '\n', 'utf8')
} catch (err) {
logForDebugging(`Hooks: Prompt request handling failed: ${err}`)
// User cancelled or prompt failed — close stdin so the hook
// process doesn't hang waiting for input
child.stdin.destroy()
}
})
continue
}
} catch {
// Not JSON, just a normal line
}
}
}
// Check for async response on first line of output. The async protocol is:
// hook emits {"async":true,...} as its FIRST line, then its normal output.
// We must parse ONLY the first line — if the process is fast and writes more
// before this 'data' event fires, parsing the full accumulated stdout fails
// and an async hook blocks for its full duration instead of backgrounding.
if (!initialResponseChecked) {
const firstLine = firstLineOf(stdout).trim()
if (!firstLine.includes('}')) return
initialResponseChecked = true
logForDebugging(`Hooks: Checking first line for async: ${firstLine}`)
try {
const parsed = jsonParse(firstLine)
logForDebugging(
`Hooks: Parsed initial response: ${jsonStringify(parsed)}`,
)
if (isAsyncHookJSONOutput(parsed) && !forceSyncExecution) {
const processId = `async_hook_${child.pid}`
logForDebugging(
`Hooks: Detected async hook, backgrounding process ${processId}`,
)
const backgrounded = executeInBackground({
processId,
hookId,
shellCommand,
asyncResponse: parsed,
hookEvent,
hookName,
command: hook.command,
pluginId,
})
if (backgrounded) {
shellCommandTransferred = true
asyncResolve?.({
stdout,
stderr,
output,
status: 0,
})
}
} else if (isAsyncHookJSONOutput(parsed) && forceSyncExecution) {
logForDebugging(
`Hooks: Detected async hook but forceSyncExecution is true, waiting for completion`,
)
} else {
logForDebugging(
`Hooks: Initial response is not async, continuing normal processing`,
)
}
} catch (e) {
logForDebugging(`Hooks: Failed to parse initial response as JSON: ${e}`)
}
}
})
child.stderr.on('data', data => {
stderr += data
output += data
})
const stopProgressInterval = startHookProgressInterval({
hookId,
hookName,
hookEvent,
getOutput: async () => ({ stdout, stderr, output }),
})
// Wait for stdout and stderr streams to finish before considering output complete
// This prevents a race condition where 'close' fires before all 'data' events are processed
const stdoutEndPromise = new Promise<void>(resolve => {
child.stdout.on('end', () => resolve())
})
const stderrEndPromise = new Promise<void>(resolve => {
child.stderr.on('end', () => resolve())
})
// Write to stdin, making sure to handle EPIPE errors that can happen when
// the hook command exits before reading all input.
// Note: EPIPE handling is difficult to set up in testing since Bun and Node
// have different behaviors.
// TODO: Add tests for EPIPE handling.
// Skip if stdin was already written (e.g., by config-based async hook path)
const stdinWritePromise = stdinWritten
? Promise.resolve()
: new Promise<void>((resolve, reject) => {
child.stdin.on('error', err => {
// When requestPrompt is provided, stdin stays open for prompt responses.
// EPIPE errors from later writes (after process exits) are expected -- suppress them.
if (!requestPrompt) {
reject(err)
} else {
logForDebugging(
`Hooks: stdin error during prompt flow (likely process exited): ${err}`,
)
}
})
// Explicitly specify UTF-8 encoding to ensure proper handling of Unicode characters
child.stdin.write(jsonInput + '\n', 'utf8')
// When requestPrompt is provided, keep stdin open for prompt responses
if (!requestPrompt) {
child.stdin.end()
}
resolve()
})
// Create promise for child process error
const childErrorPromise = new Promise<never>((_, reject) => {
child.on('error', reject)
})
// Create promise for child process close - but only resolve after streams end
// to ensure all output has been collected
const childClosePromise = new Promise<{
stdout: string
stderr: string
output: string
status: number
aborted?: boolean
}>(resolve => {
let exitCode: number | null = null
child.on('close', code => {
exitCode = code ?? 1
// Wait for both streams to end before resolving with the final output
void Promise.all([stdoutEndPromise, stderrEndPromise]).then(() => {
// Strip lines we processed as prompt requests so parseHookOutput
// only sees the final hook result. Content-matching against the set
// of actually-processed lines means prompt JSON can never leak
// through (fail-closed), regardless of line positioning.
const finalStdout =
processedPromptLines.size === 0
? stdout
: stdout
.split('\n')
.filter(line => !processedPromptLines.has(line.trim()))
.join('\n')
resolve({
stdout: finalStdout,
stderr,
output,
status: exitCode!,
aborted: signal.aborted,
})
})
})
})
// Race between stdin write, async detection, and process completion
try {
if (shouldEmitDiag) {
logForDiagnosticsNoPII('info', 'hook_spawn_started', {
hook_event_name: hookEvent,
index: hookIndex,
})
}
await Promise.race([stdinWritePromise, childErrorPromise])
// Wait for any pending prompt responses before resolving
const result = await Promise.race([
childIsAsyncPromise,
childClosePromise,
childErrorPromise,
])
// Ensure all queued prompt responses have been sent
await promptChain
diagExitCode = result.status
diagAborted = result.aborted ?? false
return result
} catch (error) {
// Handle errors from stdin write or child process
const code = getErrnoCode(error)
diagExitCode = 1
if (code === 'EPIPE') {
logForDebugging(
'EPIPE error while writing to hook stdin (hook command likely closed early)',
)
const errMsg =
'Hook command closed stdin before hook input was fully written (EPIPE)'
return {
stdout: '',
stderr: errMsg,
output: errMsg,
status: 1,
}
} else if (code === 'ABORT_ERR') {
diagAborted = true
return {
stdout: '',
stderr: 'Hook cancelled',
output: 'Hook cancelled',
status: 1,
aborted: true,
}
} else {
const errorMsg = errorMessage(error)
const errOutput = `Error occurred while executing hook command: ${errorMsg}`
return {
stdout: '',
stderr: errOutput,
output: errOutput,
status: 1,
}
}
} finally {
if (shouldEmitDiag) {
logForDiagnosticsNoPII('info', 'hook_spawn_completed', {
hook_event_name: hookEvent,
index: hookIndex,
duration_ms: Date.now() - diagStartMs,
exit_code: diagExitCode,
aborted: diagAborted,
})
}
stopProgressInterval()
// Clean up stream resources unless ownership was transferred (e.g., to async hook registry)
if (!shellCommandTransferred) {
shellCommand.cleanup()
}
}
}
/**
* Check if a match query matches a hook matcher pattern
* @param matchQuery The query to match (e.g., 'Write', 'Edit', 'Bash')
* @param matcher The matcher pattern - can be:
* - Simple string for exact match (e.g., 'Write')
* - Pipe-separated list for multiple exact matches (e.g., 'Write|Edit')
* - Regex pattern (e.g., '^Write.*', '.*', '^(Write|Edit)$')
* @returns true if the query matches the pattern
*/
function matchesPattern(matchQuery: string, matcher: string): boolean {
if (!matcher || matcher === '*') {
return true
}
// Check if it's a simple string or pipe-separated list (no regex special chars except |)
if (/^[a-zA-Z0-9_|]+$/.test(matcher)) {
// Handle pipe-separated exact matches
if (matcher.includes('|')) {
const patterns = matcher
.split('|')
.map(p => normalizeLegacyToolName(p.trim()))
return patterns.includes(matchQuery)
}
// Simple exact match
return matchQuery === normalizeLegacyToolName(matcher)
}
// Otherwise treat as regex
try {
const regex = new RegExp(matcher)
if (regex.test(matchQuery)) {
return true
}
// Also test against legacy names so patterns like "^Task$" still match
for (const legacyName of getLegacyToolNames(matchQuery)) {
if (regex.test(legacyName)) {
return true
}
}
return false
} catch {
// If the regex is invalid, log error and return false
logForDebugging(`Invalid regex pattern in hook matcher: ${matcher}`)
return false
}
}
type IfConditionMatcher = (ifCondition: string) => boolean
/**
* Prepare a matcher for hook `if` conditions. Expensive work (tool lookup,
* Zod validation, tree-sitter parsing for Bash) happens once here; the
* returned closure is called per hook. Returns undefined for non-tool events.
*/
async function prepareIfConditionMatcher(
hookInput: HookInput,
tools: Tools | undefined,
): Promise<IfConditionMatcher | undefined> {
if (
hookInput.hook_event_name !== 'PreToolUse' &&
hookInput.hook_event_name !== 'PostToolUse' &&
hookInput.hook_event_name !== 'PostToolUseFailure' &&
hookInput.hook_event_name !== 'PermissionRequest'
) {
return undefined
}
const toolName = normalizeLegacyToolName(hookInput.tool_name)
const tool = tools && findToolByName(tools, hookInput.tool_name)
const input = tool?.inputSchema.safeParse(hookInput.tool_input)
const patternMatcher =
input?.success && tool?.preparePermissionMatcher
? await tool.preparePermissionMatcher(input.data)
: undefined
return ifCondition => {
const parsed = permissionRuleValueFromString(ifCondition)
if (normalizeLegacyToolName(parsed.toolName) !== toolName) {
return false
}
if (!parsed.ruleContent) {
return true
}
return patternMatcher ? patternMatcher(parsed.ruleContent) : false
}
}
type FunctionHookMatcher = {
matcher: string
hooks: FunctionHook[]
}
/**
* A hook paired with optional plugin context.
* Used when returning matched hooks so we can apply plugin env vars at execution time.
*/
type MatchedHook = {
hook: HookCommand | HookCallback | FunctionHook
pluginRoot?: string
pluginId?: string
skillRoot?: string
hookSource?: string
}
function isInternalHook(matched: MatchedHook): boolean {
return matched.hook.type === 'callback' && matched.hook.internal === true
}
/**
* Build a dedup key for a matched hook, namespaced by source context.
*
* Settings-file hooks (no pluginRoot/skillRoot) share the '' prefix so the
* same command defined in user/project/local still collapses to one — the
* original intent of the dedup. Plugin/skill hooks get their root as the
* prefix, so two plugins sharing an unexpanded `${CLAUDE_PLUGIN_ROOT}/hook.sh`
* template don't collapse: after expansion they point to different files.
*/
function hookDedupKey(m: MatchedHook, payload: string): string {
return `${m.pluginRoot ?? m.skillRoot ?? ''}\0${payload}`
}
/**
* Build a map of {sanitizedPluginName: hookCount} from matched hooks.
* Only logs actual names for official marketplace plugins; others become 'third-party'.
*/
function getPluginHookCounts(
hooks: MatchedHook[],
): Record<string, number> | undefined {
const pluginHooks = hooks.filter(h => h.pluginId)
if (pluginHooks.length === 0) {
return undefined
}
const counts: Record<string, number> = {}
for (const h of pluginHooks) {
const atIndex = h.pluginId!.lastIndexOf('@')
const isOfficial =
atIndex > 0 &&
ALLOWED_OFFICIAL_MARKETPLACE_NAMES.has(h.pluginId!.slice(atIndex + 1))
const key = isOfficial ? h.pluginId! : 'third-party'
counts[key] = (counts[key] || 0) + 1
}
return counts
}
/**
* Build a map of {hookType: count} from matched hooks.
*/
function getHookTypeCounts(hooks: MatchedHook[]): Record<string, number> {
const counts: Record<string, number> = {}
for (const h of hooks) {
counts[h.hook.type] = (counts[h.hook.type] || 0) + 1
}
return counts
}
function getHooksConfig(
appState: AppState | undefined,
sessionId: string,
hookEvent: HookEvent,
): Array<
| HookMatcher
| HookCallbackMatcher
| FunctionHookMatcher
| PluginHookMatcher
| SkillHookMatcher
| SessionDerivedHookMatcher
> {
// HookMatcher is a zod-stripped {matcher, hooks} so snapshot matchers can be
// pushed directly without re-wrapping.
const hooks: Array<
| HookMatcher
| HookCallbackMatcher
| FunctionHookMatcher
| PluginHookMatcher
| SkillHookMatcher
| SessionDerivedHookMatcher
> = [...(getHooksConfigFromSnapshot()?.[hookEvent] ?? [])]
// Check if only managed hooks should run (used for both registered and session hooks)
const managedOnly = shouldAllowManagedHooksOnly()
// Process registered hooks (SDK callbacks and plugin native hooks)
const registeredHooks = getRegisteredHooks()?.[hookEvent]
if (registeredHooks) {
for (const matcher of registeredHooks) {
// Skip plugin hooks when restricted to managed hooks only
// Plugin hooks have pluginRoot set, SDK callbacks do not
if (managedOnly && 'pluginRoot' in matcher) {
continue
}
hooks.push(matcher)
}
}
// Merge session hooks for the current session only
// Function hooks (like structured output enforcement) must be scoped to their session
// to prevent hooks from one agent leaking to another (e.g., verification agent to main agent)
// Skip session hooks entirely when allowManagedHooksOnly is set —
// this prevents frontmatter hooks from agents/skills from bypassing the policy.
// strictPluginOnlyCustomization does NOT block here — it gates at the
// REGISTRATION sites (runAgent.ts:526 for agent frontmatter hooks) where
// agentDefinition.source is known. A blanket block here would also kill
// plugin-provided agents' frontmatter hooks, which is too broad.
// Also skip if appState not provided (for backwards compatibility)
if (!managedOnly && appState !== undefined) {
const sessionHooks = getSessionHooks(appState, sessionId, hookEvent).get(
hookEvent,
)
if (sessionHooks) {
// SessionDerivedHookMatcher already includes optional skillRoot
for (const matcher of sessionHooks) {
hooks.push(matcher)
}
}
// Merge session function hooks separately (can't be persisted to HookMatcher format)
const sessionFunctionHooks = getSessionFunctionHooks(
appState,
sessionId,
hookEvent,
).get(hookEvent)
if (sessionFunctionHooks) {
for (const matcher of sessionFunctionHooks) {
hooks.push(matcher)
}
}
}
return hooks
}
/**
* Lightweight existence check for hooks on a given event. Mirrors the sources
* assembled by getHooksConfig() but stops at the first hit without building
* the full merged config.
*
* Intentionally over-approximates: returns true if any matcher exists for the
* event, even if managed-only filtering or pattern matching would later
* discard it. A false positive just means we proceed to the full matching
* path; a false negative would skip a hook, so we err on the side of true.
*
* Used to skip createBaseHookInput (getTranscriptPathForSession path joins)
* and getMatchingHooks on hot paths where hooks are typically unconfigured.
* See hasInstructionsLoadedHook / hasWorktreeCreateHook for the same pattern.
*/
function hasHookForEvent(
hookEvent: HookEvent,
appState: AppState | undefined,
sessionId: string,
): boolean {
const snap = getHooksConfigFromSnapshot()?.[hookEvent]
if (snap && snap.length > 0) return true
const reg = getRegisteredHooks()?.[hookEvent]
if (reg && reg.length > 0) return true
if (appState?.sessionHooks.get(sessionId)?.hooks[hookEvent]) return true
return false
}
/**
* Get hook commands that match the given query
* @param appState The current app state (optional for backwards compatibility)
* @param sessionId The current session ID (main session or agent ID)
* @param hookEvent The hook event
* @param hookInput The hook input for matching
* @returns Array of matched hooks with optional plugin context
*/
export async function getMatchingHooks(
appState: AppState | undefined,
sessionId: string,
hookEvent: HookEvent,
hookInput: HookInput,
tools?: Tools,
): Promise<MatchedHook[]> {
try {
const hookMatchers = getHooksConfig(appState, sessionId, hookEvent)
// If you change the criteria below, then you must change
// src/utils/hooks/hooksConfigManager.ts as well.
let matchQuery: string | undefined = undefined
switch (hookInput.hook_event_name) {
case 'PreToolUse':
case 'PostToolUse':
case 'PostToolUseFailure':
case 'PermissionRequest':
case 'PermissionDenied':
matchQuery = hookInput.tool_name
break
case 'SessionStart':
matchQuery = hookInput.source
break
case 'Setup':
matchQuery = hookInput.trigger
break
case 'PreCompact':
case 'PostCompact':
matchQuery = hookInput.trigger
break
case 'Notification':
matchQuery = hookInput.notification_type
break
case 'SessionEnd':
matchQuery = hookInput.reason
break
case 'StopFailure':
matchQuery = hookInput.error
break
case 'SubagentStart':
matchQuery = hookInput.agent_type
break
case 'SubagentStop':
matchQuery = hookInput.agent_type
break
case 'TeammateIdle':
case 'TaskCreated':
case 'TaskCompleted':
break
case 'Elicitation':
matchQuery = hookInput.mcp_server_name
break
case 'ElicitationResult':
matchQuery = hookInput.mcp_server_name
break
case 'ConfigChange':
matchQuery = hookInput.source
break
case 'InstructionsLoaded':
matchQuery = hookInput.load_reason
break
case 'FileChanged':
matchQuery = basename(hookInput.file_path)
break
default:
break
}
logForDebugging(
`Getting matching hook commands for ${hookEvent} with query: ${matchQuery}`,
{ level: 'verbose' },
)
logForDebugging(`Found ${hookMatchers.length} hook matchers in settings`, {
level: 'verbose',
})
// Extract hooks with their plugin context (if any)
const filteredMatchers = matchQuery
? hookMatchers.filter(
matcher =>
!matcher.matcher || matchesPattern(matchQuery, matcher.matcher),
)
: hookMatchers
const matchedHooks: MatchedHook[] = filteredMatchers.flatMap(matcher => {
// Check if this is a PluginHookMatcher (has pluginRoot) or SkillHookMatcher (has skillRoot)
const pluginRoot =
'pluginRoot' in matcher ? matcher.pluginRoot : undefined
const pluginId = 'pluginId' in matcher ? matcher.pluginId : undefined
const skillRoot = 'skillRoot' in matcher ? matcher.skillRoot : undefined
const hookSource = pluginRoot
? 'pluginName' in matcher
? `plugin:${matcher.pluginName}`
: 'plugin'
: skillRoot
? 'skillName' in matcher
? `skill:${matcher.skillName}`
: 'skill'
: 'settings'
return matcher.hooks.map(hook => ({
hook,
pluginRoot,
pluginId,
skillRoot,
hookSource,
}))
})
// Deduplicate hooks by command/prompt/url within the same source context.
// Key is namespaced by pluginRoot/skillRoot (see hookDedupKey above) so
// cross-plugin template collisions don't drop hooks (gh-29724).
//
// Note: new Map(entries) keeps the LAST entry on key collision, not first.
// For settings hooks this means the last-merged scope wins; for
// same-plugin duplicates the pluginRoot is identical so it doesn't matter.
// Fast-path: callback/function hooks don't need dedup (each is unique).
// Skip the 6-pass filter + 4×Map + 4×Array.from below when all hooks are
// callback/function — the common case for internal hooks like
// sessionFileAccessHooks/attributionHooks (44x faster in microbench).
if (
matchedHooks.every(
m => m.hook.type === 'callback' || m.hook.type === 'function',
)
) {
return matchedHooks
}
// Helper to extract the `if` condition from a hook for dedup keys.
// Hooks with different `if` conditions are distinct even if otherwise identical.
const getIfCondition = (hook: { if?: string }): string => hook.if ?? ''
const uniqueCommandHooks = Array.from(
new Map(
matchedHooks
.filter(
(
m,
): m is MatchedHook & { hook: HookCommand & { type: 'command' } } =>
m.hook.type === 'command',
)
// shell is part of identity: {command:'echo x', shell:'bash'}
// and {command:'echo x', shell:'powershell'} are distinct hooks,
// not duplicates. Default to 'bash' so legacy configs (no shell
// field) still dedup against explicit shell:'bash'.
.map(m => [
hookDedupKey(
m,
`${m.hook.shell ?? DEFAULT_HOOK_SHELL}\0${m.hook.command}\0${getIfCondition(m.hook)}`,
),
m,
]),
).values(),
)
const uniquePromptHooks = Array.from(
new Map(
matchedHooks
.filter(m => m.hook.type === 'prompt')
.map(m => [
hookDedupKey(
m,
`${(m.hook as { prompt: string }).prompt}\0${getIfCondition(m.hook as { if?: string })}`,
),
m,
]),
).values(),
)
const uniqueAgentHooks = Array.from(
new Map(
matchedHooks
.filter(m => m.hook.type === 'agent')
.map(m => [
hookDedupKey(
m,
`${(m.hook as { prompt: string }).prompt}\0${getIfCondition(m.hook as { if?: string })}`,
),
m,
]),
).values(),
)
const uniqueHttpHooks = Array.from(
new Map(
matchedHooks
.filter(m => m.hook.type === 'http')
.map(m => [
hookDedupKey(
m,
`${(m.hook as { url: string }).url}\0${getIfCondition(m.hook as { if?: string })}`,
),
m,
]),
).values(),
)
const callbackHooks = matchedHooks.filter(m => m.hook.type === 'callback')
// Function hooks don't need deduplication - each callback is unique
const functionHooks = matchedHooks.filter(m => m.hook.type === 'function')
const uniqueHooks = [
...uniqueCommandHooks,
...uniquePromptHooks,
...uniqueAgentHooks,
...uniqueHttpHooks,
...callbackHooks,
...functionHooks,
]
// Filter hooks based on their `if` condition. This allows hooks to specify
// conditions like "Bash(git *)" to only run for git commands, avoiding
// process spawning overhead for non-matching commands.
const hasIfCondition = uniqueHooks.some(
h =>
(h.hook.type === 'command' ||
h.hook.type === 'prompt' ||
h.hook.type === 'agent' ||
h.hook.type === 'http') &&
(h.hook as { if?: string }).if,
)
const ifMatcher = hasIfCondition
? await prepareIfConditionMatcher(hookInput, tools)
: undefined
const ifFilteredHooks = uniqueHooks.filter(h => {
if (
h.hook.type !== 'command' &&
h.hook.type !== 'prompt' &&
h.hook.type !== 'agent' &&
h.hook.type !== 'http'
) {
return true
}
const ifCondition = (h.hook as { if?: string }).if
if (!ifCondition) {
return true
}
if (!ifMatcher) {
logForDebugging(
`Hook if condition "${ifCondition}" cannot be evaluated for non-tool event ${hookInput.hook_event_name}`,
)
return false
}
if (ifMatcher(ifCondition)) {
return true
}
logForDebugging(
`Skipping hook due to if condition "${ifCondition}" not matching`,
)
return false
})
// HTTP hooks are not supported for SessionStart/Setup events. In headless
// mode the sandbox ask callback deadlocks because the structuredInput
// consumer hasn't started yet when these hooks fire.
const filteredHooks =
hookEvent === 'SessionStart' || hookEvent === 'Setup'
? ifFilteredHooks.filter(h => {
if (h.hook.type === 'http') {
logForDebugging(
`Skipping HTTP hook ${(h.hook as { url: string }).url} — HTTP hooks are not supported for ${hookEvent}`,
)
return false
}
return true
})
: ifFilteredHooks
logForDebugging(
`Matched ${filteredHooks.length} unique hooks for query "${matchQuery || 'no match query'}" (${matchedHooks.length} before deduplication)`,
{ level: 'verbose' },
)
return filteredHooks
} catch {
return []
}
}
/**
* Format a list of blocking errors from a PreTool hook's configured commands.
* @param hookName The name of the hook (e.g., 'PreToolUse:Write', 'PreToolUse:Edit', 'PreToolUse:Bash')
* @param blockingErrors Array of blocking errors from hooks
* @returns Formatted blocking message
*/
export function getPreToolHookBlockingMessage(
hookName: string,
blockingError: HookBlockingError,
): string {
return `${hookName} hook error: ${blockingError.blockingError}`
}
/**
* Format a list of blocking errors from a Stop hook's configured commands.
* @param blockingErrors Array of blocking errors from hooks
* @returns Formatted message to give feedback to the model
*/
export function getStopHookMessage(blockingError: HookBlockingError): string {
return `Stop hook feedback:\n${blockingError.blockingError}`
}
/**
* Format a blocking error from a TeammateIdle hook.
* @param blockingError The blocking error from the hook
* @returns Formatted message to give feedback to the model
*/
export function getTeammateIdleHookMessage(
blockingError: HookBlockingError,
): string {
return `TeammateIdle hook feedback:\n${blockingError.blockingError}`
}
/**
* Format a blocking error from a TaskCreated hook.
* @param blockingError The blocking error from the hook
* @returns Formatted message to give feedback to the model
*/
export function getTaskCreatedHookMessage(
blockingError: HookBlockingError,
): string {
return `TaskCreated hook feedback:\n${blockingError.blockingError}`
}
/**
* Format a blocking error from a TaskCompleted hook.
* @param blockingError The blocking error from the hook
* @returns Formatted message to give feedback to the model
*/
export function getTaskCompletedHookMessage(
blockingError: HookBlockingError,
): string {
return `TaskCompleted hook feedback:\n${blockingError.blockingError}`
}
/**
* Format a list of blocking errors from a UserPromptSubmit hook's configured commands.
* @param blockingErrors Array of blocking errors from hooks
* @returns Formatted blocking message
*/
export function getUserPromptSubmitHookBlockingMessage(
blockingError: HookBlockingError,
): string {
return `UserPromptSubmit operation blocked by hook:\n${blockingError.blockingError}`
}
/**
* Common logic for executing hooks
* @param hookInput The structured hook input that will be validated and converted to JSON
* @param toolUseID The ID for tracking this hook execution
* @param matchQuery The query to match against hook matchers
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @param toolUseContext Optional ToolUseContext for prompt-based hooks (required if using prompt hooks)
* @param messages Optional conversation history for prompt/function hooks
* @returns Async generator that yields progress messages and hook results
*/
async function* executeHooks({
hookInput,
toolUseID,
matchQuery,
signal,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
toolUseContext,
messages,
forceSyncExecution,
requestPrompt,
toolInputSummary,
}: {
hookInput: HookInput
toolUseID: string
matchQuery?: string
signal?: AbortSignal
timeoutMs?: number
toolUseContext?: ToolUseContext
messages?: Message[]
forceSyncExecution?: boolean
requestPrompt?: (
sourceName: string,
toolInputSummary?: string | null,
) => (request: PromptRequest) => Promise<PromptResponse>
toolInputSummary?: string | null
}): AsyncGenerator<AggregatedHookResult> {
if (shouldDisableAllHooksIncludingManaged()) {
return
}
if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
return
}
const hookEvent = hookInput.hook_event_name
const hookName = matchQuery ? `${hookEvent}:${matchQuery}` : hookEvent
// Bind the prompt callback to this hook's name and tool input summary so the UI can display context
const boundRequestPrompt = requestPrompt?.(hookName, toolInputSummary)
// SECURITY: ALL hooks require workspace trust in interactive mode
// This centralized check prevents RCE vulnerabilities for all current and future hooks
if (shouldSkipHookDueToTrust()) {
logForDebugging(
`Skipping ${hookName} hook execution - workspace trust not accepted`,
)
return
}
const appState = toolUseContext ? toolUseContext.getAppState() : undefined
// Use the agent's session ID if available, otherwise fall back to main session
const sessionId = toolUseContext?.agentId ?? getSessionId()
const matchingHooks = await getMatchingHooks(
appState,
sessionId,
hookEvent,
hookInput,
toolUseContext?.options?.tools,
)
if (matchingHooks.length === 0) {
return
}
if (signal?.aborted) {
return
}
const userHooks = matchingHooks.filter(h => !isInternalHook(h))
if (userHooks.length > 0) {
const pluginHookCounts = getPluginHookCounts(userHooks)
const hookTypeCounts = getHookTypeCounts(userHooks)
logEvent(`tengu_run_hook`, {
hookName:
hookName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
numCommands: userHooks.length,
hookTypeCounts: jsonStringify(
hookTypeCounts,
) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
...(pluginHookCounts && {
pluginHookCounts: jsonStringify(
pluginHookCounts,
) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
}),
})
} else {
// Fast-path: all hooks are internal callbacks (sessionFileAccessHooks,
// attributionHooks). These return {} and don't use the abort signal, so we
// can skip span/progress/abortSignal/processHookJSONOutput/resultLoop.
// Measured: 6.01µs → ~1.8µs per PostToolUse hit (-70%).
const batchStartTime = Date.now()
const context = toolUseContext
? {
getAppState: toolUseContext.getAppState,
updateAttributionState: toolUseContext.updateAttributionState,
}
: undefined
for (const [i, { hook }] of matchingHooks.entries()) {
if (hook.type === 'callback') {
await hook.callback(hookInput, toolUseID, signal, i, context)
}
}
const totalDurationMs = Date.now() - batchStartTime
getStatsStore()?.observe('hook_duration_ms', totalDurationMs)
addToTurnHookDuration(totalDurationMs)
logEvent(`tengu_repl_hook_finished`, {
hookName:
hookName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
numCommands: matchingHooks.length,
numSuccess: matchingHooks.length,
numBlocking: 0,
numNonBlockingError: 0,
numCancelled: 0,
totalDurationMs,
})
return
}
// Collect hook definitions for beta tracing telemetry
const hookDefinitionsJson = isBetaTracingEnabled()
? jsonStringify(getHookDefinitionsForTelemetry(matchingHooks))
: '[]'
// Log hook execution start to OTEL (only for beta tracing)
if (isBetaTracingEnabled()) {
void logOTelEvent('hook_execution_start', {
hook_event: hookEvent,
hook_name: hookName,
num_hooks: String(matchingHooks.length),
managed_only: String(shouldAllowManagedHooksOnly()),
hook_definitions: hookDefinitionsJson,
hook_source: shouldAllowManagedHooksOnly() ? 'policySettings' : 'merged',
})
}
// Start hook span for beta tracing
const hookSpan = startHookSpan(
hookEvent,
hookName,
matchingHooks.length,
hookDefinitionsJson,
)
// Yield progress messages for each hook before execution
for (const { hook } of matchingHooks) {
yield {
message: {
type: 'progress',
data: {
type: 'hook_progress',
hookEvent,
hookName,
command: getHookDisplayText(hook),
...(hook.type === 'prompt' && { promptText: hook.prompt }),
...('statusMessage' in hook &&
hook.statusMessage != null && {
statusMessage: hook.statusMessage,
}),
},
parentToolUseID: toolUseID,
toolUseID,
timestamp: new Date().toISOString(),
uuid: randomUUID(),
},
}
}
// Track wall-clock time for the entire hook batch
const batchStartTime = Date.now()
// Lazy-once stringify of hookInput. Shared across all command/prompt/agent/http
// hooks in this batch (hookInput is never mutated). Callback/function hooks
// return before reaching this, so batches with only those pay no stringify cost.
let jsonInputResult:
| { ok: true; value: string }
| { ok: false; error: unknown }
| undefined
function getJsonInput() {
if (jsonInputResult !== undefined) {
return jsonInputResult
}
try {
return (jsonInputResult = { ok: true, value: jsonStringify(hookInput) })
} catch (error) {
logError(
Error(`Failed to stringify hook ${hookName} input`, { cause: error }),
)
return (jsonInputResult = { ok: false, error })
}
}
// Run all hooks in parallel with individual timeouts
const hookPromises = matchingHooks.map(async function* (
{ hook, pluginRoot, pluginId, skillRoot },
hookIndex,
): AsyncGenerator<HookResult> {
if (hook.type === 'callback') {
const callbackTimeoutMs = hook.timeout ? hook.timeout * 1000 : timeoutMs
const { signal: abortSignal, cleanup } = createCombinedAbortSignal(
signal,
{ timeoutMs: callbackTimeoutMs },
)
yield executeHookCallback({
toolUseID,
hook,
hookEvent,
hookInput,
signal: abortSignal,
hookIndex,
toolUseContext,
}).finally(cleanup)
return
}
if (hook.type === 'function') {
if (!messages) {
yield {
message: createAttachmentMessage({
type: 'hook_error_during_execution',
hookName,
toolUseID,
hookEvent,
content: 'Messages not provided for function hook',
}),
outcome: 'non_blocking_error',
hook,
}
return
}
// Function hooks only come from session storage with callback embedded
yield executeFunctionHook({
hook,
messages,
hookName,
toolUseID,
hookEvent,
timeoutMs,
signal,
})
return
}
// Command and prompt hooks need jsonInput
const commandTimeoutMs = hook.timeout ? hook.timeout * 1000 : timeoutMs
const { signal: abortSignal, cleanup } = createCombinedAbortSignal(signal, {
timeoutMs: commandTimeoutMs,
})
const hookId = randomUUID()
const hookStartMs = Date.now()
const hookCommand = getHookDisplayText(hook)
try {
const jsonInputRes = getJsonInput()
if (!jsonInputRes.ok) {
yield {
message: createAttachmentMessage({
type: 'hook_error_during_execution',
hookName,
toolUseID,
hookEvent,
content: `Failed to prepare hook input: ${errorMessage(jsonInputRes.error)}`,
command: hookCommand,
durationMs: Date.now() - hookStartMs,
}),
outcome: 'non_blocking_error',
hook,
}
cleanup()
return
}
const jsonInput = jsonInputRes.value
if (hook.type === 'prompt') {
if (!toolUseContext) {
throw new Error(
'ToolUseContext is required for prompt hooks. This is a bug.',
)
}
const promptResult = await execPromptHook(
hook,
hookName,
hookEvent,
jsonInput,
abortSignal,
toolUseContext,
messages,
toolUseID,
)
// Inject timing fields for hook visibility
if (promptResult.message?.type === 'attachment') {
const att = promptResult.message.attachment
if (
att.type === 'hook_success' ||
att.type === 'hook_non_blocking_error'
) {
att.command = hookCommand
att.durationMs = Date.now() - hookStartMs
}
}
yield promptResult
cleanup?.()
return
}
if (hook.type === 'agent') {
if (!toolUseContext) {
throw new Error(
'ToolUseContext is required for agent hooks. This is a bug.',
)
}
if (!messages) {
throw new Error(
'Messages are required for agent hooks. This is a bug.',
)
}
const agentResult = await execAgentHook(
hook,
hookName,
hookEvent,
jsonInput,
abortSignal,
toolUseContext,
toolUseID,
messages,
'agent_type' in hookInput
? (hookInput.agent_type as string)
: undefined,
)
// Inject timing fields for hook visibility
if (agentResult.message?.type === 'attachment') {
const att = agentResult.message.attachment
if (
att.type === 'hook_success' ||
att.type === 'hook_non_blocking_error'
) {
att.command = hookCommand
att.durationMs = Date.now() - hookStartMs
}
}
yield agentResult
cleanup?.()
return
}
if (hook.type === 'http') {
emitHookStarted(hookId, hookName, hookEvent)
// execHttpHook manages its own timeout internally via hook.timeout or
// DEFAULT_HTTP_HOOK_TIMEOUT_MS, so pass the parent signal directly
// to avoid double-stacking timeouts with abortSignal.
const httpResult = await execHttpHook(
hook,
hookEvent,
jsonInput,
signal,
)
cleanup?.()
if (httpResult.aborted) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: 'Hook cancelled',
stdout: '',
stderr: '',
exitCode: undefined,
outcome: 'cancelled',
})
yield {
message: createAttachmentMessage({
type: 'hook_cancelled',
hookName,
toolUseID,
hookEvent,
}),
outcome: 'cancelled' as const,
hook,
}
return
}
if (httpResult.error || !httpResult.ok) {
const stderr =
httpResult.error || `HTTP ${httpResult.statusCode} from ${hook.url}`
emitHookResponse({
hookId,
hookName,
hookEvent,
output: stderr,
stdout: '',
stderr,
exitCode: httpResult.statusCode,
outcome: 'error',
})
yield {
message: createAttachmentMessage({
type: 'hook_non_blocking_error',
hookName,
toolUseID,
hookEvent,
stderr,
stdout: '',
exitCode: httpResult.statusCode ?? 0,
}),
outcome: 'non_blocking_error' as const,
hook,
}
return
}
// HTTP hooks must return JSON — parse and validate through Zod
const { json: httpJson, validationError: httpValidationError } =
parseHttpHookOutput(httpResult.body)
if (httpValidationError) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: httpResult.body,
stdout: httpResult.body,
stderr: `JSON validation failed: ${httpValidationError}`,
exitCode: httpResult.statusCode,
outcome: 'error',
})
yield {
message: createAttachmentMessage({
type: 'hook_non_blocking_error',
hookName,
toolUseID,
hookEvent,
stderr: `JSON validation failed: ${httpValidationError}`,
stdout: httpResult.body,
exitCode: httpResult.statusCode ?? 0,
}),
outcome: 'non_blocking_error' as const,
hook,
}
return
}
if (httpJson && isAsyncHookJSONOutput(httpJson)) {
// Async response: treat as success (no further processing)
emitHookResponse({
hookId,
hookName,
hookEvent,
output: httpResult.body,
stdout: httpResult.body,
stderr: '',
exitCode: httpResult.statusCode,
outcome: 'success',
})
yield {
outcome: 'success' as const,
hook,
}
return
}
if (httpJson) {
const processed = processHookJSONOutput({
json: httpJson,
command: hook.url,
hookName,
toolUseID,
hookEvent,
expectedHookEvent: hookEvent,
stdout: httpResult.body,
stderr: '',
exitCode: httpResult.statusCode,
})
emitHookResponse({
hookId,
hookName,
hookEvent,
output: httpResult.body,
stdout: httpResult.body,
stderr: '',
exitCode: httpResult.statusCode,
outcome: 'success',
})
yield {
...processed,
outcome: 'success' as const,
hook,
}
return
}
return
}
emitHookStarted(hookId, hookName, hookEvent)
const result = await execCommandHook(
hook,
hookEvent,
hookName,
jsonInput,
abortSignal,
hookId,
hookIndex,
pluginRoot,
pluginId,
skillRoot,
forceSyncExecution,
boundRequestPrompt,
)
cleanup?.()
const durationMs = Date.now() - hookStartMs
if (result.backgrounded) {
yield {
outcome: 'success' as const,
hook,
}
return
}
if (result.aborted) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: 'cancelled',
})
yield {
message: createAttachmentMessage({
type: 'hook_cancelled',
hookName,
toolUseID,
hookEvent,
command: hookCommand,
durationMs,
}),
outcome: 'cancelled' as const,
hook,
}
return
}
// Try JSON parsing first
const { json, plainText, validationError } = parseHookOutput(
result.stdout,
)
if (validationError) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: `JSON validation failed: ${validationError}`,
exitCode: 1,
outcome: 'error',
})
yield {
message: createAttachmentMessage({
type: 'hook_non_blocking_error',
hookName,
toolUseID,
hookEvent,
stderr: `JSON validation failed: ${validationError}`,
stdout: result.stdout,
exitCode: 1,
command: hookCommand,
durationMs,
}),
outcome: 'non_blocking_error' as const,
hook,
}
return
}
if (json) {
// Async responses were already backgrounded during execution
if (isAsyncHookJSONOutput(json)) {
yield {
outcome: 'success' as const,
hook,
}
return
}
// Process JSON output
const processed = processHookJSONOutput({
json,
command: hookCommand,
hookName,
toolUseID,
hookEvent,
expectedHookEvent: hookEvent,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
durationMs,
})
// Handle suppressOutput (skip for async responses)
if (
isSyncHookJSONOutput(json) &&
!json.suppressOutput &&
plainText &&
result.status === 0
) {
// Still show non-JSON output if not suppressed
const content = `${chalk.bold(hookName)} completed`
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: 'success',
})
yield {
...processed,
message:
processed.message ||
createAttachmentMessage({
type: 'hook_success',
hookName,
toolUseID,
hookEvent,
content,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
command: hookCommand,
durationMs,
}),
outcome: 'success' as const,
hook,
}
return
}
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: result.status === 0 ? 'success' : 'error',
})
yield {
...processed,
outcome: 'success' as const,
hook,
}
return
}
// Fall back to existing logic for non-JSON output
if (result.status === 0) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: 'success',
})
yield {
message: createAttachmentMessage({
type: 'hook_success',
hookName,
toolUseID,
hookEvent,
content: result.stdout.trim(),
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
command: hookCommand,
durationMs,
}),
outcome: 'success' as const,
hook,
}
return
}
// Hooks with exit code 2 provide blocking feedback
if (result.status === 2) {
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: 'error',
})
yield {
blockingError: {
blockingError: `[${hook.command}]: ${result.stderr || 'No stderr output'}`,
command: hook.command,
},
outcome: 'blocking' as const,
hook,
}
return
}
// Any other non-zero exit code is a non-critical error that should just
// be shown to the user.
emitHookResponse({
hookId,
hookName,
hookEvent,
output: result.output,
stdout: result.stdout,
stderr: result.stderr,
exitCode: result.status,
outcome: 'error',
})
yield {
message: createAttachmentMessage({
type: 'hook_non_blocking_error',
hookName,
toolUseID,
hookEvent,
stderr: `Failed with non-blocking status code: ${result.stderr.trim() || 'No stderr output'}`,
stdout: result.stdout,
exitCode: result.status,
command: hookCommand,
durationMs,
}),
outcome: 'non_blocking_error' as const,
hook,
}
return
} catch (error) {
// Clean up on error
cleanup?.()
const errorMessage =
error instanceof Error ? error.message : String(error)
emitHookResponse({
hookId,
hookName,
hookEvent,
output: `Failed to run: ${errorMessage}`,
stdout: '',
stderr: `Failed to run: ${errorMessage}`,
exitCode: 1,
outcome: 'error',
})
yield {
message: createAttachmentMessage({
type: 'hook_non_blocking_error',
hookName,
toolUseID,
hookEvent,
stderr: `Failed to run: ${errorMessage}`,
stdout: '',
exitCode: 1,
command: hookCommand,
durationMs: Date.now() - hookStartMs,
}),
outcome: 'non_blocking_error' as const,
hook,
}
return
}
})
// Track outcomes for logging
const outcomes = {
success: 0,
blocking: 0,
non_blocking_error: 0,
cancelled: 0,
}
let permissionBehavior: PermissionResult['behavior'] | undefined
// Run all hooks in parallel and wait for all to complete
for await (const result of all(hookPromises)) {
outcomes[result.outcome]++
// Check for preventContinuation early
if (result.preventContinuation) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) requested preventContinuation`,
)
yield {
preventContinuation: true,
stopReason: result.stopReason,
}
}
// Handle different result types
if (result.blockingError) {
yield {
blockingError: result.blockingError,
}
}
if (result.message) {
yield { message: result.message }
}
// Yield system message separately if present
if (result.systemMessage) {
yield {
message: createAttachmentMessage({
type: 'hook_system_message',
content: result.systemMessage,
hookName,
toolUseID,
hookEvent,
}),
}
}
// Collect additional context from hooks
if (result.additionalContext) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) provided additionalContext (${result.additionalContext.length} chars)`,
)
yield {
additionalContexts: [result.additionalContext],
}
}
if (result.initialUserMessage) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) provided initialUserMessage (${result.initialUserMessage.length} chars)`,
)
yield {
initialUserMessage: result.initialUserMessage,
}
}
if (result.watchPaths && result.watchPaths.length > 0) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) provided ${result.watchPaths.length} watchPaths`,
)
yield {
watchPaths: result.watchPaths,
}
}
// Yield updatedMCPToolOutput if provided (from PostToolUse hooks)
if (result.updatedMCPToolOutput) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) replaced MCP tool output`,
)
yield {
updatedMCPToolOutput: result.updatedMCPToolOutput,
}
}
// Check for permission behavior with precedence: deny > ask > allow
if (result.permissionBehavior) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) returned permissionDecision: ${result.permissionBehavior}${result.hookPermissionDecisionReason ? ` (reason: ${result.hookPermissionDecisionReason})` : ''}`,
)
// Apply precedence rules
switch (result.permissionBehavior) {
case 'deny':
// deny always takes precedence
permissionBehavior = 'deny'
break
case 'ask':
// ask takes precedence over allow but not deny
if (permissionBehavior !== 'deny') {
permissionBehavior = 'ask'
}
break
case 'allow':
// allow only if no other behavior set
if (!permissionBehavior) {
permissionBehavior = 'allow'
}
break
case 'passthrough':
// passthrough doesn't set permission behavior
break
}
}
// Yield permission behavior and updatedInput if provided (from allow or ask behavior)
if (permissionBehavior !== undefined) {
const updatedInput =
result.updatedInput &&
(result.permissionBehavior === 'allow' ||
result.permissionBehavior === 'ask')
? result.updatedInput
: undefined
if (updatedInput) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) modified tool input keys: [${Object.keys(updatedInput).join(', ')}]`,
)
}
yield {
permissionBehavior,
hookPermissionDecisionReason: result.hookPermissionDecisionReason,
hookSource: matchingHooks.find(m => m.hook === result.hook)?.hookSource,
updatedInput,
}
}
// Yield updatedInput separately for passthrough case (no permission decision)
// This allows hooks to modify input without making a permission decision
// Note: Check result.permissionBehavior (this hook's behavior), not the aggregated permissionBehavior
if (result.updatedInput && result.permissionBehavior === undefined) {
logForDebugging(
`Hook ${hookEvent} (${getHookDisplayText(result.hook)}) modified tool input keys: [${Object.keys(result.updatedInput).join(', ')}]`,
)
yield {
updatedInput: result.updatedInput,
}
}
// Yield permission request result if provided (from PermissionRequest hooks)
if (result.permissionRequestResult) {
yield {
permissionRequestResult: result.permissionRequestResult,
}
}
// Yield retry flag if provided (from PermissionDenied hooks)
if (result.retry) {
yield {
retry: result.retry,
}
}
// Yield elicitation response if provided (from Elicitation hooks)
if (result.elicitationResponse) {
yield {
elicitationResponse: result.elicitationResponse,
}
}
// Yield elicitation result response if provided (from ElicitationResult hooks)
if (result.elicitationResultResponse) {
yield {
elicitationResultResponse: result.elicitationResultResponse,
}
}
// Invoke session hook callback if this is a command/prompt/function hook (not a callback hook)
if (appState && result.hook.type !== 'callback') {
const sessionId = getSessionId()
// Use empty string as matcher when matchQuery is undefined (e.g., for Stop hooks)
const matcher = matchQuery ?? ''
const hookEntry = getSessionHookCallback(
appState,
sessionId,
hookEvent,
matcher,
result.hook,
)
// Invoke onHookSuccess only on success outcome
if (hookEntry?.onHookSuccess && result.outcome === 'success') {
try {
hookEntry.onHookSuccess(result.hook, result as AggregatedHookResult)
} catch (error) {
logError(
Error('Session hook success callback failed', { cause: error }),
)
}
}
}
}
const totalDurationMs = Date.now() - batchStartTime
getStatsStore()?.observe('hook_duration_ms', totalDurationMs)
addToTurnHookDuration(totalDurationMs)
logEvent(`tengu_repl_hook_finished`, {
hookName:
hookName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
numCommands: matchingHooks.length,
numSuccess: outcomes.success,
numBlocking: outcomes.blocking,
numNonBlockingError: outcomes.non_blocking_error,
numCancelled: outcomes.cancelled,
totalDurationMs,
})
// Log hook execution completion to OTEL (only for beta tracing)
if (isBetaTracingEnabled()) {
const hookDefinitionsComplete =
getHookDefinitionsForTelemetry(matchingHooks)
void logOTelEvent('hook_execution_complete', {
hook_event: hookEvent,
hook_name: hookName,
num_hooks: String(matchingHooks.length),
num_success: String(outcomes.success),
num_blocking: String(outcomes.blocking),
num_non_blocking_error: String(outcomes.non_blocking_error),
num_cancelled: String(outcomes.cancelled),
managed_only: String(shouldAllowManagedHooksOnly()),
hook_definitions: jsonStringify(hookDefinitionsComplete),
hook_source: shouldAllowManagedHooksOnly() ? 'policySettings' : 'merged',
})
}
// End hook span for beta tracing
endHookSpan(hookSpan, {
numSuccess: outcomes.success,
numBlocking: outcomes.blocking,
numNonBlockingError: outcomes.non_blocking_error,
numCancelled: outcomes.cancelled,
})
}
export type HookOutsideReplResult = {
command: string
succeeded: boolean
output: string
blocked: boolean
watchPaths?: string[]
systemMessage?: string
}
export function hasBlockingResult(results: HookOutsideReplResult[]): boolean {
return results.some(r => r.blocked)
}
/**
* Execute hooks outside of the REPL (e.g. notifications, session end)
*
* Unlike executeHooks() which yields messages that are exposed to the model as
* system messages, this function only logs errors via logForDebugging (visible
* with --debug). Callers that need to surface errors to users should handle
* the returned results appropriately (e.g. executeSessionEndHooks writes to
* stderr during shutdown).
*
* @param getAppState Optional function to get the current app state (for session hooks)
* @param hookInput The structured hook input that will be validated and converted to JSON
* @param matchQuery The query to match against hook matchers
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Array of HookOutsideReplResult objects containing command, succeeded, and output
*/
async function executeHooksOutsideREPL({
getAppState,
hookInput,
matchQuery,
signal,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
}: {
getAppState?: () => AppState
hookInput: HookInput
matchQuery?: string
signal?: AbortSignal
timeoutMs: number
}): Promise<HookOutsideReplResult[]> {
if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
return []
}
const hookEvent = hookInput.hook_event_name
const hookName = matchQuery ? `${hookEvent}:${matchQuery}` : hookEvent
if (shouldDisableAllHooksIncludingManaged()) {
logForDebugging(
`Skipping hooks for ${hookName} due to 'disableAllHooks' managed setting`,
)
return []
}
// SECURITY: ALL hooks require workspace trust in interactive mode
// This centralized check prevents RCE vulnerabilities for all current and future hooks
if (shouldSkipHookDueToTrust()) {
logForDebugging(
`Skipping ${hookName} hook execution - workspace trust not accepted`,
)
return []
}
const appState = getAppState ? getAppState() : undefined
// Use main session ID for outside-REPL hooks
const sessionId = getSessionId()
const matchingHooks = await getMatchingHooks(
appState,
sessionId,
hookEvent,
hookInput,
)
if (matchingHooks.length === 0) {
return []
}
if (signal?.aborted) {
return []
}
const userHooks = matchingHooks.filter(h => !isInternalHook(h))
if (userHooks.length > 0) {
const pluginHookCounts = getPluginHookCounts(userHooks)
const hookTypeCounts = getHookTypeCounts(userHooks)
logEvent(`tengu_run_hook`, {
hookName:
hookName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
numCommands: userHooks.length,
hookTypeCounts: jsonStringify(
hookTypeCounts,
) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
...(pluginHookCounts && {
pluginHookCounts: jsonStringify(
pluginHookCounts,
) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
}),
})
}
// Validate and stringify the hook input
let jsonInput: string
try {
jsonInput = jsonStringify(hookInput)
} catch (error) {
logError(error)
return []
}
// Run all hooks in parallel with individual timeouts
const hookPromises = matchingHooks.map(
async ({ hook, pluginRoot, pluginId }, hookIndex) => {
// Handle callback hooks
if (hook.type === 'callback') {
const callbackTimeoutMs = hook.timeout ? hook.timeout * 1000 : timeoutMs
const { signal: abortSignal, cleanup } = createCombinedAbortSignal(
signal,
{ timeoutMs: callbackTimeoutMs },
)
try {
const toolUseID = randomUUID()
const json = await hook.callback(
hookInput,
toolUseID,
abortSignal,
hookIndex,
)
cleanup?.()
if (isAsyncHookJSONOutput(json)) {
logForDebugging(
`${hookName} [callback] returned async response, returning empty output`,
)
return {
command: 'callback',
succeeded: true,
output: '',
blocked: false,
}
}
const output =
hookEvent === 'WorktreeCreate' &&
isSyncHookJSONOutput(json) &&
json.hookSpecificOutput?.hookEventName === 'WorktreeCreate'
? json.hookSpecificOutput.worktreePath
: json.systemMessage || ''
const blocked =
isSyncHookJSONOutput(json) && json.decision === 'block'
logForDebugging(`${hookName} [callback] completed successfully`)
return {
command: 'callback',
succeeded: true,
output,
blocked,
}
} catch (error) {
cleanup?.()
const errorMessage =
error instanceof Error ? error.message : String(error)
logForDebugging(
`${hookName} [callback] failed to run: ${errorMessage}`,
{ level: 'error' },
)
return {
command: 'callback',
succeeded: false,
output: errorMessage,
blocked: false,
}
}
}
// TODO: Implement prompt stop hooks outside REPL
if (hook.type === 'prompt') {
return {
command: hook.prompt,
succeeded: false,
output: 'Prompt stop hooks are not yet supported outside REPL',
blocked: false,
}
}
// TODO: Implement agent stop hooks outside REPL
if (hook.type === 'agent') {
return {
command: hook.prompt,
succeeded: false,
output: 'Agent stop hooks are not yet supported outside REPL',
blocked: false,
}
}
// Function hooks require messages array (only available in REPL context)
// For -p mode Stop hooks, use executeStopHooks which supports function hooks
if (hook.type === 'function') {
logError(
new Error(
`Function hook reached executeHooksOutsideREPL for ${hookEvent}. Function hooks should only be used in REPL context (Stop hooks).`,
),
)
return {
command: 'function',
succeeded: false,
output: 'Internal error: function hook executed outside REPL context',
blocked: false,
}
}
// Handle HTTP hooks (no toolUseContext needed - just HTTP POST).
// execHttpHook handles its own timeout internally via hook.timeout or
// DEFAULT_HTTP_HOOK_TIMEOUT_MS, so we pass signal directly.
if (hook.type === 'http') {
try {
const httpResult = await execHttpHook(
hook,
hookEvent,
jsonInput,
signal,
)
if (httpResult.aborted) {
logForDebugging(`${hookName} [${hook.url}] cancelled`)
return {
command: hook.url,
succeeded: false,
output: 'Hook cancelled',
blocked: false,
}
}
if (httpResult.error || !httpResult.ok) {
const errMsg =
httpResult.error ||
`HTTP ${httpResult.statusCode} from ${hook.url}`
logForDebugging(`${hookName} [${hook.url}] failed: ${errMsg}`, {
level: 'error',
})
return {
command: hook.url,
succeeded: false,
output: errMsg,
blocked: false,
}
}
// HTTP hooks must return JSON — parse and validate through Zod
const { json: httpJson, validationError: httpValidationError } =
parseHttpHookOutput(httpResult.body)
if (httpValidationError) {
throw new Error(httpValidationError)
}
if (httpJson && !isAsyncHookJSONOutput(httpJson)) {
logForDebugging(
`Parsed JSON output from HTTP hook: ${jsonStringify(httpJson)}`,
{ level: 'verbose' },
)
}
const jsonBlocked =
httpJson &&
!isAsyncHookJSONOutput(httpJson) &&
isSyncHookJSONOutput(httpJson) &&
httpJson.decision === 'block'
// WorktreeCreate's consumer reads `output` as the bare filesystem
// path. Command hooks provide it via stdout; http hooks provide it
// via hookSpecificOutput.worktreePath. Without worktreePath, emit ''
// so the consumer's length filter skips it instead of treating the
// raw '{}' body as a path.
const output =
hookEvent === 'WorktreeCreate'
? httpJson &&
isSyncHookJSONOutput(httpJson) &&
httpJson.hookSpecificOutput?.hookEventName === 'WorktreeCreate'
? httpJson.hookSpecificOutput.worktreePath
: ''
: httpResult.body
return {
command: hook.url,
succeeded: true,
output,
blocked: !!jsonBlocked,
}
} catch (error) {
const errorMessage =
error instanceof Error ? error.message : String(error)
logForDebugging(
`${hookName} [${hook.url}] failed to run: ${errorMessage}`,
{ level: 'error' },
)
return {
command: hook.url,
succeeded: false,
output: errorMessage,
blocked: false,
}
}
}
// Handle command hooks
const commandTimeoutMs = hook.timeout ? hook.timeout * 1000 : timeoutMs
const { signal: abortSignal, cleanup } = createCombinedAbortSignal(
signal,
{ timeoutMs: commandTimeoutMs },
)
try {
const result = await execCommandHook(
hook,
hookEvent,
hookName,
jsonInput,
abortSignal,
randomUUID(),
hookIndex,
pluginRoot,
pluginId,
)
// Clear timeout if hook completes
cleanup?.()
if (result.aborted) {
logForDebugging(`${hookName} [${hook.command}] cancelled`)
return {
command: hook.command,
succeeded: false,
output: 'Hook cancelled',
blocked: false,
}
}
logForDebugging(
`${hookName} [${hook.command}] completed with status ${result.status}`,
)
// Parse JSON for any messages to print out.
const { json, validationError } = parseHookOutput(result.stdout)
if (validationError) {
// Validation error is logged via logForDebugging and returned in output
throw new Error(validationError)
}
if (json && !isAsyncHookJSONOutput(json)) {
logForDebugging(
`Parsed JSON output from hook: ${jsonStringify(json)}`,
{ level: 'verbose' },
)
}
// Blocked if exit code 2 or JSON decision: 'block'
const jsonBlocked =
json &&
!isAsyncHookJSONOutput(json) &&
isSyncHookJSONOutput(json) &&
json.decision === 'block'
const blocked = result.status === 2 || !!jsonBlocked
// For successful hooks (exit code 0), use stdout; for failed hooks, use stderr
const output =
result.status === 0 ? result.stdout || '' : result.stderr || ''
const watchPaths =
json &&
isSyncHookJSONOutput(json) &&
json.hookSpecificOutput &&
'watchPaths' in json.hookSpecificOutput
? json.hookSpecificOutput.watchPaths
: undefined
const systemMessage =
json && isSyncHookJSONOutput(json) ? json.systemMessage : undefined
return {
command: hook.command,
succeeded: result.status === 0,
output,
blocked,
watchPaths,
systemMessage,
}
} catch (error) {
// Clean up on error
cleanup?.()
const errorMessage =
error instanceof Error ? error.message : String(error)
logForDebugging(
`${hookName} [${hook.command}] failed to run: ${errorMessage}`,
{ level: 'error' },
)
return {
command: hook.command,
succeeded: false,
output: errorMessage,
blocked: false,
}
}
},
)
// Wait for all hooks to complete and collect results
return await Promise.all(hookPromises)
}
/**
* Execute pre-tool hooks if configured
* @param toolName The name of the tool (e.g., 'Write', 'Edit', 'Bash')
* @param toolUseID The ID of the tool use
* @param toolInput The input that will be passed to the tool
* @param permissionMode Optional permission mode from toolPermissionContext
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @param toolUseContext Optional ToolUseContext for prompt-based hooks
* @returns Async generator that yields progress messages and returns blocking errors
*/
export async function* executePreToolHooks<ToolInput>(
toolName: string,
toolUseID: string,
toolInput: ToolInput,
toolUseContext: ToolUseContext,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
requestPrompt?: (
sourceName: string,
toolInputSummary?: string | null,
) => (request: PromptRequest) => Promise<PromptResponse>,
toolInputSummary?: string | null,
): AsyncGenerator<AggregatedHookResult> {
const appState = toolUseContext.getAppState()
const sessionId = toolUseContext.agentId ?? getSessionId()
if (!hasHookForEvent('PreToolUse', appState, sessionId)) {
return
}
logForDebugging(`executePreToolHooks called for tool: ${toolName}`, {
level: 'verbose',
})
const hookInput: PreToolUseHookInput = {
...createBaseHookInput(permissionMode, undefined, toolUseContext),
hook_event_name: 'PreToolUse',
tool_name: toolName,
tool_input: toolInput,
tool_use_id: toolUseID,
}
yield* executeHooks({
hookInput,
toolUseID,
matchQuery: toolName,
signal,
timeoutMs,
toolUseContext,
requestPrompt,
toolInputSummary,
})
}
/**
* Execute post-tool hooks if configured
* @param toolName The name of the tool (e.g., 'Write', 'Edit', 'Bash')
* @param toolUseID The ID of the tool use
* @param toolInput The input that was passed to the tool
* @param toolResponse The response from the tool
* @param toolUseContext ToolUseContext for prompt-based hooks
* @param permissionMode Optional permission mode from toolPermissionContext
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and blocking errors for automated feedback
*/
export async function* executePostToolHooks<ToolInput, ToolResponse>(
toolName: string,
toolUseID: string,
toolInput: ToolInput,
toolResponse: ToolResponse,
toolUseContext: ToolUseContext,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: PostToolUseHookInput = {
...createBaseHookInput(permissionMode, undefined, toolUseContext),
hook_event_name: 'PostToolUse',
tool_name: toolName,
tool_input: toolInput,
tool_response: toolResponse,
tool_use_id: toolUseID,
}
yield* executeHooks({
hookInput,
toolUseID,
matchQuery: toolName,
signal,
timeoutMs,
toolUseContext,
})
}
/**
* Execute post-tool-use-failure hooks if configured
* @param toolName The name of the tool (e.g., 'Write', 'Edit', 'Bash')
* @param toolUseID The ID of the tool use
* @param toolInput The input that was passed to the tool
* @param error The error message from the failed tool call
* @param toolUseContext ToolUseContext for prompt-based hooks
* @param isInterrupt Whether the tool was interrupted by user
* @param permissionMode Optional permission mode from toolPermissionContext
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and blocking errors
*/
export async function* executePostToolUseFailureHooks<ToolInput>(
toolName: string,
toolUseID: string,
toolInput: ToolInput,
error: string,
toolUseContext: ToolUseContext,
isInterrupt?: boolean,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): AsyncGenerator<AggregatedHookResult> {
const appState = toolUseContext.getAppState()
const sessionId = toolUseContext.agentId ?? getSessionId()
if (!hasHookForEvent('PostToolUseFailure', appState, sessionId)) {
return
}
const hookInput: PostToolUseFailureHookInput = {
...createBaseHookInput(permissionMode, undefined, toolUseContext),
hook_event_name: 'PostToolUseFailure',
tool_name: toolName,
tool_input: toolInput,
tool_use_id: toolUseID,
error,
is_interrupt: isInterrupt,
}
yield* executeHooks({
hookInput,
toolUseID,
matchQuery: toolName,
signal,
timeoutMs,
toolUseContext,
})
}
export async function* executePermissionDeniedHooks<ToolInput>(
toolName: string,
toolUseID: string,
toolInput: ToolInput,
reason: string,
toolUseContext: ToolUseContext,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): AsyncGenerator<AggregatedHookResult> {
const appState = toolUseContext.getAppState()
const sessionId = toolUseContext.agentId ?? getSessionId()
if (!hasHookForEvent('PermissionDenied', appState, sessionId)) {
return
}
const hookInput: PermissionDeniedHookInput = {
...createBaseHookInput(permissionMode, undefined, toolUseContext),
hook_event_name: 'PermissionDenied',
tool_name: toolName,
tool_input: toolInput,
tool_use_id: toolUseID,
reason,
}
yield* executeHooks({
hookInput,
toolUseID,
matchQuery: toolName,
signal,
timeoutMs,
toolUseContext,
})
}
/**
* Execute notification hooks if configured
* @param notificationData The notification data to pass to hooks
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Promise that resolves when all hooks complete
*/
export async function executeNotificationHooks(
notificationData: {
message: string
title?: string
notificationType: string
},
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<void> {
const { message, title, notificationType } = notificationData
const hookInput: NotificationHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'Notification',
message,
title,
notification_type: notificationType,
}
await executeHooksOutsideREPL({
hookInput,
timeoutMs,
matchQuery: notificationType,
})
}
export async function executeStopFailureHooks(
lastMessage: AssistantMessage,
toolUseContext?: ToolUseContext,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<void> {
const appState = toolUseContext?.getAppState()
// executeHooksOutsideREPL hardcodes main sessionId (:2738). Agent frontmatter
// hooks (registerFrontmatterHooks) key by agentId; gating with agentId here
// would pass the gate but fail execution. Align gate with execution.
const sessionId = getSessionId()
if (!hasHookForEvent('StopFailure', appState, sessionId)) return
const lastAssistantText =
extractTextContent(lastMessage.message.content, '\n').trim() || undefined
// Some createAssistantAPIErrorMessage call sites omit `error` (e.g.
// image-size at errors.ts:431). Default to 'unknown' so matcher filtering
// at getMatchingHooks:1525 always applies.
const error = lastMessage.error ?? 'unknown'
const hookInput: StopFailureHookInput = {
...createBaseHookInput(undefined, undefined, toolUseContext),
hook_event_name: 'StopFailure',
error,
error_details: lastMessage.errorDetails,
last_assistant_message: lastAssistantText,
}
await executeHooksOutsideREPL({
getAppState: toolUseContext?.getAppState,
hookInput,
timeoutMs,
matchQuery: error,
})
}
/**
* Execute stop hooks if configured
* @param toolUseContext ToolUseContext for prompt-based hooks
* @param permissionMode permission mode from toolPermissionContext
* @param signal AbortSignal to cancel hook execution
* @param stopHookActive Whether this call is happening within another stop hook
* @param isSubagent Whether the current execution context is a subagent
* @param messages Optional conversation history for prompt/function hooks
* @returns Async generator that yields progress messages and blocking errors
*/
export async function* executeStopHooks(
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
stopHookActive: boolean = false,
subagentId?: AgentId,
toolUseContext?: ToolUseContext,
messages?: Message[],
agentType?: string,
requestPrompt?: (
sourceName: string,
toolInputSummary?: string | null,
) => (request: PromptRequest) => Promise<PromptResponse>,
): AsyncGenerator<AggregatedHookResult> {
const hookEvent = subagentId ? 'SubagentStop' : 'Stop'
const appState = toolUseContext?.getAppState()
const sessionId = toolUseContext?.agentId ?? getSessionId()
if (!hasHookForEvent(hookEvent, appState, sessionId)) {
return
}
// Extract text content from the last assistant message so hooks can
// inspect the final response without reading the transcript file.
const lastAssistantMessage = messages
? getLastAssistantMessage(messages)
: undefined
const lastAssistantText = lastAssistantMessage
? extractTextContent(lastAssistantMessage.message.content, '\n').trim() ||
undefined
: undefined
const hookInput: StopHookInput | SubagentStopHookInput = subagentId
? {
...createBaseHookInput(permissionMode),
hook_event_name: 'SubagentStop',
stop_hook_active: stopHookActive,
agent_id: subagentId,
agent_transcript_path: getAgentTranscriptPath(subagentId),
agent_type: agentType ?? '',
last_assistant_message: lastAssistantText,
}
: {
...createBaseHookInput(permissionMode),
hook_event_name: 'Stop',
stop_hook_active: stopHookActive,
last_assistant_message: lastAssistantText,
}
// Trust check is now centralized in executeHooks()
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
signal,
timeoutMs,
toolUseContext,
messages,
requestPrompt,
})
}
/**
* Execute TeammateIdle hooks when a teammate is about to go idle.
* If a hook blocks (exit code 2), the teammate should continue working instead of going idle.
* @param teammateName The name of the teammate going idle
* @param teamName The team this teammate belongs to
* @param permissionMode Optional permission mode
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and blocking errors
*/
export async function* executeTeammateIdleHooks(
teammateName: string,
teamName: string,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: TeammateIdleHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'TeammateIdle',
teammate_name: teammateName,
team_name: teamName,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
signal,
timeoutMs,
})
}
/**
* Execute TaskCreated hooks when a task is being created.
* If a hook blocks (exit code 2), the task creation should be prevented and feedback returned.
* @param taskId The ID of the task being created
* @param taskSubject The subject/title of the task
* @param taskDescription Optional description of the task
* @param teammateName Optional name of the teammate creating the task
* @param teamName Optional team name
* @param permissionMode Optional permission mode
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @param toolUseContext Optional ToolUseContext for resolving appState and sessionId
* @returns Async generator that yields progress messages and blocking errors
*/
export async function* executeTaskCreatedHooks(
taskId: string,
taskSubject: string,
taskDescription?: string,
teammateName?: string,
teamName?: string,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
toolUseContext?: ToolUseContext,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: TaskCreatedHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'TaskCreated',
task_id: taskId,
task_subject: taskSubject,
task_description: taskDescription,
teammate_name: teammateName,
team_name: teamName,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
signal,
timeoutMs,
toolUseContext,
})
}
/**
* Execute TaskCompleted hooks when a task is being marked as completed.
* If a hook blocks (exit code 2), the task completion should be prevented and feedback returned.
* @param taskId The ID of the task being completed
* @param taskSubject The subject/title of the task
* @param taskDescription Optional description of the task
* @param teammateName Optional name of the teammate completing the task
* @param teamName Optional team name
* @param permissionMode Optional permission mode
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @param toolUseContext Optional ToolUseContext for resolving appState and sessionId
* @returns Async generator that yields progress messages and blocking errors
*/
export async function* executeTaskCompletedHooks(
taskId: string,
taskSubject: string,
taskDescription?: string,
teammateName?: string,
teamName?: string,
permissionMode?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
toolUseContext?: ToolUseContext,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: TaskCompletedHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'TaskCompleted',
task_id: taskId,
task_subject: taskSubject,
task_description: taskDescription,
teammate_name: teammateName,
team_name: teamName,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
signal,
timeoutMs,
toolUseContext,
})
}
/**
* Execute start hooks if configured
* @param prompt The user prompt that will be passed to the tool
* @param permissionMode Permission mode from toolPermissionContext
* @param toolUseContext ToolUseContext for prompt-based hooks
* @returns Async generator that yields progress messages and hook results
*/
export async function* executeUserPromptSubmitHooks(
prompt: string,
permissionMode: string,
toolUseContext: ToolUseContext,
requestPrompt?: (
sourceName: string,
toolInputSummary?: string | null,
) => (request: PromptRequest) => Promise<PromptResponse>,
): AsyncGenerator<AggregatedHookResult> {
const appState = toolUseContext.getAppState()
const sessionId = toolUseContext.agentId ?? getSessionId()
if (!hasHookForEvent('UserPromptSubmit', appState, sessionId)) {
return
}
const hookInput: UserPromptSubmitHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'UserPromptSubmit',
prompt,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
signal: toolUseContext.abortController.signal,
timeoutMs: TOOL_HOOK_EXECUTION_TIMEOUT_MS,
toolUseContext,
requestPrompt,
})
}
/**
* Execute session start hooks if configured
* @param source The source of the session start (startup, resume, clear)
* @param sessionId Optional The session id to use as hook input
* @param agentType Optional The agent type (from --agent flag) running this session
* @param model Optional The model being used for this session
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and hook results
*/
export async function* executeSessionStartHooks(
source: 'startup' | 'resume' | 'clear' | 'compact',
sessionId?: string,
agentType?: string,
model?: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
forceSyncExecution?: boolean,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: SessionStartHookInput = {
...createBaseHookInput(undefined, sessionId),
hook_event_name: 'SessionStart',
source,
agent_type: agentType,
model,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
matchQuery: source,
signal,
timeoutMs,
forceSyncExecution,
})
}
/**
* Execute setup hooks if configured
* @param trigger The trigger type ('init' or 'maintenance')
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @param forceSyncExecution If true, async hooks will not be backgrounded
* @returns Async generator that yields progress messages and hook results
*/
export async function* executeSetupHooks(
trigger: 'init' | 'maintenance',
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
forceSyncExecution?: boolean,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: SetupHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'Setup',
trigger,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
matchQuery: trigger,
signal,
timeoutMs,
forceSyncExecution,
})
}
/**
* Execute subagent start hooks if configured
* @param agentId The unique identifier for the subagent
* @param agentType The type/name of the subagent being started
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and hook results
*/
export async function* executeSubagentStartHooks(
agentId: string,
agentType: string,
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): AsyncGenerator<AggregatedHookResult> {
const hookInput: SubagentStartHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'SubagentStart',
agent_id: agentId,
agent_type: agentType,
}
yield* executeHooks({
hookInput,
toolUseID: randomUUID(),
matchQuery: agentType,
signal,
timeoutMs,
})
}
/**
* Execute pre-compact hooks if configured
* @param compactData The compact data to pass to hooks
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Object with optional newCustomInstructions and userDisplayMessage
*/
export async function executePreCompactHooks(
compactData: {
trigger: 'manual' | 'auto'
customInstructions: string | null
},
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<{
newCustomInstructions?: string
userDisplayMessage?: string
}> {
const hookInput: PreCompactHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'PreCompact',
trigger: compactData.trigger,
custom_instructions: compactData.customInstructions,
}
const results = await executeHooksOutsideREPL({
hookInput,
matchQuery: compactData.trigger,
signal,
timeoutMs,
})
if (results.length === 0) {
return {}
}
// Extract custom instructions from successful hooks with non-empty output
const successfulOutputs = results
.filter(result => result.succeeded && result.output.trim().length > 0)
.map(result => result.output.trim())
// Build user display messages with command info
const displayMessages: string[] = []
for (const result of results) {
if (result.succeeded) {
if (result.output.trim()) {
displayMessages.push(
`PreCompact [${result.command}] completed successfully: ${result.output.trim()}`,
)
} else {
displayMessages.push(
`PreCompact [${result.command}] completed successfully`,
)
}
} else {
if (result.output.trim()) {
displayMessages.push(
`PreCompact [${result.command}] failed: ${result.output.trim()}`,
)
} else {
displayMessages.push(`PreCompact [${result.command}] failed`)
}
}
}
return {
newCustomInstructions:
successfulOutputs.length > 0 ? successfulOutputs.join('\n\n') : undefined,
userDisplayMessage:
displayMessages.length > 0 ? displayMessages.join('\n') : undefined,
}
}
/**
* Execute post-compact hooks if configured
* @param compactData The compact data to pass to hooks, including the summary
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Object with optional userDisplayMessage
*/
export async function executePostCompactHooks(
compactData: {
trigger: 'manual' | 'auto'
compactSummary: string
},
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<{
userDisplayMessage?: string
}> {
const hookInput: PostCompactHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'PostCompact',
trigger: compactData.trigger,
compact_summary: compactData.compactSummary,
}
const results = await executeHooksOutsideREPL({
hookInput,
matchQuery: compactData.trigger,
signal,
timeoutMs,
})
if (results.length === 0) {
return {}
}
const displayMessages: string[] = []
for (const result of results) {
if (result.succeeded) {
if (result.output.trim()) {
displayMessages.push(
`PostCompact [${result.command}] completed successfully: ${result.output.trim()}`,
)
} else {
displayMessages.push(
`PostCompact [${result.command}] completed successfully`,
)
}
} else {
if (result.output.trim()) {
displayMessages.push(
`PostCompact [${result.command}] failed: ${result.output.trim()}`,
)
} else {
displayMessages.push(`PostCompact [${result.command}] failed`)
}
}
}
return {
userDisplayMessage:
displayMessages.length > 0 ? displayMessages.join('\n') : undefined,
}
}
/**
* Execute session end hooks if configured
* @param reason The reason for ending the session
* @param options Optional parameters including app state functions and signal
* @returns Promise that resolves when all hooks complete
*/
export async function executeSessionEndHooks(
reason: ExitReason,
options?: {
getAppState?: () => AppState
setAppState?: (updater: (prev: AppState) => AppState) => void
signal?: AbortSignal
timeoutMs?: number
},
): Promise<void> {
const {
getAppState,
setAppState,
signal,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
} = options || {}
const hookInput: SessionEndHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'SessionEnd',
reason,
}
const results = await executeHooksOutsideREPL({
getAppState,
hookInput,
matchQuery: reason,
signal,
timeoutMs,
})
// During shutdown, Ink is unmounted so we can write directly to stderr
for (const result of results) {
if (!result.succeeded && result.output) {
process.stderr.write(
`SessionEnd hook [${result.command}] failed: ${result.output}\n`,
)
}
}
// Clear session hooks after execution
if (setAppState) {
const sessionId = getSessionId()
clearSessionHooks(setAppState, sessionId)
}
}
/**
* Execute permission request hooks if configured
* These hooks are called when a permission dialog would be displayed to the user.
* Hooks can approve or deny the permission request programmatically.
* @param toolName The name of the tool requesting permission
* @param toolUseID The ID of the tool use
* @param toolInput The input that would be passed to the tool
* @param toolUseContext ToolUseContext for the request
* @param permissionMode Optional permission mode from toolPermissionContext
* @param permissionSuggestions Optional permission suggestions (the "always allow" options)
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Async generator that yields progress messages and returns aggregated result
*/
export async function* executePermissionRequestHooks<ToolInput>(
toolName: string,
toolUseID: string,
toolInput: ToolInput,
toolUseContext: ToolUseContext,
permissionMode?: string,
permissionSuggestions?: PermissionUpdate[],
signal?: AbortSignal,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
requestPrompt?: (
sourceName: string,
toolInputSummary?: string | null,
) => (request: PromptRequest) => Promise<PromptResponse>,
toolInputSummary?: string | null,
): AsyncGenerator<AggregatedHookResult> {
logForDebugging(`executePermissionRequestHooks called for tool: ${toolName}`)
const hookInput: PermissionRequestHookInput = {
...createBaseHookInput(permissionMode, undefined, toolUseContext),
hook_event_name: 'PermissionRequest',
tool_name: toolName,
tool_input: toolInput,
permission_suggestions: permissionSuggestions,
}
yield* executeHooks({
hookInput,
toolUseID,
matchQuery: toolName,
signal,
timeoutMs,
toolUseContext,
requestPrompt,
toolInputSummary,
})
}
export type ConfigChangeSource =
| 'user_settings'
| 'project_settings'
| 'local_settings'
| 'policy_settings'
| 'skills'
/**
* Execute config change hooks when configuration files change during a session.
* Fired by file watchers when settings, skills, or commands change on disk.
* Enables enterprise admins to audit/log configuration changes for security.
*
* Policy settings are enterprise-managed and must never be blockable by hooks.
* Hooks still fire (for audit logging) but blocking results are ignored — callers
* will always see an empty result for policy sources.
*
* @param source The type of config that changed
* @param filePath Optional path to the changed file
* @param timeoutMs Optional timeout in milliseconds for hook execution
*/
export async function executeConfigChangeHooks(
source: ConfigChangeSource,
filePath?: string,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<HookOutsideReplResult[]> {
const hookInput: ConfigChangeHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'ConfigChange',
source,
file_path: filePath,
}
const results = await executeHooksOutsideREPL({
hookInput,
timeoutMs,
matchQuery: source,
})
// Policy settings are enterprise-managed — hooks fire for audit logging
// but must never block policy changes from being applied
if (source === 'policy_settings') {
return results.map(r => ({ ...r, blocked: false }))
}
return results
}
async function executeEnvHooks(
hookInput: HookInput,
timeoutMs: number,
): Promise<{
results: HookOutsideReplResult[]
watchPaths: string[]
systemMessages: string[]
}> {
const results = await executeHooksOutsideREPL({ hookInput, timeoutMs })
if (results.length > 0) {
invalidateSessionEnvCache()
}
const watchPaths = results.flatMap(r => r.watchPaths ?? [])
const systemMessages = results
.map(r => r.systemMessage)
.filter((m): m is string => !!m)
return { results, watchPaths, systemMessages }
}
export function executeCwdChangedHooks(
oldCwd: string,
newCwd: string,
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<{
results: HookOutsideReplResult[]
watchPaths: string[]
systemMessages: string[]
}> {
const hookInput: CwdChangedHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'CwdChanged',
old_cwd: oldCwd,
new_cwd: newCwd,
}
return executeEnvHooks(hookInput, timeoutMs)
}
export function executeFileChangedHooks(
filePath: string,
event: 'change' | 'add' | 'unlink',
timeoutMs: number = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
): Promise<{
results: HookOutsideReplResult[]
watchPaths: string[]
systemMessages: string[]
}> {
const hookInput: FileChangedHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'FileChanged',
file_path: filePath,
event,
}
return executeEnvHooks(hookInput, timeoutMs)
}
export type InstructionsLoadReason =
| 'session_start'
| 'nested_traversal'
| 'path_glob_match'
| 'include'
| 'compact'
export type InstructionsMemoryType = 'User' | 'Project' | 'Local' | 'Managed'
/**
* Check if InstructionsLoaded hooks are configured (without executing them).
* Callers should check this before invoking executeInstructionsLoadedHooks to avoid
* building hook inputs for every instruction file when no hook is configured.
*
* Checks both settings-file hooks (getHooksConfigFromSnapshot) and registered
* hooks (plugin hooks + SDK callback hooks via registerHookCallbacks). Session-
* derived hooks (structured output enforcement etc.) are internal and not checked.
*/
export function hasInstructionsLoadedHook(): boolean {
const snapshotHooks = getHooksConfigFromSnapshot()?.['InstructionsLoaded']
if (snapshotHooks && snapshotHooks.length > 0) return true
const registeredHooks = getRegisteredHooks()?.['InstructionsLoaded']
if (registeredHooks && registeredHooks.length > 0) return true
return false
}
/**
* Execute InstructionsLoaded hooks when an instruction file (CLAUDE.md or
* .claude/rules/*.md) is loaded into context. Fire-and-forget — this hook is
* for observability/audit only and does not support blocking.
*
* Dispatch sites:
* - Eager load at session start (getMemoryFiles in claudemd.ts)
* - Eager reload after compaction (getMemoryFiles cache cleared by
* runPostCompactCleanup; next call reports load_reason: 'compact')
* - Lazy load when Claude touches a file that triggers nested CLAUDE.md or
* conditional rules with paths: frontmatter (memoryFilesToAttachments in
* attachments.ts)
*/
export async function executeInstructionsLoadedHooks(
filePath: string,
memoryType: InstructionsMemoryType,
loadReason: InstructionsLoadReason,
options?: {
globs?: string[]
triggerFilePath?: string
parentFilePath?: string
timeoutMs?: number
},
): Promise<void> {
const {
globs,
triggerFilePath,
parentFilePath,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
} = options ?? {}
const hookInput: InstructionsLoadedHookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'InstructionsLoaded',
file_path: filePath,
memory_type: memoryType,
load_reason: loadReason,
globs,
trigger_file_path: triggerFilePath,
parent_file_path: parentFilePath,
}
await executeHooksOutsideREPL({
hookInput,
timeoutMs,
matchQuery: loadReason,
})
}
/** Result of an elicitation hook execution (non-REPL path). */
export type ElicitationHookResult = {
elicitationResponse?: ElicitationResponse
blockingError?: HookBlockingError
}
/** Result of an elicitation-result hook execution (non-REPL path). */
export type ElicitationResultHookResult = {
elicitationResultResponse?: ElicitationResponse
blockingError?: HookBlockingError
}
/**
* Parse elicitation-specific fields from a HookOutsideReplResult.
* Mirrors the relevant branches of processHookJSONOutput for Elicitation
* and ElicitationResult hook events.
*/
function parseElicitationHookOutput(
result: HookOutsideReplResult,
expectedEventName: 'Elicitation' | 'ElicitationResult',
): {
response?: ElicitationResponse
blockingError?: HookBlockingError
} {
// Exit code 2 = blocking (same as executeHooks path)
if (result.blocked && !result.succeeded) {
return {
blockingError: {
blockingError: result.output || `Elicitation blocked by hook`,
command: result.command,
},
}
}
if (!result.output.trim()) {
return {}
}
// Try to parse JSON output for structured elicitation response
const trimmed = result.output.trim()
if (!trimmed.startsWith('{')) {
return {}
}
try {
const parsed = hookJSONOutputSchema().parse(JSON.parse(trimmed))
if (isAsyncHookJSONOutput(parsed)) {
return {}
}
if (!isSyncHookJSONOutput(parsed)) {
return {}
}
// Check for top-level decision: 'block' (exit code 0 + JSON block)
if (parsed.decision === 'block' || result.blocked) {
return {
blockingError: {
blockingError: parsed.reason || 'Elicitation blocked by hook',
command: result.command,
},
}
}
const specific = parsed.hookSpecificOutput
if (!specific || specific.hookEventName !== expectedEventName) {
return {}
}
if (!specific.action) {
return {}
}
const response: ElicitationResponse = {
action: specific.action,
content: specific.content as ElicitationResponse['content'] | undefined,
}
const out: {
response?: ElicitationResponse
blockingError?: HookBlockingError
} = { response }
if (specific.action === 'decline') {
out.blockingError = {
blockingError:
parsed.reason ||
(expectedEventName === 'Elicitation'
? 'Elicitation denied by hook'
: 'Elicitation result blocked by hook'),
command: result.command,
}
}
return out
} catch {
return {}
}
}
export async function executeElicitationHooks({
serverName,
message,
requestedSchema,
permissionMode,
signal,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
mode,
url,
elicitationId,
}: {
serverName: string
message: string
requestedSchema?: Record<string, unknown>
permissionMode?: string
signal?: AbortSignal
timeoutMs?: number
mode?: 'form' | 'url'
url?: string
elicitationId?: string
}): Promise<ElicitationHookResult> {
const hookInput: ElicitationHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'Elicitation',
mcp_server_name: serverName,
message,
mode,
url,
elicitation_id: elicitationId,
requested_schema: requestedSchema,
}
const results = await executeHooksOutsideREPL({
hookInput,
matchQuery: serverName,
signal,
timeoutMs,
})
let elicitationResponse: ElicitationResponse | undefined
let blockingError: HookBlockingError | undefined
for (const result of results) {
const parsed = parseElicitationHookOutput(result, 'Elicitation')
if (parsed.blockingError) {
blockingError = parsed.blockingError
}
if (parsed.response) {
elicitationResponse = parsed.response
}
}
return { elicitationResponse, blockingError }
}
export async function executeElicitationResultHooks({
serverName,
action,
content,
permissionMode,
signal,
timeoutMs = TOOL_HOOK_EXECUTION_TIMEOUT_MS,
mode,
elicitationId,
}: {
serverName: string
action: 'accept' | 'decline' | 'cancel'
content?: Record<string, unknown>
permissionMode?: string
signal?: AbortSignal
timeoutMs?: number
mode?: 'form' | 'url'
elicitationId?: string
}): Promise<ElicitationResultHookResult> {
const hookInput: ElicitationResultHookInput = {
...createBaseHookInput(permissionMode),
hook_event_name: 'ElicitationResult',
mcp_server_name: serverName,
elicitation_id: elicitationId,
mode,
action,
content,
}
const results = await executeHooksOutsideREPL({
hookInput,
matchQuery: serverName,
signal,
timeoutMs,
})
let elicitationResultResponse: ElicitationResponse | undefined
let blockingError: HookBlockingError | undefined
for (const result of results) {
const parsed = parseElicitationHookOutput(result, 'ElicitationResult')
if (parsed.blockingError) {
blockingError = parsed.blockingError
}
if (parsed.response) {
elicitationResultResponse = parsed.response
}
}
return { elicitationResultResponse, blockingError }
}
/**
* Execute status line command if configured
* @param statusLineInput The structured status input that will be converted to JSON
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns The status line text to display, or undefined if no command configured
*/
export async function executeStatusLineCommand(
statusLineInput: StatusLineCommandInput,
signal?: AbortSignal,
timeoutMs: number = 5000, // Short timeout for status line
logResult: boolean = false,
): Promise<string | undefined> {
// Check if all hooks (including statusLine) are disabled by managed settings
if (shouldDisableAllHooksIncludingManaged()) {
return undefined
}
// SECURITY: ALL hooks require workspace trust in interactive mode
// This centralized check prevents RCE vulnerabilities for all current and future hooks
if (shouldSkipHookDueToTrust()) {
logForDebugging(
`Skipping StatusLine command execution - workspace trust not accepted`,
)
return undefined
}
// When disableAllHooks is set in non-managed settings, only managed statusLine runs
// (non-managed settings cannot disable managed commands, but non-managed commands are disabled)
let statusLine
if (shouldAllowManagedHooksOnly()) {
statusLine = getSettingsForSource('policySettings')?.statusLine
} else {
statusLine = getSettings_DEPRECATED()?.statusLine
}
if (!statusLine || statusLine.type !== 'command') {
return undefined
}
// Use provided signal or create a default one
const abortSignal = signal || AbortSignal.timeout(timeoutMs)
try {
// Convert status input to JSON
const jsonInput = jsonStringify(statusLineInput)
const result = await execCommandHook(
statusLine,
'StatusLine',
'statusLine',
jsonInput,
abortSignal,
randomUUID(),
)
if (result.aborted) {
return undefined
}
// For successful hooks (exit code 0), use stdout
if (result.status === 0) {
// Trim and split output into lines, then join with newlines
const output = result.stdout
.trim()
.split('\n')
.flatMap(line => line.trim() || [])
.join('\n')
if (output) {
if (logResult) {
logForDebugging(
`StatusLine [${statusLine.command}] completed with status ${result.status}`,
)
}
return output
}
} else if (logResult) {
logForDebugging(
`StatusLine [${statusLine.command}] completed with status ${result.status}`,
{ level: 'warn' },
)
}
return undefined
} catch (error) {
logForDebugging(`Status hook failed: ${error}`, { level: 'error' })
return undefined
}
}
/**
* Execute file suggestion command if configured
* @param fileSuggestionInput The structured input that will be converted to JSON
* @param signal Optional AbortSignal to cancel hook execution
* @param timeoutMs Optional timeout in milliseconds for hook execution
* @returns Array of file paths, or empty array if no command configured
*/
export async function executeFileSuggestionCommand(
fileSuggestionInput: FileSuggestionCommandInput,
signal?: AbortSignal,
timeoutMs: number = 5000, // Short timeout for typeahead suggestions
): Promise<string[]> {
// Check if all hooks are disabled by managed settings
if (shouldDisableAllHooksIncludingManaged()) {
return []
}
// SECURITY: ALL hooks require workspace trust in interactive mode
// This centralized check prevents RCE vulnerabilities for all current and future hooks
if (shouldSkipHookDueToTrust()) {
logForDebugging(
`Skipping FileSuggestion command execution - workspace trust not accepted`,
)
return []
}
// When disableAllHooks is set in non-managed settings, only managed fileSuggestion runs
// (non-managed settings cannot disable managed commands, but non-managed commands are disabled)
let fileSuggestion
if (shouldAllowManagedHooksOnly()) {
fileSuggestion = getSettingsForSource('policySettings')?.fileSuggestion
} else {
fileSuggestion = getSettings_DEPRECATED()?.fileSuggestion
}
if (!fileSuggestion || fileSuggestion.type !== 'command') {
return []
}
// Use provided signal or create a default one
const abortSignal = signal || AbortSignal.timeout(timeoutMs)
try {
const jsonInput = jsonStringify(fileSuggestionInput)
const hook = { type: 'command' as const, command: fileSuggestion.command }
const result = await execCommandHook(
hook,
'FileSuggestion',
'FileSuggestion',
jsonInput,
abortSignal,
randomUUID(),
)
if (result.aborted || result.status !== 0) {
return []
}
return result.stdout
.split('\n')
.map(line => line.trim())
.filter(Boolean)
} catch (error) {
logForDebugging(`File suggestion helper failed: ${error}`, {
level: 'error',
})
return []
}
}
async function executeFunctionHook({
hook,
messages,
hookName,
toolUseID,
hookEvent,
timeoutMs,
signal,
}: {
hook: FunctionHook
messages: Message[]
hookName: string
toolUseID: string
hookEvent: HookEvent
timeoutMs: number
signal?: AbortSignal
}): Promise<HookResult> {
const callbackTimeoutMs = hook.timeout ?? timeoutMs
const { signal: abortSignal, cleanup } = createCombinedAbortSignal(signal, {
timeoutMs: callbackTimeoutMs,
})
try {
// Check if already aborted
if (abortSignal.aborted) {
cleanup()
return {
outcome: 'cancelled',
hook,
}
}
// Execute callback with abort signal
const passed = await new Promise<boolean>((resolve, reject) => {
// Handle abort signal
const onAbort = () => reject(new Error('Function hook cancelled'))
abortSignal.addEventListener('abort', onAbort)
// Execute callback
Promise.resolve(hook.callback(messages, abortSignal))
.then(result => {
abortSignal.removeEventListener('abort', onAbort)
resolve(result)
})
.catch(error => {
abortSignal.removeEventListener('abort', onAbort)
reject(error)
})
})
cleanup()
if (passed) {
return {
outcome: 'success',
hook,
}
}
return {
blockingError: {
blockingError: hook.errorMessage,
command: 'function',
},
outcome: 'blocking',
hook,
}
} catch (error) {
cleanup()
// Handle cancellation
if (
error instanceof Error &&
(error.message === 'Function hook cancelled' ||
error.name === 'AbortError')
) {
return {
outcome: 'cancelled',
hook,
}
}
// Log for monitoring
logError(error)
return {
message: createAttachmentMessage({
type: 'hook_error_during_execution',
hookName,
toolUseID,
hookEvent,
content:
error instanceof Error
? error.message
: 'Function hook execution error',
}),
outcome: 'non_blocking_error',
hook,
}
}
}
async function executeHookCallback({
toolUseID,
hook,
hookEvent,
hookInput,
signal,
hookIndex,
toolUseContext,
}: {
toolUseID: string
hook: HookCallback
hookEvent: HookEvent
hookInput: HookInput
signal: AbortSignal
hookIndex?: number
toolUseContext?: ToolUseContext
}): Promise<HookResult> {
// Create context for callbacks that need state access
const context = toolUseContext
? {
getAppState: toolUseContext.getAppState,
updateAttributionState: toolUseContext.updateAttributionState,
}
: undefined
const json = await hook.callback(
hookInput,
toolUseID,
signal,
hookIndex,
context,
)
if (isAsyncHookJSONOutput(json)) {
return {
outcome: 'success',
hook,
}
}
const processed = processHookJSONOutput({
json,
command: 'callback',
// TODO: If the hook came from a plugin, use the full path to the plugin for easier debugging
hookName: `${hookEvent}:Callback`,
toolUseID,
hookEvent,
expectedHookEvent: hookEvent,
// Callbacks don't have stdout/stderr/exitCode
stdout: undefined,
stderr: undefined,
exitCode: undefined,
})
return {
...processed,
outcome: 'success',
hook,
}
}
/**
* Check if WorktreeCreate hooks are configured (without executing them).
*
* Checks both settings-file hooks (getHooksConfigFromSnapshot) and registered
* hooks (plugin hooks + SDK callback hooks via registerHookCallbacks).
*
* Must mirror the managedOnly filtering in getHooksConfig() — when
* shouldAllowManagedHooksOnly() is true, plugin hooks (pluginRoot set) are
* skipped at execution, so we must also skip them here. Otherwise this returns
* true but executeWorktreeCreateHook() finds no matching hooks and throws,
* blocking the git-worktree fallback.
*/
export function hasWorktreeCreateHook(): boolean {
const snapshotHooks = getHooksConfigFromSnapshot()?.['WorktreeCreate']
if (snapshotHooks && snapshotHooks.length > 0) return true
const registeredHooks = getRegisteredHooks()?.['WorktreeCreate']
if (!registeredHooks || registeredHooks.length === 0) return false
// Mirror getHooksConfig(): skip plugin hooks in managed-only mode
const managedOnly = shouldAllowManagedHooksOnly()
return registeredHooks.some(
matcher => !(managedOnly && 'pluginRoot' in matcher),
)
}
/**
* Execute WorktreeCreate hooks.
* Returns the worktree path from hook stdout.
* Throws if hooks fail or produce no output.
* Callers should check hasWorktreeCreateHook() before calling this.
*/
export async function executeWorktreeCreateHook(
name: string,
): Promise<{ worktreePath: string }> {
const hookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'WorktreeCreate' as const,
name,
}
const results = await executeHooksOutsideREPL({
hookInput,
timeoutMs: TOOL_HOOK_EXECUTION_TIMEOUT_MS,
})
// Find the first successful result with non-empty output
const successfulResult = results.find(
r => r.succeeded && r.output.trim().length > 0,
)
if (!successfulResult) {
const failedOutputs = results
.filter(r => !r.succeeded)
.map(r => `${r.command}: ${r.output.trim() || 'no output'}`)
throw new Error(
`WorktreeCreate hook failed: ${failedOutputs.join('; ') || 'no successful output'}`,
)
}
const worktreePath = successfulResult.output.trim()
return { worktreePath }
}
/**
* Execute WorktreeRemove hooks if configured.
* Returns true if hooks were configured and ran, false if no hooks are configured.
*
* Checks both settings-file hooks (getHooksConfigFromSnapshot) and registered
* hooks (plugin hooks + SDK callback hooks via registerHookCallbacks).
*/
export async function executeWorktreeRemoveHook(
worktreePath: string,
): Promise<boolean> {
const snapshotHooks = getHooksConfigFromSnapshot()?.['WorktreeRemove']
const registeredHooks = getRegisteredHooks()?.['WorktreeRemove']
const hasSnapshotHooks = snapshotHooks && snapshotHooks.length > 0
const hasRegisteredHooks = registeredHooks && registeredHooks.length > 0
if (!hasSnapshotHooks && !hasRegisteredHooks) {
return false
}
const hookInput = {
...createBaseHookInput(undefined),
hook_event_name: 'WorktreeRemove' as const,
worktree_path: worktreePath,
}
const results = await executeHooksOutsideREPL({
hookInput,
timeoutMs: TOOL_HOOK_EXECUTION_TIMEOUT_MS,
})
if (results.length === 0) {
return false
}
for (const result of results) {
if (!result.succeeded) {
logForDebugging(
`WorktreeRemove hook failed [${result.command}]: ${result.output.trim()}`,
{ level: 'error' },
)
}
}
return true
}
function getHookDefinitionsForTelemetry(
matchedHooks: MatchedHook[],
): Array<{ type: string; command?: string; prompt?: string; name?: string }> {
return matchedHooks.map(({ hook }) => {
if (hook.type === 'command') {
return { type: 'command', command: hook.command }
} else if (hook.type === 'prompt') {
return { type: 'prompt', prompt: hook.prompt }
} else if (hook.type === 'http') {
return { type: 'http', command: hook.url }
} else if (hook.type === 'function') {
return { type: 'function', name: 'function' }
} else if (hook.type === 'callback') {
return { type: 'callback', name: 'callback' }
}
return { type: 'unknown' }
})
}
