@s_s/agent-kit 1.0.0

package/build/hook-capabilities.js

@@ -0,0 +1,191 @@
+const S = { level: 'supported' };
+const U = (note) => ({ level: 'unsupported', note });
+const P = (note) => ({ level: 'partial', note });
+/**
+ * The capability matrix: intent sub-capability × agent → support level.
+ *
+ * This is the single source of truth for what each agent can and cannot do
+ * with each intent type. Used by installHooks() to generate precise warnings.
+ */
+export const CAPABILITY_MATRIX = {
+    'claude-code': {
+        inject: {
+            perTurn: S,
+            sessionStart: S,
+            compaction: S,
+            sessionEnd: S,
+        },
+        beforeToolCall: {
+            intercept: S,
+            block: S,
+            modifyArgs: S,
+            matcher: S,
+        },
+        afterToolCall: {
+            observe: S,
+            matcher: S,
+        },
+        onSession: {
+            start: S,
+            end: S,
+        },
+        onPermission: {
+            decide: S,
+            matcher: S,
+        },
+    },
+    codex: {
+        inject: {
+            perTurn: S,
+            sessionStart: S,
+            compaction: S,
+            sessionEnd: S,
+        },
+        beforeToolCall: {
+            intercept: S,
+            block: S,
+            modifyArgs: S,
+            matcher: S,
+        },
+        afterToolCall: {
+            observe: S,
+            matcher: S,
+        },
+        onSession: {
+            start: S,
+            end: S,
+        },
+        onPermission: {
+            decide: S,
+            matcher: S,
+        },
+    },
+    opencode: {
+        inject: {
+            perTurn: S,
+            sessionStart: S,
+            compaction: P('Relies on experimental.session.compacting which is marked experimental and may change.'),
+            sessionEnd: U('OpenCode has no session end hook. The event hook does not emit session.end.'),
+        },
+        beforeToolCall: {
+            intercept: S,
+            block: P("OpenCode's tool.execute.before has no explicit block mechanism. " +
+                'Blocking is simulated by clearing tool arguments, which may produce inconsistent behavior.'),
+            modifyArgs: S,
+            matcher: U('OpenCode hooks do not support regex matchers. All tool calls are received; filtering is done in handler code.'),
+        },
+        afterToolCall: {
+            observe: S,
+            matcher: U('OpenCode hooks do not support regex matchers. All tool calls are received; filtering is done in handler code.'),
+        },
+        onSession: {
+            start: P('OpenCode session start is detected via event hook filtering, not a dedicated hook.'),
+            end: U('OpenCode has no session end hook.'),
+        },
+        onPermission: {
+            decide: S,
+            matcher: U('OpenCode permission.ask does not support regex matchers.'),
+        },
+    },
+    openclaw: {
+        inject: {
+            perTurn: S,
+            sessionStart: S,
+            compaction: S,
+            sessionEnd: P('OpenClaw session_end is a void plugin hook; content injection may not reach the agent context.'),
+        },
+        beforeToolCall: {
+            intercept: S,
+            block: S,
+            modifyArgs: S,
+            matcher: U('OpenClaw before_tool_call does not support regex matchers. All tool calls are received.'),
+        },
+        afterToolCall: {
+            observe: S,
+            matcher: U('OpenClaw after_tool_call does not support regex matchers. All tool calls are received.'),
+        },
+        onSession: {
+            start: S,
+            end: S,
+        },
+        onPermission: {
+            decide: U('OpenClaw has no dedicated permission hook. Use hooks.raw() with before_tool_call as a workaround.'),
+            matcher: U('OpenClaw has no dedicated permission hook.'),
+        },
+    },
+};
+/**
+ * Check all sub-capabilities for a given intent type on a given agent.
+ * Returns warnings for any partial or unsupported sub-capabilities.
+ *
+ * Only checks sub-capabilities that the intent actually uses.
+ * For example, if an inject intent has no `compaction` field, the compaction
+ * capability is not checked.
+ */
+export function checkDegradation(agent, intentType, usedCapabilities) {
+    const caps = CAPABILITY_MATRIX[agent][intentType];
+    const warnings = [];
+    const entries = Object.entries(caps);
+    for (const [capName, entry] of entries) {
+        // If usedCapabilities is specified, only check those
+        if (usedCapabilities && !usedCapabilities.includes(capName))
+            continue;
+        if (entry.level !== 'supported') {
+            warnings.push({
+                agent,
+                intent: intentType,
+                capability: capName,
+                level: entry.level,
+                message: `[${agent}] ${intentType}.${capName}: ${entry.note ?? `${entry.level} — no details available.`}`,
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Check degradation for all registered intents on a specific agent.
+ * Analyzes which sub-capabilities each intent actually uses and only
+ * warns about those.
+ */
+export function checkAllDegradation(agent, intentTypes) {
+    const warnings = [];
+    const seen = new Set();
+    for (const intentType of intentTypes) {
+        const intentWarnings = checkDegradation(agent, intentType);
+        for (const w of intentWarnings) {
+            const key = `${w.agent}::${w.intent}::${w.capability}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                warnings.push(w);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Check if a specific intent type is fully unsupported on an agent.
+ * Returns true only if ALL sub-capabilities are unsupported.
+ */
+export function isIntentFullyUnsupported(agent, intentType) {
+    const caps = CAPABILITY_MATRIX[agent][intentType];
+    return Object.values(caps).every((entry) => entry.level === 'unsupported');
+}
+/**
+ * Detect conflicts between intent-generated hooks and raw hooks.
+ *
+ * @param agent - The target agent.
+ * @param intentNativeHooks - Set of native hook names generated by intents.
+ * @param rawNativeHooks - Set of native hook names registered via hooks.raw().
+ * @returns Warning messages for each conflict.
+ */
+export function detectConflicts(agent, intentNativeHooks, rawNativeHooks) {
+    const warnings = [];
+    for (const hookName of intentNativeHooks) {
+        if (rawNativeHooks.has(hookName)) {
+            warnings.push(`[${agent}] Conflict: raw hook for '${hookName}' overrides intent-generated hook. ` +
+                `The raw hook will be used; intent-generated logic for this hook is discarded.`);
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=hook-capabilities.js.map

package/build/hook-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-capabilities.js","sourceRoot":"","sources":["../src/hook-capabilities.ts"],"names":[],"mappings":"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"}

package/build/hook-registry.d.ts

@@ -0,0 +1,158 @@
+import type { AgentType } from './types.js';
+import type { InjectIntent, BeforeToolCallIntent, AfterToolCallIntent, OnSessionIntent, OnPermissionIntent, HookIntent, RawHookRegistration, ExtendHookRegistration } from './hook-types.js';
+/** Get a snapshot of all registered intents. */
+export declare function getIntents(): readonly HookIntent[];
+/** Get intents filtered by type. */
+export declare function getIntentsByType<T extends HookIntent['type']>(type: T): Extract<HookIntent, {
+    type: T;
+}>[];
+/** Get the raw hook map (read-only view). */
+export declare function getRawHooks(): ReadonlyMap<string, RawHookRegistration>;
+/** Get the extend hook map (read-only view). */
+export declare function getExtendHooks(): ReadonlyMap<string, readonly ExtendHookRegistration[]>;
+/** Check if a raw hook is registered for a specific agent + native hook name. */
+export declare function hasRawHook(agent: AgentType, hookName: string): boolean;
+/** Get a raw hook registration for a specific agent + native hook name. */
+export declare function getRawHook(agent: AgentType, hookName: string): RawHookRegistration | undefined;
+/** Get extend registrations for a specific agent + native hook name. */
+export declare function getExtendHooksFor(agent: AgentType, hookName: string): readonly ExtendHookRegistration[];
+/**
+ * Register a content injection intent.
+ *
+ * Injects text into agent context at various lifecycle points.
+ * At minimum, `perTurn` is required.
+ *
+ * @example
+ * ```ts
+ * hooks.inject({
+ *     perTurn: 'Always remember: you are a helpful assistant.',
+ *     sessionStart: 'Welcome! This session uses the Foo tool.',
+ *     compaction: 'Preserve the Foo tool context.',
+ * });
+ * ```
+ */
+declare function inject(config: Omit<InjectIntent, 'type'>): void;
+/**
+ * Register a pre-tool-call interception intent.
+ *
+ * Intercept tool calls before execution — can block or modify arguments.
+ *
+ * @example
+ * ```ts
+ * hooks.beforeToolCall({
+ *     match: /^(Bash|Write)/,
+ *     handler: (ctx) => {
+ *         if (ctx.args.path?.includes('/etc/')) {
+ *             return { block: true, reason: 'Cannot modify /etc/' };
+ *         }
+ *     },
+ * });
+ * ```
+ */
+declare function beforeToolCall(config: Omit<BeforeToolCallIntent, 'type'>): void;
+/**
+ * Register a post-tool-call observation intent.
+ *
+ * Observe tool call results — cannot modify, only react.
+ *
+ * @example
+ * ```ts
+ * hooks.afterToolCall({
+ *     match: 'Bash',
+ *     handler: (ctx) => {
+ *         console.log(`Tool ${ctx.toolName} returned: ${ctx.result}`);
+ *     },
+ * });
+ * ```
+ */
+declare function afterToolCall(config: Omit<AfterToolCallIntent, 'type'>): void;
+/**
+ * Register a session lifecycle intent.
+ *
+ * React to session start and/or end.
+ *
+ * @example
+ * ```ts
+ * hooks.onSession({
+ *     start: (ctx) => console.log('Session started:', ctx.sessionId),
+ *     end: (ctx) => console.log('Session ended:', ctx.sessionId),
+ * });
+ * ```
+ */
+declare function onSession(config: Omit<OnSessionIntent, 'type'>): void;
+/**
+ * Register a permission decision intent.
+ *
+ * Intercept permission requests and decide allow/deny/ask.
+ *
+ * @example
+ * ```ts
+ * hooks.onPermission({
+ *     match: 'Bash',
+ *     handler: (ctx) => {
+ *         if (ctx.args.command?.startsWith('git ')) return 'allow';
+ *         return 'ask';
+ *     },
+ * });
+ * ```
+ */
+declare function onPermission(config: Omit<OnPermissionIntent, 'type'>): void;
+/**
+ * Register a raw native hook for a specific agent.
+ *
+ * Raw hooks bypass the intent layer entirely and write handler code directly.
+ * When a raw hook targets the same native hook as an intent-generated hook,
+ * the raw hook wins and a warning is emitted during `installHooks()`.
+ *
+ * @example
+ * ```ts
+ * hooks.raw({
+ *     agent: 'claude-code',
+ *     hookName: 'Notification',
+ *     handler: '#!/bin/bash\ncurl -X POST https://webhook.example.com',
+ * });
+ * ```
+ */
+declare function raw<A extends AgentType>(registration: RawHookRegistration<A>): void;
+/**
+ * Register an extend hook for a specific agent.
+ *
+ * Extend hooks run after the intent-generated handler for the same native hook.
+ * They cannot replace, only augment. Multiple extends for the same hook
+ * are executed in registration order.
+ *
+ * @example
+ * ```ts
+ * hooks.extend({
+ *     agent: 'opencode',
+ *     hookName: 'tool.execute.after',
+ *     handler: 'console.log("Tool execution completed");',
+ * });
+ * ```
+ */
+declare function extend<A extends AgentType>(registration: ExtendHookRegistration<A>): void;
+/**
+ * Reset all registrations. For testing only.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Hook declaration API.
+ *
+ * Use `hooks.inject()`, `hooks.beforeToolCall()`, etc. to declare intents.
+ * Use `hooks.raw()` to bypass the intent layer for a specific agent.
+ * Use `hooks.extend()` to augment intent-generated hooks for a specific agent.
+ *
+ * All registrations are stored in a module-level singleton and consumed by
+ * `installHooks()` when generating native hook files.
+ */
+export declare const hooks: {
+    readonly inject: typeof inject;
+    readonly beforeToolCall: typeof beforeToolCall;
+    readonly afterToolCall: typeof afterToolCall;
+    readonly onSession: typeof onSession;
+    readonly onPermission: typeof onPermission;
+    readonly raw: typeof raw;
+    readonly extend: typeof extend;
+    readonly _resetForTesting: typeof _resetForTesting;
+};
+export {};

package/build/hook-registry.js

@@ -0,0 +1,223 @@
+// ---------------------------------------------------------------------------
+// Internal state — module-level singleton
+// ---------------------------------------------------------------------------
+/** All registered intents (ordered by registration time). */
+let intents = [];
+/** Raw hook registrations keyed by `${agent}::${hookName}`. */
+let rawHooks = new Map();
+/** Extend hook registrations keyed by `${agent}::${hookName}` (multiple per key). */
+let extendHooks = new Map();
+// ---------------------------------------------------------------------------
+// Key helpers
+// ---------------------------------------------------------------------------
+function rawKey(agent, hookName) {
+    return `${agent}::${hookName}`;
+}
+// ---------------------------------------------------------------------------
+// Read-only accessors (for translators and installHooks)
+// ---------------------------------------------------------------------------
+/** Get a snapshot of all registered intents. */
+export function getIntents() {
+    return intents;
+}
+/** Get intents filtered by type. */
+export function getIntentsByType(type) {
+    return intents.filter((i) => i.type === type);
+}
+/** Get the raw hook map (read-only view). */
+export function getRawHooks() {
+    return rawHooks;
+}
+/** Get the extend hook map (read-only view). */
+export function getExtendHooks() {
+    return extendHooks;
+}
+/** Check if a raw hook is registered for a specific agent + native hook name. */
+export function hasRawHook(agent, hookName) {
+    return rawHooks.has(rawKey(agent, hookName));
+}
+/** Get a raw hook registration for a specific agent + native hook name. */
+export function getRawHook(agent, hookName) {
+    return rawHooks.get(rawKey(agent, hookName));
+}
+/** Get extend registrations for a specific agent + native hook name. */
+export function getExtendHooksFor(agent, hookName) {
+    return extendHooks.get(rawKey(agent, hookName)) ?? [];
+}
+// ---------------------------------------------------------------------------
+// Intent registration API
+// ---------------------------------------------------------------------------
+/**
+ * Register a content injection intent.
+ *
+ * Injects text into agent context at various lifecycle points.
+ * At minimum, `perTurn` is required.
+ *
+ * @example
+ * ```ts
+ * hooks.inject({
+ *     perTurn: 'Always remember: you are a helpful assistant.',
+ *     sessionStart: 'Welcome! This session uses the Foo tool.',
+ *     compaction: 'Preserve the Foo tool context.',
+ * });
+ * ```
+ */
+function inject(config) {
+    intents.push({ type: 'inject', ...config });
+}
+/**
+ * Register a pre-tool-call interception intent.
+ *
+ * Intercept tool calls before execution — can block or modify arguments.
+ *
+ * @example
+ * ```ts
+ * hooks.beforeToolCall({
+ *     match: /^(Bash|Write)/,
+ *     handler: (ctx) => {
+ *         if (ctx.args.path?.includes('/etc/')) {
+ *             return { block: true, reason: 'Cannot modify /etc/' };
+ *         }
+ *     },
+ * });
+ * ```
+ */
+function beforeToolCall(config) {
+    intents.push({ type: 'beforeToolCall', ...config });
+}
+/**
+ * Register a post-tool-call observation intent.
+ *
+ * Observe tool call results — cannot modify, only react.
+ *
+ * @example
+ * ```ts
+ * hooks.afterToolCall({
+ *     match: 'Bash',
+ *     handler: (ctx) => {
+ *         console.log(`Tool ${ctx.toolName} returned: ${ctx.result}`);
+ *     },
+ * });
+ * ```
+ */
+function afterToolCall(config) {
+    intents.push({ type: 'afterToolCall', ...config });
+}
+/**
+ * Register a session lifecycle intent.
+ *
+ * React to session start and/or end.
+ *
+ * @example
+ * ```ts
+ * hooks.onSession({
+ *     start: (ctx) => console.log('Session started:', ctx.sessionId),
+ *     end: (ctx) => console.log('Session ended:', ctx.sessionId),
+ * });
+ * ```
+ */
+function onSession(config) {
+    intents.push({ type: 'onSession', ...config });
+}
+/**
+ * Register a permission decision intent.
+ *
+ * Intercept permission requests and decide allow/deny/ask.
+ *
+ * @example
+ * ```ts
+ * hooks.onPermission({
+ *     match: 'Bash',
+ *     handler: (ctx) => {
+ *         if (ctx.args.command?.startsWith('git ')) return 'allow';
+ *         return 'ask';
+ *     },
+ * });
+ * ```
+ */
+function onPermission(config) {
+    intents.push({ type: 'onPermission', ...config });
+}
+// ---------------------------------------------------------------------------
+// Raw hook registration — bypass intent layer
+// ---------------------------------------------------------------------------
+/**
+ * Register a raw native hook for a specific agent.
+ *
+ * Raw hooks bypass the intent layer entirely and write handler code directly.
+ * When a raw hook targets the same native hook as an intent-generated hook,
+ * the raw hook wins and a warning is emitted during `installHooks()`.
+ *
+ * @example
+ * ```ts
+ * hooks.raw({
+ *     agent: 'claude-code',
+ *     hookName: 'Notification',
+ *     handler: '#!/bin/bash\ncurl -X POST https://webhook.example.com',
+ * });
+ * ```
+ */
+function raw(registration) {
+    const key = rawKey(registration.agent, registration.hookName);
+    rawHooks.set(key, registration);
+}
+// ---------------------------------------------------------------------------
+// Extend hook registration — augment intent-generated hooks
+// ---------------------------------------------------------------------------
+/**
+ * Register an extend hook for a specific agent.
+ *
+ * Extend hooks run after the intent-generated handler for the same native hook.
+ * They cannot replace, only augment. Multiple extends for the same hook
+ * are executed in registration order.
+ *
+ * @example
+ * ```ts
+ * hooks.extend({
+ *     agent: 'opencode',
+ *     hookName: 'tool.execute.after',
+ *     handler: 'console.log("Tool execution completed");',
+ * });
+ * ```
+ */
+function extend(registration) {
+    const key = rawKey(registration.agent, registration.hookName);
+    const existing = extendHooks.get(key) ?? [];
+    existing.push(registration);
+    extendHooks.set(key, existing);
+}
+// ---------------------------------------------------------------------------
+// Testing utilities
+// ---------------------------------------------------------------------------
+/**
+ * Reset all registrations. For testing only.
+ */
+function _resetForTesting() {
+    intents = [];
+    rawHooks = new Map();
+    extendHooks = new Map();
+}
+// ---------------------------------------------------------------------------
+// Public namespace object
+// ---------------------------------------------------------------------------
+/**
+ * Hook declaration API.
+ *
+ * Use `hooks.inject()`, `hooks.beforeToolCall()`, etc. to declare intents.
+ * Use `hooks.raw()` to bypass the intent layer for a specific agent.
+ * Use `hooks.extend()` to augment intent-generated hooks for a specific agent.
+ *
+ * All registrations are stored in a module-level singleton and consumed by
+ * `installHooks()` when generating native hook files.
+ */
+export const hooks = {
+    inject,
+    beforeToolCall,
+    afterToolCall,
+    onSession,
+    onPermission,
+    raw,
+    extend,
+    _resetForTesting,
+};
+//# sourceMappingURL=hook-registry.js.map

package/build/hook-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.js","sourceRoot":"","sources":["../src/hook-registry.ts"],"names":[],"mappings":"AAYA,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAE9E,6DAA6D;AAC7D,IAAI,OAAO,GAAiB,EAAE,CAAC;AAE/B,+DAA+D;AAC/D,IAAI,QAAQ,GAAqC,IAAI,GAAG,EAAE,CAAC;AAE3D,qFAAqF;AACrF,IAAI,WAAW,GAA0C,IAAI,GAAG,EAAE,CAAC;AAEnE,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,SAAS,MAAM,CAAC,KAAgB,EAAE,QAAgB;IAC9C,OAAO,GAAG,KAAK,KAAK,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,gDAAgD;AAChD,MAAM,UAAU,UAAU;IACtB,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,gBAAgB,CAA+B,IAAO;IAClE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAuC,CAAC;AACxF,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,WAAW;IACvB,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,cAAc;IAC1B,OAAO,WAAW,CAAC;AACvB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,QAAgB;IACzD,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,QAAgB;IACzD,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,KAAgB,EAAE,QAAgB;IAChE,OAAO,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,SAAS,MAAM,CAAC,MAAkC;IAC9C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,cAAc,CAAC,MAA0C;IAC9D,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,aAAa,CAAC,MAAyC;IAC5D,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,SAAS,CAAC,MAAqC;IACpD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,YAAY,CAAC,MAAwC;IAC1D,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,SAAS,GAAG,CAAsB,YAAoC;IAClE,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,QAAkB,CAAC,CAAC;IACxE,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,YAAmC,CAAC,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,SAAS,MAAM,CAAsB,YAAuC;IACxE,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,QAAkB,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,CAAC,YAAsC,CAAC,CAAC;IACtD,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;GAEG;AACH,SAAS,gBAAgB;IACrB,OAAO,GAAG,EAAE,CAAC;IACb,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;IACrB,WAAW,GAAG,IAAI,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACjB,MAAM;IACN,cAAc;IACd,aAAa;IACb,SAAS;IACT,YAAY;IACZ,GAAG;IACH,MAAM;IACN,gBAAgB;CACV,CAAC"}

package/build/hook-translators/claude-code.d.ts

@@ -0,0 +1,26 @@
+import type { AgentHookTranslator, TranslationResult, SettingsHookEntry } from './types.js';
+import type { HookIntent, RawHookRegistration, ExtendHookRegistration } from '../hook-types.js';
+/**
+ * Translates intent-based hooks into Claude Code / Codex native format.
+ *
+ * Claude Code uses:
+ * - Shell scripts executed as external processes
+ * - JSON input via stdin, JSON output via stdout
+ * - Exit codes for control (0 = allow, 2 = block)
+ * - settings.json for hook registration (event → matcher → handler)
+ */
+export declare class ClaudeCodeTranslator implements AgentHookTranslator {
+    private readonly agent;
+    constructor(agent?: 'claude-code' | 'codex');
+    translate(intents: readonly HookIntent[], rawHooks: ReadonlyMap<string, RawHookRegistration>, extendHooks: ReadonlyMap<string, readonly ExtendHookRegistration[]>, toolName: string): TranslationResult;
+    getSettingsEntries(hookDir: string, toolName: string): SettingsHookEntry[];
+    private mergeInjectIntents;
+    private buildInjectScript;
+    private buildSessionStartInjectScript;
+    private buildCompactionScript;
+    private buildSessionEndInjectScript;
+    private buildBeforeToolCallScript;
+    private buildAfterToolCallScript;
+    private buildOnSessionScript;
+    private buildPermissionScript;
+}