@evo-dev/core 0.0.1-alpha

package/src/hooks/index.ts

@@ -0,0 +1,1023 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  type TaskContract,
+  createTaskContract,
+  routeTaskContract,
+  writeTaskContract,
+} from "../task/index.ts";
+
+export const CANONICAL_HOOK_EVENT_TYPES = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "PostToolBatch",
+  "PermissionDenied",
+  "SubagentStart",
+  "Stop",
+  "StopFailure",
+  "TeammateIdle",
+  "SubagentStop",
+  "TaskCreated",
+  "TaskCompleted",
+  "PreCompact",
+  "PostCompact",
+  "SessionEnd",
+  "ConfigChange",
+  "CwdChanged",
+  "FileChanged",
+  "WorktreeCreate",
+  "WorktreeRemove",
+] as const;
+
+export type CanonicalHookEventType = (typeof CANONICAL_HOOK_EVENT_TYPES)[number];
+export type LegacyHookEventType = "AgentStop";
+export type HookInputEventType = CanonicalHookEventType | LegacyHookEventType;
+export type CodeAgentHookTarget = "claude" | "codex";
+export type CommandRiskClass =
+  | "read-only"
+  | "test-command"
+  | "write"
+  | "delete"
+  | "network"
+  | "publish"
+  | "credential-sensitive"
+  | "path-escaping"
+  | "unknown";
+export type HookDecisionAction = "allow" | "warn" | "ask-user" | "block";
+
+export interface HookSettings {
+  enabled: boolean;
+  targets: Record<CodeAgentHookTarget, HookTargetSettings>;
+  observability: {
+    metadataOnly: true;
+    rawPayloadStorage: false;
+    appendEvents: false;
+  };
+  learning: {
+    emitCandidates: false;
+    writeMemory: false;
+  };
+}
+
+export interface HookTargetSettings {
+  enabled: boolean;
+  events: Record<CanonicalHookEventType, boolean>;
+}
+
+export interface HookEventV1 {
+  version: 1;
+  eventId: string;
+  type: CanonicalHookEventType;
+  source: {
+    pluginId: string;
+    agent: string;
+    sessionIdHash: string | null;
+    rawPayloadStored: false;
+  };
+  time: {
+    occurredAt: string | null;
+    receivedAt: string;
+  };
+  scope: {
+    taskId: string | null;
+    projectId: string | null;
+    cwdPolicy: "metadata-only";
+    projectContextOptedIn: false;
+  };
+  payload: {
+    summary: string;
+    metadata: Record<string, string | number | boolean | string[]>;
+    redactions: string[];
+    redactionCount: number;
+    rawContentIncluded: false;
+  };
+  policy: {
+    classification: "local-private";
+    allowedUses: Array<"observability" | "safety-check" | "workflow-suggestion">;
+    learningAllowed: false;
+    externalUploadAllowed: false;
+  };
+  decision: {
+    action: HookDecisionAction;
+    reason: string;
+    requiresUserConfirmation: boolean;
+  };
+  warnings: string[];
+}
+
+export interface NormalizeHookEventInput {
+  pluginId: string;
+  agent?: string;
+  type: HookInputEventType;
+  payload: Record<string, unknown>;
+  receivedAt?: string;
+}
+
+export interface HookInstallDryRunPlan {
+  target: CodeAgentHookTarget;
+  settings: HookSettings;
+  plannedWrites: Array<{
+    action: "merge-with-backup" | "create";
+    targetPath: string;
+    reason: string;
+  }>;
+  warnings: string[];
+  blockers: string[];
+}
+
+export interface HookRuntimeSessionBinding {
+  version: 1;
+  target: CodeAgentHookTarget;
+  sessionKey: string;
+  taskId: string | null;
+  contractPath: string | null;
+  cwd: string | null;
+  route: TaskContract["route"] | null;
+  updatedAt: string;
+}
+
+export interface HookRuntimeResult {
+  target: CodeAgentHookTarget;
+  event: CanonicalHookEventType;
+  enabled: boolean;
+  output: Record<string, unknown> | null;
+  stateWrites: string[];
+  summary: string;
+}
+
+export interface HandleHookRuntimeInput {
+  target: CodeAgentHookTarget;
+  homeDir: string;
+  settings: HookSettings;
+  event: HookEventV1;
+  rawPayload: Record<string, unknown>;
+  receivedAt?: string;
+}
+
+const DEFAULT_EVENT_SETTINGS: Record<CanonicalHookEventType, boolean> = {
+  SessionStart: false,
+  UserPromptSubmit: false,
+  UserPromptExpansion: false,
+  PreToolUse: false,
+  PermissionRequest: false,
+  PostToolUse: false,
+  PostToolUseFailure: false,
+  PostToolBatch: false,
+  PermissionDenied: false,
+  SubagentStart: false,
+  Stop: false,
+  StopFailure: false,
+  TeammateIdle: false,
+  SubagentStop: false,
+  TaskCreated: false,
+  TaskCompleted: false,
+  PreCompact: false,
+  PostCompact: false,
+  SessionEnd: false,
+  ConfigChange: false,
+  CwdChanged: false,
+  FileChanged: false,
+  WorktreeCreate: false,
+  WorktreeRemove: false,
+};
+
+const SENSITIVE_TEXT_PATTERN =
+  /https?:\/\/\S+|\b(secret|token|password|passwd|private|internal|api[_-]?key|apikey|credential|credentials|\.env)\b/i;
+const SOURCE_LIKE_PATTERN = /\b(function|class|import|export|const|let|var)\b.*[{};]/s;
+
+export function createDefaultHookSettings(): HookSettings {
+  return {
+    enabled: false,
+    targets: {
+      claude: {
+        enabled: false,
+        events: { ...DEFAULT_EVENT_SETTINGS },
+      },
+      codex: {
+        enabled: false,
+        events: { ...DEFAULT_EVENT_SETTINGS },
+      },
+    },
+    observability: {
+      metadataOnly: true,
+      rawPayloadStorage: false,
+      appendEvents: false,
+    },
+    learning: {
+      emitCandidates: false,
+      writeMemory: false,
+    },
+  };
+}
+
+export function parseHookSettings(value: unknown): HookSettings {
+  const defaults = createDefaultHookSettings();
+  if (value === undefined || value === null) return defaults;
+  if (!isRecord(value)) throw new Error("Invalid hooks settings; expected object.");
+
+  return {
+    enabled: optionalBoolean(value.enabled, defaults.enabled, "hooks.enabled"),
+    targets: {
+      claude: parseHookTargetSettings(value.targets, defaults.targets.claude, "claude"),
+      codex: parseHookTargetSettings(value.targets, defaults.targets.codex, "codex"),
+    },
+    observability: {
+      metadataOnly: true,
+      rawPayloadStorage: false,
+      appendEvents: false,
+    },
+    learning: {
+      emitCandidates: false,
+      writeMemory: false,
+    },
+  };
+}
+
+export function normalizeHookEvent(input: NormalizeHookEventInput): HookEventV1 {
+  const warnings: string[] = [];
+  const type = normalizeHookEventType(input.type, warnings);
+  const redactions: string[] = [];
+  const metadata = extractMetadata(type, input.payload, redactions);
+  const commandClass =
+    typeof metadata.commandClass === "string" ? metadata.commandClass : undefined;
+  const decision = decideHookPolicy(commandClass);
+  const sessionIdHash = hashOptionalIdentifier(input.payload.session_id ?? input.payload.sessionId);
+
+  return {
+    version: 1,
+    eventId: stableEventId(input.pluginId, type, sessionIdHash),
+    type,
+    source: {
+      pluginId: sanitizeScalar(input.pluginId, redactions),
+      agent: sanitizeScalar(input.agent ?? "unknown", redactions),
+      sessionIdHash,
+      rawPayloadStored: false,
+    },
+    time: {
+      occurredAt: optionalSanitizedString(
+        input.payload.timestamp ?? input.payload.occurredAt,
+        redactions,
+      ),
+      receivedAt: input.receivedAt ?? "dry-run",
+    },
+    scope: {
+      taskId: optionalSanitizedString(input.payload.taskId, redactions),
+      projectId: optionalSanitizedString(input.payload.projectId, redactions),
+      cwdPolicy: "metadata-only",
+      projectContextOptedIn: false,
+    },
+    payload: {
+      summary: summarizeEvent(type, metadata),
+      metadata,
+      redactions,
+      redactionCount: redactions.length,
+      rawContentIncluded: false,
+    },
+    policy: {
+      classification: "local-private",
+      allowedUses: ["observability", "safety-check", "workflow-suggestion"],
+      learningAllowed: false,
+      externalUploadAllowed: false,
+    },
+    decision,
+    warnings,
+  };
+}
+
+export function classifyCommandRisk(command: string | undefined): CommandRiskClass {
+  if (command === undefined || command.trim() === "") return "unknown";
+  const lower = command.toLowerCase();
+  if (/(^|\s)(\.\.\/|\/\.\.)/.test(lower)) return "path-escaping";
+  if (/\b(npm|pnpm|yarn|bun)\s+publish\b|\bgh\s+release\b/.test(lower)) return "publish";
+  if (/\b(curl|wget|scp|rsync|ssh|ftp)\b|https?:\/\//.test(lower)) return "network";
+  if (/\b(rm|rmdir|unlink)\b|--delete\b/.test(lower)) return "delete";
+  if (/\b(secret|token|password|passwd|credential|api[_-]?key)\b|(^|\s)\.env(\s|$)/.test(lower)) {
+    return "credential-sensitive";
+  }
+  if (/\b(vim|nano|tee|touch|mkdir|mv|cp|chmod|chown)\b|>/.test(lower)) return "write";
+  if (/\b(test|lint|typecheck|check)\b/.test(lower)) return "test-command";
+  if (/\b(ls|pwd|grep|rg|find|git status|git diff|cat)\b/.test(lower)) return "read-only";
+  return "unknown";
+}
+
+export function formatHookInstallDryRun(plan: HookInstallDryRunPlan): string {
+  return [
+    "EvoDev hook install dry-run",
+    "",
+    `Target: ${plan.target}`,
+    "Mode: dry-run (no writes)",
+    `Hooks enabled by default: ${plan.settings.enabled}`,
+    "Selected events:",
+    ...CANONICAL_HOOK_EVENT_TYPES.map(
+      (eventType) => `  - ${eventType}: ${plan.settings.targets[plan.target].events[eventType]}`,
+    ),
+    "Boundaries:",
+    "  - observability: metadata-only, appendEvents=false, rawPayloadStorage=false",
+    "  - learning: emitCandidates=false, writeMemory=false",
+    "  - external upload: false",
+    "  - protected project writes: .claude/.codex/CLAUDE.md/AGENTS.md not targeted",
+    "  - backup/merge: required before any future real install; dry-run writes nothing",
+    "Planned writes:",
+    ...plan.plannedWrites.map(
+      (write) => `  - ${write.action}: ${write.targetPath} (${write.reason})`,
+    ),
+    "Warnings:",
+    ...(plan.warnings.length === 0
+      ? ["  - none"]
+      : plan.warnings.map((warning) => `  - ${warning}`)),
+    "Blockers:",
+    ...(plan.blockers.length === 0
+      ? ["  - none"]
+      : plan.blockers.map((blocker) => `  - ${blocker}`)),
+  ].join("\n");
+}
+
+export function formatHookEventDryRun(event: HookEventV1): string {
+  return [
+    "EvoDev hook event dry-run",
+    "",
+    `Type: ${event.type}`,
+    `Plugin: ${event.source.pluginId}`,
+    `Summary: ${event.payload.summary}`,
+    `Decision: ${event.decision.action} (${event.decision.reason})`,
+    "Metadata:",
+    ...Object.entries(event.payload.metadata).map(
+      ([key, value]) => `  - ${key}: ${formatMetadataValue(value)}`,
+    ),
+    "Redactions:",
+    ...(event.payload.redactions.length === 0
+      ? ["  - none"]
+      : event.payload.redactions.map((redaction) => `  - ${redaction}`)),
+    "Warnings:",
+    ...(event.warnings.length === 0
+      ? ["  - none"]
+      : event.warnings.map((warning) => `  - ${warning}`)),
+  ].join("\n");
+}
+
+export function resolveHookRuntimeSessionPaths(input: {
+  homeDir: string;
+  sessionKey: string;
+}): { sessionDir: string; bindingPath: string; contractPath: string } {
+  const sessionDir = join(input.homeDir, ".evodev", "STATE", "hooks", "sessions", input.sessionKey);
+  return {
+    sessionDir,
+    bindingPath: join(sessionDir, "binding.json"),
+    contractPath: join(sessionDir, "contract.json"),
+  };
+}
+
+export async function handleHookRuntime(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const enabled = isHookEventEnabled(input.settings, input.target, input.event.type);
+  if (!enabled) {
+    return {
+      target: input.target,
+      event: input.event.type,
+      enabled,
+      output: null,
+      stateWrites: [],
+      summary: `Hook ${input.event.type} ignored because EvoDev hooks are disabled.`,
+    };
+  }
+
+  if (input.event.type === "SessionStart") return handleSessionStart(input);
+  if (input.event.type === "UserPromptSubmit") return handleUserPromptSubmit(input);
+  if (input.event.type === "PreToolUse") return handlePreToolUse(input);
+  if (input.event.type === "PostToolUse" || input.event.type === "PostToolUseFailure") {
+    return handlePostToolUse(input);
+  }
+  if (input.event.type === "PostToolBatch") return handleAdditionalContext(input, "PostToolBatch");
+  if (
+    input.event.type === "SubagentStart" ||
+    input.event.type === "TaskCreated" ||
+    input.event.type === "PermissionRequest"
+  ) {
+    return handlePreToolUse(input);
+  }
+  if (
+    input.event.type === "Stop" ||
+    input.event.type === "SubagentStop" ||
+    input.event.type === "TaskCompleted" ||
+    input.event.type === "TeammateIdle"
+  ) {
+    return handleCompletionGate(input);
+  }
+  if (input.event.type === "PreCompact") return handlePreCompact(input);
+  if (input.event.type === "SessionEnd") return handleSessionEnd(input);
+  return handleAdditionalContext(input, input.event.type);
+}
+
+export function formatHookRuntimeOutput(result: HookRuntimeResult): string {
+  return result.output === null ? "" : `${JSON.stringify(result.output)}\n`;
+}
+
+function isHookEventEnabled(
+  settings: HookSettings,
+  target: CodeAgentHookTarget,
+  eventType: CanonicalHookEventType,
+): boolean {
+  return (
+    settings.enabled === true &&
+    settings.targets[target]?.enabled === true &&
+    settings.targets[target]?.events[eventType] === true
+  );
+}
+
+async function handleSessionStart(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const binding = await readSessionBinding(input.homeDir, input.rawPayload);
+  const context = [
+    "EvoDev session initialized.",
+    binding?.contractPath
+      ? `Active Task Contract: ${binding.contractPath}`
+      : "No active Task Contract yet.",
+    "User prompts will be routed through EvoDev before execution.",
+  ].join(" ");
+  return createRuntimeResult(input, hookOutput(input.event.type, { additionalContext: context }), {
+    summary: "Session context prepared.",
+  });
+}
+
+async function handleUserPromptSubmit(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const classification = classifyUserPrompt(input.rawPayload.prompt ?? input.rawPayload.userPrompt);
+  const sessionKey = resolveHookSessionKey(input.rawPayload);
+  const paths = resolveHookRuntimeSessionPaths({ homeDir: input.homeDir, sessionKey });
+  const contract = routeTaskContract(createHookTaskContract(input, classification));
+  const binding: HookRuntimeSessionBinding = {
+    version: 1,
+    target: input.target,
+    sessionKey,
+    taskId: contract.taskId,
+    contractPath: paths.contractPath,
+    cwd: optionalPayloadString(input.rawPayload.cwd),
+    route: contract.route,
+    updatedAt: input.receivedAt ?? new Date().toISOString(),
+  };
+
+  await writeTaskContract(paths.contractPath, contract, { overwrite: true });
+  await writeJsonFile(paths.bindingPath, binding);
+
+  const context = [
+    `EvoDev routed this request before ${formatHookTargetName(input.target)} execution.`,
+    `Task Contract: ${paths.contractPath}`,
+    `Mode: ${contract.route.mode ?? "unknown"}`,
+    `Workflow: ${contract.route.workflowId ?? "none"}`,
+    `Reason: ${contract.route.rationale}`,
+    "Follow the contract scope, anti-criteria, and verification plan before finishing.",
+  ].join(" ");
+
+  return createRuntimeResult(input, hookOutput(input.event.type, { additionalContext: context }), {
+    summary: "User prompt routed through Task Contract.",
+    stateWrites: [paths.contractPath, paths.bindingPath],
+  });
+}
+
+async function handlePreToolUse(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const contract = await readActiveContract(input.homeDir, input.rawPayload);
+  const commandClass =
+    typeof input.event.payload.metadata.commandClass === "string"
+      ? input.event.payload.metadata.commandClass
+      : undefined;
+  const protectedPath = findProtectedPath(input.rawPayload);
+
+  if (contract === null) {
+    return createRuntimeResult(
+      input,
+      hookOutput(input.event.type, {
+        permissionDecision: "ask",
+        permissionDecisionReason: "EvoDev requires an active Task Contract before tool use.",
+        additionalContext:
+          "Submit the user prompt through UserPromptSubmit to create the Task Contract first.",
+      }),
+      { summary: "Tool use requires user confirmation because no active contract exists." },
+    );
+  }
+
+  if (protectedPath !== null) {
+    return createRuntimeResult(
+      input,
+      hookOutput(input.event.type, {
+        permissionDecision: "deny",
+        permissionDecisionReason: `EvoDev blocked access to protected project asset: ${protectedPath}`,
+      }),
+      { summary: "Protected path access denied." },
+    );
+  }
+
+  if (
+    commandClass === "delete" ||
+    commandClass === "publish" ||
+    commandClass === "credential-sensitive" ||
+    commandClass === "path-escaping"
+  ) {
+    return createRuntimeResult(
+      input,
+      hookOutput(input.event.type, {
+        permissionDecision: "deny",
+        permissionDecisionReason: `EvoDev blocked high-risk tool action: ${commandClass}`,
+      }),
+      { summary: "High-risk tool action denied." },
+    );
+  }
+
+  if (commandClass === "network" || commandClass === "unknown" || commandClass === "write") {
+    return createRuntimeResult(
+      input,
+      hookOutput(input.event.type, {
+        permissionDecision: "ask",
+        permissionDecisionReason: `EvoDev requires confirmation for ${commandClass} action under ${contract.route.mode ?? "unrouted"} mode.`,
+        additionalContext: `Active Task Contract: ${contract.taskId}. Confirm scope before continuing.`,
+      }),
+      { summary: "Tool use requires user confirmation." },
+    );
+  }
+
+  return createRuntimeResult(
+    input,
+    hookOutput(input.event.type, {
+      permissionDecision: "allow",
+      permissionDecisionReason: `EvoDev allowed ${commandClass ?? "metadata-only"} action under Task Contract ${contract.taskId}.`,
+    }),
+    { summary: "Tool use allowed by EvoDev policy." },
+  );
+}
+
+async function handlePostToolUse(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const contract = await readActiveContract(input.homeDir, input.rawPayload);
+  const binding = await readSessionBinding(input.homeDir, input.rawPayload);
+  if (contract === null || binding?.contractPath === null || binding?.contractPath === undefined) {
+    return handleAdditionalContext(input, input.event.type);
+  }
+
+  const status = optionalPayloadNumber(input.rawPayload.exit_code ?? input.rawPayload.exitCode);
+  const nextContract: TaskContract = {
+    ...contract,
+    evidence: {
+      metadataOnly: true,
+      items: [
+        ...contract.evidence.items,
+        {
+          type: "command-result",
+          id: input.event.eventId,
+          status: status === 0 ? "pass" : status === null ? "unknown" : "fail",
+          summary: input.event.payload.summary,
+          rawOutputStored: false,
+          sourceContentStored: false,
+        },
+      ],
+    },
+  };
+  await writeTaskContract(binding.contractPath, nextContract, { overwrite: true });
+
+  return createRuntimeResult(
+    input,
+    hookOutput(input.event.type, {
+      additionalContext: `EvoDev recorded metadata-only evidence for Task Contract ${contract.taskId}. Raw output was not stored.`,
+    }),
+    {
+      summary: "Post-tool metadata evidence recorded.",
+      stateWrites: [binding.contractPath],
+    },
+  );
+}
+
+async function handleCompletionGate(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const contract = await readActiveContract(input.homeDir, input.rawPayload);
+  if (contract === null) return handleAdditionalContext(input, input.event.type);
+
+  const stopHookActive = input.rawPayload.stop_hook_active === true;
+  if (
+    !stopHookActive &&
+    contract.route.mode === "rigorous" &&
+    contract.evidence.items.length === 0
+  ) {
+    return createRuntimeResult(
+      input,
+      {
+        decision: "block",
+        reason: "EvoDev rigorous mode requires metadata-only evidence before stopping.",
+        ...hookOutput(input.event.type, {
+          additionalContext:
+            "Run the required verification or record metadata-only evidence before finishing.",
+        }),
+      },
+      { summary: "Completion blocked until evidence exists." },
+    );
+  }
+
+  return createRuntimeResult(
+    input,
+    hookOutput(input.event.type, {
+      additionalContext: `EvoDev completion gate checked Task Contract ${contract.taskId}. Evidence items: ${contract.evidence.items.length}.`,
+    }),
+    { summary: "Completion gate checked." },
+  );
+}
+
+async function handlePreCompact(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const binding = await readSessionBinding(input.homeDir, input.rawPayload);
+  return createRuntimeResult(
+    input,
+    hookOutput(input.event.type, {
+      additionalContext: binding?.contractPath
+        ? `Preserve EvoDev Task Contract reference across compaction: ${binding.contractPath}`
+        : "No EvoDev Task Contract is active for this session.",
+    }),
+    { summary: "PreCompact context prepared." },
+  );
+}
+
+async function handleSessionEnd(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
+  const binding = await readSessionBinding(input.homeDir, input.rawPayload);
+  if (binding === null)
+    return createRuntimeResult(input, null, { summary: "No session state to close." });
+  const nextBinding = {
+    ...binding,
+    updatedAt: input.receivedAt ?? new Date().toISOString(),
+  };
+  const paths = resolveHookRuntimeSessionPaths({
+    homeDir: input.homeDir,
+    sessionKey: binding.sessionKey,
+  });
+  await writeJsonFile(paths.bindingPath, nextBinding);
+  return createRuntimeResult(input, null, {
+    summary: "Session state updated for SessionEnd.",
+    stateWrites: [paths.bindingPath],
+  });
+}
+
+function handleAdditionalContext(
+  input: HandleHookRuntimeInput,
+  eventName: CanonicalHookEventType,
+): Promise<HookRuntimeResult> {
+  return Promise.resolve(
+    createRuntimeResult(
+      input,
+      hookOutput(eventName, {
+        additionalContext: `EvoDev processed ${eventName} as metadata-only hook context.`,
+      }),
+      { summary: `${eventName} processed as metadata-only context.` },
+    ),
+  );
+}
+
+function createRuntimeResult(
+  input: HandleHookRuntimeInput,
+  output: Record<string, unknown> | null,
+  options: { summary: string; stateWrites?: string[] },
+): HookRuntimeResult {
+  return {
+    target: input.target,
+    event: input.event.type,
+    enabled: true,
+    output,
+    stateWrites: options.stateWrites ?? [],
+    summary: options.summary,
+  };
+}
+
+function hookOutput(
+  eventName: CanonicalHookEventType,
+  output: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      ...output,
+    },
+  };
+}
+
+function createHookTaskContract(
+  input: HandleHookRuntimeInput,
+  classification: ReturnType<typeof classifyUserPrompt>,
+): TaskContract {
+  const sessionKey = resolveHookSessionKey(input.rawPayload);
+  const targetName = formatHookTargetName(input.target);
+  const contract = createTaskContract({
+    title: `${targetName} hook task ${sessionKey}`,
+    summary: `${targetName} prompt classified as ${classification.kind}; raw prompt not stored.`,
+    projectId: null,
+  });
+
+  return {
+    ...contract,
+    currentState: {
+      summary: `UserPromptSubmit received through ${targetName} hooks; raw prompt omitted.`,
+      evidenceRefs: [],
+    },
+    targetState: {
+      summary: `Complete the ${classification.kind} task through EvoDev-controlled workflow.`,
+      nonGoals: ["Do not store raw prompts, transcripts, source content, secrets, or raw output."],
+      constraints: [
+        `prompt-kind:${classification.kind}`,
+        ...classification.riskTerms.map((term) => `risk:${term}`),
+      ],
+    },
+    scope: {
+      ...contract.scope,
+      requiresUserConfirmation: classification.riskTerms,
+    },
+    context: {
+      ...contract.context,
+      assumptions: [
+        `hook-session:${sessionKey}`,
+        `cwd:${optionalPayloadString(input.rawPayload.cwd) ?? "unknown"}`,
+      ],
+      openQuestions: classification.needsClarification
+        ? ["User request may need clarification before broad changes."]
+        : [],
+    },
+  };
+}
+
+function formatHookTargetName(target: CodeAgentHookTarget): string {
+  return target === "codex" ? "Codex" : "Claude";
+}
+
+function classifyUserPrompt(value: unknown): {
+  kind: string;
+  riskTerms: string[];
+  needsClarification: boolean;
+} {
+  const text = typeof value === "string" ? value.toLowerCase() : "";
+  const riskTerms = [
+    "security",
+    "release",
+    "publish",
+    "hook",
+    "memory",
+    "learning",
+    "secret",
+    "privacy",
+  ].filter((term) => text.includes(term));
+  let kind = "feature";
+  if (/\bbug|fix|error|failed|failure\b/.test(text)) kind = "bugfix";
+  if (/\brefactor|migration|migrate\b/.test(text)) kind = "refactor";
+  if (/\breview|audit\b/.test(text)) kind = "review";
+  if (/\btest|coverage\b/.test(text)) kind = "test";
+  if (/\bdoc|readme|guide\b/.test(text)) kind = "docs";
+  if (riskTerms.includes("security") || riskTerms.includes("privacy")) kind = "security";
+  if (riskTerms.includes("release") || riskTerms.includes("publish")) kind = "release";
+  return {
+    kind,
+    riskTerms,
+    needsClarification: text.trim().length < 12 || /\bmaybe|unclear|not sure\b/.test(text),
+  };
+}
+
+async function readActiveContract(
+  homeDir: string,
+  payload: Record<string, unknown>,
+): Promise<TaskContract | null> {
+  const binding = await readSessionBinding(homeDir, payload);
+  if (binding?.contractPath === null || binding?.contractPath === undefined) return null;
+  try {
+    return JSON.parse(await readFile(binding.contractPath, "utf8")) as TaskContract;
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+async function readSessionBinding(
+  homeDir: string,
+  payload: Record<string, unknown>,
+): Promise<HookRuntimeSessionBinding | null> {
+  const sessionKey = resolveHookSessionKey(payload);
+  const paths = resolveHookRuntimeSessionPaths({ homeDir, sessionKey });
+  try {
+    return JSON.parse(await readFile(paths.bindingPath, "utf8")) as HookRuntimeSessionBinding;
+  } catch (error) {
+    if (isNotFoundError(error)) return null;
+    throw error;
+  }
+}
+
+function resolveHookSessionKey(payload: Record<string, unknown>): string {
+  const sessionId = optionalPayloadString(payload.session_id ?? payload.sessionId);
+  const cwd = optionalPayloadString(payload.cwd);
+  const source = sessionId ?? cwd ?? "local";
+  return `session-${createHash("sha256").update(source).digest("hex").slice(0, 16)}`;
+}
+
+async function writeJsonFile(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function findProtectedPath(payload: Record<string, unknown>): string | null {
+  const candidates = collectStringValues(payload).filter((value) => value.length < 500);
+  for (const candidate of candidates) {
+    if (
+      candidate === "CLAUDE.md" ||
+      candidate === "AGENTS.md" ||
+      candidate.includes("/CLAUDE.md") ||
+      candidate.includes("/AGENTS.md") ||
+      candidate.includes(".claude/") ||
+      candidate.includes(".codex/")
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function collectStringValues(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap((item) => collectStringValues(item));
+  if (isRecord(value)) return Object.values(value).flatMap((item) => collectStringValues(item));
+  return [];
+}
+
+function optionalPayloadString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value.slice(0, 300) : null;
+}
+
+function optionalPayloadNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+function normalizeHookEventType(
+  type: HookInputEventType,
+  warnings: string[],
+): CanonicalHookEventType {
+  if (type === "AgentStop") {
+    warnings.push("Legacy AgentStop event normalized to SubagentStop.");
+    return "SubagentStop";
+  }
+  if ((CANONICAL_HOOK_EVENT_TYPES as readonly string[]).includes(type)) return type;
+  throw new Error(`Unsupported hook event type: ${type}`);
+}
+
+function parseHookTargetSettings(
+  value: unknown,
+  defaults: HookTargetSettings,
+  target: CodeAgentHookTarget,
+): HookTargetSettings {
+  const targets = isRecord(value) ? value : {};
+  const targetSettings = isRecord(targets[target]) ? targets[target] : {};
+  const events = isRecord(targetSettings.events) ? targetSettings.events : {};
+  const parsedEvents: Record<CanonicalHookEventType, boolean> = { ...defaults.events };
+  for (const eventType of CANONICAL_HOOK_EVENT_TYPES) {
+    parsedEvents[eventType] = optionalBoolean(
+      events[eventType],
+      defaults.events[eventType],
+      `hooks.targets.${target}.events.${eventType}`,
+    );
+  }
+  return {
+    enabled: optionalBoolean(
+      targetSettings.enabled,
+      defaults.enabled,
+      `hooks.targets.${target}.enabled`,
+    ),
+    events: parsedEvents,
+  };
+}
+
+function extractMetadata(
+  type: CanonicalHookEventType,
+  payload: Record<string, unknown>,
+  redactions: string[],
+): Record<string, string | number | boolean | string[]> {
+  const metadata: Record<string, string | number | boolean | string[]> = {
+    rawContentIncluded: false,
+  };
+  const toolInput = isRecord(payload.tool_input)
+    ? payload.tool_input
+    : isRecord(payload.toolInput)
+      ? payload.toolInput
+      : {};
+  const toolName = optionalSanitizedString(payload.tool_name ?? payload.toolName, redactions);
+  if (toolName !== null) metadata.toolName = toolName;
+  const rawCommand =
+    typeof payload.command === "string"
+      ? payload.command
+      : typeof toolInput.command === "string"
+        ? toolInput.command
+        : undefined;
+  const command = optionalSanitizedString(rawCommand, redactions, { classifyOnly: true });
+  if (rawCommand !== undefined) redactions.push("raw-command");
+  if (
+    type === "PreToolUse" ||
+    type === "PostToolUse" ||
+    type === "PostToolUseFailure" ||
+    type === "PermissionRequest" ||
+    type === "PermissionDenied"
+  ) {
+    const commandClass = classifyCommandRisk(command ?? undefined);
+    metadata.commandClass = commandClass;
+  }
+  const exitCode = optionalNumber(payload.exit_code ?? payload.exitCode);
+  if (exitCode !== null) metadata.exitCode = exitCode;
+  const status = optionalSanitizedString(payload.status, redactions);
+  if (status !== null) metadata.status = status;
+  const redactedPrompt = payload.prompt ?? payload.userPrompt;
+  if (redactedPrompt !== undefined) redactions.push("raw-prompt");
+  const rawOutput = payload.stdout ?? payload.stderr ?? payload.output;
+  if (rawOutput !== undefined) redactions.push("raw-command-output");
+  return metadata;
+}
+
+function decideHookPolicy(commandClass: string | undefined): HookEventV1["decision"] {
+  if (
+    commandClass === "delete" ||
+    commandClass === "network" ||
+    commandClass === "publish" ||
+    commandClass === "credential-sensitive" ||
+    commandClass === "path-escaping" ||
+    commandClass === "unknown"
+  ) {
+    return {
+      action: "ask-user",
+      reason: `Command risk requires explicit confirmation: ${commandClass}`,
+      requiresUserConfirmation: true,
+    };
+  }
+  if (commandClass === "write") {
+    return {
+      action: "warn",
+      reason: "Write-like command requires scope review.",
+      requiresUserConfirmation: true,
+    };
+  }
+  return {
+    action: "allow",
+    reason: "No policy violation detected.",
+    requiresUserConfirmation: false,
+  };
+}
+
+function summarizeEvent(
+  type: CanonicalHookEventType,
+  metadata: Record<string, string | number | boolean | string[]>,
+): string {
+  if (type === "PreToolUse") return `Tool use requested (${metadata.commandClass ?? "unknown"}).`;
+  if (type === "PostToolUse") return "Tool use completed with metadata-only result.";
+  if (type === "UserPromptSubmit") return "User prompt submitted; raw prompt redacted.";
+  if (type === "SubagentStop") return "Subagent stopped; transcript omitted.";
+  return `${type} received; metadata-only dry-run.`;
+}
+
+function optionalSanitizedString(
+  value: unknown,
+  redactions: string[],
+  options: { classifyOnly?: boolean } = {},
+): string | null {
+  if (typeof value !== "string" || value.length === 0) return null;
+  if (SENSITIVE_TEXT_PATTERN.test(value) || SOURCE_LIKE_PATTERN.test(value)) {
+    redactions.push(options.classifyOnly ? "sensitive-command" : "sensitive-text");
+    return options.classifyOnly ? value : "[redacted]";
+  }
+  return value.slice(0, 120);
+}
+
+function sanitizeScalar(value: string, redactions: string[]): string {
+  return optionalSanitizedString(value, redactions) ?? "unknown";
+}
+
+function stableEventId(
+  pluginId: string,
+  type: CanonicalHookEventType,
+  sessionIdHash: string | null,
+): string {
+  const stableSessionPart = sessionIdHash ?? "local";
+  return `hook-${pluginId}-${type}-${stableSessionPart}`
+    .replace(/[^a-zA-Z0-9._-]/g, "-")
+    .slice(0, 100);
+}
+
+function hashOptionalIdentifier(value: unknown): string | null {
+  if (typeof value !== "string" || value.length === 0) return null;
+  return `sha256-${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+
+function optionalBoolean(value: unknown, fallback: boolean, path: string): boolean {
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") throw new Error(`Invalid ${path}; expected boolean.`);
+  return value;
+}
+
+function optionalNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function formatMetadataValue(value: string | number | boolean | string[]): string {
+  return Array.isArray(value) ? value.join(",") : String(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}