intentdna 1.9.0 → 1.9.3

package/dist/hooks/host-event.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { canonicalizeJson } from "../runtime/canonical-json.js";
+import { isCurrentClaudeSubagentStopInput } from "./schema.js";
+export const CLAUDE_HOST_EVENT_SCHEMA_VERSION = "intentdna.claude_host_event.v1";
+export const CLAUDE_HOST_EVENT_STDERR_PREFIX = "INTENTDNA_CLAUDE_HOST_EVENT_V1 ";
+export class ClaudeHostEventError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ClaudeHostEventError";
+        this.code = code;
+    }
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function digest(value) {
+    return `sha256:${createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+function hostSessionId(input) {
+    if (nonEmpty(input.session_id))
+        return input.session_id;
+    if (nonEmpty(input.sessionId))
+        return input.sessionId;
+    return undefined;
+}
+export function buildClaudeSubagentStopHostEvent(input, state) {
+    if (!state?.active
+        || !nonEmpty(state.run_id)
+        || !nonEmpty(state.step_id)
+        || !nonEmpty(state.attempt_id)
+        || !nonEmpty(state.worker_session_id)
+        || !isCurrentClaudeSubagentStopInput(input)
+        || input.agent_id !== state.worker_session_id) {
+        return null;
+    }
+    return {
+        schema_version: CLAUDE_HOST_EVENT_SCHEMA_VERSION,
+        hook_event_name: "SubagentStop",
+        session_id: hostSessionId(input),
+        transcript_path: input.transcript_path,
+        agent_id: input.agent_id,
+        agent_type: input.agent_type,
+        agent_transcript_path: input.agent_transcript_path,
+        last_assistant_message_digest: digest(input.last_assistant_message),
+        run_id: state.run_id,
+        step_id: state.step_id,
+        attempt_id: state.attempt_id,
+        worker_session_id: state.worker_session_id,
+    };
+}
+export function encodeClaudeHostEventForStderr(event) {
+    return `${CLAUDE_HOST_EVENT_STDERR_PREFIX}${Buffer.from(canonicalizeJson(event), "utf8").toString("base64url")}\n`;
+}
+function parseEnvelope(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ClaudeHostEventError("malformed_envelope", "Claude host event envelope must be an object");
+    }
+    const event = value;
+    const expectedKeys = [
+        "agent_id",
+        "agent_transcript_path",
+        "agent_type",
+        "attempt_id",
+        "hook_event_name",
+        "last_assistant_message_digest",
+        "run_id",
+        "schema_version",
+        "session_id",
+        "step_id",
+        "transcript_path",
+        "worker_session_id",
+    ];
+    if (Object.keys(event).sort().join("\0") !== expectedKeys.join("\0")) {
+        throw new ClaudeHostEventError("malformed_envelope", "Claude host event envelope fields are not the fixed v1 projection");
+    }
+    if (event.schema_version !== CLAUDE_HOST_EVENT_SCHEMA_VERSION
+        || event.hook_event_name !== "SubagentStop"
+        || !nonEmpty(event.session_id)
+        || !nonEmpty(event.transcript_path)
+        || !nonEmpty(event.agent_id)
+        || !nonEmpty(event.agent_type)
+        || !nonEmpty(event.agent_transcript_path)
+        || !nonEmpty(event.last_assistant_message_digest)
+        || !/^sha256:[0-9a-f]{64}$/.test(event.last_assistant_message_digest)
+        || !nonEmpty(event.run_id)
+        || !nonEmpty(event.step_id)
+        || !nonEmpty(event.attempt_id)
+        || !nonEmpty(event.worker_session_id)) {
+        throw new ClaudeHostEventError("malformed_envelope", "Claude host event envelope is invalid");
+    }
+    if (event.agent_id !== event.worker_session_id) {
+        throw new ClaudeHostEventError("identity_mismatch", "Claude agent_id does not match the Controller worker_session_id");
+    }
+    return {
+        schema_version: CLAUDE_HOST_EVENT_SCHEMA_VERSION,
+        hook_event_name: "SubagentStop",
+        session_id: event.session_id,
+        transcript_path: event.transcript_path,
+        agent_id: event.agent_id,
+        agent_type: event.agent_type,
+        agent_transcript_path: event.agent_transcript_path,
+        last_assistant_message_digest: event.last_assistant_message_digest,
+        run_id: event.run_id,
+        step_id: event.step_id,
+        attempt_id: event.attempt_id,
+        worker_session_id: event.worker_session_id,
+    };
+}
+function assertExpectedContext(value, event, expected) {
+    const mismatches = [
+        ["hook_id", value.hook_id, expected.hook_id],
+        ["session_id", event.session_id, expected.session_id],
+        ["run_id", event.run_id, expected.run_id],
+        ["step_id", event.step_id, expected.step_id],
+        ["attempt_id", event.attempt_id, expected.attempt_id],
+        ["worker_session_id", event.worker_session_id, expected.worker_session_id],
+    ].filter(([, actual, wanted]) => actual !== wanted);
+    if (mismatches.length > 0) {
+        throw new ClaudeHostEventError("context_mismatch", `Claude hook response does not match the Controller expectation: ${mismatches
+            .map(([field]) => field)
+            .join(", ")}`);
+    }
+}
+export async function parseClaudeSubagentStopHookResponse(frame, expected, consumptionStore) {
+    if (frame === null || typeof frame !== "object" || Array.isArray(frame)) {
+        throw new ClaudeHostEventError("invalid_frame", "Claude hook response frame must be an object");
+    }
+    const value = frame;
+    if (value.type !== "system"
+        || value.subtype !== "hook_response"
+        || value.hook_event !== "SubagentStop"
+        || value.outcome !== "success"
+        || value.exit_code !== 0
+        || !nonEmpty(value.hook_id)
+        || !nonEmpty(value.session_id)
+        || !nonEmpty(value.uuid)
+        || typeof value.stderr !== "string") {
+        throw new ClaudeHostEventError("invalid_frame", "Claude hook response frame is not an accepted SubagentStop success");
+    }
+    const encoded = value.stderr
+        .split(/\r?\n/u)
+        .filter((line) => line.startsWith(CLAUDE_HOST_EVENT_STDERR_PREFIX))
+        .map((line) => line.slice(CLAUDE_HOST_EVENT_STDERR_PREFIX.length));
+    if (encoded.length === 0) {
+        throw new ClaudeHostEventError("missing_envelope", "Claude hook response has no IntentDNA host event envelope");
+    }
+    if (encoded.length !== 1) {
+        throw new ClaudeHostEventError("duplicate_envelope", "Claude hook response has multiple IntentDNA host event envelopes");
+    }
+    const payload = encoded[0];
+    if (!/^[A-Za-z0-9_-]+$/u.test(payload)) {
+        throw new ClaudeHostEventError("malformed_envelope", "Claude host event envelope encoding is invalid");
+    }
+    let parsed;
+    try {
+        const decoded = Buffer.from(payload, "base64url").toString("utf8");
+        if (Buffer.from(decoded, "utf8").toString("base64url") !== payload) {
+            throw new Error("non-canonical base64url");
+        }
+        parsed = JSON.parse(decoded);
+        if (canonicalizeJson(parsed) !== decoded) {
+            throw new Error("non-canonical JSON");
+        }
+    }
+    catch (error) {
+        throw new ClaudeHostEventError("malformed_envelope", `Claude host event envelope cannot be decoded: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const event = parseEnvelope(parsed);
+    if (event.session_id !== value.session_id) {
+        throw new ClaudeHostEventError("identity_mismatch", "Claude hook frame session_id does not match its host event envelope");
+    }
+    assertExpectedContext(value, event, expected);
+    const consumptionKey = {
+        session_id: event.session_id,
+        frame_uuid: value.uuid,
+        hook_id: value.hook_id,
+    };
+    if (!await consumptionStore.consume(consumptionKey)) {
+        throw new ClaudeHostEventError("replayed_frame", "Claude hook response frame was already consumed");
+    }
+    return {
+        hook_id: value.hook_id,
+        frame_uuid: value.uuid,
+        event,
+    };
+}

package/dist/hooks/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { type HookEvent, type HookInput, type HookOutput, type HookInputBase, type PreToolUseInput, type PostToolUseInput, type UserPromptSubmitInput, type SubagentStopInput, type PreCompactInput, type NotificationInput, type StopInput, type SessionStartInput as SessionStartHookInput, type StdinReadResult, readStdin, readStdinResult, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
 export { type HookFailureDisposition, type HookFailureKind, hookFailureDisposition, hookFailureOutput, } from "./enforcement-boundary.js";
+export { type ClaudeSubagentStopHostEvent, type ClaudeSubagentStopHostEventExpectation, type ClaudeHookResponseFrame, type ClaudeHostEventConsumptionKey, type ClaudeHostEventConsumptionStore, type VerifiedClaudeSubagentStopHostEvent, type ClaudeHostEventErrorCode, ClaudeHostEventError, CLAUDE_HOST_EVENT_SCHEMA_VERSION, CLAUDE_HOST_EVENT_STDERR_PREFIX, buildClaudeSubagentStopHostEvent, encodeClaudeHostEventForStderr, parseClaudeSubagentStopHookResponse, } from "./host-event.js";
 export { type EnforceState, type SessionStartInput, type StopEnforceInput, type StopWorkflowContext, enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
 export { type DNAWorkflowState, type AuditEntry, resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, cleanupWorkerHookState, appendAudit, } from "./state.js";
 export { type SessionSummary, computeSummary, formatSummary, } from "./cli.js";

package/dist/hooks/index.js

@@ -7,6 +7,7 @@
 // Protocol types and I/O
 export { readStdin, readStdinResult, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
 export { hookFailureDisposition, hookFailureOutput, } from "./enforcement-boundary.js";
+export { ClaudeHostEventError, CLAUDE_HOST_EVENT_SCHEMA_VERSION, CLAUDE_HOST_EVENT_STDERR_PREFIX, buildClaudeSubagentStopHostEvent, encodeClaudeHostEventForStderr, parseClaudeSubagentStopHookResponse, } from "./host-event.js";
 // Enforcement engine
 export { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
 // State management

package/dist/hooks/protocol.d.ts

@@ -11,6 +11,10 @@ export type { HookEvent } from "./event-registry.js";
 export interface HookInputBase {
     cwd?: string;
     sessionId?: string;
+    transcript_path?: string;
+    permission_mode?: string;
+    hook_event_name?: string;
+    agent_id?: string;
     worker_session_id?: string;
     run_id?: string;
     step_id?: string;
@@ -33,6 +37,9 @@ export interface UserPromptSubmitInput extends HookInputBase {
 export interface SubagentStopInput extends HookInputBase {
     agent_name?: string;
     agent_type?: string;
+    agent_transcript_path?: string;
+    last_assistant_message?: string;
+    stop_hook_active?: boolean;
 }
 export interface PreCompactInput extends HookInputBase {
 }

package/dist/hooks/schema.d.ts

@@ -8,6 +8,7 @@ export interface ValidationResult {
     errors: string[];
     normalized?: Record<string, unknown>;
 }
+export declare function isCurrentClaudeSubagentStopInput(input: Record<string, unknown>): boolean;
 /**
  * Validate hook input against expected schema for each event type.
  * Returns normalized input (camelCase) on success.

package/dist/hooks/schema.js

@@ -4,6 +4,30 @@
  * Classification of invalid input belongs to the event boundary.
  */
 import { isHookEventSupportedBySurface } from "./event-registry.js";
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function isCurrentClaudeSubagentStopInput(input) {
+    const parentSessionId = nonEmptyString(input.session_id)
+        ? input.session_id
+        : nonEmptyString(input.sessionId)
+            ? input.sessionId
+            : undefined;
+    return parentSessionId !== undefined
+        && !(nonEmptyString(input.session_id)
+            && nonEmptyString(input.sessionId)
+            && input.session_id !== input.sessionId)
+        && input.hook_event_name === "SubagentStop"
+        && nonEmptyString(input.transcript_path)
+        && nonEmptyString(input.permission_mode)
+        && typeof input.stop_hook_active === "boolean"
+        && nonEmptyString(input.agent_id)
+        && nonEmptyString(input.agent_type)
+        && nonEmptyString(input.agent_transcript_path)
+        && typeof input.last_assistant_message === "string"
+        && (input.worker_session_id === undefined
+            || input.worker_session_id === input.agent_id);
+}
 /**
  * Validate hook input against expected schema for each event type.
  * Returns normalized input (camelCase) on success.
@@ -15,6 +39,26 @@ export function validateHookInput(event, raw) {
     const input = raw;
     const errors = [];
     const normalized = { ...input };
+    for (const field of [
+        "session_id",
+        "sessionId",
+        "worker_session_id",
+        "transcript_path",
+        "permission_mode",
+        "hook_event_name",
+    ]) {
+        if (input[field] !== undefined && typeof input[field] !== "string") {
+            errors.push(`${field} must be a string if present`);
+        }
+    }
+    if (typeof input.session_id === "string"
+        && typeof input.sessionId === "string"
+        && input.session_id !== input.sessionId) {
+        errors.push("session_id and sessionId must match when both are present");
+    }
+    if (typeof input.hook_event_name === "string" && input.hook_event_name !== event) {
+        errors.push(`hook_event_name must match ${event}`);
+    }
     // The Controller's disposable worker session is the Hook context key.
     const sessionId = normalizeSessionId(input);
     if (sessionId !== undefined) {
@@ -46,7 +90,51 @@ export function validateHookInput(event, raw) {
             // session_id is optional but should be normalized if present
             break;
         case "SubagentStop":
-            // agent_type or agent_name should be present but not strictly required
+            for (const field of [
+                "agent_id",
+                "agent_name",
+                "agent_type",
+                "agent_transcript_path",
+                "last_assistant_message",
+            ]) {
+                if (input[field] !== undefined && typeof input[field] !== "string") {
+                    errors.push(`SubagentStop: ${field} must be a string if present`);
+                }
+            }
+            if (typeof input.agent_id === "string" && input.agent_id.trim().length === 0) {
+                errors.push("SubagentStop: agent_id must be non-empty if present");
+            }
+            if (typeof input.agent_id === "string" && input.agent_id.trim().length > 0) {
+                for (const field of [
+                    "transcript_path",
+                    "permission_mode",
+                    "agent_type",
+                    "agent_transcript_path",
+                ]) {
+                    if (typeof input[field] !== "string" || input[field].trim().length === 0) {
+                        errors.push(`SubagentStop: ${field} must be a non-empty string when agent_id is present`);
+                    }
+                }
+                if (!nonEmptyString(input.session_id) && !nonEmptyString(input.sessionId)) {
+                    errors.push("SubagentStop: a non-empty parent session_id is required when agent_id is present");
+                }
+                if (input.hook_event_name !== "SubagentStop") {
+                    errors.push("SubagentStop: hook_event_name must be SubagentStop when agent_id is present");
+                }
+                if (typeof input.last_assistant_message !== "string") {
+                    errors.push("SubagentStop: last_assistant_message must be a string when agent_id is present");
+                }
+                if (typeof input.stop_hook_active !== "boolean") {
+                    errors.push("SubagentStop: stop_hook_active must be a boolean when agent_id is present");
+                }
+                if (typeof input.worker_session_id === "string"
+                    && input.worker_session_id !== input.agent_id) {
+                    errors.push("SubagentStop: worker_session_id must match agent_id when both are present");
+                }
+            }
+            if (input.stop_hook_active !== undefined && typeof input.stop_hook_active !== "boolean") {
+                errors.push("SubagentStop: stop_hook_active must be a boolean if present");
+            }
             break;
         case "Notification":
             if (typeof input.title !== "string" && input.title !== undefined) {

package/dist/hooks/state.d.ts

@@ -10,6 +10,8 @@
  * 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 { CompiledIRFile } from "../runtime/plugin-adapter.js";
+import type { ClaimToken } from "../runtime/run-contracts.js";
 import { type RuntimeDecisionEvent } from "../governance/index.js";
 export declare const EVIDENCE_CAPTURE_SCHEMA_VERSION = "intentdna.evidence_capture.v1";
 /** Workflow state written by runtime and read by hooks */
@@ -108,6 +110,25 @@ export declare function safePathComponent(value: string, label: string): string;
  * Without: `.dna/state/`
  */
 export declare function resolveStateDir(projectDir: string, sessionId?: string): string;
+interface CanonicalHookRuntimeProjectionBase {
+    readonly run_id: string;
+    readonly step_id: string;
+    readonly attempt_id: string;
+    readonly worker_session_id: string;
+    readonly compiled_ir_hash: string;
+    readonly compiled_ir: CompiledIRFile;
+}
+export interface CanonicalHookRuntimeProjectionV1 extends CanonicalHookRuntimeProjectionBase {
+    readonly schema_version: "intentdna.canonical_hook_projection.v1";
+}
+export interface CanonicalHookRuntimeProjectionV2 extends CanonicalHookRuntimeProjectionBase {
+    readonly schema_version: "intentdna.canonical_hook_projection.v2";
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+}
+export type CanonicalHookRuntimeProjection = CanonicalHookRuntimeProjectionV1 | CanonicalHookRuntimeProjectionV2;
+export declare function resolveSessionCompiledIRPath(projectDir: string, workerSessionId: string): string;
+export declare function writeCanonicalHookRuntimeProjection(projectDir: string, projection: CanonicalHookRuntimeProjection): Promise<void>;
 export declare const ARTIFACT_RESOLVER_VERSION = 1;
 export declare function isRequiredArtifact(artifact: HandoffArtifact): boolean;
 export declare function artifactIdentity(artifact: HandoffArtifact, resolvedPath?: string): string | null;
@@ -237,7 +258,7 @@ export interface TraceEntry {
  * Fail-open: never throws.
  */
 export declare function appendTrace(projectDir: string, entry: TraceEntry, sessionId?: string): Promise<void>;
-export declare function appendEvidenceCaptureEvent(projectDir: string, event: EvidenceCaptureEvent): Promise<void>;
+export declare function appendEvidenceCaptureEvent(projectDir: string, event: EvidenceCaptureEvent): Promise<boolean>;
 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[]>;
@@ -265,3 +286,4 @@ export declare function cleanStaleState(projectDir: string): Promise<number>;
  * or removed by this operation.
  */
 export declare function cleanupWorkerHookState(projectDir: string, workerSessionId: string): Promise<void>;
+export {};

package/dist/hooks/state.js

@@ -17,6 +17,7 @@ import { CASCADE_LAYER_NAMES, RUNTIME_DECISION_EVENT_SCHEMA_VERSION } from "../g
 export const EVIDENCE_CAPTURE_SCHEMA_VERSION = "intentdna.evidence_capture.v1";
 // ── Constants ──────────────────────────────────────────────
 const WORKFLOW_FILE = "workflow.json";
+const SESSION_COMPILED_IR_FILE = "compiled-ir.json";
 const DEFAULT_STALENESS_MS = 2 * 60 * 60 * 1000; // 2 hours
 const SAFE_PATH_COMPONENT = /^[A-Za-z0-9._-]{1,128}$/;
 const USER_ARTIFACT_PATH_ARGUMENTS = new Set(["ARGUMENTS", "arguments", "task_id"]);
@@ -47,6 +48,12 @@ export function resolveStateDir(projectDir, sessionId) {
     }
     return base;
 }
+export function resolveSessionCompiledIRPath(projectDir, workerSessionId) {
+    return join(resolveStateDir(projectDir, safePathComponent(workerSessionId, "worker_session_id")), SESSION_COMPILED_IR_FILE);
+}
+export async function writeCanonicalHookRuntimeProjection(projectDir, projection) {
+    await atomicWrite(resolveSessionCompiledIRPath(projectDir, projection.worker_session_id), `${JSON.stringify(projection, null, 2)}\n`);
+}
 export const ARTIFACT_RESOLVER_VERSION = 1;
 export function isRequiredArtifact(artifact) {
     return artifact.required !== false;
@@ -847,9 +854,11 @@ export async function appendEvidenceCaptureEvent(projectDir, event) {
         const captureDir = join(projectDir, ".dna", EVIDENCE_CAPTURE_DIR);
         await mkdir(captureDir, { recursive: true });
         await atomicAppend(join(captureDir, evidenceCaptureFileName(date)), line);
+        return true;
     }
     catch {
         // Fail-open: evidence capture write failure never affects hook execution
+        return false;
     }
 }
 export async function appendRuntimeDecisionEvent(projectDir, event, sessionId) {

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./governance/index.js";
 export * from "./assets/index.js";
 export * from "./workflow/index.js";
 export * from "./organization/index.js";
+export * from "./hooks/host-event.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./governance/index.js";
 export * from "./assets/index.js";
 export * from "./workflow/index.js";
 export * from "./organization/index.js";
+export * from "./hooks/host-event.js";

package/dist/mcp/index.js

@@ -17,6 +17,7 @@ import { createEnforceTools } from "./tools-enforce.js";
 import { createObservabilityTools } from "./tools-observability.js";
 import { createContextTools } from "./tools-context.js";
 import { createArtifactTools } from "./tools-artifacts.js";
+import { createRunTools } from "./tools-run.js";
 // Parse args
 const args = process.argv.slice(2);
 let projectDir = process.cwd();
@@ -42,5 +43,6 @@ const tools = [
     ...createArtifactTools(projectDir),
     ...createEnforceTools(projectDir),
     ...createObservabilityTools(projectDir),
+    ...createRunTools(projectDir),
 ];
 createMCPServer({ name: "intentdna", version }, tools);

package/dist/mcp/tools-run.d.ts

@@ -0,0 +1,4 @@
+import { HarnessPullAdapter } from "../runtime/harness-pull-adapter.js";
+import type { ToolDef } from "./server.js";
+export declare function createMCPHarnessAdapter(projectDirectory: string): HarnessPullAdapter;
+export declare function createRunTools(projectDir: string): ToolDef[];