intentdna 1.7.0 → 1.7.5

package/dist/governance/runtime-decision-event.js

@@ -0,0 +1,231 @@
+export const RUNTIME_DECISION_EVENT_SCHEMA_VERSION = "intentdna.runtime_decision_event.v1.7.1";
+export const CASCADE_LAYER_NAMES = [
+    "species",
+    "enterprise",
+    "project",
+    "personal",
+    "role",
+    "context",
+    "task",
+];
+const RUNTIME_DECISIONS = new Set(["allow", "warn", "block", "escalate", "validate"]);
+const ENFORCEMENT_POINTS = new Set([
+    "hook",
+    "sdk",
+    "ci",
+    "plugin_runtime",
+    "mcp_external_write",
+    "unknown",
+    "unsupported",
+]);
+const CASCADE_LAYER_VALUES = new Set([...CASCADE_LAYER_NAMES, "unknown", "unsupported"]);
+const CODON_TYPES = new Set(["attract", "repel", "threshold", "weight", "sense"]);
+const EVIDENCE_REF_TYPES = new Set([
+    "trace",
+    "audit",
+    "artifact",
+    "verifier",
+    "handoff",
+    "legacy",
+    "unknown",
+    "unsupported",
+]);
+const REQUIRED_STRING_FIELDS = [
+    "schema_version",
+    "event_id",
+    "timestamp",
+    "org_id",
+    "team_id",
+    "user_id",
+    "project_id",
+    "agent_id",
+    "agent_role",
+    "agent_type",
+    "session_agent",
+    "harness_adapter",
+    "runtime",
+    "policy_bundle_id",
+    "policy_bundle_version",
+    "compiled_ir_hash",
+    "decision_reason",
+    "enforcement_point",
+    "session_id",
+    "run_id",
+    "step_id",
+    "tool_name",
+    "action_kind",
+    "resource_ref",
+];
+const REQUIRED_WINNING_CONSTRAINT_FIELDS = [
+    "constraint_id",
+    "source_layer",
+    "source_dna_id",
+    "gene_id",
+    "codon_type",
+    "provenance_reason",
+];
+const REQUIRED_HARNESS_CONTEXT_FIELDS = [
+    "agent_id",
+    "agent_role",
+    "agent_type",
+    "session_agent",
+    "harness_adapter",
+    "runtime",
+];
+const ENTERPRISE_EVIDENCE_FIELDS = [
+    ...REQUIRED_STRING_FIELDS,
+    "decision",
+];
+const ENTERPRISE_WINNING_CONSTRAINT_FIELDS = [
+    ...REQUIRED_WINNING_CONSTRAINT_FIELDS,
+    "action",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasString(record, field) {
+    return typeof record[field] === "string" && record[field].trim().length > 0;
+}
+function isPlaceholder(value) {
+    return value === "unknown" || value === "unsupported";
+}
+function validateStringFields(record, fields, prefix, errors) {
+    for (const field of fields) {
+        if (!hasString(record, field))
+            errors.push(`${prefix}${field} must be a non-empty string`);
+    }
+}
+function validateCascadeLayers(value, errors) {
+    if (!isRecord(value)) {
+        errors.push("cascade_layers must be an object with all cascade layer keys");
+        return;
+    }
+    for (const layer of CASCADE_LAYER_NAMES) {
+        const entry = value[layer];
+        if (!isRecord(entry)) {
+            errors.push(`cascade_layers.${layer} must be an object`);
+            continue;
+        }
+        if (entry.layer !== layer)
+            errors.push(`cascade_layers.${layer}.layer must be ${layer}`);
+        validateStringFields(entry, ["source_id", "source_ref", "fingerprint", "status"], `cascade_layers.${layer}.`, errors);
+        if (hasString(entry, "status") && entry.status !== "active" && entry.status !== "unknown" && entry.status !== "unsupported") {
+            errors.push(`cascade_layers.${layer}.status must be active, unknown, or unsupported`);
+        }
+    }
+}
+function validateWinningConstraint(value, event, errors) {
+    if (!isRecord(value)) {
+        errors.push("winning_constraint must be an object");
+        return;
+    }
+    validateStringFields(value, REQUIRED_WINNING_CONSTRAINT_FIELDS, "winning_constraint.", errors);
+    if (hasString(value, "source_layer") && !CASCADE_LAYER_VALUES.has(value.source_layer)) {
+        errors.push("winning_constraint.source_layer must be a known cascade layer, unknown, or unsupported");
+    }
+    if (hasString(value, "codon_type") && !CODON_TYPES.has(value.codon_type)) {
+        errors.push("winning_constraint.codon_type must be a known codon type");
+    }
+    if (!RUNTIME_DECISIONS.has(value.action)) {
+        errors.push("winning_constraint.action must be allow, warn, block, escalate, or validate");
+    }
+    if (hasString(event, "decision") && value.action !== event.decision) {
+        errors.push("winning_constraint.action must match top-level decision");
+    }
+}
+function validateHarnessRuntimeContext(value, event, errors) {
+    if (!isRecord(value)) {
+        errors.push("harness_runtime_context must be an object");
+        return;
+    }
+    validateStringFields(value, REQUIRED_HARNESS_CONTEXT_FIELDS, "harness_runtime_context.", errors);
+    for (const field of REQUIRED_HARNESS_CONTEXT_FIELDS) {
+        if (hasString(event, field) && hasString(value, field) && event[field] !== value[field]) {
+            errors.push(`harness_runtime_context.${field} must match top-level ${field}`);
+        }
+    }
+}
+function validateEvidenceRefs(value, errors) {
+    if (!Array.isArray(value)) {
+        errors.push("evidence_refs must be an array");
+        return;
+    }
+    if (value.length === 0) {
+        errors.push("evidence_refs must contain at least one evidence reference");
+        return;
+    }
+    value.forEach((ref, index) => {
+        if (!isRecord(ref)) {
+            errors.push(`evidence_refs.${index} must be an object`);
+            return;
+        }
+        validateStringFields(ref, ["type", "ref"], `evidence_refs.${index}.`, errors);
+        if (hasString(ref, "type") && !EVIDENCE_REF_TYPES.has(ref.type)) {
+            errors.push(`evidence_refs.${index}.type must be a known evidence reference type`);
+        }
+    });
+}
+function hasCompleteEnterpriseProvenance(event) {
+    if (!ENTERPRISE_EVIDENCE_FIELDS.every((field) => hasString(event, field) && !isPlaceholder(event[field])))
+        return false;
+    if (!isRecord(event.harness_runtime_context))
+        return false;
+    if (!REQUIRED_HARNESS_CONTEXT_FIELDS.every((field) => hasString(event.harness_runtime_context, field) && !isPlaceholder(event.harness_runtime_context[field])))
+        return false;
+    if (!isRecord(event.winning_constraint))
+        return false;
+    if (!ENTERPRISE_WINNING_CONSTRAINT_FIELDS.every((field) => hasString(event.winning_constraint, field) && !isPlaceholder(event.winning_constraint[field])))
+        return false;
+    if (!isRecord(event.cascade_layers))
+        return false;
+    for (const layer of CASCADE_LAYER_NAMES) {
+        const entry = event.cascade_layers[layer];
+        if (!isRecord(entry))
+            return false;
+        if (entry.status !== "active")
+            return false;
+        if (["source_id", "source_ref", "fingerprint"].some((field) => !hasString(entry, field) || isPlaceholder(entry[field])))
+            return false;
+    }
+    if (!Array.isArray(event.evidence_refs) || event.evidence_refs.length === 0)
+        return false;
+    for (const ref of event.evidence_refs) {
+        if (!isRecord(ref))
+            return false;
+        if (!hasString(ref, "type") || isPlaceholder(ref.type) || ref.type === "legacy")
+            return false;
+        if (!hasString(ref, "ref") || isPlaceholder(ref.ref))
+            return false;
+    }
+    return true;
+}
+export function validateRuntimeDecisionEvent(event) {
+    const errors = [];
+    if (!isRecord(event)) {
+        return {
+            valid: false,
+            classification: "legacy_diagnostic",
+            errors: ["RuntimeDecisionEvent must be an object"],
+        };
+    }
+    validateStringFields(event, REQUIRED_STRING_FIELDS, "", errors);
+    if (event.schema_version !== RUNTIME_DECISION_EVENT_SCHEMA_VERSION) {
+        errors.push(`schema_version must be ${RUNTIME_DECISION_EVENT_SCHEMA_VERSION}`);
+    }
+    if (!RUNTIME_DECISIONS.has(event.decision)) {
+        errors.push("decision must be allow, warn, block, escalate, or validate");
+    }
+    if (!ENFORCEMENT_POINTS.has(event.enforcement_point)) {
+        errors.push("enforcement_point must identify hook, sdk, ci, plugin runtime, MCP external write, unknown, or unsupported");
+    }
+    validateCascadeLayers(event.cascade_layers, errors);
+    validateWinningConstraint(event.winning_constraint, event, errors);
+    validateHarnessRuntimeContext(event.harness_runtime_context, event, errors);
+    validateEvidenceRefs(event.evidence_refs, errors);
+    const valid = errors.length === 0;
+    return {
+        valid,
+        classification: valid && hasCompleteEnterpriseProvenance(event) ? "enterprise_evidence" : "legacy_diagnostic",
+        errors,
+    };
+}

package/dist/governance/types.d.ts

@@ -1,10 +1,10 @@
 /**
  * Intent DNA — Remote Governance Types
  *
- * Architecture reservation for enterprise governance communication.
- * Phase 7 implementation — current phase only defines interfaces.
+ * Architecture reservation for future remote enterprise governance communication.
+ * Current Enterprise Safety Slice uses local/shared policy bundles and RuntimeDecisionEvent evidence.
  *
- * Capabilities:
+ * Reserved capabilities:
  *   - Audit data reporting to central server
  *   - Enterprise DNA policy pull
  *   - Policy update push notifications

package/dist/governance/types.js

@@ -1,10 +1,10 @@
 /**
  * Intent DNA — Remote Governance Types
  *
- * Architecture reservation for enterprise governance communication.
- * Phase 7 implementation — current phase only defines interfaces.
+ * Architecture reservation for future remote enterprise governance communication.
+ * Current Enterprise Safety Slice uses local/shared policy bundles and RuntimeDecisionEvent evidence.
  *
- * Capabilities:
+ * Reserved capabilities:
  *   - Audit data reporting to central server
  *   - Enterprise DNA policy pull
  *   - Policy update push notifications

package/dist/hooks/cli.d.ts

@@ -47,6 +47,7 @@ export interface RunHookEventOptions {
     sessionId?: string;
     roles?: Record<string, RoleDef>;
 }
+export declare function normalizeHookOutputForEvent(output: HookOutput, event: HookEvent): HookOutput;
 export declare function runHookEvent(options: RunHookEventOptions): Promise<HookOutput>;
 declare function recordProducedArtifacts(projectDir: string, ir: ConstraintIR, wfState: {
     workflow: string;

package/dist/hooks/cli.js

@@ -18,17 +18,138 @@ import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/prom
 import { realpathSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { readStdin, writeOutput, silentOutput, allowOutput, blockOutput, stopOutput } from "./protocol.js";
 import { validateHookInput } from "./schema.js";
 import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, safePathComponent, writeArtifactManifest } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, appendRuntimeDecisionEvent, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, safePathComponent, writeArtifactManifest } from "./state.js";
 import { hookEventsForSurface } from "./event-registry.js";
 import { writeAuditEvent } from "../audit/index.js";
+import { RUNTIME_DECISION_EVENT_SCHEMA_VERSION } from "../governance/index.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set(hookEventsForSurface("cli"));
+// ── Runtime Decision Evidence ────────────────────────────
+function normalizeDecision(output) {
+    if (output.continue === false)
+        return "block";
+    if (output.hookSpecificOutput?.permissionDecision === "ask")
+        return "escalate";
+    if (output.hookSpecificOutput?.additionalContext?.startsWith("WARN"))
+        return "warn";
+    return "allow";
+}
+function hashedRef(value) {
+    const raw = typeof value === "string" && value.length > 0 ? value : "unknown";
+    return `sha256:${createHash("sha256").update(raw, "utf-8").digest("hex")}`;
+}
+function resourceRef(rawInput) {
+    const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
+        ? rawInput.tool_input
+        : {};
+    return hashedRef(toolInput.file_path ?? toolInput.notebook_path ?? toolInput.command ?? rawInput.message ?? rawInput.prompt ?? "unknown");
+}
+function actionKind(rawInput) {
+    const toolName = typeof rawInput.tool_name === "string" ? rawInput.tool_name : "unknown";
+    if (["Edit", "Write", "NotebookEdit"].includes(toolName))
+        return "file_write";
+    if (toolName === "Bash")
+        return "shell_command";
+    return toolName === "unknown" ? "unknown" : "tool_use";
+}
+function cascadeLayers(ir) {
+    const layers = ir.provenance?.cascade_layers;
+    const result = {};
+    for (const layer of ["species", "enterprise", "project", "personal", "role", "context", "task"]) {
+        const entry = layers?.[layer];
+        result[layer] = {
+            layer,
+            source_id: entry?.source_id ?? "unknown",
+            source_ref: entry?.source_ref ?? "unknown",
+            fingerprint: entry?.fingerprint ?? "unknown",
+            status: entry?.status ?? "unknown",
+        };
+    }
+    return result;
+}
+function fallbackConstraint(decision, reason, ir) {
+    return {
+        constraint_id: decision === "allow" ? "allow:no_blocking_constraint" : "unknown",
+        source_layer: decision === "allow" && ir?.provenance?.policy_bundle_id ? "enterprise" : "unknown",
+        source_dna_id: decision === "allow" ? ir?.provenance?.policy_bundle_id ?? "unknown" : "unknown",
+        gene_id: decision === "allow" ? "no_blocking_constraint" : "unknown",
+        codon_type: "threshold",
+        action: decision,
+        provenance_reason: reason || "unknown",
+    };
+}
+function candidateConstraintMatches(candidate, decision, result) {
+    if (candidate.action !== decision)
+        return false;
+    const geneId = result?.trace?.gene_id;
+    return !geneId || candidate.gene_id === geneId;
+}
+function winningConstraint(ir, decision, reason, result) {
+    const candidates = ir.provenance?.constraint_winners ?? [];
+    if (decision === "allow")
+        return fallbackConstraint(decision, reason, ir);
+    const matched = candidates.find((candidate) => candidateConstraintMatches(candidate, decision, result))
+        ?? candidates.find((candidate) => candidate.action === decision);
+    if (!matched)
+        return fallbackConstraint(decision, reason, ir);
+    return { ...matched, action: decision };
+}
+function identityField(rawInput, inputKey, envKey) {
+    const value = rawInput[inputKey];
+    if (typeof value === "string" && value.trim().length > 0)
+        return value;
+    return process.env[envKey] ?? "unknown";
+}
+function buildRuntimeDecisionEvent(params) {
+    const agentType = typeof params.rawInput.agent_type === "string" ? params.rawInput.agent_type : "unknown";
+    const derivedRole = agentType.startsWith("dna-") ? agentType.slice("dna-".length) : agentType;
+    const agentRole = params.wfState?.current_role ?? params.result?.trace?.role ?? (derivedRole === "unknown" ? "unknown" : derivedRole);
+    const sessionId = params.sessionId ?? "unknown";
+    return {
+        schema_version: RUNTIME_DECISION_EVENT_SCHEMA_VERSION,
+        event_id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        org_id: identityField(params.rawInput, "org_id", "INTENTDNA_ORG_ID"),
+        team_id: identityField(params.rawInput, "team_id", "INTENTDNA_TEAM_ID"),
+        user_id: identityField(params.rawInput, "user_id", "INTENTDNA_USER_ID"),
+        project_id: params.projectDir,
+        agent_id: agentType,
+        agent_role: agentRole,
+        agent_type: agentType,
+        session_agent: sessionId,
+        harness_adapter: "claude-code",
+        runtime: "hook",
+        policy_bundle_id: params.ir.provenance?.policy_bundle_id ?? "unknown",
+        policy_bundle_version: params.ir.provenance?.policy_bundle_version ?? "unknown",
+        cascade_layers: cascadeLayers(params.ir),
+        winning_constraint: winningConstraint(params.ir, params.decision, params.reason, params.result),
+        compiled_ir_hash: params.ir.compiled_ir_hash ?? params.ir.provenance?.compiled_ir_hash ?? "unknown",
+        decision: params.decision,
+        decision_reason: params.reason || "unknown",
+        enforcement_point: "hook",
+        harness_runtime_context: {
+            agent_id: agentType,
+            agent_role: agentRole,
+            agent_type: agentType,
+            session_agent: sessionId,
+            harness_adapter: "claude-code",
+            runtime: "hook",
+        },
+        session_id: sessionId,
+        run_id: params.wfState?.workflow ?? sessionId,
+        step_id: params.wfState?.current_step ?? params.result?.trace?.step_id ?? `${params.event}:direct`,
+        tool_name: typeof params.rawInput.tool_name === "string" ? params.rawInput.tool_name : "unknown",
+        action_kind: actionKind(params.rawInput),
+        resource_ref: resourceRef(params.rawInput),
+        evidence_refs: [{ type: "trace", ref: params.traceId }],
+    };
+}
 export function computeSummary(traces) {
     let blocks = 0, warns = 0;
     const toolCounts = new Map();
@@ -106,15 +227,45 @@ async function main() {
     const output = await runHookEvent({ event, ir, rawInput, projectDir, sessionId });
     writeOutput(output);
 }
+export function normalizeHookOutputForEvent(output, event) {
+    if (!output.hookSpecificOutput)
+        return output;
+    return {
+        ...output,
+        hookSpecificOutput: {
+            ...output.hookSpecificOutput,
+            hookEventName: output.hookSpecificOutput.hookEventName ?? event,
+        },
+    };
+}
 export async function runHookEvent(options) {
     const { event, ir, rawInput, projectDir, sessionId, roles } = options;
+    const finish = (output) => normalizeHookOutputForEvent(output, event);
     const state = {};
+    const writeRuntimeDecision = async (output, result, wfState, traceId = randomUUID()) => {
+        const decision = normalizeDecision(output);
+        const reason = decision !== "allow" ? (output.reason ?? output.hookSpecificOutput?.additionalContext ?? "unknown") : "allowed by active policy";
+        await appendRuntimeDecisionEvent(projectDir, buildRuntimeDecisionEvent({
+            ir,
+            rawInput,
+            output,
+            result,
+            event,
+            projectDir,
+            sessionId,
+            traceId,
+            decision,
+            reason,
+            wfState,
+        }), sessionId);
+    };
     let wfStateRaw = null;
     // Load workflow state for events that need it (handoff context + PreCompact preservation)
     if (event === "PreToolUse" || event === "PostToolUse" || event === "PreCompact") {
         const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
         if ("output" in workflowState) {
-            return workflowState.output;
+            await writeRuntimeDecision(workflowState.output, { output: workflowState.output, trace: { matched_rule: "workflow_boundary" } }, null);
+            return finish(workflowState.output);
         }
         wfStateRaw = workflowState.state;
         if (wfStateRaw && wfStateRaw.active) {
@@ -128,7 +279,8 @@ export async function runHookEvent(options) {
             const artifactFacts = await resolveWorkflowArtifactFactsForHook(projectDir, ir, wfStateRaw, event, sessionId);
             if ("output" in artifactFacts) {
                 appendArtifactResolverTrace(projectDir, event, wfStateRaw, artifactFacts.output, sessionId);
-                return artifactFacts.output;
+                await writeRuntimeDecision(artifactFacts.output, { output: artifactFacts.output, trace: { matched_rule: "handoff", step_id: wfStateRaw.current_step } }, wfStateRaw);
+                return finish(artifactFacts.output);
             }
             state.artifactFacts = artifactFacts.facts;
         }
@@ -144,8 +296,9 @@ export async function runHookEvent(options) {
     if (event === "PreToolUse") {
         const gateResult = await handlePreToolGates(ir, rawInput, wfStateRaw, projectDir, sessionId);
         if (gateResult) {
+            const traceId = randomUUID();
             appendTrace(projectDir, {
-                trace_id: randomUUID(),
+                trace_id: traceId,
                 event,
                 tool_name: typeof rawInput.tool_name === "string" ? rawInput.tool_name : undefined,
                 agent_type: typeof rawInput.agent_type === "string" ? rawInput.agent_type : undefined,
@@ -156,14 +309,16 @@ export async function runHookEvent(options) {
                 duration_ms: 0,
                 timestamp: new Date().toISOString(),
             }, sessionId).catch(() => { });
-            return gateResult.output;
+            await writeRuntimeDecision(gateResult.output, { output: gateResult.output, trace: { matched_rule: gateResult.matched_rule, step_id: wfStateRaw?.current_step } }, wfStateRaw, traceId);
+            return finish(gateResult.output);
         }
     }
     // Special handling for Stop — needs async workflow state read + session summary
     if (event === "Stop") {
         const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
         if ("output" in workflowState) {
-            return workflowState.output;
+            await writeRuntimeDecision(workflowState.output, { output: workflowState.output, trace: { matched_rule: "workflow_boundary" } }, null);
+            return finish(workflowState.output);
         }
         const wfState = workflowState.state;
         let stopArtifactFacts = [];
@@ -171,7 +326,8 @@ export async function runHookEvent(options) {
             const artifactFacts = await finalizeAndResolveArtifactsForHook(projectDir, ir, wfState, event, sessionId);
             if ("output" in artifactFacts) {
                 appendArtifactResolverTrace(projectDir, event, wfState, artifactFacts.output, sessionId);
-                return artifactFacts.output;
+                await writeRuntimeDecision(artifactFacts.output, { output: artifactFacts.output, trace: { matched_rule: "handoff", step_id: wfState.current_step } }, wfState);
+                return finish(artifactFacts.output);
             }
             stopArtifactFacts = artifactFacts.facts;
         }
@@ -220,8 +376,9 @@ export async function runHookEvent(options) {
         }
         catch { /* fail-open */ }
         // Trace for Stop
+        const traceId = randomUUID();
         appendTrace(projectDir, {
-            trace_id: randomUUID(),
+            trace_id: traceId,
             event: "Stop",
             workflow: wfState?.workflow,
             step: wfState?.current_step,
@@ -229,7 +386,8 @@ export async function runHookEvent(options) {
             duration_ms: 0,
             timestamp: new Date().toISOString(),
         }, sessionId).catch(() => { });
-        return stopOutput;
+        await writeRuntimeDecision(stopOutput, { output: stopOutput, trace: { matched_rule: "validator", step_id: wfState?.current_step } }, wfState, traceId);
+        return finish(stopOutput);
     }
     // Dispatch to enforcement engine with timing
     const start = Date.now();
@@ -306,24 +464,27 @@ export async function runHookEvent(options) {
         catch { /* fail-open: pattern detection never blocks */ }
     }
     // Trace logging (async, fail-open)
-    const decision = output.continue === false ? "block"
-        : output.hookSpecificOutput?.additionalContext?.startsWith("WARN") ? "warn"
-            : "allow";
+    const decision = normalizeDecision(output);
+    const traceDecision = decision === "block" ? "block" : decision === "allow" ? "allow" : "warn";
+    const traceId = randomUUID();
+    const decisionReason = decision !== "allow"
+        ? (output.reason ?? output.hookSpecificOutput?.additionalContext ?? "unknown")
+        : "allowed by active policy";
+    const traceTimestamp = new Date().toISOString();
     appendTrace(projectDir, {
-        trace_id: randomUUID(),
+        trace_id: traceId,
         event,
         tool_name: typeof rawInput.tool_name === "string" ? rawInput.tool_name : undefined,
         agent_type: typeof rawInput.agent_type === "string" ? rawInput.agent_type : undefined,
         workflow: state.workflowState?.workflow,
         step: state.workflowState?.current_step,
-        decision: decision,
-        reason: decision !== "allow"
-            ? (output.reason ?? output.hookSpecificOutput?.additionalContext)
-            : undefined,
+        decision: traceDecision,
+        reason: decision !== "allow" ? decisionReason : undefined,
         target_path: decision !== "allow" ? targetPath : undefined,
         duration_ms: durationMs,
-        timestamp: new Date().toISOString(),
+        timestamp: traceTimestamp,
     }, sessionId).catch(() => { }); // Fail-open
+    await writeRuntimeDecision(output, result, state.workflowState, traceId);
     // Side effect: rotate traces + clean stale state on SessionStart
     if (event === "SessionStart") {
         rotateTraces(projectDir).catch(() => { });
@@ -339,7 +500,7 @@ export async function runHookEvent(options) {
             session_id: sessionId,
         }).catch(() => { }); // Fail-open
     }
-    return output;
+    return finish(output);
 }
 // ── Dispatch ───────────────────────────────────────────────
 function dispatch(event, ir, input, state, roles) {

package/dist/hooks/state.d.ts

@@ -10,6 +10,7 @@
  * All write operations use atomic temp+rename pattern.
  */
 import type { ArtifactFact, ArtifactKey, ArtifactManifest, CompletedArtifactEntry, HandoffArtifact, HandoffType, VerifierKind, VerifierSeverity, VerifierWhen } from "../schema/types.js";
+import { type RuntimeDecisionEvent } from "../governance/index.js";
 /** Workflow state written by runtime and read by hooks */
 export interface DNAWorkflowState {
     active: boolean;
@@ -180,16 +181,8 @@ export interface TraceEntry {
  * Fail-open: never throws.
  */
 export declare function appendTrace(projectDir: string, entry: TraceEntry, sessionId?: string): Promise<void>;
-/**
- * Read trace entries.
- *
- * G1 session isolation:
- *   - With sessionId: reads from `.dna/state/sessions/{id}/trace.jsonl`
- *     (falls back to legacy global files with sessionId in name for backward compat)
- *   - Without sessionId: reads from `.dna/state/trace/trace-{date}.jsonl` (global merged view)
- *
- * Returns parsed entries sorted by timestamp.
- */
+export declare function appendRuntimeDecisionEvent(projectDir: string, event: RuntimeDecisionEvent, sessionId?: string): Promise<void>;
+export declare function readRuntimeDecisionEvents(projectDir: string, days?: number, sessionId?: string): Promise<RuntimeDecisionEvent[]>;
 export declare function readTraces(projectDir: string, days?: number, sessionId?: string): Promise<TraceEntry[]>;
 /**
  * List active session directories under `.dna/state/sessions/`.