Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🪝 feat: Add Claude Hook Compatibility Layer (#14412)

Danny Avila493ffced46d9
diff --git a/packages/api/src/agents/hooks/compatibility.spec.ts b/packages/api/src/agents/hooks/compatibility.spec.ts
new file mode 100644
index 0000000000..99aa5c744a
--- /dev/null
+++ b/packages/api/src/agents/hooks/compatibility.spec.ts
@@ -0,0 +1,649 @@
+import type { PluginHookCapabilities } from './compatibility';
+import type { PluginHooksDocument } from './schema';
+import { planPluginHooks } from './compatibility';
+
+const commandCapabilities: PluginHookCapabilities = {
+ handlerTypes: new Set(['command']),
+ translateMatcher: ({ matcher }: { matcher: string }) => matcher,
+};
+
+function document(hooks: PluginHooksDocument['hooks']): PluginHooksDocument {
+ return { hooks };
+}
+
+describe('planPluginHooks', () => {
+ test('maps the common Claude lifecycle events directly', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: '^write_file$', hooks: [{ type: 'command', command: 'check' }] }],
+ PostToolUse: [{ hooks: [{ type: 'command', command: 'record' }] }],
+ Stop: [{ matcher: '.*', hooks: [{ type: 'command', command: 'verify' }] }],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 3, ready: 3, unsupported: 0 });
+ expect(
+ plan.entries.map(({ sourceEvent, targetEvent, matcher }) => ({
+ sourceEvent,
+ targetEvent,
+ matcher,
+ })),
+ ).toEqual([
+ { sourceEvent: 'PreToolUse', targetEvent: 'PreToolUse', matcher: '^write_file$' },
+ { sourceEvent: 'PostToolUse', targetEvent: 'PostToolUse', matcher: undefined },
+ { sourceEvent: 'Stop', targetEvent: 'Stop', matcher: undefined },
+ ]);
+ });
+
+ test('maps SessionStart to RunStart with an explicit lifecycle warning', () => {
+ const plan = planPluginHooks(
+ document({
+ SessionStart: [
+ { matcher: 'resume', hooks: [{ type: 'command', command: 'load-context' }] },
+ ],
+ }),
+ { handlerTypes: new Set(['command']), sessionLifecycle: true },
+ );
+
+ expect(plan.summary.ready).toBe(1);
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceEvent: 'SessionStart',
+ targetEvent: 'RunStart',
+ sourceMatcher: 'resume',
+ matcher: '^(?:resume)$',
+ status: 'ready',
+ issues: [
+ expect.objectContaining({
+ code: 'event_alias',
+ severity: 'warning',
+ }),
+ ],
+ }),
+ );
+ });
+
+ test('normalizes Claude exact and list matchers while preserving regex matchers', () => {
+ const translatedMatchers: string[] = [];
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [
+ { matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'pipe-list' }] },
+ { matcher: 'Edit, Write', hooks: [{ type: 'command', command: 'comma-list' }] },
+ {
+ matcher: 'mcp__.*__write.*',
+ hooks: [{ type: 'command', command: 'regex-pattern' }],
+ },
+ ],
+ SessionStart: [
+ { matcher: 'startup, resume', hooks: [{ type: 'command', command: 'load-context' }] },
+ ],
+ SubagentStart: [
+ { matcher: 'code-reviewer', hooks: [{ type: 'command', command: 'track-agent' }] },
+ ],
+ StopFailure: [
+ {
+ matcher: 'rate_limit, overloaded',
+ hooks: [{ type: 'command', command: 'track-failure' }],
+ },
+ ],
+ }),
+ {
+ ...commandCapabilities,
+ sessionLifecycle: true,
+ translateMatcher: ({ matcher }) => {
+ translatedMatchers.push(matcher);
+ return matcher;
+ },
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 6, ready: 6, unsupported: 0 });
+ expect(plan.entries.map(({ sourceMatcher, matcher }) => ({ sourceMatcher, matcher }))).toEqual([
+ { sourceMatcher: 'Edit|Write', matcher: '^(?:Edit|Write)$' },
+ { sourceMatcher: 'Edit, Write', matcher: '^(?:Edit|Write)$' },
+ { sourceMatcher: 'mcp__.*__write.*', matcher: 'mcp__.*__write.*' },
+ { sourceMatcher: 'startup, resume', matcher: '^(?:startup|resume)$' },
+ { sourceMatcher: 'code-reviewer', matcher: '^(?:code-reviewer)$' },
+ { sourceMatcher: 'rate_limit, overloaded', matcher: 'rate_limit, overloaded' },
+ ]);
+ expect(translatedMatchers).toEqual([
+ 'Edit|Write',
+ 'Edit|Write',
+ 'mcp__.*__write.*',
+ 'code-reviewer',
+ 'rate_limit, overloaded',
+ ]);
+ });
+
+ test('fails closed for SessionStart compact matchers', () => {
+ const plan = planPluginHooks(
+ document({
+ SessionStart: [
+ { matcher: 'compact', hooks: [{ type: 'command', command: 'reload-context' }] },
+ ],
+ }),
+ { handlerTypes: new Set(['command']), sessionLifecycle: true },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 0, unsupported: 1 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceEvent: 'SessionStart',
+ targetEvent: 'RunStart',
+ status: 'unsupported',
+ issues: expect.arrayContaining([
+ expect.objectContaining({
+ code: 'unsupported_session_source',
+ severity: 'error',
+ }),
+ ]),
+ }),
+ );
+ });
+
+ test('keeps wildcard SessionStart ready while reporting compact as filtered', () => {
+ const plan = planPluginHooks(
+ document({
+ SessionStart: [{ hooks: [{ type: 'command', command: 'load-context' }] }],
+ }),
+ { handlerTypes: new Set(['command']), sessionLifecycle: true },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 1, unsupported: 0 });
+ expect(plan.entries[0].issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: 'unsupported_session_source',
+ severity: 'warning',
+ }),
+ ]),
+ );
+ });
+
+ test('plans translated compaction-trigger matchers', () => {
+ const plan = planPluginHooks(
+ document({
+ PreCompact: [{ matcher: 'auto', hooks: [{ type: 'command', command: 'before' }] }],
+ PostCompact: [{ matcher: 'manual', hooks: [{ type: 'command', command: 'after' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: ({ matcher }) =>
+ matcher === 'auto'
+ ? '^(token_ratio|remaining_tokens|messages_to_refine|default)$'
+ : '^manual$',
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 2, unsupported: 0 });
+ expect(plan.entries).toEqual([
+ expect.objectContaining({
+ sourceEvent: 'PreCompact',
+ sourceMatcher: 'auto',
+ matcher: '^(?:^(token_ratio|remaining_tokens|messages_to_refine|default)$)$',
+ status: 'ready',
+ }),
+ expect.objectContaining({
+ sourceEvent: 'PostCompact',
+ sourceMatcher: 'manual',
+ matcher: '^(?:^manual$)$',
+ status: 'ready',
+ }),
+ ]);
+ });
+
+ test('plans StopFailure matchers against translated error names', () => {
+ const plan = planPluginHooks(
+ document({
+ StopFailure: [
+ {
+ matcher: 'rate_limit|overloaded',
+ hooks: [{ type: 'command', command: 'record-failure' }],
+ },
+ ],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 1, unsupported: 0 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceEvent: 'StopFailure',
+ targetEvent: 'StopFailure',
+ sourceMatcher: 'rate_limit|overloaded',
+ matcher: '^(?:rate_limit|overloaded)$',
+ status: 'ready',
+ }),
+ );
+ });
+
+ test('does not activate events whose Claude control surfaces are unavailable', () => {
+ const plan = planPluginHooks(
+ document({
+ SubagentStop: [{ hooks: [{ type: 'command', command: 'verify' }] }],
+ PermissionDenied: [{ hooks: [{ type: 'command', command: 'retry' }] }],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 0, unsupported: 2 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceEvent: 'SubagentStop',
+ targetEvent: 'SubagentStop',
+ status: 'unsupported',
+ issues: [
+ expect.objectContaining({
+ code: 'unsupported_event_payload',
+ severity: 'error',
+ }),
+ ],
+ }),
+ );
+ expect(plan.entries[1]).toEqual(
+ expect.objectContaining({
+ sourceEvent: 'PermissionDenied',
+ targetEvent: 'PermissionDenied',
+ status: 'unsupported',
+ issues: [
+ expect.objectContaining({
+ code: 'unsupported_event_output',
+ severity: 'error',
+ }),
+ ],
+ }),
+ );
+ });
+
+ test('does not silently activate events or handler types the runtime cannot execute', () => {
+ const plan = planPluginHooks(
+ document({
+ UserPromptExpansion: [{ hooks: [{ type: 'command', command: 'banner' }] }],
+ Stop: [{ hooks: [{ type: 'prompt', prompt: 'Verify completion' }] }],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 0, unsupported: 2 });
+ expect(plan.entries[0].issues).toEqual([
+ expect.objectContaining({ code: 'unsupported_event' }),
+ ]);
+ expect(plan.entries[1].issues).toEqual([
+ expect.objectContaining({ code: 'unsupported_handler' }),
+ ]);
+ });
+
+ test('keeps known unsupported handler declarations in a mixed compatibility plan', () => {
+ const plan = planPluginHooks(
+ document({
+ Stop: [
+ {
+ hooks: [
+ { type: 'command', command: 'verify' },
+ { type: 'http', url: 'https://hooks.example.com/stop' },
+ { type: 'mcp_tool', server: 'policy', tool: 'validate', input: { strict: true } },
+ { type: 'agent', prompt: 'Review completion', model: 'claude-sonnet-4-5' },
+ ],
+ },
+ ],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 4, ready: 1, unsupported: 3 });
+ expect(plan.entries[0].status).toBe('ready');
+ expect(plan.entries.slice(1)).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ handler: expect.objectContaining({ type: 'http' }),
+ status: 'unsupported',
+ issues: [expect.objectContaining({ code: 'unsupported_handler' })],
+ }),
+ expect.objectContaining({
+ handler: expect.objectContaining({ type: 'mcp_tool' }),
+ status: 'unsupported',
+ issues: [expect.objectContaining({ code: 'unsupported_handler' })],
+ }),
+ expect.objectContaining({
+ handler: expect.objectContaining({ type: 'agent' }),
+ status: 'unsupported',
+ issues: [expect.objectContaining({ code: 'unsupported_handler' })],
+ }),
+ ]),
+ );
+ });
+
+ test('preserves continueOnBlock for supported prompt handlers', () => {
+ const plan = planPluginHooks(
+ document({
+ PostToolUse: [
+ {
+ hooks: [
+ {
+ type: 'prompt',
+ prompt: 'Review this tool result',
+ continueOnBlock: true,
+ },
+ ],
+ },
+ ],
+ PreToolUse: [
+ {
+ hooks: [
+ {
+ type: 'prompt',
+ prompt: 'Verify this tool call',
+ continueOnBlock: true,
+ },
+ ],
+ },
+ ],
+ }),
+ {
+ ...commandCapabilities,
+ handlerTypes: new Set(['command', 'prompt']),
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 2, unsupported: 0 });
+ expect(plan.entries).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ status: 'ready',
+ handler: expect.objectContaining({ continueOnBlock: true }),
+ }),
+ ]),
+ );
+ });
+
+ test('rejects continueOnBlock on non-prompt handlers', () => {
+ const plan = planPluginHooks(
+ document({
+ PostToolUse: [
+ {
+ hooks: [{ type: 'command', command: 'verify-output', continueOnBlock: true }],
+ },
+ ],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 0, unsupported: 1 });
+ expect(plan.entries[0].issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: 'unsupported_continue_on_block',
+ severity: 'error',
+ }),
+ ]),
+ );
+ });
+
+ test('rejects prompt handlers on events that do not support them', () => {
+ const plan = planPluginHooks(
+ document({
+ SessionStart: [
+ {
+ matcher: 'startup',
+ hooks: [{ type: 'prompt', prompt: 'Load context' }],
+ },
+ ],
+ StopFailure: [{ hooks: [{ type: 'prompt', prompt: 'Classify the failure' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command', 'prompt']),
+ sessionLifecycle: true,
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 0, unsupported: 2 });
+ for (const entry of plan.entries) {
+ expect(entry.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: 'unsupported_handler_event',
+ severity: 'error',
+ }),
+ ]),
+ );
+ }
+ });
+
+ test('rejects conditional, async-rewake, and unsafe matcher semantics by default', () => {
+ const plan = planPluginHooks(
+ document({
+ RunStart: [
+ {
+ matcher: 'startup',
+ hooks: [{ type: 'command', command: 'load' }],
+ },
+ ],
+ PostToolUse: [
+ {
+ matcher: '(a+)+',
+ hooks: [
+ {
+ type: 'command',
+ command: 'review',
+ if: 'Bash(git commit:*)',
+ async: true,
+ asyncRewake: true,
+ },
+ ],
+ },
+ ],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.summary.unsupported).toBe(2);
+ expect(plan.entries[0].issues).toEqual([
+ expect.objectContaining({ code: 'unsupported_matcher' }),
+ ]);
+ expect(plan.entries[1].issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ code: 'invalid_matcher' }),
+ expect.objectContaining({ code: 'unsupported_condition' }),
+ expect.objectContaining({ code: 'unsupported_async' }),
+ expect.objectContaining({ code: 'unsupported_async_rewake' }),
+ ]),
+ );
+ });
+
+ test('requires explicit matcher and session-lifecycle adapters', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'check' }] }],
+ SessionStart: [{ hooks: [{ type: 'command', command: 'load' }] }],
+ }),
+ { handlerTypes: new Set(['command']) },
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 0, unsupported: 2 });
+ expect(plan.entries[0].issues).toEqual([expect.objectContaining({ code: 'unmapped_matcher' })]);
+ expect(plan.entries[1].issues).toEqual([
+ expect.objectContaining({ code: 'unsupported_session_lifecycle' }),
+ ]);
+ });
+
+ test('records matcher translation without losing the source declaration', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: ' Bash|Write ', hooks: [{ type: 'command', command: 'check' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: () => '^(bash_tool|create_file)$',
+ toPluginToolName: ({ toolName }) => toolName,
+ },
+ );
+
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceMatcher: 'Bash|Write',
+ matcher: '^(?:^(bash_tool|create_file)$)$',
+ status: 'ready',
+ issues: [expect.objectContaining({ code: 'matcher_translated', severity: 'warning' })],
+ }),
+ );
+ });
+
+ test('keeps invalid authored regex matchers unsupported after a valid translation', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: '[invalid', hooks: [{ type: 'command', command: 'check' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: () => '^bash_tool$',
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 0, unsupported: 1 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ sourceMatcher: '[invalid',
+ matcher: '^bash_tool$',
+ status: 'unsupported',
+ issues: expect.arrayContaining([
+ expect.objectContaining({ code: 'invalid_matcher', severity: 'error' }),
+ expect.objectContaining({ code: 'matcher_translated', severity: 'warning' }),
+ ]),
+ }),
+ );
+ });
+
+ test('requires reverse tool-name translation when matcher namespaces differ', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'check' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: () => ({
+ matcher: '^bash_tool$',
+ requiresToolNameTranslation: true,
+ }),
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 0, unsupported: 1 });
+ expect(plan.entries[0].issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ code: 'matcher_translated', severity: 'warning' }),
+ expect.objectContaining({ code: 'unmapped_tool_name', severity: 'error' }),
+ ]),
+ );
+ });
+
+ test('allows regex-only matcher rewrites without reverse tool-name mapping', () => {
+ const plan = planPluginHooks(
+ document({
+ PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'check' }] }],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: () => '^Bash$',
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 1, unsupported: 0 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ matcher: '^(?:^Bash$)$',
+ status: 'ready',
+ issues: [expect.objectContaining({ code: 'matcher_translated', severity: 'warning' })],
+ }),
+ );
+ });
+
+ test('plans current handler-level conditions independently', () => {
+ const plan = planPluginHooks(
+ document({
+ PostToolUse: [
+ {
+ matcher: 'Bash',
+ hooks: [
+ {
+ type: 'command',
+ command: 'review-commit',
+ if: 'Bash(git commit:*)',
+ },
+ {
+ type: 'command',
+ command: 'record-all',
+ },
+ ],
+ },
+ ],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ translateMatcher: () => '^bash_tool$',
+ toPluginToolName: ({ toolName }) => toolName,
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 2, ready: 1, unsupported: 1 });
+ expect(plan.entries[0]).toEqual(
+ expect.objectContaining({
+ condition: 'Bash(git commit:*)',
+ status: 'unsupported',
+ issues: expect.arrayContaining([
+ expect.objectContaining({ code: 'unsupported_condition' }),
+ ]),
+ }),
+ );
+ expect(plan.entries[1]).toEqual(
+ expect.objectContaining({
+ status: 'ready',
+ }),
+ );
+ });
+
+ test('rejects conditional expressions on non-tool events', () => {
+ const plan = planPluginHooks(
+ document({
+ Stop: [
+ {
+ hooks: [
+ {
+ type: 'command',
+ command: 'verify',
+ if: 'Bash(git status:*)',
+ },
+ ],
+ },
+ ],
+ }),
+ {
+ handlerTypes: new Set(['command']),
+ matchCondition: () => true,
+ },
+ );
+
+ expect(plan.summary).toEqual({ declared: 1, ready: 0, unsupported: 1 });
+ expect(plan.entries[0].issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ code: 'unsupported_condition',
+ severity: 'error',
+ message: 'Conditional `if` hook expressions are only supported for tool events',
+ }),
+ ]),
+ );
+ });
+
+ test('converts portable timeout seconds to the SDK timeout in milliseconds', () => {
+ const plan = planPluginHooks(
+ document({
+ Stop: [{ hooks: [{ type: 'command', command: 'verify', timeout: 30 }] }],
+ }),
+ commandCapabilities,
+ );
+
+ expect(plan.entries[0].timeoutMs).toBe(30_000);
+ });
+});
diff --git a/packages/api/src/agents/hooks/compatibility.ts b/packages/api/src/agents/hooks/compatibility.ts
new file mode 100644
index 0000000000..f7fb4a5e50
--- /dev/null
+++ b/packages/api/src/agents/hooks/compatibility.ts
@@ -0,0 +1,544 @@
+import { MAX_PATTERN_LENGTH, hasNestedQuantifier } from '@librechat/agents';
+import type { HookEvent } from '@librechat/agents';
+import type { PluginHookHandler, PluginHooksDocument } from './schema';
+
+const EVENT_MAP = new Map<string, HookEvent>([
+ ['RunStart', 'RunStart'],
+ ['SessionStart', 'RunStart'],
+ ['UserPromptSubmit', 'UserPromptSubmit'],
+ ['PreToolUse', 'PreToolUse'],
+ ['PostToolUse', 'PostToolUse'],
+ ['PostToolUseFailure', 'PostToolUseFailure'],
+ ['PostToolBatch', 'PostToolBatch'],
+ ['PermissionDenied', 'PermissionDenied'],
+ ['SubagentStart', 'SubagentStart'],
+ ['SubagentStop', 'SubagentStop'],
+ ['Stop', 'Stop'],
+ ['StopFailure', 'StopFailure'],
+ ['PreCompact', 'PreCompact'],
+ ['PostCompact', 'PostCompact'],
+]);
+
+const QUERY_EVENTS = new Set<HookEvent>([
+ 'PreToolUse',
+ 'PostToolUse',
+ 'PostToolUseFailure',
+ 'PermissionDenied',
+ 'SubagentStart',
+ 'SubagentStop',
+ 'StopFailure',
+ 'PreCompact',
+ 'PostCompact',
+]);
+
+const TOOL_NAME_EVENTS = new Set<HookEvent>([
+ 'PreToolUse',
+ 'PostToolUse',
+ 'PostToolUseFailure',
+ 'PermissionDenied',
+]);
+
+const GENERAL_EXACT_MATCHER = /^[-A-Za-z0-9_,| ]+$/;
+const NARROW_EXACT_MATCHER = /^[A-Za-z0-9_|]+$/;
+const NARROW_EXACT_MATCHER_EVENTS = new Set(['FileChanged', 'StopFailure']);
+
+export type PluginHookIssueSeverity = 'warning' | 'error';
+
+export type PluginHookIssueCode =
+ | 'event_alias'
+ | 'unsupported_event'
+ | 'unsupported_handler'
+ | 'invalid_matcher'
+ | 'matcher_translated'
+ | 'unmapped_matcher'
+ | 'unmapped_tool_name'
+ | 'unsupported_matcher'
+ | 'unsupported_condition'
+ | 'conflicting_condition'
+ | 'unsupported_async'
+ | 'unsupported_async_rewake'
+ | 'unsupported_continue_on_block'
+ | 'unsupported_handler_event'
+ | 'unsupported_session_lifecycle'
+ | 'unsupported_session_source'
+ | 'unsupported_event_payload'
+ | 'unsupported_event_output'
+ | 'long_timeout';
+
+export interface PluginHookCompatibilityIssue {
+ code: PluginHookIssueCode;
+ severity: PluginHookIssueSeverity;
+ message: string;
+}
+
+export type PluginHookHandlerType = 'command' | 'prompt';
+
+export interface PluginHookMatcherTranslation {
+ sourceEvent: string;
+ targetEvent: HookEvent;
+ /** Authored regex, or a canonical pipe-separated list when Claude applies exact matching. */
+ matcher: string;
+}
+
+export interface PluginHookMatcherTranslationResult {
+ /** Runtime pattern; translations of Claude exact matchers are whole-string anchored. */
+ matcher: string;
+ requiresToolNameTranslation?: boolean;
+}
+
+export interface PluginHookToolNameTranslation {
+ sourceEvent: string;
+ targetEvent: HookEvent;
+ toolName: string;
+}
+
+export interface PluginHookConditionMatch {
+ sourceEvent: string;
+ targetEvent: HookEvent;
+ condition: string;
+ toolName: string;
+ toolInput: Record<string, unknown>;
+}
+
+export interface PluginHookCapabilities {
+ handlerTypes: ReadonlySet<PluginHookHandlerType>;
+ translateMatcher?: (
+ input: PluginHookMatcherTranslation,
+ ) => string | PluginHookMatcherTranslationResult | undefined;
+ /** Maps a LibreChat runtime tool name back into the plugin's source namespace. */
+ toPluginToolName?: (input: PluginHookToolNameTranslation) => string;
+ /** Evaluates Claude permission-rule syntax before a conditional handler executes. */
+ matchCondition?: (input: PluginHookConditionMatch) => boolean;
+ async?: boolean;
+ asyncRewake?: boolean;
+ sessionLifecycle?: boolean;
+}
+
+export interface PluginHookPlanEntry {
+ sourceEvent: string;
+ targetEvent?: HookEvent;
+ groupIndex: number;
+ handlerIndex: number;
+ sourceMatcher?: string;
+ matcher?: string;
+ condition?: string;
+ timeoutMs?: number;
+ handler: PluginHookHandler;
+ status: 'ready' | 'unsupported';
+ issues: PluginHookCompatibilityIssue[];
+}
+
+export interface PluginHookPlanSummary {
+ declared: number;
+ ready: number;
+ unsupported: number;
+}
+
+export interface PluginHookPlan {
+ description?: string;
+ entries: PluginHookPlanEntry[];
+ summary: PluginHookPlanSummary;
+}
+
+function normalizeMatcher(matcher: string | undefined): string | undefined {
+ const trimmed = matcher?.trim();
+ if (!trimmed || trimmed === '*' || trimmed === '.*') {
+ return undefined;
+ }
+ return trimmed;
+}
+
+type ClaudeMatcherSemantics =
+ | { kind: 'exact'; canonicalMatcher: string; values: string[] }
+ | { kind: 'regex'; canonicalMatcher: string };
+
+function getClaudeMatcherSemantics(sourceEvent: string, matcher: string): ClaudeMatcherSemantics {
+ const isNarrowEvent = NARROW_EXACT_MATCHER_EVENTS.has(sourceEvent);
+ const exactMatcher = isNarrowEvent ? NARROW_EXACT_MATCHER : GENERAL_EXACT_MATCHER;
+ if (!exactMatcher.test(matcher)) {
+ return { kind: 'regex', canonicalMatcher: matcher };
+ }
+ const values = matcher.split(isNarrowEvent ? /\|/ : /[|,]/).map((value) => value.trim());
+ return {
+ kind: 'exact',
+ canonicalMatcher: values.join('|'),
+ values,
+ };
+}
+
+function anchorExactMatcher(matcher: string): string {
+ return `^(?:${matcher})$`;
+}
+
+function matcherIncludesValue(matcher: string, value: string): boolean {
+ try {
+ return new RegExp(matcher).test(value);
+ } catch {
+ return false;
+ }
+}
+
+function getMatcherValidationIssue(
+ sourceEvent: string,
+ matcher: string | undefined,
+ targetEvent: HookEvent | undefined,
+): PluginHookCompatibilityIssue | undefined {
+ if (!matcher) {
+ return undefined;
+ }
+ if (targetEvent && !QUERY_EVENTS.has(targetEvent) && sourceEvent !== 'SessionStart') {
+ return {
+ code: 'unsupported_matcher',
+ severity: 'error',
+ message: `${targetEvent} does not expose a matcher query in the LibreChat hook runtime`,
+ };
+ }
+ if (matcher.length > MAX_PATTERN_LENGTH || hasNestedQuantifier(matcher)) {
+ return {
+ code: 'invalid_matcher',
+ severity: 'error',
+ message: 'Matcher exceeds the safe regex limits enforced by the LibreChat hook runtime',
+ };
+ }
+ try {
+ void new RegExp(matcher);
+ return undefined;
+ } catch {
+ return {
+ code: 'invalid_matcher',
+ severity: 'error',
+ message: 'Matcher is not a valid regular expression',
+ };
+ }
+}
+
+function getEventIssues(
+ sourceEvent: string,
+ targetEvent: HookEvent | undefined,
+ capabilities: PluginHookCapabilities,
+): PluginHookCompatibilityIssue[] {
+ if (!targetEvent) {
+ return [
+ {
+ code: 'unsupported_event',
+ severity: 'error',
+ message: `${sourceEvent} has no equivalent LibreChat lifecycle event`,
+ },
+ ];
+ }
+ if (sourceEvent === 'SubagentStop') {
+ return [
+ {
+ code: 'unsupported_event_payload',
+ severity: 'error',
+ message:
+ 'SubagentStop is unavailable because the LibreChat hook input does not expose stop-hook state',
+ },
+ ];
+ }
+ if (sourceEvent === 'PermissionDenied') {
+ return [
+ {
+ code: 'unsupported_event_output',
+ severity: 'error',
+ message:
+ 'PermissionDenied is unavailable because the LibreChat hook output cannot request a retry',
+ },
+ ];
+ }
+ if (sourceEvent !== 'SessionStart') {
+ return [];
+ }
+ if (capabilities.sessionLifecycle !== true) {
+ return [
+ {
+ code: 'unsupported_session_lifecycle',
+ severity: 'error',
+ message: 'SessionStart requires a runtime that deduplicates RunStart by plugin session',
+ },
+ ];
+ }
+ return [
+ {
+ code: 'event_alias',
+ severity: 'warning',
+ message: 'SessionStart maps to RunStart with runtime-provided once-per-session semantics',
+ },
+ ];
+}
+
+const PROMPT_UNSUPPORTED_EVENTS = new Set([
+ 'SessionStart',
+ 'PermissionDenied',
+ 'SubagentStart',
+ 'StopFailure',
+ 'PreCompact',
+ 'PostCompact',
+]);
+
+function getHandlerIssues(
+ sourceEvent: string,
+ handler: PluginHookHandler,
+ capabilities: PluginHookCapabilities,
+): PluginHookCompatibilityIssue[] {
+ const issues: PluginHookCompatibilityIssue[] = [];
+ const supportedHandlerType =
+ handler.type === 'command' || handler.type === 'prompt' ? handler.type : undefined;
+ if (!supportedHandlerType || !capabilities.handlerTypes.has(supportedHandlerType)) {
+ issues.push({
+ code: 'unsupported_handler',
+ severity: 'error',
+ message: `The configured executor does not support ${handler.type} hook handlers`,
+ });
+ }
+ if (handler.type === 'prompt' && PROMPT_UNSUPPORTED_EVENTS.has(sourceEvent)) {
+ issues.push({
+ code: 'unsupported_handler_event',
+ severity: 'error',
+ message: `${sourceEvent} does not support prompt hook handlers`,
+ });
+ }
+ if (handler.async === true && capabilities.async !== true) {
+ issues.push({
+ code: 'unsupported_async',
+ severity: 'error',
+ message: 'The configured executor does not support asynchronous hook execution',
+ });
+ }
+ if (handler.asyncRewake === true && capabilities.asyncRewake !== true) {
+ issues.push({
+ code: 'unsupported_async_rewake',
+ severity: 'error',
+ message: 'The configured executor does not support asyncRewake',
+ });
+ }
+ if (handler.continueOnBlock === true && handler.type !== 'prompt') {
+ issues.push({
+ code: 'unsupported_continue_on_block',
+ severity: 'error',
+ message: 'continueOnBlock is only supported for prompt hook handlers',
+ });
+ }
+ if ((handler.timeout ?? 0) > 600) {
+ issues.push({
+ code: 'long_timeout',
+ severity: 'warning',
+ message: 'Hook timeout exceeds the portable 600-second compatibility target',
+ });
+ }
+ return issues;
+}
+
+interface MatcherPlan {
+ sourceMatcher?: string;
+ matcher?: string;
+ issues: PluginHookCompatibilityIssue[];
+}
+
+function planMatcher(
+ sourceEvent: string,
+ targetEvent: HookEvent | undefined,
+ configuredMatcher: string | undefined,
+ capabilities: PluginHookCapabilities,
+): MatcherPlan {
+ const sourceMatcher = normalizeMatcher(configuredMatcher);
+ if (!sourceMatcher) {
+ if (sourceEvent === 'SessionStart' && capabilities.sessionLifecycle === true) {
+ return {
+ issues: [
+ {
+ code: 'unsupported_session_source',
+ severity: 'warning',
+ message:
+ 'Wildcard SessionStart compatibility covers startup, resume, and clear; compact is runtime-filtered',
+ },
+ ],
+ };
+ }
+ return { issues: [] };
+ }
+ const matcherSemantics = getClaudeMatcherSemantics(sourceEvent, sourceMatcher);
+ const validationIssue = getMatcherValidationIssue(sourceEvent, sourceMatcher, targetEvent);
+ if (validationIssue?.code === 'unsupported_matcher' || !targetEvent) {
+ return {
+ sourceMatcher,
+ matcher: sourceMatcher,
+ issues: validationIssue ? [validationIssue] : [],
+ };
+ }
+ if (sourceEvent === 'SessionStart') {
+ const matcher =
+ matcherSemantics.kind === 'exact'
+ ? anchorExactMatcher(matcherSemantics.canonicalMatcher)
+ : sourceMatcher;
+ const runtimeValidationIssue =
+ validationIssue ?? getMatcherValidationIssue(sourceEvent, matcher, targetEvent);
+ const includesCompact =
+ matcherSemantics.kind === 'exact'
+ ? matcherSemantics.values.includes('compact')
+ : matcherIncludesValue(matcher, 'compact');
+ if (!runtimeValidationIssue && includesCompact) {
+ return {
+ sourceMatcher,
+ matcher,
+ issues: [
+ {
+ code: 'unsupported_session_source',
+ severity: 'error',
+ message:
+ 'SessionStart source "compact" is unavailable because LibreChat PostCompact hook output cannot inject session context',
+ },
+ ],
+ };
+ }
+ return {
+ sourceMatcher,
+ matcher,
+ issues: runtimeValidationIssue ? [runtimeValidationIssue] : [],
+ };
+ }
+ if (!capabilities.translateMatcher) {
+ return {
+ sourceMatcher,
+ issues: [
+ {
+ code: 'unmapped_matcher',
+ severity: 'error',
+ message: 'Plugin matcher namespaces require an explicit LibreChat query translation',
+ },
+ ],
+ };
+ }
+
+ let translation: string | PluginHookMatcherTranslationResult | undefined;
+ try {
+ translation = capabilities.translateMatcher({
+ sourceEvent,
+ targetEvent,
+ matcher: matcherSemantics.canonicalMatcher,
+ });
+ } catch {
+ translation = undefined;
+ }
+ const translatedMatcher = typeof translation === 'string' ? translation : translation?.matcher;
+ const requiresToolNameTranslation =
+ typeof translation === 'object' && translation.requiresToolNameTranslation === true;
+ if (!translatedMatcher?.trim()) {
+ return {
+ sourceMatcher,
+ issues: [
+ {
+ code: 'unmapped_matcher',
+ severity: 'error',
+ message: 'The configured matcher translator could not map this plugin matcher',
+ },
+ ],
+ };
+ }
+
+ const normalizedTranslation = translatedMatcher.trim();
+ const matcher =
+ matcherSemantics.kind === 'exact'
+ ? anchorExactMatcher(normalizedTranslation)
+ : normalizedTranslation;
+ const issues: PluginHookCompatibilityIssue[] = validationIssue ? [validationIssue] : [];
+ const translatedValidationIssue = getMatcherValidationIssue(sourceEvent, matcher, targetEvent);
+ if (translatedValidationIssue && !validationIssue) {
+ issues.push(translatedValidationIssue);
+ }
+ if (normalizedTranslation !== matcherSemantics.canonicalMatcher) {
+ issues.push({
+ code: 'matcher_translated',
+ severity: 'warning',
+ message: `Plugin matcher "${sourceMatcher}" maps to LibreChat matcher "${matcher}"`,
+ });
+ }
+ if (
+ requiresToolNameTranslation &&
+ TOOL_NAME_EVENTS.has(targetEvent) &&
+ !capabilities.toPluginToolName
+ ) {
+ issues.push({
+ code: 'unmapped_tool_name',
+ severity: 'error',
+ message: 'Translated tool matchers require a reverse tool-name mapping for plugin payloads',
+ });
+ }
+ return { sourceMatcher, matcher, issues };
+}
+
+function hasError(issues: readonly PluginHookCompatibilityIssue[]): boolean {
+ return issues.some((issue) => issue.severity === 'error');
+}
+
+export function planPluginHooks(
+ document: PluginHooksDocument,
+ capabilities: PluginHookCapabilities,
+): PluginHookPlan {
+ const entries: PluginHookPlanEntry[] = [];
+ const summary: PluginHookPlanSummary = { declared: 0, ready: 0, unsupported: 0 };
+
+ for (const [sourceEvent, groups] of Object.entries(document.hooks)) {
+ const targetEvent = EVENT_MAP.get(sourceEvent);
+ const eventIssues = getEventIssues(sourceEvent, targetEvent, capabilities);
+
+ for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+ const group = groups[groupIndex];
+ const matcherPlan = planMatcher(sourceEvent, targetEvent, group.matcher, capabilities);
+ const groupIssues = [...eventIssues, ...matcherPlan.issues];
+
+ for (let handlerIndex = 0; handlerIndex < group.hooks.length; handlerIndex++) {
+ const handler = group.hooks[handlerIndex];
+ const issues = [...groupIssues, ...getHandlerIssues(sourceEvent, handler, capabilities)];
+ const condition = handler.if ?? group.if;
+ if (handler.if && group.if && handler.if !== group.if) {
+ issues.push({
+ code: 'conflicting_condition',
+ severity: 'error',
+ message: 'A hook cannot combine different group-level and handler-level conditions',
+ });
+ }
+ if (condition) {
+ if (!targetEvent || !TOOL_NAME_EVENTS.has(targetEvent)) {
+ issues.push({
+ code: 'unsupported_condition',
+ severity: 'error',
+ message: 'Conditional `if` hook expressions are only supported for tool events',
+ });
+ } else if (!capabilities.matchCondition) {
+ issues.push({
+ code: 'unsupported_condition',
+ severity: 'error',
+ message: 'The configured executor does not support conditional `if` hook expressions',
+ });
+ }
+ }
+ const status = hasError(issues) ? 'unsupported' : 'ready';
+
+ entries.push({
+ sourceEvent,
+ targetEvent,
+ groupIndex,
+ handlerIndex,
+ ...(matcherPlan.sourceMatcher !== undefined && {
+ sourceMatcher: matcherPlan.sourceMatcher,
+ }),
+ ...(matcherPlan.matcher !== undefined && { matcher: matcherPlan.matcher }),
+ ...(condition !== undefined && { condition }),
+ handler,
+ status,
+ issues,
+ ...(handler.timeout !== undefined && { timeoutMs: handler.timeout * 1_000 }),
+ });
+ summary.declared++;
+ summary[status === 'ready' ? 'ready' : 'unsupported']++;
+ }
+ }
+ }
+
+ return {
+ ...(document.description !== undefined && { description: document.description }),
+ entries,
+ summary,
+ };
+}
diff --git a/packages/api/src/agents/hooks/index.ts b/packages/api/src/agents/hooks/index.ts
new file mode 100644
index 0000000000..d4ad47f63d
--- /dev/null
+++ b/packages/api/src/agents/hooks/index.ts
@@ -0,0 +1,3 @@
+export * from './schema';
+export * from './runtime';
+export * from './compatibility';
diff --git a/packages/api/src/agents/hooks/runtime.spec.ts b/packages/api/src/agents/hooks/runtime.spec.ts
new file mode 100644
index 0000000000..2ec0811873
--- /dev/null
+++ b/packages/api/src/agents/hooks/runtime.spec.ts
@@ -0,0 +1,968 @@
+import { HookRegistry, executeHooks } from '@librechat/agents';
+import { AIMessage } from '@librechat/agents/langchain/messages';
+import type { HookOutput } from '@librechat/agents';
+import type { PluginHookCapabilities } from './compatibility';
+import type { PluginHookExecutor } from './runtime';
+import type { PluginHooksDocument } from './schema';
+import { createPluginHookPayload, registerPluginHooks } from './runtime';
+
+const commandCapabilities: PluginHookCapabilities = {
+ handlerTypes: new Set(['command']),
+ translateMatcher: ({ matcher }: { matcher: string }) => matcher,
+};
+
+function document(hooks: PluginHooksDocument['hooks']): PluginHooksDocument {
+ return { hooks };
+}
+
+function executor(output: HookOutput = {}): PluginHookExecutor & {
+ execute: jest.Mock<Promise<HookOutput>, Parameters<PluginHookExecutor['execute']>>;
+} {
+ const execute = jest.fn<Promise<HookOutput>, Parameters<PluginHookExecutor['execute']>>(
+ async (_request, _signal) => output,
+ );
+ return {
+ capabilities: {
+ ...commandCapabilities,
+ handlerTypes: new Set(commandCapabilities.handlerTypes),
+ },
+ execute,
+ };
+}
+
+describe('registerPluginHooks', () => {
+ test('registers a supported command hook and passes a Claude-shaped payload', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor({
+ decision: 'deny',
+ reason: 'Protected path',
+ additionalContext: 'Policy checked',
+ });
+ hookExecutor.capabilities.matchCondition = ({ toolInput }) =>
+ typeof toolInput.path === 'string' && toolInput.path.startsWith('/workspace/');
+ const registration = registerPluginHooks({
+ pluginId: 'security-guidance',
+ registry,
+ executor: hookExecutor,
+ context: {
+ sessionId: 'conversation-1',
+ cwd: '/workspace',
+ permissionMode: 'default',
+ },
+ document: document({
+ PreToolUse: [
+ {
+ matcher: '^write_file$',
+ hooks: [
+ {
+ type: 'command',
+ command: 'check-write',
+ if: 'Write(/workspace/**)',
+ timeout: 5,
+ once: true,
+ },
+ ],
+ },
+ ],
+ }),
+ });
+
+ expect(registration.registered).toBe(1);
+ expect(registry.getMatchers('PreToolUse')[0].timeout).toBe(5_000);
+ expect(registry.getMatchers('PreToolUse')[0].once).toBeUndefined();
+
+ const result = await executeHooks({
+ registry,
+ matchQuery: 'write_file',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId: 'run-1',
+ threadId: 'thread-1',
+ agentId: 'agent-1',
+ toolName: 'write_file',
+ toolInput: { path: '/workspace/file.ts' },
+ toolUseId: 'tool-1',
+ },
+ });
+
+ expect(result).toEqual(
+ expect.objectContaining({
+ decision: 'deny',
+ reason: 'Protected path',
+ additionalContexts: ['Policy checked'],
+ }),
+ );
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ pluginId: 'security-guidance',
+ sourceEvent: 'PreToolUse',
+ targetEvent: 'PreToolUse',
+ condition: 'Write(/workspace/**)',
+ payload: expect.objectContaining({
+ hook_event_name: 'PreToolUse',
+ session_id: 'conversation-1',
+ run_id: 'run-1',
+ thread_id: 'thread-1',
+ cwd: '/workspace',
+ permission_mode: 'default',
+ agent_id: 'agent-1',
+ tool_name: 'write_file',
+ tool_input: { path: '/workspace/file.ts' },
+ tool_use_id: 'tool-1',
+ }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('registers Claude exact and list matchers without substring matches', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ const registration = registerPluginHooks({
+ pluginId: 'exact-tool-matches',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ {
+ matcher: 'Edit|Write',
+ hooks: [{ type: 'command', command: 'pipe-list-audit' }],
+ },
+ {
+ matcher: 'Edit, Write',
+ hooks: [{ type: 'command', command: 'comma-list-audit' }],
+ },
+ ],
+ }),
+ });
+
+ const run = async (runId: string, toolName: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ matchQuery: toolName,
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId,
+ toolName,
+ toolInput: {},
+ toolUseId: `tool-${runId}`,
+ },
+ });
+ };
+
+ await run('substring', 'MultiEdit');
+ expect(hookExecutor.execute).not.toHaveBeenCalled();
+
+ await run('exact', 'Edit');
+
+ expect(registration.plan.entries.map(({ matcher }) => matcher)).toEqual([
+ '^(?:Edit|Write)$',
+ '^(?:Edit|Write)$',
+ ]);
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+ });
+
+ test('applies Claude default timeouts when handlers omit them', () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.handlerTypes = new Set(['command', 'prompt']);
+ registerPluginHooks({
+ pluginId: 'timeout-defaults',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ Stop: [
+ {
+ hooks: [
+ { type: 'command', command: 'long-running-check' },
+ { type: 'prompt', prompt: 'Verify completion' },
+ ],
+ },
+ ],
+ UserPromptSubmit: [
+ {
+ hooks: [{ type: 'command', command: 'validate-prompt' }],
+ },
+ ],
+ }),
+ });
+
+ expect(registry.getMatchers('Stop').map(({ timeout }) => timeout)).toEqual([600_000, 30_000]);
+ expect(registry.getMatchers('UserPromptSubmit')[0].timeout).toBe(30_000);
+ });
+
+ test('maps LibreChat tool names back into the plugin payload namespace', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.translateMatcher = () => ({
+ matcher: '^bash_tool$',
+ requiresToolNameTranslation: true,
+ });
+ hookExecutor.capabilities.toPluginToolName = ({ toolName }) =>
+ toolName === 'bash_tool' ? 'Bash' : toolName;
+ registerPluginHooks({
+ pluginId: 'tool-name-adapter',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ {
+ matcher: 'Bash',
+ hooks: [{ type: 'command', command: 'check-bash' }],
+ },
+ ],
+ }),
+ });
+
+ await executeHooks({
+ registry,
+ matchQuery: 'bash_tool',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId: 'run-tool-name',
+ toolName: 'bash_tool',
+ toolInput: { command: 'npm test' },
+ toolUseId: 'tool-name-1',
+ },
+ });
+
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ input: expect.objectContaining({ toolName: 'bash_tool' }),
+ payload: expect.objectContaining({ tool_name: 'Bash' }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('does not consume a conditional once hook before its condition matches', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.translateMatcher = () => ({
+ matcher: '^bash_tool$',
+ requiresToolNameTranslation: true,
+ });
+ hookExecutor.capabilities.toPluginToolName = ({ toolName }) =>
+ toolName === 'bash_tool' ? 'Bash' : toolName;
+ hookExecutor.capabilities.matchCondition = ({ toolName, toolInput }) =>
+ toolName === 'Bash' &&
+ typeof toolInput.command === 'string' &&
+ toolInput.command.startsWith('git commit ');
+ registerPluginHooks({
+ pluginId: 'commit-review',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ {
+ matcher: 'Bash',
+ hooks: [
+ {
+ type: 'command',
+ command: 'review-commit',
+ if: 'Bash(git commit:*)',
+ once: true,
+ },
+ ],
+ },
+ ],
+ }),
+ });
+
+ expect(registry.getMatchers('PreToolUse')[0].once).toBeUndefined();
+
+ const run = async (runId: string, command: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ matchQuery: 'bash_tool',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId,
+ threadId: 'commit-session',
+ toolName: 'bash_tool',
+ toolInput: { command },
+ toolUseId: `tool-${runId}`,
+ },
+ });
+ };
+
+ await run('test', 'npm test');
+ await run('commit', 'git commit -m "test"');
+ await run('second-commit', 'git commit -m "again"');
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ condition: 'Bash(git commit:*)',
+ input: expect.objectContaining({ runId: 'commit' }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('scopes once handlers to each plugin session', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ registerPluginHooks({
+ pluginId: 'session-once',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ {
+ matcher: 'Write',
+ hooks: [{ type: 'command', command: 'initialize-write-audit', once: true }],
+ },
+ ],
+ }),
+ });
+
+ const run = async (runId: string, threadId: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ matchQuery: 'Write',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId,
+ threadId,
+ toolName: 'Write',
+ toolInput: { file_path: '/workspace/file.ts' },
+ toolUseId: `tool-${runId}`,
+ },
+ });
+ };
+
+ await run('session-a-first', 'session-a');
+ await run('session-a-second', 'session-a');
+ await run('session-b-first', 'session-b');
+
+ expect(registry.getMatchers('PreToolUse')[0].once).toBeUndefined();
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+ expect(hookExecutor.execute.mock.calls.map(([request]) => request.input.threadId)).toEqual([
+ 'session-a',
+ 'session-b',
+ ]);
+ });
+
+ test('shares once state across duplicate overlapping handlers', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ const duplicateHandler = {
+ type: 'command',
+ command: 'initialize-write-audit',
+ once: true,
+ };
+ registerPluginHooks({
+ pluginId: 'deduplicated-session-once',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ { matcher: '^Write$', hooks: [duplicateHandler] },
+ { matcher: '^Wri.*$', hooks: [{ ...duplicateHandler }] },
+ ],
+ }),
+ });
+
+ const run = async (runId: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ matchQuery: 'Write',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId,
+ threadId: 'shared-once-session',
+ toolName: 'Write',
+ toolInput: { file_path: '/workspace/file.ts' },
+ toolUseId: `tool-${runId}`,
+ },
+ });
+ };
+
+ await run('first');
+ await run('second');
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ });
+
+ test('keeps once state separate across disjoint matcher declarations', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ const duplicateHandler = {
+ type: 'command',
+ command: 'initialize-tool-audit',
+ once: true,
+ };
+ registerPluginHooks({
+ pluginId: 'separate-session-once',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ { matcher: '^Write$', hooks: [duplicateHandler] },
+ { matcher: '^Bash$', hooks: [{ ...duplicateHandler }] },
+ ],
+ }),
+ });
+
+ const run = async (runId: string, toolName: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ matchQuery: toolName,
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId,
+ threadId: 'separate-once-session',
+ toolName,
+ toolInput: {},
+ toolUseId: `tool-${runId}`,
+ },
+ });
+ };
+
+ await run('write-first', 'Write');
+ await run('write-second', 'Write');
+ await run('bash-first', 'Bash');
+ await run('bash-second', 'Bash');
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+ });
+
+ test('passes prompt continueOnBlock through to the executor', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.handlerTypes = new Set(['command', 'prompt']);
+ registerPluginHooks({
+ pluginId: 'self-correcting-review',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PostToolUse: [
+ {
+ matcher: 'Write',
+ hooks: [
+ {
+ type: 'prompt',
+ prompt: 'Verify this write result',
+ continueOnBlock: true,
+ },
+ ],
+ },
+ ],
+ }),
+ });
+
+ await executeHooks({
+ registry,
+ matchQuery: 'Write',
+ input: {
+ hook_event_name: 'PostToolUse',
+ runId: 'run-write',
+ toolName: 'Write',
+ toolInput: { file_path: '/workspace/file.ts' },
+ toolOutput: 'updated',
+ toolUseId: 'tool-write',
+ },
+ });
+
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ handler: expect.objectContaining({ continueOnBlock: true }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('deduplicates identical handlers across overlapping matcher groups', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ const duplicateHandler = { type: 'command', command: 'audit-write' };
+ const registration = registerPluginHooks({
+ pluginId: 'deduplicated-hooks',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreToolUse: [
+ { matcher: '^write_file$', hooks: [duplicateHandler] },
+ { matcher: '^write_.*$', hooks: [{ ...duplicateHandler }] },
+ ],
+ }),
+ });
+
+ await executeHooks({
+ registry,
+ matchQuery: 'write_file',
+ input: {
+ hook_event_name: 'PreToolUse',
+ runId: 'run-deduplicate',
+ toolName: 'write_file',
+ toolInput: { path: '/workspace/file.ts' },
+ toolUseId: 'tool-deduplicate',
+ },
+ });
+
+ expect(registration.registered).toBe(2);
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ });
+
+ test('filters and deduplicates SessionStart while registering RunStart', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor({ additionalContext: 'Loaded project context' });
+ hookExecutor.capabilities.sessionLifecycle = true;
+ delete hookExecutor.capabilities.translateMatcher;
+ registerPluginHooks({
+ pluginId: 'learning-output-style',
+ registry,
+ executor: hookExecutor,
+ context: {
+ sessionStartSource: 'resume',
+ model: 'claude-sonnet-4-6',
+ agentType: 'code-reviewer',
+ },
+ document: document({
+ SessionStart: [
+ {
+ matcher: 'resume',
+ hooks: [{ type: 'command', command: 'load-context' }],
+ },
+ {
+ matcher: 'startup',
+ hooks: [{ type: 'command', command: 'do-not-load' }],
+ },
+ ],
+ }),
+ });
+
+ const firstResult = await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'RunStart',
+ runId: 'run-2',
+ threadId: 'conversation-2',
+ messages: [],
+ },
+ });
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'RunStart',
+ runId: 'run-3',
+ threadId: 'conversation-2',
+ messages: [],
+ },
+ });
+
+ expect(firstResult.additionalContexts).toEqual(['Loaded project context']);
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ sourceEvent: 'SessionStart',
+ targetEvent: 'RunStart',
+ handler: expect.objectContaining({ command: 'load-context' }),
+ payload: expect.objectContaining({
+ hook_event_name: 'SessionStart',
+ session_id: 'conversation-2',
+ source: 'resume',
+ model: 'claude-sonnet-4-6',
+ agent_type: 'code-reviewer',
+ }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('runtime-filters compact from wildcard SessionStart hooks', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.sessionLifecycle = true;
+ registerPluginHooks({
+ pluginId: 'compact-context',
+ registry,
+ executor: hookExecutor,
+ context: { sessionStartSource: 'compact', model: 'claude-sonnet-4-6' },
+ document: document({
+ SessionStart: [{ hooks: [{ type: 'command', command: 'load-context' }] }],
+ }),
+ });
+
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'RunStart',
+ runId: 'run-compact-session',
+ threadId: 'conversation-compact-session',
+ messages: [],
+ },
+ });
+
+ expect(hookExecutor.execute).not.toHaveBeenCalled();
+ });
+
+ test('shares SessionStart deduplication across overlapping declarations', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.sessionLifecycle = true;
+ delete hookExecutor.capabilities.translateMatcher;
+ const duplicateHandler = { type: 'command', command: 'load-context' };
+ registerPluginHooks({
+ pluginId: 'deduplicated-session-start',
+ registry,
+ executor: hookExecutor,
+ context: { sessionStartSource: 'resume' },
+ document: document({
+ SessionStart: [
+ { matcher: 'startup|resume', hooks: [duplicateHandler] },
+ { matcher: 'resume', hooks: [{ ...duplicateHandler }] },
+ ],
+ }),
+ });
+
+ const run = async (runId: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'RunStart',
+ runId,
+ threadId: 'shared-session-start',
+ messages: [],
+ },
+ });
+ };
+
+ await run('first');
+ await run('second');
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ });
+
+ test('keeps SessionStart state separate across disjoint source declarations', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.sessionLifecycle = true;
+ const context = { sessionStartSource: 'startup' };
+ const duplicateHandler = { type: 'command', command: 'load-context' };
+ registerPluginHooks({
+ pluginId: 'separate-session-start',
+ registry,
+ executor: hookExecutor,
+ context,
+ document: document({
+ SessionStart: [
+ { matcher: 'startup', hooks: [duplicateHandler] },
+ { matcher: 'resume', hooks: [{ ...duplicateHandler }] },
+ ],
+ }),
+ });
+
+ const run = async (runId: string): Promise<void> => {
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'RunStart',
+ runId,
+ threadId: 'separate-session-start',
+ messages: [],
+ },
+ });
+ };
+
+ await run('startup');
+ context.sessionStartSource = 'resume';
+ await run('resume');
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+ });
+
+ test('translates compaction matchers and carries the trigger into PostCompact', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ hookExecutor.capabilities.translateMatcher = ({ matcher }) =>
+ matcher === 'auto' ? '^(token_ratio|remaining_tokens|messages_to_refine|default)$' : matcher;
+ const registration = registerPluginHooks({
+ pluginId: 'compact-audit',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ PreCompact: [
+ {
+ matcher: 'auto',
+ hooks: [{ type: 'command', command: 'before-compact' }],
+ },
+ ],
+ PostCompact: [
+ {
+ matcher: 'auto',
+ hooks: [{ type: 'command', command: 'after-compact' }],
+ },
+ ],
+ }),
+ });
+
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'PreCompact',
+ runId: 'run-compact',
+ threadId: 'conversation-compact',
+ trigger: 'token_ratio',
+ messagesBeforeCount: 12,
+ },
+ });
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'PostCompact',
+ runId: 'run-compact',
+ threadId: 'conversation-compact',
+ summary: 'Compacted context',
+ messagesAfterCount: 0,
+ },
+ });
+
+ expect(registration.registered).toBe(2);
+ expect(registry.getMatchers('PreCompact')).toHaveLength(2);
+ expect(registry.getMatchers('PostCompact')).toHaveLength(2);
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+ expect(hookExecutor.execute).toHaveBeenNthCalledWith(
+ 1,
+ expect.objectContaining({
+ sourceEvent: 'PreCompact',
+ payload: expect.objectContaining({
+ hook_event_name: 'PreCompact',
+ trigger: 'auto',
+ messages_before_count: 12,
+ }),
+ }),
+ expect.any(AbortSignal),
+ );
+ expect(hookExecutor.execute).toHaveBeenNthCalledWith(
+ 2,
+ expect.objectContaining({
+ sourceEvent: 'PostCompact',
+ payload: expect.objectContaining({
+ hook_event_name: 'PostCompact',
+ trigger: 'auto',
+ compact_summary: 'Compacted context',
+ messages_after_count: 0,
+ }),
+ }),
+ expect.any(AbortSignal),
+ );
+
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'PostCompact',
+ runId: 'run-compact',
+ threadId: 'conversation-compact',
+ summary: 'No matching trigger',
+ messagesAfterCount: 0,
+ },
+ });
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(2);
+
+ registration.unregister();
+ expect(registry.getMatchers('PreCompact')).toHaveLength(0);
+ expect(registry.getMatchers('PostCompact')).toHaveLength(0);
+ });
+
+ test('translates batch entries and preserves the PostToolUseFailure error field', () => {
+ const batchPayload = createPluginHookPayload('PostToolBatch', {
+ hook_event_name: 'PostToolBatch',
+ runId: 'run-batch',
+ entries: [
+ {
+ toolName: 'Read',
+ toolInput: { file_path: '/workspace/file.ts' },
+ toolUseId: 'tool-success',
+ toolOutput: 'file contents',
+ status: 'success',
+ },
+ {
+ toolName: 'Bash',
+ toolInput: { command: 'exit 1' },
+ toolUseId: 'tool-failure',
+ error: 'Command failed',
+ status: 'error',
+ },
+ ],
+ });
+ const failurePayload = createPluginHookPayload('PostToolUseFailure', {
+ hook_event_name: 'PostToolUseFailure',
+ runId: 'run-failure',
+ toolName: 'Bash',
+ toolInput: { command: 'exit 1' },
+ toolUseId: 'tool-failure',
+ error: 'Command failed',
+ });
+
+ expect(batchPayload.tool_calls).toEqual([
+ {
+ tool_name: 'Read',
+ tool_input: { file_path: '/workspace/file.ts' },
+ tool_use_id: 'tool-success',
+ tool_response: 'file contents',
+ },
+ {
+ tool_name: 'Bash',
+ tool_input: { command: 'exit 1' },
+ tool_use_id: 'tool-failure',
+ tool_response: 'Command failed',
+ },
+ ]);
+ expect(batchPayload).not.toHaveProperty('entries');
+ expect(failurePayload).toEqual(
+ expect.objectContaining({
+ hook_event_name: 'PostToolUseFailure',
+ error: 'Command failed',
+ }),
+ );
+ expect(failurePayload).not.toHaveProperty('tool_error');
+ });
+
+ test('emits the documented SubagentStart identity fields', () => {
+ const payload = createPluginHookPayload('SubagentStart', {
+ hook_event_name: 'SubagentStart',
+ runId: 'run-subagent',
+ parentAgentId: 'agent-parent',
+ agentId: 'agent-child',
+ agentType: 'Explore',
+ inputs: [],
+ });
+
+ expect(payload).toEqual(
+ expect.objectContaining({
+ hook_event_name: 'SubagentStart',
+ agent_id: 'agent-child',
+ agent_type: 'Explore',
+ }),
+ );
+ });
+
+ test('includes StopFailure assistant text when the SDK provides it', () => {
+ const payload = createPluginHookPayload('StopFailure', {
+ hook_event_name: 'StopFailure',
+ runId: 'run-stop-failure',
+ error: 'Model response could not be parsed',
+ lastAssistantMessage: new AIMessage('Partial assistant response'),
+ });
+
+ expect(payload).toEqual(
+ expect.objectContaining({
+ hook_event_name: 'StopFailure',
+ error: 'Model response could not be parsed',
+ last_assistant_message: 'Partial assistant response',
+ }),
+ );
+ });
+
+ test('filters StopFailure matchers against the runtime error', async () => {
+ const registry = new HookRegistry();
+ const hookExecutor = executor();
+ const registration = registerPluginHooks({
+ pluginId: 'failure-audit',
+ registry,
+ executor: hookExecutor,
+ document: document({
+ StopFailure: [
+ {
+ matcher: 'rate_limit|overloaded',
+ hooks: [{ type: 'command', command: 'record-failure' }],
+ },
+ ],
+ }),
+ });
+
+ expect(registration.registered).toBe(1);
+ expect(registry.getMatchers('StopFailure')[0].pattern).toBeUndefined();
+
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'StopFailure',
+ runId: 'run-auth-failure',
+ error: 'authentication_failed',
+ },
+ });
+ await executeHooks({
+ registry,
+ input: {
+ hook_event_name: 'StopFailure',
+ runId: 'run-rate-limit',
+ error: 'rate_limit',
+ },
+ });
+
+ expect(hookExecutor.execute).toHaveBeenCalledTimes(1);
+ expect(hookExecutor.execute).toHaveBeenCalledWith(
+ expect.objectContaining({
+ sourceEvent: 'StopFailure',
+ targetEvent: 'StopFailure',
+ payload: expect.objectContaining({
+ hook_event_name: 'StopFailure',
+ error: 'rate_limit',
+ }),
+ }),
+ expect.any(AbortSignal),
+ );
+ });
+
+ test('registers the event surface used by the official hookify plugin', () => {
+ const registry = new HookRegistry();
+ const registration = registerPluginHooks({
+ pluginId: 'hookify',
+ registry,
+ executor: executor(),
+ document: document({
+ PreToolUse: [{ hooks: [{ type: 'command', command: 'pretooluse.py' }] }],
+ PostToolUse: [{ hooks: [{ type: 'command', command: 'posttooluse.py' }] }],
+ Stop: [{ hooks: [{ type: 'command', command: 'stop.py' }] }],
+ UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'userpromptsubmit.py' }] }],
+ }),
+ });
+
+ expect(registration.registered).toBe(4);
+ expect(registration.plan.summary).toEqual({ declared: 4, ready: 4, unsupported: 0 });
+ expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
+ expect(registry.getMatchers('PostToolUse')).toHaveLength(1);
+ expect(registry.getMatchers('Stop')).toHaveLength(1);
+ expect(registry.getMatchers('UserPromptSubmit')).toHaveLength(1);
+ });
+
+ test('leaves unsupported declarations in the plan without registering them', () => {
+ const registry = new HookRegistry();
+ const registration = registerPluginHooks({
+ pluginId: 'mixed-plugin',
+ registry,
+ executor: executor(),
+ document: document({
+ UserPromptExpansion: [{ hooks: [{ type: 'command', command: 'banner' }] }],
+ Stop: [{ hooks: [{ type: 'prompt', prompt: 'Verify completion' }] }],
+ }),
+ });
+
+ expect(registration.registered).toBe(0);
+ expect(registration.plan.summary.unsupported).toBe(2);
+ expect(registry.getMatchers('Stop')).toHaveLength(0);
+ });
+
+ test('unregisters only this plugin registration and is idempotent', () => {
+ const registry = new HookRegistry();
+ const existing = jest.fn(async () => ({}));
+ registry.register('Stop', { hooks: [existing] });
+ const registration = registerPluginHooks({
+ pluginId: 'ralph-loop',
+ registry,
+ executor: executor(),
+ document: document({
+ Stop: [{ hooks: [{ type: 'command', command: 'stop-hook.sh' }] }],
+ }),
+ });
+
+ expect(registry.getMatchers('Stop')).toHaveLength(2);
+ registration.unregister();
+ registration.unregister();
+ expect(registry.getMatchers('Stop')).toHaveLength(1);
+ expect(registry.getMatchers('Stop')[0].hooks[0]).toBe(existing);
+ });
+});
diff --git a/packages/api/src/agents/hooks/runtime.ts b/packages/api/src/agents/hooks/runtime.ts
new file mode 100644
index 0000000000..4372e444cc
--- /dev/null
+++ b/packages/api/src/agents/hooks/runtime.ts
@@ -0,0 +1,473 @@
+import { HookRegistry, matchesQuery } from '@librechat/agents';
+import type {
+ HookInput,
+ HookOutput,
+ HookMatcher,
+ HookCallback,
+ HookEvent,
+ PostToolBatchEntry,
+} from '@librechat/agents';
+import type { PluginHookCapabilities, PluginHookPlan } from './compatibility';
+import type { PluginHookHandler, PluginHooksDocument } from './schema';
+import { planPluginHooks } from './compatibility';
+
+export interface PluginHookRuntimeContext {
+ sessionId?: string;
+ cwd?: string;
+ transcriptPath?: string | null;
+ permissionMode?: string;
+ sessionStartSource?: string;
+ model?: string;
+ agentType?: string;
+}
+
+export interface PluginHookBatchToolCall {
+ tool_name: string;
+ tool_input: Record<string, unknown>;
+ tool_use_id: string;
+ tool_response?: unknown;
+}
+
+export interface PluginHookPayload {
+ hook_event_name: string;
+ session_id: string;
+ run_id: string;
+ thread_id?: string;
+ cwd?: string;
+ transcript_path?: string | null;
+ permission_mode?: string;
+ source?: string;
+ model?: string;
+ agent_id?: string;
+ executing_agent_id?: string;
+ prompt?: string;
+ tool_name?: string;
+ tool_input?: Record<string, unknown>;
+ tool_use_id?: string;
+ tool_response?: unknown;
+ error?: string;
+ last_assistant_message?: string;
+ reason?: string;
+ agent_type?: string;
+ stop_hook_active?: boolean;
+ trigger?: string;
+ compact_summary?: string;
+ messages_before_count?: number;
+ messages_after_count?: number;
+ tool_calls?: PluginHookBatchToolCall[];
+}
+
+export interface PluginHookExecutionRequest {
+ pluginId: string;
+ sourceEvent: string;
+ targetEvent: HookEvent;
+ handler: PluginHookHandler;
+ condition?: string;
+ input: HookInput;
+ payload: PluginHookPayload;
+}
+
+/**
+ * Host-owned boundary for executing a planned hook.
+ * This compatibility layer never launches plugin code in the LibreChat API process.
+ */
+export interface PluginHookExecutor {
+ capabilities: PluginHookCapabilities;
+ execute(
+ request: PluginHookExecutionRequest,
+ signal: AbortSignal,
+ ): HookOutput | Promise<HookOutput>;
+}
+
+export interface RegisterPluginHooksOptions {
+ pluginId: string;
+ registry: HookRegistry;
+ document: PluginHooksDocument;
+ executor: PluginHookExecutor;
+ context?: PluginHookRuntimeContext;
+}
+
+export interface PluginHookRegistration {
+ plan: PluginHookPlan;
+ registered: number;
+ unregister: () => void;
+}
+
+interface PluginHookPayloadState {
+ compactTrigger?: string;
+ toPluginToolName?: (toolName: string) => string;
+}
+
+function getSessionId(input: HookInput, context: PluginHookRuntimeContext): string {
+ return context.sessionId ?? input.threadId ?? input.runId;
+}
+
+function toClaudeCompactTrigger(trigger: string | undefined): string | undefined {
+ if (!trigger) {
+ return undefined;
+ }
+ return trigger === 'manual' ? 'manual' : 'auto';
+}
+
+function getPluginToolName(toolName: string, state: PluginHookPayloadState): string {
+ if (!state.toPluginToolName) {
+ return toolName;
+ }
+ const translated = state.toPluginToolName(toolName);
+ if (!translated?.trim()) {
+ throw new Error(`No plugin tool-name mapping is available for "${toolName}"`);
+ }
+ return translated;
+}
+
+function getMessageText(message: unknown): string | undefined {
+ if (!message || typeof message !== 'object' || !('content' in message)) {
+ return undefined;
+ }
+ const content = (message as { content?: unknown }).content;
+ if (typeof content === 'string') {
+ return content;
+ }
+ if (!Array.isArray(content)) {
+ return undefined;
+ }
+ const text = content
+ .flatMap((block) => {
+ if (typeof block === 'string') {
+ return [block];
+ }
+ if (block && typeof block === 'object' && 'text' in block && typeof block.text === 'string') {
+ return [block.text];
+ }
+ return [];
+ })
+ .join('\n');
+ return text || undefined;
+}
+
+function toPluginBatchToolCall(
+ entry: PostToolBatchEntry,
+ state: PluginHookPayloadState,
+): PluginHookBatchToolCall {
+ const toolResponse = entry.status === 'success' ? entry.toolOutput : entry.error;
+ return {
+ tool_name: getPluginToolName(entry.toolName, state),
+ tool_input: entry.toolInput,
+ tool_use_id: entry.toolUseId,
+ ...(toolResponse !== undefined && { tool_response: toolResponse }),
+ };
+}
+
+function basePayload(
+ sourceEvent: string,
+ input: HookInput,
+ context: PluginHookRuntimeContext,
+): PluginHookPayload {
+ const sessionId = getSessionId(input, context);
+ return {
+ hook_event_name: sourceEvent,
+ session_id: sessionId,
+ run_id: input.runId,
+ ...(input.threadId !== undefined && { thread_id: input.threadId }),
+ ...(context.cwd !== undefined && { cwd: context.cwd }),
+ ...(context.transcriptPath !== undefined && { transcript_path: context.transcriptPath }),
+ ...(context.permissionMode !== undefined && { permission_mode: context.permissionMode }),
+ ...(input.agentId !== undefined && { agent_id: input.agentId }),
+ ...(input.executingAgentId !== undefined && {
+ executing_agent_id: input.executingAgentId,
+ }),
+ };
+}
+
+export function createPluginHookPayload(
+ sourceEvent: string,
+ input: HookInput,
+ context: PluginHookRuntimeContext = {},
+ state: PluginHookPayloadState = {},
+): PluginHookPayload {
+ const payload = basePayload(sourceEvent, input, context);
+
+ switch (input.hook_event_name) {
+ case 'RunStart':
+ return {
+ ...payload,
+ ...(sourceEvent === 'SessionStart' && {
+ source: context.sessionStartSource ?? 'startup',
+ ...(context.model !== undefined && { model: context.model }),
+ ...(context.agentType !== undefined && { agent_type: context.agentType }),
+ }),
+ };
+ case 'UserPromptSubmit':
+ return { ...payload, prompt: input.prompt };
+ case 'PreToolUse':
+ return {
+ ...payload,
+ tool_name: getPluginToolName(input.toolName, state),
+ tool_input: input.toolInput,
+ tool_use_id: input.toolUseId,
+ };
+ case 'PostToolUse':
+ return {
+ ...payload,
+ tool_name: getPluginToolName(input.toolName, state),
+ tool_input: input.toolInput,
+ tool_use_id: input.toolUseId,
+ tool_response: input.toolOutput,
+ };
+ case 'PostToolUseFailure':
+ return {
+ ...payload,
+ tool_name: getPluginToolName(input.toolName, state),
+ tool_input: input.toolInput,
+ tool_use_id: input.toolUseId,
+ error: input.error,
+ };
+ case 'PostToolBatch':
+ return {
+ ...payload,
+ tool_calls: input.entries.map((entry) => toPluginBatchToolCall(entry, state)),
+ };
+ /** LibreChat steering seal; no Claude counterpart, so it is never mapped to a declaration. */
+ case 'PreemptBoundary':
+ return payload;
+ case 'PermissionDenied':
+ return {
+ ...payload,
+ tool_name: getPluginToolName(input.toolName, state),
+ tool_input: input.toolInput,
+ tool_use_id: input.toolUseId,
+ reason: input.reason,
+ };
+ case 'SubagentStart':
+ case 'SubagentStop':
+ return { ...payload, agent_type: input.agentType };
+ case 'Stop':
+ return { ...payload, stop_hook_active: input.stopHookActive };
+ case 'StopFailure': {
+ const lastAssistantMessage = getMessageText(input.lastAssistantMessage);
+ return {
+ ...payload,
+ error: input.error,
+ ...(lastAssistantMessage !== undefined && {
+ last_assistant_message: lastAssistantMessage,
+ }),
+ };
+ }
+ case 'PreCompact':
+ return {
+ ...payload,
+ trigger: toClaudeCompactTrigger(input.trigger),
+ messages_before_count: input.messagesBeforeCount,
+ };
+ case 'PostCompact':
+ return {
+ ...payload,
+ ...(state.compactTrigger !== undefined && {
+ trigger: toClaudeCompactTrigger(state.compactTrigger),
+ }),
+ compact_summary: input.summary,
+ messages_after_count: input.messagesAfterCount,
+ };
+ }
+}
+
+function getHookTimeoutMs(
+ sourceEvent: string,
+ handler: PluginHookHandler,
+ configuredTimeoutMs: number | undefined,
+): number | undefined {
+ if (configuredTimeoutMs !== undefined) {
+ return configuredTimeoutMs;
+ }
+ if (handler.type === 'command') {
+ return sourceEvent === 'UserPromptSubmit' ? 30_000 : 600_000;
+ }
+ if (handler.type === 'prompt') {
+ return 30_000;
+ }
+ return undefined;
+}
+
+function getHandlerIdentity(
+ sourceEvent: string,
+ handler: PluginHookHandler,
+ condition: string | undefined,
+): string {
+ const handlerProperties = Object.entries(handler)
+ .filter(([key]) => key !== 'if')
+ .sort(([left], [right]) => left.localeCompare(right));
+ return JSON.stringify([sourceEvent, condition ?? null, handlerProperties]);
+}
+
+export function registerPluginHooks(options: RegisterPluginHooksOptions): PluginHookRegistration {
+ const { pluginId, registry, document, executor, context = {} } = options;
+ const plan = planPluginHooks(document, executor.capabilities);
+ const unregisters: Array<() => void> = [];
+ const compactTriggers = new Map<string, string>();
+ const executedHandlers = new WeakMap<HookInput, Set<string>>();
+ const tracksCompactTriggers = plan.entries.some(
+ (entry) => entry.status === 'ready' && entry.targetEvent === 'PostCompact',
+ );
+ let registered = 0;
+
+ if (tracksCompactTriggers) {
+ const trackCompactTrigger: HookCallback<'PreCompact'> = (input) => {
+ compactTriggers.set(getSessionId(input, context), input.trigger);
+ return {};
+ };
+ unregisters.push(
+ registry.register('PreCompact', {
+ hooks: [trackCompactTrigger],
+ internal: true,
+ }),
+ );
+ }
+
+ for (const entry of plan.entries) {
+ if (entry.status !== 'ready' || entry.targetEvent === undefined) {
+ continue;
+ }
+ const targetEvent = entry.targetEvent;
+ const handlerIdentity = getHandlerIdentity(entry.sourceEvent, entry.handler, entry.condition);
+ const seenSessionIds = entry.sourceEvent === 'SessionStart' ? new Set<string>() : undefined;
+ const firedSessionIds = entry.handler.once === true ? new Set<string>() : undefined;
+ const toolNameTranslator = executor.capabilities.toPluginToolName;
+ const toPluginToolName =
+ toolNameTranslator === undefined
+ ? undefined
+ : (toolName: string): string =>
+ toolNameTranslator({
+ sourceEvent: entry.sourceEvent,
+ targetEvent,
+ toolName,
+ });
+ const hook: HookCallback<HookEvent> = (input, signal) => {
+ const sessionId = getSessionId(input, context);
+ const compactTrigger = compactTriggers.get(sessionId);
+ if (entry.sourceEvent === 'SessionStart') {
+ const source = context.sessionStartSource ?? 'startup';
+ if (
+ source === 'compact' ||
+ !matchesQuery(entry.matcher, source) ||
+ seenSessionIds?.has(sessionId) === true
+ ) {
+ return {};
+ }
+ seenSessionIds?.add(sessionId);
+ }
+ if (
+ targetEvent === 'PreCompact' &&
+ input.hook_event_name === 'PreCompact' &&
+ !matchesQuery(entry.matcher, input.trigger)
+ ) {
+ return {};
+ }
+ if (
+ targetEvent === 'PostCompact' &&
+ input.hook_event_name === 'PostCompact' &&
+ (compactTrigger === undefined || !matchesQuery(entry.matcher, compactTrigger))
+ ) {
+ return {};
+ }
+ if (
+ targetEvent === 'StopFailure' &&
+ input.hook_event_name === 'StopFailure' &&
+ !matchesQuery(entry.matcher, input.error)
+ ) {
+ return {};
+ }
+ if (entry.condition !== undefined) {
+ const matchCondition = executor.capabilities.matchCondition;
+ if (!matchCondition || !('toolName' in input) || !('toolInput' in input)) {
+ return {};
+ }
+ let matchesCondition = false;
+ try {
+ matchesCondition = matchCondition({
+ sourceEvent: entry.sourceEvent,
+ targetEvent,
+ condition: entry.condition,
+ toolName: getPluginToolName(input.toolName, { toPluginToolName }),
+ toolInput: input.toolInput,
+ });
+ } catch {
+ return {};
+ }
+ if (!matchesCondition) {
+ return {};
+ }
+ }
+ if (firedSessionIds?.has(sessionId) === true) {
+ return {};
+ }
+ const handlersForInput = executedHandlers.get(input);
+ if (handlersForInput?.has(handlerIdentity) === true) {
+ firedSessionIds?.add(sessionId);
+ return {};
+ }
+ if (handlersForInput) {
+ handlersForInput.add(handlerIdentity);
+ } else {
+ executedHandlers.set(input, new Set([handlerIdentity]));
+ }
+ firedSessionIds?.add(sessionId);
+ return executor.execute(
+ {
+ pluginId,
+ sourceEvent: entry.sourceEvent,
+ targetEvent,
+ handler: entry.handler,
+ ...(entry.condition !== undefined && { condition: entry.condition }),
+ input,
+ payload: createPluginHookPayload(entry.sourceEvent, input, context, {
+ compactTrigger,
+ toPluginToolName,
+ }),
+ },
+ signal,
+ );
+ };
+ const runtimeFiltered =
+ entry.sourceEvent === 'SessionStart' ||
+ targetEvent === 'PreCompact' ||
+ targetEvent === 'PostCompact' ||
+ targetEvent === 'StopFailure';
+ const timeoutMs = getHookTimeoutMs(entry.sourceEvent, entry.handler, entry.timeoutMs);
+ const matcher: HookMatcher<HookEvent> = {
+ hooks: [hook],
+ ...(!runtimeFiltered && entry.matcher !== undefined && { pattern: entry.matcher }),
+ ...(timeoutMs !== undefined && { timeout: timeoutMs }),
+ };
+ unregisters.push(registry.register(targetEvent, matcher));
+ registered++;
+ }
+
+ if (tracksCompactTriggers) {
+ const clearCompactTrigger: HookCallback<'PostCompact'> = (input) => {
+ compactTriggers.delete(getSessionId(input, context));
+ return {};
+ };
+ unregisters.push(
+ registry.register('PostCompact', {
+ hooks: [clearCompactTrigger],
+ internal: true,
+ }),
+ );
+ }
+
+ let active = true;
+ return {
+ plan,
+ registered,
+ unregister: () => {
+ if (!active) {
+ return;
+ }
+ active = false;
+ compactTriggers.clear();
+ for (let index = unregisters.length - 1; index >= 0; index--) {
+ unregisters[index]();
+ }
+ },
+ };
+}
diff --git a/packages/api/src/agents/hooks/schema.spec.ts b/packages/api/src/agents/hooks/schema.spec.ts
new file mode 100644
index 0000000000..f23ef37a9c
--- /dev/null
+++ b/packages/api/src/agents/hooks/schema.spec.ts
@@ -0,0 +1,301 @@
+import { MAX_PATTERN_LENGTH } from '@librechat/agents';
+import { parsePluginHooks } from './schema';
+
+describe('parsePluginHooks', () => {
+ test('parses the plugin hooks wrapper used by Claude and Codex', () => {
+ const result = parsePluginHooks({
+ description: 'Guard file writes',
+ hooks: {
+ PreToolUse: [
+ {
+ matcher: 'Write|Edit',
+ hooks: [
+ {
+ type: 'command',
+ command: 'python3 "${CLAUDE_PLUGIN_ROOT}/hooks/check.py"',
+ timeout: 10,
+ },
+ ],
+ },
+ ],
+ },
+ });
+
+ expect(result.success).toBe(true);
+ if (!result.success) {
+ return;
+ }
+ expect(result.document.hooks.PreToolUse[0].hooks[0]).toEqual({
+ type: 'command',
+ command: 'python3 "${CLAUDE_PLUGIN_ROOT}/hooks/check.py"',
+ timeout: 10,
+ });
+ });
+
+ test('rejects a direct settings-style event map without the plugin wrapper', () => {
+ const result = parsePluginHooks({
+ PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: 'check' }] }],
+ });
+
+ expect(result.success).toBe(false);
+ if (result.success) {
+ return;
+ }
+ expect(result.issues).toEqual(
+ expect.arrayContaining([expect.objectContaining({ path: 'hooks' })]),
+ );
+ });
+
+ test('rejects command handlers without a command', () => {
+ const result = parsePluginHooks({
+ hooks: {
+ Stop: [{ hooks: [{ type: 'command' }] }],
+ },
+ });
+
+ expect(result.success).toBe(false);
+ if (result.success) {
+ return;
+ }
+ expect(result.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: 'hooks.Stop.0.hooks.0.command',
+ message: 'Command hooks require a non-empty command',
+ }),
+ ]),
+ );
+ });
+
+ test('rejects prompt handlers without a prompt', () => {
+ const result = parsePluginHooks({
+ hooks: {
+ Stop: [{ hooks: [{ type: 'prompt' }] }],
+ },
+ });
+
+ expect(result.success).toBe(false);
+ if (result.success) {
+ return;
+ }
+ expect(result.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: 'hooks.Stop.0.hooks.0.prompt',
+ message: 'Prompt hooks require a non-empty prompt',
+ }),
+ ]),
+ );
+ });
+
+ test('retains compatibility modifiers needed by the planner', () => {
+ const result = parsePluginHooks({
+ hooks: {
+ PostToolUse: [
+ {
+ matcher: ' Bash ',
+ hooks: [
+ {
+ type: 'command',
+ command: 'review',
+ if: ' Bash(git commit:*) ',
+ asyncRewake: true,
+ rewakeMessage: 'Review these findings',
+ rewakeSummary: 'Review complete',
+ continueOnBlock: true,
+ },
+ ],
+ },
+ ],
+ },
+ });
+
+ expect(result.success).toBe(true);
+ if (!result.success) {
+ return;
+ }
+ expect(result.document.hooks.PostToolUse[0]).toEqual({
+ matcher: 'Bash',
+ hooks: [
+ {
+ type: 'command',
+ command: 'review',
+ if: 'Bash(git commit:*)',
+ asyncRewake: true,
+ rewakeMessage: 'Review these findings',
+ rewakeSummary: 'Review complete',
+ continueOnBlock: true,
+ },
+ ],
+ });
+ });
+
+ test('retains official command and prompt handler options', () => {
+ const result = parsePluginHooks({
+ hooks: {
+ Stop: [
+ {
+ hooks: [
+ {
+ type: 'command',
+ command: 'verify',
+ args: ['--mode', 'strict'],
+ shell: 'bash',
+ once: true,
+ },
+ {
+ type: 'prompt',
+ prompt: 'Check whether the task is complete',
+ model: 'claude-sonnet-4-5',
+ },
+ ],
+ },
+ ],
+ },
+ });
+
+ expect(result.success).toBe(true);
+ if (!result.success) {
+ return;
+ }
+ expect(result.document.hooks.Stop[0].hooks).toEqual([
+ {
+ type: 'command',
+ command: 'verify',
+ args: ['--mode', 'strict'],
+ shell: 'bash',
+ once: true,
+ },
+ {
+ type: 'prompt',
+ prompt: 'Check whether the task is complete',
+ model: 'claude-sonnet-4-5',
+ },
+ ]);
+ });
+
+ test('retains schema metadata and known handlers for compatibility planning', () => {
+ const result = parsePluginHooks({
+ $schema: 'https://json.schemastore.org/claude-code-settings.json',
+ hooks: {
+ PreToolUse: [
+ {
+ matcher: 'Bash',
+ hooks: [
+ {
+ type: 'command',
+ command: 'verify',
+ },
+ {
+ type: 'http',
+ url: 'https://hooks.example.com/pre-tool',
+ headers: { Authorization: 'Bearer ${HOOK_TOKEN}' },
+ allowedEnvVars: ['HOOK_TOKEN'],
+ },
+ {
+ type: 'mcp_tool',
+ server: 'policy',
+ tool: 'validate',
+ input: { strict: true },
+ },
+ {
+ type: 'agent',
+ prompt: 'Review this tool call',
+ model: 'claude-sonnet-4-5',
+ },
+ ],
+ },
+ ],
+ },
+ });
+
+ expect(result.success).toBe(true);
+ if (!result.success) {
+ return;
+ }
+ expect(result.document.$schema).toBe('https://json.schemastore.org/claude-code-settings.json');
+ expect(result.document.hooks.PreToolUse[0].hooks).toEqual([
+ {
+ type: 'command',
+ command: 'verify',
+ },
+ {
+ type: 'http',
+ url: 'https://hooks.example.com/pre-tool',
+ headers: { Authorization: 'Bearer ${HOOK_TOKEN}' },
+ allowedEnvVars: ['HOOK_TOKEN'],
+ },
+ {
+ type: 'mcp_tool',
+ server: 'policy',
+ tool: 'validate',
+ input: { strict: true },
+ },
+ {
+ type: 'agent',
+ prompt: 'Review this tool call',
+ model: 'claude-sonnet-4-5',
+ },
+ ]);
+ });
+
+ test('rejects blank conditions and oversized matchers', () => {
+ const blankCondition = parsePluginHooks({
+ hooks: {
+ PostToolUse: [
+ {
+ matcher: 'Bash',
+ hooks: [{ type: 'command', command: 'review', if: ' ' }],
+ },
+ ],
+ },
+ });
+ const oversizedMatcher = parsePluginHooks({
+ hooks: {
+ PostToolUse: [
+ {
+ matcher: 'a'.repeat(MAX_PATTERN_LENGTH + 1),
+ hooks: [{ type: 'command', command: 'review' }],
+ },
+ ],
+ },
+ });
+
+ expect(blankCondition.success).toBe(false);
+ expect(oversizedMatcher.success).toBe(false);
+ if (blankCondition.success || oversizedMatcher.success) {
+ return;
+ }
+ expect(blankCondition.issues).toEqual(
+ expect.arrayContaining([expect.objectContaining({ path: 'hooks.PostToolUse.0.hooks.0.if' })]),
+ );
+ expect(oversizedMatcher.issues).toEqual(
+ expect.arrayContaining([expect.objectContaining({ path: 'hooks.PostToolUse.0.matcher' })]),
+ );
+ });
+
+ test('rejects unrecognized behavior instead of silently stripping it', () => {
+ const result = parsePluginHooks({
+ hooks: {
+ Stop: [
+ {
+ hooks: [{ type: 'command', command: 'verify', futureMode: 'detached' }],
+ },
+ ],
+ },
+ });
+
+ expect(result.success).toBe(false);
+ if (result.success) {
+ return;
+ }
+ expect(result.issues).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ path: 'hooks.Stop.0.hooks.0',
+ message: expect.stringContaining('futureMode'),
+ }),
+ ]),
+ );
+ });
+});
diff --git a/packages/api/src/agents/hooks/schema.ts b/packages/api/src/agents/hooks/schema.ts
new file mode 100644
index 0000000000..e5882a9c12
--- /dev/null
+++ b/packages/api/src/agents/hooks/schema.ts
@@ -0,0 +1,199 @@
+import { z } from 'zod';
+import { MAX_PATTERN_LENGTH } from '@librechat/agents';
+
+const MAX_DESCRIPTION_LENGTH = 2_000;
+const MAX_COMMAND_LENGTH = 32_768;
+const MAX_HANDLER_TYPE_LENGTH = 64;
+const MAX_STATUS_MESSAGE_LENGTH = 500;
+const MAX_EVENT_NAME_LENGTH = 80;
+const MAX_GROUPS_PER_EVENT = 128;
+const MAX_HANDLERS_PER_GROUP = 32;
+const MAX_TOTAL_HANDLERS = 512;
+const MAX_TIMEOUT_SECONDS = 3_600;
+const MAX_COMMAND_ARGS = 256;
+const MAX_HTTP_HEADERS = 256;
+
+export interface PluginHookHandler {
+ type: string;
+ command?: string;
+ commandWindows?: string;
+ args?: string[];
+ shell?: 'bash' | 'powershell';
+ url?: string;
+ headers?: Record<string, string>;
+ allowedEnvVars?: string[];
+ server?: string;
+ tool?: string;
+ input?: Record<string, unknown>;
+ prompt?: string;
+ model?: string;
+ timeout?: number;
+ statusMessage?: string;
+ if?: string;
+ once?: boolean;
+ continueOnBlock?: boolean;
+ async?: boolean;
+ asyncRewake?: boolean;
+ rewakeMessage?: string;
+ rewakeSummary?: string;
+}
+
+export interface PluginHookGroup {
+ matcher?: string;
+ if?: string;
+ hooks: PluginHookHandler[];
+}
+
+export interface PluginHooksDocument {
+ $schema?: string;
+ description?: string;
+ hooks: Record<string, PluginHookGroup[]>;
+}
+
+export const pluginHookHandlerSchema: z.ZodType<PluginHookHandler> = z
+ .object({
+ type: z.string().trim().min(1).max(MAX_HANDLER_TYPE_LENGTH),
+ command: z.string().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ commandWindows: z.string().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ args: z.array(z.string().max(MAX_COMMAND_LENGTH)).max(MAX_COMMAND_ARGS).optional(),
+ shell: z.enum(['bash', 'powershell']).optional(),
+ url: z.string().trim().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ headers: z
+ .record(
+ z.string().trim().min(1).max(MAX_STATUS_MESSAGE_LENGTH),
+ z.string().max(MAX_COMMAND_LENGTH),
+ )
+ .refine((headers) => Object.keys(headers).length <= MAX_HTTP_HEADERS, {
+ message: `HTTP hooks may declare at most ${MAX_HTTP_HEADERS} headers`,
+ })
+ .optional(),
+ allowedEnvVars: z
+ .array(z.string().trim().min(1).max(MAX_STATUS_MESSAGE_LENGTH))
+ .max(MAX_COMMAND_ARGS)
+ .optional(),
+ server: z.string().trim().min(1).max(MAX_STATUS_MESSAGE_LENGTH).optional(),
+ tool: z.string().trim().min(1).max(MAX_STATUS_MESSAGE_LENGTH).optional(),
+ input: z.record(z.string(), z.unknown()).optional(),
+ prompt: z.string().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ model: z.string().trim().min(1).max(MAX_STATUS_MESSAGE_LENGTH).optional(),
+ timeout: z.number().int().positive().max(MAX_TIMEOUT_SECONDS).optional(),
+ statusMessage: z.string().max(MAX_STATUS_MESSAGE_LENGTH).optional(),
+ if: z.string().trim().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ once: z.boolean().optional(),
+ continueOnBlock: z.boolean().optional(),
+ async: z.boolean().optional(),
+ asyncRewake: z.boolean().optional(),
+ rewakeMessage: z.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+ rewakeSummary: z.string().max(MAX_STATUS_MESSAGE_LENGTH).optional(),
+ })
+ .strict()
+ .superRefine((handler, context) => {
+ if (handler.type === 'command' && !handler.command?.trim()) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['command'],
+ message: 'Command hooks require a non-empty command',
+ });
+ }
+ if (handler.type === 'prompt' && !handler.prompt?.trim()) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['prompt'],
+ message: 'Prompt hooks require a non-empty prompt',
+ });
+ }
+ if (handler.type === 'agent' && !handler.prompt?.trim()) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['prompt'],
+ message: 'Agent hooks require a non-empty prompt',
+ });
+ }
+ if (handler.type === 'http' && !handler.url) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['url'],
+ message: 'HTTP hooks require a non-empty URL',
+ });
+ }
+ if (handler.type === 'mcp_tool' && !handler.server) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['server'],
+ message: 'MCP tool hooks require a non-empty server',
+ });
+ }
+ if (handler.type === 'mcp_tool' && !handler.tool) {
+ context.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['tool'],
+ message: 'MCP tool hooks require a non-empty tool',
+ });
+ }
+ });
+
+export const pluginHookGroupSchema: z.ZodType<PluginHookGroup> = z
+ .object({
+ matcher: z.string().trim().max(MAX_PATTERN_LENGTH).optional(),
+ /** Retained for older hook bundles; current Claude plugins declare `if` per handler. */
+ if: z.string().trim().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ hooks: z.array(pluginHookHandlerSchema).min(1).max(MAX_HANDLERS_PER_GROUP),
+ })
+ .strict();
+
+const pluginHookEventsSchema = z.record(
+ z.string().trim().min(1).max(MAX_EVENT_NAME_LENGTH),
+ z.array(pluginHookGroupSchema).min(1).max(MAX_GROUPS_PER_EVENT),
+);
+
+export const pluginHooksDocumentSchema: z.ZodType<PluginHooksDocument> = z
+ .object({
+ $schema: z.string().trim().min(1).max(MAX_COMMAND_LENGTH).optional(),
+ description: z.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+ hooks: pluginHookEventsSchema,
+ })
+ .strict()
+ .superRefine((document, context) => {
+ let total = 0;
+ for (const groups of Object.values(document.hooks)) {
+ for (const group of groups) {
+ total += group.hooks.length;
+ if (total <= MAX_TOTAL_HANDLERS) {
+ continue;
+ }
+ context.addIssue({
+ code: z.ZodIssueCode.too_big,
+ type: 'array',
+ maximum: MAX_TOTAL_HANDLERS,
+ inclusive: true,
+ path: ['hooks'],
+ message: `Hook documents may declare at most ${MAX_TOTAL_HANDLERS} handlers`,
+ });
+ return;
+ }
+ }
+ });
+
+export interface PluginHookValidationIssue {
+ path: string;
+ message: string;
+}
+
+export type PluginHooksParseResult =
+ | { success: true; document: PluginHooksDocument }
+ | { success: false; issues: PluginHookValidationIssue[] };
+
+/** Parse Claude's plugin-specific `{"hooks": {...}}` wrapper. */
+export function parsePluginHooks(input: unknown): PluginHooksParseResult {
+ const parsed = pluginHooksDocumentSchema.safeParse(input);
+ if (parsed.success) {
+ return { success: true, document: parsed.data };
+ }
+ return {
+ success: false,
+ issues: parsed.error.issues.map((issue) => ({
+ path: issue.path.join('.'),
+ message: issue.message,
+ })),
+ };
+}
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts
index 46da9f2a8e..2074539372 100644
--- a/packages/api/src/agents/index.ts
+++ b/packages/api/src/agents/index.ts
@@ -38,6 +38,7 @@ export * from './validation';
export * from './added';
export * from './load';
export * from './hitl';
+export * from './hooks';
export * from './steering';
export * from './activityLabels';
export * from './toolValidation';