feat(runtime): add trusted PreToolUse policy hooks

packages/core/package.json

@@ -96,6 +96,7 @@
     "./result": "./dist/result.js",
     "./settings": "./dist/settings.js",
     "./mcp": "./dist/mcp.js",
+    "./hooks": "./dist/hooks.js",
     "./settings/network-settings": "./dist/settings/network-settings.js",
     "./usage-stats/types": "./dist/usage-stats/types.js",
     "./usage-stats/pricing": "./dist/usage-stats/pricing.js",

packages/core/src/hooks.ts

@@ -0,0 +1,90 @@
+export const HOOK_CONFIG_VERSION = 1 as const;
+export const HOOK_TRUST_VERSION = 1 as const;
+export const PRE_TOOL_USE_HOOK_EVENT = 'PreToolUse' as const;
+
+export type HookEventName = typeof PRE_TOOL_USE_HOOK_EVENT;
+export type HookSource = 'user' | 'project';
+
+export interface HookCommandConfig {
+  id: string;
+  type: 'command';
+  command: string;
+  args?: string[];
+  timeoutMs?: number;
+  enabled?: boolean;
+}
+
+export interface HookMatcherGroupConfig {
+  matcher?: string;
+  hooks: HookCommandConfig[];
+}
+
+export interface HookConfigFile {
+  version: typeof HOOK_CONFIG_VERSION;
+  hooks: {
+    PreToolUse?: HookMatcherGroupConfig[];
+  };
+}
+
+export interface HookTrustRecord {
+  definitionHash: `sha256:${string}`;
+  source: HookSource;
+  projectIdentity: string;
+  trustedAt: number;
+}
+
+export interface HookTrustFile {
+  version: typeof HOOK_TRUST_VERSION;
+  trustedDefinitions: HookTrustRecord[];
+}
+
+export interface ResolvedHookDefinition {
+  id: string;
+  eventName: HookEventName;
+  matcher: string;
+  command: string;
+  args: string[];
+  timeoutMs: number;
+  source: HookSource;
+  sourceOrder: number;
+  definitionOrder: number;
+  projectIdentity: string;
+  definitionHash: `sha256:${string}`;
+  trusted: boolean;
+}
+
+export interface PreToolUseHookInput {
+  schema_version: 1;
+  hook_event_name: HookEventName;
+  session_id: string;
+  turn_id: string;
+  run_id: string;
+  tool_use_id: string;
+  tool_name: string;
+  tool_input: unknown;
+  cwd: string;
+  permission_mode: string;
+  origin: 'provider' | 'code_mode';
+}
+
+export type HookExecutionStatus = 'allowed' | 'denied' | 'failed' | 'skipped_untrusted';
+
+export interface HookCompletedAudit {
+  eventName: HookEventName;
+  handlerId: string;
+  definitionHash: `sha256:${string}`;
+  source: HookSource;
+  toolUseId: string;
+  toolName: string;
+  status: HookExecutionStatus;
+  durationMs: number;
+  message?: string;
+}
+
+export function createDefaultHookConfig(): HookConfigFile {
+  return { version: HOOK_CONFIG_VERSION, hooks: {} };
+}
+
+export function createDefaultHookTrust(): HookTrustFile {
+  return { version: HOOK_TRUST_VERSION, trustedDefinitions: [] };
+}

packages/core/src/runtime-event.ts

@@ -23,6 +23,7 @@ import {
 import { INTERACTION_ID_MAX_BYTES, INTERACTION_TOOL_NAME_MAX_BYTES } from './interaction.js';
 import type { PermissionRequestPayload, PermissionResponse } from './permission.js';
 import type { TurnOrigin } from './runtime-inputs.js';
+import type { HookExecutionStatus, HookSource } from './hooks.js';
 import type { UserQuestionRequest } from './user-question.js';
 import {
   defineObjectShape,
@@ -241,6 +242,18 @@ export interface RuntimeEventProtocolMarker {
   toolBoundary: ToolBoundaryProtocol;
 }
 
+export interface RuntimeEventHookCompleted {
+  eventName: 'PreToolUse';
+  handlerId: string;
+  definitionHash: `sha256:${string}`;
+  source: HookSource;
+  toolUseId: string;
+  toolName: string;
+  status: HookExecutionStatus;
+  durationMs: number;
+  message?: string;
+}
+
 export interface RuntimeEventContinuationStartV2 {
   protocol: 'continuation_start_v2';
   /** Mirrors store-owned claim state; recovery never trusts this field alone. */
@@ -308,6 +321,8 @@ export interface RuntimeEventActions {
   toolRecovery?: ToolRecoveryFactEnvelope;
   /** Protocols that were actually active from the first event of this run. */
   runtimeProtocol?: RuntimeEventProtocolMarker;
+  /** Bounded, non-model-visible result of one user-configured lifecycle Hook. */
+  hookCompleted?: RuntimeEventHookCompleted;
   /** Durable provider-call T1 for a claimed continuation. */
   continuationStart?: RuntimeEventContinuationStartV2;
   /** Reserved workspace authority fact; only its atomic SQLite writer may persist it. */
@@ -497,6 +512,7 @@ const RUNTIME_ACTIONS_SHAPE = defineObjectShape<RuntimeEventActions>()(
     'toolDispatch',
     'toolRecovery',
     'runtimeProtocol',
+    'hookCompleted',
     'continuationStart',
     'workspaceFact',
   ],
@@ -527,6 +543,19 @@ const RUNTIME_PROTOCOL_MARKER_SHAPE = defineObjectShape<RuntimeEventProtocolMark
   ['toolBoundary'],
   [],
 );
+const RUNTIME_HOOK_COMPLETED_SHAPE = defineObjectShape<RuntimeEventHookCompleted>()(
+  [
+    'eventName',
+    'handlerId',
+    'definitionHash',
+    'source',
+    'toolUseId',
+    'toolName',
+    'status',
+    'durationMs',
+  ],
+  ['message'],
+);
 const RUNTIME_CONTINUATION_START_SHAPE = defineObjectShape<RuntimeEventContinuationStartV2>()(
   [
     'protocol',
@@ -741,12 +770,37 @@ function isRuntimeEventActions(value: unknown): value is RuntimeEventActions {
     (value.toolDispatch === undefined || isRuntimeToolDispatch(value.toolDispatch)) &&
     (value.toolRecovery === undefined || isToolRecoveryFactEnvelope(value.toolRecovery)) &&
     (value.runtimeProtocol === undefined || isRuntimeProtocolMarker(value.runtimeProtocol)) &&
+    (value.hookCompleted === undefined || isRuntimeHookCompleted(value.hookCompleted)) &&
     (value.continuationStart === undefined ||
       isRuntimeContinuationStart(value.continuationStart)) &&
     (value.workspaceFact === undefined || isRuntimeEventWorkspaceFactEnvelope(value.workspaceFact))
   );
 }
 
+function isRuntimeHookCompleted(value: unknown): value is RuntimeEventHookCompleted {
+  return (
+    isRecord(value) &&
+    hasExactShape(value, RUNTIME_HOOK_COMPLETED_SHAPE) &&
+    value.eventName === 'PreToolUse' &&
+    typeof value.handlerId === 'string' &&
+    value.handlerId.length > 0 &&
+    typeof value.definitionHash === 'string' &&
+    /^sha256:[0-9a-f]{64}$/u.test(value.definitionHash) &&
+    (value.source === 'user' || value.source === 'project') &&
+    typeof value.toolUseId === 'string' &&
+    value.toolUseId.length > 0 &&
+    typeof value.toolName === 'string' &&
+    value.toolName.length > 0 &&
+    (value.status === 'allowed' ||
+      value.status === 'denied' ||
+      value.status === 'failed' ||
+      value.status === 'skipped_untrusted') &&
+    isFiniteNumber(value.durationMs) &&
+    value.durationMs >= 0 &&
+    isOptionalString(value.message)
+  );
+}
+
 function isRuntimeEventPermissionDecision(value: unknown): value is RuntimeEventPermissionDecision {
   return (
     isRecord(value) &&