@evo-dev/core 0.0.1-alpha → 0.0.1-alpha.10

package/src/hooks/index.ts

@@ -1,12 +1,31 @@
-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";
+  type SessionMemoryPolicySnapshot,
+  updateSessionMemoryFromHook,
+} from "../evolution/evidence/session-memory/index.ts";
+import {
+  createScopedKnowledgeContextPack,
+  formatScopedKnowledgePromptBlock,
+  hasContextInjectionReceipt,
+  writeContextInjectionReceipt,
+} from "../evolution/knowledge/index.ts";
+import {
+  enqueueEvolutionTrigger,
+  resolveEvolutionTriggerDecision,
+} from "../evolution/triggers/index.ts";
+import { recordDiscoveredProject } from "../projects/index.ts";
+import { resolveTraceSessionKey, resolveTraceTeamContext } from "../runtime-logs/index.ts";
+import {
+  type TeamMessageRecord,
+  createTeamRoleRuntimeContext,
+  markTeamMessagesDelivered,
+  readPendingTeamMessagesForRole,
+  recordTeamAgentNativeSession,
+  resolveTeamRunPaths,
+  updateTeamAgentHookState,
+} from "../team/index.ts";
+import { sha256Short } from "../utils/index.ts";
 
 export const CANONICAL_HOOK_EVENT_TYPES = [
   "SessionStart",
@@ -49,15 +68,15 @@ export type CommandRiskClass =
   | "credential-sensitive"
   | "path-escaping"
   | "unknown";
-export type HookDecisionAction = "allow" | "warn" | "ask-user" | "block";
+export type HookDecisionAction = "allow" | "warn";
 
 export interface HookSettings {
   enabled: boolean;
   targets: Record<CodeAgentHookTarget, HookTargetSettings>;
   observability: {
-    metadataOnly: true;
-    rawPayloadStorage: false;
-    appendEvents: false;
+    metadataOnly: boolean;
+    rawPayloadStorage: boolean;
+    appendEvents: boolean;
   };
   learning: {
     emitCandidates: false;
@@ -78,7 +97,7 @@ export interface HookEventV1 {
     pluginId: string;
     agent: string;
     sessionIdHash: string | null;
-    rawPayloadStored: false;
+    rawPayloadStored: boolean;
   };
   time: {
     occurredAt: string | null;
@@ -87,7 +106,7 @@ export interface HookEventV1 {
   scope: {
     taskId: string | null;
     projectId: string | null;
-    cwdPolicy: "metadata-only";
+    cwdPolicy: "metadata-only" | "raw-local";
     projectContextOptedIn: false;
   };
   payload: {
@@ -95,11 +114,11 @@ export interface HookEventV1 {
     metadata: Record<string, string | number | boolean | string[]>;
     redactions: string[];
     redactionCount: number;
-    rawContentIncluded: false;
+    rawContentIncluded: boolean;
   };
   policy: {
     classification: "local-private";
-    allowedUses: Array<"observability" | "safety-check" | "workflow-suggestion">;
+    allowedUses: Array<"observability" | "workflow-suggestion">;
     learningAllowed: false;
     externalUploadAllowed: false;
   };
@@ -128,17 +147,15 @@ export interface HookInstallDryRunPlan {
     reason: string;
   }>;
   warnings: string[];
-  blockers: string[];
+  advisories: string[];
 }
 
 export interface HookRuntimeSessionBinding {
   version: 1;
   target: CodeAgentHookTarget;
   sessionKey: string;
-  taskId: string | null;
-  contractPath: string | null;
   cwd: string | null;
-  route: TaskContract["route"] | null;
+  teamRuntimeContextDeliveredAt?: string | null;
   updatedAt: string;
 }
 
@@ -148,6 +165,7 @@ export interface HookRuntimeResult {
   enabled: boolean;
   output: Record<string, unknown> | null;
   stateWrites: string[];
+  warnings: string[];
   summary: string;
 }
 
@@ -155,52 +173,76 @@ export interface HandleHookRuntimeInput {
   target: CodeAgentHookTarget;
   homeDir: string;
   settings: HookSettings;
+  teamRuntimeDisplayMode?: "normal" | "development";
   event: HookEventV1;
   rawPayload: Record<string, unknown>;
   receivedAt?: string;
+  environment?: Record<string, string | undefined>;
+  runtimeInjectionEnabled?: boolean;
+  sessionMemoryPolicy?: Partial<SessionMemoryPolicySnapshot>;
 }
 
 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,
+  SessionStart: true,
+  UserPromptSubmit: true,
+  UserPromptExpansion: true,
+  PreToolUse: true,
+  PermissionRequest: true,
+  PostToolUse: true,
+  PostToolUseFailure: true,
+  PostToolBatch: true,
+  PermissionDenied: true,
+  SubagentStart: true,
+  Stop: true,
+  StopFailure: true,
+  TeammateIdle: true,
+  SubagentStop: true,
+  TaskCreated: true,
+  TaskCompleted: true,
+  PreCompact: true,
+  PostCompact: true,
+  SessionEnd: true,
+  ConfigChange: true,
+  CwdChanged: true,
+  FileChanged: true,
+  WorktreeCreate: true,
+  WorktreeRemove: true,
 };
 
 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;
+const TEAM_MESSAGE_DELIVERY_EVENTS = new Set<CanonicalHookEventType>([
+  "SessionStart",
+  "UserPromptSubmit",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "Stop",
+  "TeammateIdle",
+  "SubagentStop",
+  "TaskCompleted",
+]);
+const CODEX_STOP_EVENTS_WITHOUT_ADDITIONAL_CONTEXT = new Set<CanonicalHookEventType>([
+  "Stop",
+  "SubagentStop",
+]);
+const COMPLETION_EVENTS_WITHOUT_DEVELOPMENT_DIAGNOSTICS = new Set<CanonicalHookEventType>([
+  "Stop",
+  "SubagentStop",
+  "TaskCompleted",
+  "TeammateIdle",
+]);
 
 export function createDefaultHookSettings(): HookSettings {
   return {
-    enabled: false,
+    enabled: true,
     targets: {
       claude: {
-        enabled: false,
+        enabled: true,
         events: { ...DEFAULT_EVENT_SETTINGS },
       },
       codex: {
-        enabled: false,
+        enabled: true,
         events: { ...DEFAULT_EVENT_SETTINGS },
       },
     },
@@ -220,6 +262,17 @@ 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.");
+  const observability = isRecord(value.observability) ? value.observability : undefined;
+  optionalBoolean(
+    observability?.metadataOnly,
+    defaults.observability.metadataOnly,
+    "hooks.observability.metadataOnly",
+  );
+  optionalBoolean(
+    observability?.rawPayloadStorage,
+    defaults.observability.rawPayloadStorage,
+    "hooks.observability.rawPayloadStorage",
+  );
 
   return {
     enabled: optionalBoolean(value.enabled, defaults.enabled, "hooks.enabled"),
@@ -230,7 +283,11 @@ export function parseHookSettings(value: unknown): HookSettings {
     observability: {
       metadataOnly: true,
       rawPayloadStorage: false,
-      appendEvents: false,
+      appendEvents: optionalBoolean(
+        observability?.appendEvents,
+        defaults.observability.appendEvents,
+        "hooks.observability.appendEvents",
+      ),
     },
     learning: {
       emitCandidates: false,
@@ -281,7 +338,7 @@ export function normalizeHookEvent(input: NormalizeHookEventInput): HookEventV1
     },
     policy: {
       classification: "local-private",
-      allowedUses: ["observability", "safety-check", "workflow-suggestion"],
+      allowedUses: ["observability", "workflow-suggestion"],
       learningAllowed: false,
       externalUploadAllowed: false,
     },
@@ -318,7 +375,8 @@ export function formatHookInstallDryRun(plan: HookInstallDryRunPlan): string {
       (eventType) => `  - ${eventType}: ${plan.settings.targets[plan.target].events[eventType]}`,
     ),
     "Boundaries:",
-    "  - observability: metadata-only, appendEvents=false, rawPayloadStorage=false",
+    "  - execution events: metadata-only; raw payload/prompt/output/source storage=false",
+    "  - historical raw trace files may remain for read-only migration compatibility",
     "  - learning: emitCandidates=false, writeMemory=false",
     "  - external upload: false",
     "  - protected project writes: .claude/.codex/CLAUDE.md/AGENTS.md not targeted",
@@ -331,10 +389,10 @@ export function formatHookInstallDryRun(plan: HookInstallDryRunPlan): string {
     ...(plan.warnings.length === 0
       ? ["  - none"]
       : plan.warnings.map((warning) => `  - ${warning}`)),
-    "Blockers:",
-    ...(plan.blockers.length === 0
+    "Advisories:",
+    ...(plan.advisories.length === 0
       ? ["  - none"]
-      : plan.blockers.map((blocker) => `  - ${blocker}`)),
+      : plan.advisories.map((advisory) => `  - ${advisory}`)),
   ].join("\n");
 }
 
@@ -364,12 +422,11 @@ export function formatHookEventDryRun(event: HookEventV1): string {
 export function resolveHookRuntimeSessionPaths(input: {
   homeDir: string;
   sessionKey: string;
-}): { sessionDir: string; bindingPath: string; contractPath: string } {
+}): { sessionDir: string; bindingPath: string } {
   const sessionDir = join(input.homeDir, ".evodev", "STATE", "hooks", "sessions", input.sessionKey);
   return {
     sessionDir,
     bindingPath: join(sessionDir, "binding.json"),
-    contractPath: join(sessionDir, "contract.json"),
   };
 }
 
@@ -382,35 +439,76 @@ export async function handleHookRuntime(input: HandleHookRuntimeInput): Promise<
       enabled,
       output: null,
       stateWrites: [],
+      warnings: [],
       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 (isActiveClaudeStopHook(input)) {
+    return createRuntimeResult(input, null, {
+      summary: `${input.event.type} re-entry allowed to complete without hook output.`,
+    });
   }
-  if (input.event.type === "PostToolBatch") return handleAdditionalContext(input, "PostToolBatch");
-  if (
+
+  const diagnostics = await recordTeamNativeSessionFromHook(input);
+  const projectDiagnostics = await recordDiscoveredProjectFromHook(input);
+  let result: HookRuntimeResult | undefined;
+  if (input.event.type === "SessionStart") result = await handleSessionStart(input);
+  else if (input.event.type === "UserPromptSubmit") result = await handleUserPromptSubmit(input);
+  else if (input.event.type === "PreToolUse") result = await handlePreToolUse(input);
+  if (input.event.type === "PostToolUse" || input.event.type === "PostToolUseFailure") {
+    result = await handlePostToolUse(input);
+  } else if (input.event.type === "PostToolBatch") {
+    result = await handleAdditionalContext(input, "PostToolBatch");
+  } else if (
     input.event.type === "SubagentStart" ||
     input.event.type === "TaskCreated" ||
     input.event.type === "PermissionRequest"
   ) {
-    return handlePreToolUse(input);
-  }
-  if (
+    result = await handlePreToolUse(input);
+  } else if (
     input.event.type === "Stop" ||
     input.event.type === "SubagentStop" ||
     input.event.type === "TaskCompleted" ||
     input.event.type === "TeammateIdle"
   ) {
-    return handleCompletionGate(input);
+    result = await handleCompletionObservation(input);
+  } else if (input.event.type === "PreCompact") {
+    result = await handlePreCompact(input);
+  } else if (input.event.type === "SessionEnd") {
+    result = await handleSessionEnd(input);
+  } else if (result === undefined) {
+    result = await handleAdditionalContext(input, input.event.type);
   }
-  if (input.event.type === "PreCompact") return handlePreCompact(input);
-  if (input.event.type === "SessionEnd") return handleSessionEnd(input);
-  return handleAdditionalContext(input, input.event.type);
+  const sessionMemoryDiagnostics = await recordSessionMemoryFromHook(input);
+  const evolutionDiagnostics =
+    sessionMemoryDiagnostics.queuedSegmentTriggerId !== null ||
+    shouldSuppressLegacyEvolutionTrigger(input.event.type)
+      ? { stateWrites: [], warnings: [] }
+      : await recordEvolutionTriggerFromHook(input);
+  const messageDiagnostics = await deliverPendingTeamMessagesFromHook(input, result);
+  const scopedContextDiagnostics = await injectScopedKnowledgeContextFromHook(input, result);
+  const teamStateDiagnostics = await recordTeamAgentHookStateFromHook(input);
+  const completed = appendRuntimeDiagnostics(
+    appendRuntimeDiagnostics(
+      appendRuntimeDiagnostics(
+        appendRuntimeDiagnostics(
+          appendRuntimeDiagnostics(
+            appendRuntimeDiagnostics(
+              appendRuntimeDiagnostics(result, diagnostics),
+              projectDiagnostics,
+            ),
+            sessionMemoryDiagnostics,
+          ),
+          evolutionDiagnostics,
+        ),
+        messageDiagnostics,
+      ),
+      scopedContextDiagnostics,
+    ),
+    teamStateDiagnostics,
+  );
+  return appendDevelopmentHookDiagnostics(input, completed);
 }
 
 export function formatHookRuntimeOutput(result: HookRuntimeResult): string {
@@ -429,207 +527,427 @@ function isHookEventEnabled(
   );
 }
 
+interface HookRuntimeDiagnostics {
+  stateWrites: string[];
+  warnings: string[];
+}
+
+async function recordDiscoveredProjectFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics> {
+  if (
+    input.event.type !== "SessionStart" &&
+    input.event.type !== "UserPromptSubmit" &&
+    input.event.type !== "CwdChanged"
+  ) {
+    return { stateWrites: [], warnings: [] };
+  }
+  const cwd = optionalPayloadString(input.rawPayload.cwd);
+  if (cwd === null) return { stateWrites: [], warnings: [] };
+
+  try {
+    const result = await recordDiscoveredProject({
+      homeDir: input.homeDir,
+      cwd,
+      target: input.target,
+      sessionKey: resolveTraceSessionKey(input.rawPayload),
+      now:
+        input.receivedAt === undefined || input.receivedAt === "dry-run"
+          ? undefined
+          : input.receivedAt,
+    });
+    return result === null
+      ? { stateWrites: [], warnings: [] }
+      : { stateWrites: [result.path], warnings: [] };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: ["Local project discovery could not be updated at this hook safe point."],
+    };
+  }
+}
+
+async function recordTeamNativeSessionFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics> {
+  const environment = input.environment ?? {};
+  const runId = optionalPayloadString(environment.EVODEV_TEAM_RUN_ID);
+  const roleId = optionalPayloadString(environment.EVODEV_TEAM_ROLE_ID);
+  const sessionId = optionalPayloadString(
+    input.rawPayload.session_id ?? input.rawPayload.sessionId,
+  );
+  if (runId === null || roleId === null || sessionId === null) {
+    return { stateWrites: [], warnings: [] };
+  }
+
+  try {
+    await recordTeamAgentNativeSession({
+      homeDir: input.homeDir,
+      runId,
+      roleId,
+      sessionId,
+      now:
+        input.receivedAt === undefined || input.receivedAt === "dry-run"
+          ? undefined
+          : new Date(input.receivedAt),
+    });
+    return {
+      stateWrites: [resolveTeamRunPaths(input.homeDir).agentPath(runId, roleId)],
+      warnings: [],
+    };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: [
+        `Team native session metadata could not be recorded for run ${safeDiagnosticId(runId)} role ${safeDiagnosticId(roleId)}.`,
+      ],
+    };
+  }
+}
+
+async function recordEvolutionTriggerFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics> {
+  const decision = resolveEvolutionTriggerDecision({
+    eventType: input.event.type,
+    summary: input.event.payload.summary,
+  });
+  if (!decision.shouldQueue) return { stateWrites: [], warnings: [] };
+
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    environment: input.environment,
+    payload: input.rawPayload,
+  });
+  if (team === null) {
+    return {
+      stateWrites: [],
+      warnings:
+        decision.strength === "strong"
+          ? [
+              `Evolution trigger ${input.event.type} was not queued because team context is missing.`,
+            ]
+          : [],
+    };
+  }
+
+  try {
+    const trigger = await enqueueEvolutionTrigger({
+      homeDir: input.homeDir,
+      projectKey: team.projectKey,
+      runId: team.runId,
+      roleId: team.roleId,
+      taskId: input.event.scope.taskId,
+      eventType: input.event.type,
+      eventId: input.event.eventId,
+      summary: input.event.payload.summary,
+      now:
+        input.receivedAt === undefined || input.receivedAt === "dry-run"
+          ? undefined
+          : input.receivedAt,
+    });
+    if (trigger === null) return { stateWrites: [], warnings: [] };
+    return {
+      stateWrites: [
+        join(
+          input.homeDir,
+          ".evodev",
+          "state",
+          "evolution",
+          trigger.projectKey,
+          trigger.runId,
+          "triggers",
+          `${trigger.id}.json`,
+        ),
+      ],
+      warnings: [],
+    };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: [`Evolution trigger ${input.event.type} could not be queued.`],
+    };
+  }
+}
+
+async function recordSessionMemoryFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics & { queuedSegmentTriggerId: string | null }> {
+  try {
+    const result = await updateSessionMemoryFromHook({
+      homeDir: input.homeDir,
+      target: input.target,
+      event: input.event,
+      rawPayload: input.rawPayload,
+      environment: input.environment,
+      receivedAt: input.receivedAt,
+      policy: input.sessionMemoryPolicy,
+    });
+    return {
+      stateWrites: result.stateWrites,
+      warnings: result.warnings,
+      queuedSegmentTriggerId: result.queuedSegmentTriggerId,
+    };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: ["Session Memory state could not be updated at this hook safe point."],
+      queuedSegmentTriggerId: null,
+    };
+  }
+}
+
+function shouldSuppressLegacyEvolutionTrigger(eventType: CanonicalHookEventType): boolean {
+  return eventType === "Stop" || eventType === "SubagentStop" || eventType === "SessionEnd";
+}
+
+async function deliverPendingTeamMessagesFromHook(
+  input: HandleHookRuntimeInput,
+  result: HookRuntimeResult | undefined,
+): Promise<HookRuntimeDiagnostics> {
+  if (result === undefined || !canDeliverTeamMessagesFromHook(input.target, input.event.type)) {
+    return { stateWrites: [], warnings: [] };
+  }
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    environment: input.environment,
+    payload: input.rawPayload,
+  });
+  if (team === null) return { stateWrites: [], warnings: [] };
+
+  try {
+    const messages = await readPendingTeamMessagesForRole({
+      homeDir: input.homeDir,
+      runId: team.runId,
+      roleId: team.roleId,
+      limit: 5,
+    });
+    if (messages.length === 0) return { stateWrites: [], warnings: [] };
+    result.output = appendAdditionalContext(
+      result.output,
+      input.event.type,
+      formatTeamInboxContext(messages),
+    );
+    await markTeamMessagesDelivered({
+      homeDir: input.homeDir,
+      runId: team.runId,
+      roleId: team.roleId,
+      messageIds: messages.map((message) => message.messageId),
+      now:
+        input.receivedAt === undefined || input.receivedAt === "dry-run"
+          ? undefined
+          : new Date(input.receivedAt),
+    });
+    const teamPaths = resolveTeamRunPaths(input.homeDir);
+    return {
+      stateWrites: [teamPaths.eventsPath(team.runId), teamPaths.messageListPath(team.runId)],
+      warnings: [],
+    };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: [
+        `Team inbox messages could not be delivered for role ${safeDiagnosticId(team.roleId)}.`,
+      ],
+    };
+  }
+}
+
+async function injectScopedKnowledgeContextFromHook(
+  input: HandleHookRuntimeInput,
+  result: HookRuntimeResult | undefined,
+): Promise<HookRuntimeDiagnostics> {
+  if (result === undefined || !canDeliverTeamMessagesFromHook(input.target, input.event.type)) {
+    return { stateWrites: [], warnings: [] };
+  }
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    environment: input.environment,
+    payload: input.rawPayload,
+  });
+  if (team === null || team.roleId !== "main") return { stateWrites: [], warnings: [] };
+
+  try {
+    if (input.runtimeInjectionEnabled === false) return { stateWrites: [], warnings: [] };
+    const pack = await createScopedKnowledgeContextPack({
+      homeDir: input.homeDir,
+      projectKey: team.projectKey,
+      roleId: team.roleId,
+    });
+    if (pack === null) return { stateWrites: [], warnings: [] };
+    const sessionKey = resolveHookSessionKey(input.rawPayload);
+    if (
+      await hasContextInjectionReceipt({
+        homeDir: input.homeDir,
+        sessionKey,
+        contextPackId: pack.id,
+      })
+    ) {
+      return { stateWrites: [], warnings: [] };
+    }
+    const receipt = await writeContextInjectionReceipt({
+      homeDir: input.homeDir,
+      sessionKey,
+      pack,
+      trigger: "hook-safe-point",
+      hookEventId: input.event.eventId,
+      injectedAt: input.receivedAt ?? new Date().toISOString(),
+    });
+    result.output = appendAdditionalContext(
+      result.output,
+      input.event.type,
+      formatScopedKnowledgePromptBlock(pack),
+    );
+    return { stateWrites: [receipt.path], warnings: [] };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: ["Scoped knowledge context could not be injected at this hook safe point."],
+    };
+  }
+}
+
+function canDeliverTeamMessagesFromHook(
+  target: CodeAgentHookTarget,
+  eventType: CanonicalHookEventType,
+): boolean {
+  if (!TEAM_MESSAGE_DELIVERY_EVENTS.has(eventType)) return false;
+  return target !== "codex" || !CODEX_STOP_EVENTS_WITHOUT_ADDITIONAL_CONTEXT.has(eventType);
+}
+
+async function recordTeamAgentHookStateFromHook(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeDiagnostics> {
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    environment: input.environment,
+    payload: input.rawPayload,
+  });
+  if (team === null) return { stateWrites: [], warnings: [] };
+
+  try {
+    const result = await updateTeamAgentHookState({
+      homeDir: input.homeDir,
+      runId: team.runId,
+      roleId: team.roleId,
+      hookEvent: input.event.type,
+      now:
+        input.receivedAt === undefined || input.receivedAt === "dry-run"
+          ? undefined
+          : new Date(input.receivedAt),
+    });
+    return { stateWrites: [result.agentPath, result.statusPath], warnings: [] };
+  } catch {
+    return {
+      stateWrites: [],
+      warnings: [
+        `Team agent state could not be updated for hook role ${safeDiagnosticId(team.roleId)}.`,
+      ],
+    };
+  }
+}
+
+function appendRuntimeDiagnostics(
+  result: HookRuntimeResult | undefined,
+  diagnostics: HookRuntimeDiagnostics,
+): HookRuntimeResult {
+  if (result === undefined) {
+    throw new Error("Hook runtime did not produce a result.");
+  }
+  return {
+    ...result,
+    stateWrites: [...new Set([...diagnostics.stateWrites, ...result.stateWrites])],
+    warnings: [...new Set([...diagnostics.warnings, ...result.warnings])],
+  };
+}
+
 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 }), {
+  return createRuntimeResult(input, null, {
     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 previousBinding = await readSessionBinding(input.homeDir, input.rawPayload);
+  const teamRuntimeContext =
+    previousBinding?.teamRuntimeContextDeliveredAt === undefined ||
+    previousBinding.teamRuntimeContextDeliveredAt === null
+      ? await createTeamRuntimeContextForUserPrompt(input)
+      : null;
+  const teamRuntimeContextDeliveredAt =
+    teamRuntimeContext !== null
+      ? (input.receivedAt ?? new Date().toISOString())
+      : (previousBinding?.teamRuntimeContextDeliveredAt ?? null);
   const binding: HookRuntimeSessionBinding = {
     version: 1,
     target: input.target,
     sessionKey,
-    taskId: contract.taskId,
-    contractPath: paths.contractPath,
     cwd: optionalPayloadString(input.rawPayload.cwd),
-    route: contract.route,
+    teamRuntimeContextDeliveredAt,
     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],
+  let output: Record<string, unknown> | null = null;
+  if (teamRuntimeContext !== null) {
+    output = appendAdditionalContext(output, input.event.type, teamRuntimeContext);
+  }
+
+  return createRuntimeResult(input, output, {
+    summary: "User prompt observed; session binding updated.",
+    stateWrites: [paths.bindingPath],
   });
 }
 
+async function createTeamRuntimeContextForUserPrompt(
+  input: HandleHookRuntimeInput,
+): Promise<string | null> {
+  const team = resolveTraceTeamContext({
+    homeDir: input.homeDir,
+    environment: input.environment,
+    payload: input.rawPayload,
+  });
+  if (team === null || team.roleId !== "main") return null;
+
+  try {
+    return await createTeamRoleRuntimeContext({
+      homeDir: input.homeDir,
+      runId: team.runId,
+      roleId: team.roleId,
+    });
+  } catch {
+    return null;
+  }
+}
+
 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." },
-  );
+  return createRuntimeResult(input, null, {
+    summary: `${input.event.type} observed (${commandClass ?? "metadata-only"}); no permission decision emitted.`,
+  });
 }
 
 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],
-    },
-  );
+  return handleAdditionalContext(input, input.event.type);
 }
 
-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 handleCompletionObservation(
+  input: HandleHookRuntimeInput,
+): Promise<HookRuntimeResult> {
+  return createRuntimeResult(input, null, {
+    summary: `${input.event.type} observed as metadata-only hook context.`,
+  });
 }
 
 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." },
-  );
+  return createRuntimeResult(input, null, { summary: "PreCompact observed." });
 }
 
 async function handleSessionEnd(input: HandleHookRuntimeInput): Promise<HookRuntimeResult> {
@@ -656,20 +974,16 @@ function handleAdditionalContext(
   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.` },
-    ),
+    createRuntimeResult(input, null, {
+      summary: `${eventName} observed as metadata-only hook context.`,
+    }),
   );
 }
 
 function createRuntimeResult(
   input: HandleHookRuntimeInput,
   output: Record<string, unknown> | null,
-  options: { summary: string; stateWrites?: string[] },
+  options: { summary: string; stateWrites?: string[]; warnings?: string[] },
 ): HookRuntimeResult {
   return {
     target: input.target,
@@ -677,6 +991,7 @@ function createRuntimeResult(
     enabled: true,
     output,
     stateWrites: options.stateWrites ?? [],
+    warnings: options.warnings ?? [],
     summary: options.summary,
   };
 }
@@ -693,96 +1008,101 @@ function hookOutput(
   };
 }
 
-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,
-  });
-
+function appendAdditionalContext(
+  output: Record<string, unknown> | null,
+  eventName: CanonicalHookEventType,
+  context: string,
+): Record<string, unknown> {
+  if (output === null) return hookOutput(eventName, { additionalContext: context });
+  const hookSpecificOutput = isRecord(output.hookSpecificOutput) ? output.hookSpecificOutput : {};
+  const previous =
+    typeof hookSpecificOutput.additionalContext === "string"
+      ? hookSpecificOutput.additionalContext
+      : "";
   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."]
-        : [],
+    ...output,
+    hookSpecificOutput: {
+      ...hookSpecificOutput,
+      hookEventName:
+        typeof hookSpecificOutput.hookEventName === "string"
+          ? hookSpecificOutput.hookEventName
+          : eventName,
+      additionalContext: previous === "" ? context : `${previous}\n\n${context}`,
     },
   };
 }
 
-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";
+function appendDevelopmentHookDiagnostics(
+  input: HandleHookRuntimeInput,
+  result: HookRuntimeResult,
+): HookRuntimeResult {
+  if (
+    input.teamRuntimeDisplayMode !== "development" ||
+    COMPLETION_EVENTS_WITHOUT_DEVELOPMENT_DIAGNOSTICS.has(input.event.type) ||
+    !canDeliverTeamMessagesFromHook(input.target, input.event.type)
+  ) {
+    return result;
+  }
   return {
-    kind,
-    riskTerms,
-    needsClarification: text.trim().length < 12 || /\bmaybe|unclear|not sure\b/.test(text),
+    ...result,
+    output: appendAdditionalContext(
+      result.output,
+      input.event.type,
+      formatDevelopmentHookDiagnostics(input),
+    ),
   };
 }
 
-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;
-  }
+function isActiveClaudeStopHook(input: HandleHookRuntimeInput): boolean {
+  return (
+    input.target === "claude" &&
+    (input.event.type === "Stop" || input.event.type === "SubagentStop") &&
+    input.rawPayload.stop_hook_active === true
+  );
+}
+
+function formatDevelopmentHookDiagnostics(input: HandleHookRuntimeInput): string {
+  const metadata = Object.entries(input.event.payload.metadata);
+  const inputFields = Object.keys(input.rawPayload)
+    .map((field) => field.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 80))
+    .filter((field) => field.length > 0)
+    .slice(0, 30);
+  return [
+    "EvoDev hook development diagnostics",
+    `Target: ${input.target}`,
+    `Event: ${input.event.type}`,
+    `Summary: ${input.event.payload.summary}`,
+    `Input fields: ${inputFields.join(", ") || "none"}`,
+    "Normalized metadata:",
+    ...(metadata.length === 0
+      ? ["- none"]
+      : metadata.map(([key, value]) => `- ${key}: ${formatMetadataValue(value)}`)),
+    `Redactions: ${input.event.payload.redactions.join(", ") || "none"}`,
+    "Raw payload included: false",
+  ].join("\n");
+}
+
+function formatTeamInboxContext(messages: TeamMessageRecord[]): string {
+  const blocks = messages.map((message) =>
+    [
+      "[EvoDev team message]",
+      "Instruction: read this queued team message at this safe point; reply through Teams MCP only when a response is needed.",
+      `from: ${message.fromRoleId}`,
+      `to: ${message.toRoleId}`,
+      `type: ${message.type}`,
+      `messageId: ${message.messageId}`,
+      `cc: ${message.ccRoleIds.join(",") || "none"}`,
+      "",
+      truncateTeamMessageBody(message.body),
+      "[/EvoDev team message]",
+    ].join("\n"),
+  );
+  return ["EvoDev team inbox:", ...blocks].join("\n\n");
+}
+
+function truncateTeamMessageBody(value: string): string {
+  if (value.length <= 4000) return value;
+  return `${value.slice(0, 4000)}...[truncated:${value.length - 4000}]`;
 }
 
 async function readSessionBinding(
@@ -803,7 +1123,7 @@ 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)}`;
+  return `session-${sha256Short(source)}`;
 }
 
 async function writeJsonFile(path: string, value: unknown): Promise<void> {
@@ -811,36 +1131,12 @@ async function writeJsonFile(path: string, value: unknown): Promise<void> {
   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 safeDiagnosticId(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 120) || "unknown";
 }
 
 function isNotFoundError(error: unknown): boolean {
@@ -892,9 +1188,7 @@ function extractMetadata(
   payload: Record<string, unknown>,
   redactions: string[],
 ): Record<string, string | number | boolean | string[]> {
-  const metadata: Record<string, string | number | boolean | string[]> = {
-    rawContentIncluded: false,
-  };
+  const metadata: Record<string, string | number | boolean | string[]> = {};
   const toolInput = isRecord(payload.tool_input)
     ? payload.tool_input
     : isRecord(payload.toolInput)
@@ -932,30 +1226,12 @@ function extractMetadata(
 }
 
 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.",
+    reason:
+      commandClass === undefined
+        ? "Observed metadata only; EvoDev does not stop hook execution."
+        : `Observed ${commandClass} tool action; EvoDev does not stop hook execution.`,
     requiresUserConfirmation: false,
   };
 }
@@ -966,7 +1242,7 @@ function summarizeEvent(
 ): 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 === "UserPromptSubmit") return "User prompt submitted.";
   if (type === "SubagentStop") return "Subagent stopped; transcript omitted.";
   return `${type} received; metadata-only dry-run.`;
 }
@@ -1001,7 +1277,7 @@ function stableEventId(
 
 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)}`;
+  return `sha256-${sha256Short(value)}`;
 }
 
 function optionalBoolean(value: unknown, fallback: boolean, path: string): boolean {