intentdna 1.2.2 → 1.3.0

package/dist/hooks/enforce.js

@@ -0,0 +1,431 @@
+/**
+ * Intent DNA — Enforcement Engine
+ *
+ * Pure functions that evaluate ConstraintIR against hook inputs.
+ * No I/O — reads no files, runs no commands, writes no state.
+ * The hook CLI handles stdin/stdout, IR loading, state, and checkpoint execution.
+ *
+ * Enforcement order for PreToolUse:
+ *   1. Role scope (agent_type → write glob patterns)
+ *   2. Tool filters (block/warn/deprioritize by tool name)
+ *   3. Pre-execution gates (condition-based block/escalate)
+ *   4. Output schema (required sections for Write tool)
+ *
+ * Step checkpoints are handled by the CLI, not here.
+ */
+import { allowOutput, blockOutput, escalateOutput, silentOutput } from "./protocol.js";
+// ── PreToolUse Enforcement ─────────────────────────────────
+/**
+ * Enforce PreToolUse constraints.
+ * Returns the first blocking/escalating result, or allow if all pass.
+ *
+ * Optional `roles` parameter provides output_schema enforcement.
+ */
+export function enforcePreToolUse(ir, input, state, roles) {
+    // Layer 2: Role scope
+    if (input.agent_type && ir.roles_scope_map && ir.roles_scope_map.length > 0) {
+        const result = enforceRoleScope(ir.roles_scope_map, input);
+        if (result)
+            return result;
+    }
+    // Layer 3: Tool filters
+    if (ir.tool_filters.length > 0) {
+        const result = enforceToolFilters(ir.tool_filters, input);
+        if (result)
+            return result;
+    }
+    // Layer 4: Pre-execution gates
+    if (ir.pre_execution_gates.length > 0) {
+        const result = enforceGates(ir.pre_execution_gates, input);
+        if (result)
+            return result;
+    }
+    // Layer 5: Output schema
+    if (roles && input.tool_name === "Write") {
+        const result = enforceOutputSchema(roles, input);
+        if (result)
+            return result;
+    }
+    return silentOutput();
+}
+// ── PostToolUse Enforcement ────────────────────────────────
+/**
+ * Enforce PostToolUse validators.
+ * Currently logs validators for audit. Returns allow with context.
+ */
+export function enforcePostToolUse(ir, input) {
+    const validators = ir.post_execution_validators;
+    if (validators.length === 0)
+        return silentOutput();
+    const lines = [];
+    for (const v of validators) {
+        lines.push(`[Intent DNA] PostToolUse validator: ${v.check} (gene: ${v.source_gene})`);
+    }
+    return allowOutput(lines.join("\n"));
+}
+// ── UserPromptSubmit Enforcement ───────────────────────────
+/**
+ * Inject DNA policy reminders on each user prompt.
+ * Only injects when there are high-priority directives.
+ */
+export function enforceUserPromptSubmit(ir, _input) {
+    const highPriority = ir.prompt_directives.filter(d => d.priority === "high");
+    if (highPriority.length === 0)
+        return silentOutput();
+    const lines = [
+        "<system-reminder>[Intent DNA] Active high-priority policies:",
+    ];
+    for (const d of highPriority) {
+        lines.push(`  - [${d.source_gene}] ${d.text}`);
+    }
+    lines.push("</system-reminder>");
+    return allowOutput(lines.join("\n"));
+}
+// ── SubagentStop Enforcement ───────────────────────────────
+/**
+ * Audit role scope compliance when a subagent finishes.
+ */
+export function enforceSubagentStop(ir, input) {
+    const rolesScopeMap = ir.roles_scope_map;
+    if (!rolesScopeMap || rolesScopeMap.length === 0)
+        return silentOutput();
+    if (!input.agent_type)
+        return silentOutput();
+    for (const entry of rolesScopeMap) {
+        const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
+        if (input.agent_type === agentTypeName) {
+            const writeGlobs = entry.scope.write ?? [];
+            const scopeDesc = writeGlobs.length > 0
+                ? `write:[${writeGlobs.join(",")}]`
+                : "write:[]";
+            return allowOutput(`[Intent DNA] SubagentStop audit: role=${entry.role_name} agent=${input.agent_name ?? "unknown"} scope=${scopeDesc}`);
+        }
+    }
+    return allowOutput(`[Intent DNA] SubagentStop: unknown role for agent_type=${input.agent_type}`);
+}
+// ── PreCompact Enforcement ─────────────────────────────────
+/**
+ * Preserve DNA directive summary before context compaction.
+ */
+export function enforcePreCompact(ir) {
+    if (ir.prompt_directives.length === 0)
+        return silentOutput();
+    const critical = ir.prompt_directives.filter(d => d.priority === "high");
+    const standard = ir.prompt_directives.filter(d => d.priority === "medium");
+    const lines = [
+        "[Intent DNA] PreCompact: Preserving directive summary for compact",
+    ];
+    if (critical.length > 0) {
+        lines.push("  Critical directives:");
+        for (const d of critical) {
+            lines.push(`    - [${d.source_gene}] ${d.text}`);
+        }
+    }
+    if (standard.length > 0) {
+        lines.push(`  Standard directives (${standard.length}):`);
+        for (const d of standard) {
+            lines.push(`    - [${d.source_gene}] ${d.text}`);
+        }
+    }
+    return allowOutput(lines.join("\n"));
+}
+// ── Notification Enforcement ───────────────────────────────
+/**
+ * Check if a notification is a DNA violation and return audit info.
+ * The CLI handles actual audit file writes.
+ */
+export function enforceNotification(ir, input) {
+    const blockGates = ir.pre_execution_gates.filter(g => g.action === "block" || g.action === "escalate");
+    const blockFilters = ir.tool_filters.filter(f => f.action === "remove");
+    if (blockGates.length === 0 && blockFilters.length === 0)
+        return silentOutput();
+    const message = input.message ?? "";
+    if (message.includes("Intent DNA")) {
+        return allowOutput(`[Intent DNA] Notification: violation detected — ${input.title ?? "untitled"}: ${message}`);
+    }
+    return silentOutput();
+}
+// ── SessionStart Enforcement ───────────────────────────────
+/**
+ * Initialize DNA state and inject policy summary on session start.
+ * Returns silent if no DNA policies are active.
+ */
+export function enforceSessionStart(ir, input) {
+    // Check if there's anything meaningful to report
+    const directiveCount = ir.prompt_directives.length;
+    const gateCount = ir.pre_execution_gates.length;
+    const filterCount = ir.tool_filters.length;
+    const roleCount = ir.roles_scope_map?.length ?? 0;
+    const workflowCount = ir.workflows_ir?.length ?? 0;
+    if (directiveCount === 0 && gateCount === 0 && filterCount === 0 && roleCount === 0) {
+        return silentOutput();
+    }
+    // Build policy summary
+    const lines = [
+        "[Intent DNA] Session initialized — active governance:",
+    ];
+    if (ir.source_dna_ids.length > 0) {
+        lines.push(`  Templates: ${ir.source_dna_ids.join(", ")}`);
+    }
+    const stats = [];
+    if (directiveCount > 0)
+        stats.push(`${directiveCount} directives`);
+    if (gateCount > 0)
+        stats.push(`${gateCount} gates`);
+    if (filterCount > 0)
+        stats.push(`${filterCount} filters`);
+    if (roleCount > 0)
+        stats.push(`${roleCount} roles`);
+    if (workflowCount > 0)
+        stats.push(`${workflowCount} workflows`);
+    if (stats.length > 0) {
+        lines.push(`  Enforcement: ${stats.join(", ")}`);
+    }
+    return allowOutput(lines.join("\n"));
+}
+/**
+ * Enforce Stop hook — verify workflow checkpoint completion.
+ *
+ * Safety valves (NEVER block):
+ *   - context_limit / context_window stops
+ *   - Stale workflow state (>2h)
+ *   - No active workflow
+ *   - No checkpoints defined
+ *
+ * Block when:
+ *   - Workflow active + unmet checkpoints for current step
+ */
+export function enforceStop(ir, input, workflowState) {
+    // Safety valve 1: no workflow state → silent
+    if (!workflowState || !workflowState.active) {
+        return silentOutput();
+    }
+    // Safety valve 2: context_limit stops → NEVER block
+    const reason = input.stop_reason ?? "";
+    if (reason.includes("context_limit") || reason.includes("context_window")) {
+        return silentOutput();
+    }
+    // Safety valve 3: user abort → don't block
+    if (reason === "user_abort" || reason === "sigint") {
+        return silentOutput();
+    }
+    // Safety valve 4: stale state (>2h)
+    const STALE_MS = 2 * 60 * 60 * 1000;
+    if (workflowState.started_at) {
+        const age = Date.now() - new Date(workflowState.started_at).getTime();
+        if (age > STALE_MS) {
+            return silentOutput();
+        }
+    }
+    // Check for unmet checkpoints in current step
+    const checkpoints = ir.step_checkpoints ?? [];
+    const currentStepCheckpoints = checkpoints.filter(cp => cp.step_id === workflowState.current_step);
+    // Also check workflows_ir for the active workflow's checkpoints
+    let workflowCheckpoints = currentStepCheckpoints;
+    if (ir.workflows_ir && ir.workflows_ir.length > 0) {
+        const activeWf = ir.workflows_ir.find(w => w.workflow_name === workflowState.workflow);
+        if (activeWf) {
+            const wfStepCps = activeWf.step_checkpoints.filter(cp => cp.step_id === workflowState.current_step);
+            if (wfStepCps.length > 0) {
+                workflowCheckpoints = wfStepCps;
+            }
+        }
+    }
+    if (workflowCheckpoints.length === 0) {
+        return silentOutput(); // No checkpoints for current step
+    }
+    // Build list of blocking checkpoints
+    const blocking = workflowCheckpoints.flatMap(cp => cp.checkpoints.filter(c => (c.action ?? "block") === "block"));
+    if (blocking.length === 0) {
+        return silentOutput();
+    }
+    // Block: workflow active with unmet checkpoints
+    const messages = blocking.map(c => c.message);
+    return blockOutput(`[Intent DNA] Workflow '${workflowState.workflow}' has unmet checkpoints at step '${workflowState.current_step}':\n` +
+        messages.map(m => `  - ${m}`).join("\n"));
+}
+// ── Internal: Layer Enforcement ────────────────────────────
+function enforceRoleScope(rolesScopeMap, input) {
+    if (!input.agent_type)
+        return null;
+    if (!isWriteTool(input.tool_name))
+        return null;
+    const filePath = extractFilePath(input);
+    if (!filePath)
+        return null;
+    for (const entry of rolesScopeMap) {
+        const agentTypeName = `dna-${toKebabCase(entry.role_name)}`;
+        if (input.agent_type !== agentTypeName)
+            continue;
+        const writeGlobs = entry.scope.write ?? [];
+        if (writeGlobs.length === 0) {
+            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath})`);
+        }
+        if (!checkWriteAllowed(filePath, writeGlobs)) {
+            return blockOutput(`[Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${writeGlobs.join(", ")})`);
+        }
+        return null; // Role matched, write allowed
+    }
+    return null; // No matching role — allow
+}
+function enforceToolFilters(filters, input) {
+    for (const filter of filters) {
+        const matchedTools = resolveToolTarget(filter.target);
+        if (!matchedTools)
+            continue;
+        if (!matchedTools.includes(input.tool_name))
+            continue;
+        if (filter.action === "remove") {
+            return blockOutput(`[Intent DNA]: ${filter.reason} (gene: ${filter.source_gene})`);
+        }
+        if (filter.action === "warn") {
+            // Warn but don't block — inject context
+            return allowOutput(`WARN [Intent DNA]: ${filter.reason} (gene: ${filter.source_gene})`);
+        }
+        // deprioritize — log only
+        // Don't return, continue checking other filters
+    }
+    return null;
+}
+function enforceGates(gates, input) {
+    for (const gate of gates) {
+        const matches = evaluateGateCondition(gate.condition, input);
+        if (matches === null)
+            continue; // Condition too complex — skip
+        if (!matches)
+            continue; // Condition not triggered
+        if (gate.action === "block") {
+            return blockOutput(`[Intent DNA]: ${gate.message}`);
+        }
+        if (gate.action === "escalate") {
+            return escalateOutput(`[Intent DNA] ${gate.message}`);
+        }
+        // warn
+        return allowOutput(`WARN [Intent DNA]: ${gate.message}`);
+    }
+    return null;
+}
+function enforceOutputSchema(roles, input) {
+    if (!input.agent_type)
+        return null;
+    const content = input.tool_input.content;
+    if (typeof content !== "string" || !content)
+        return null;
+    for (const [roleName, role] of Object.entries(roles)) {
+        if (!role.output_schema || typeof role.output_schema === "string")
+            continue;
+        const schema = role.output_schema;
+        if (!schema.required_sections || schema.required_sections.length === 0)
+            continue;
+        const agentName = `dna-${toKebabCase(roleName)}`;
+        if (input.agent_type !== agentName)
+            continue;
+        for (const section of schema.required_sections) {
+            if (!content.includes(`## ${section}`)) {
+                return blockOutput(`[Intent DNA]: Output missing required section '${section}' (role: ${roleName})`);
+            }
+        }
+    }
+    return null;
+}
+// ── Public Helpers ──────────────────────────────────────────
+/** Check if a file path is allowed by a list of write globs (prefix matching). */
+export function checkWriteAllowed(filePath, allowedGlobs) {
+    for (const glob of allowedGlobs) {
+        const prefix = globToPrefix(glob);
+        if (prefix.length === 0)
+            return true; // Root glob like "*.md" — allow all
+        if (filePath.startsWith(prefix))
+            return true;
+        // Also check exact match for non-glob patterns
+        if (!glob.includes("*") && filePath === glob)
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract directory prefix from a glob pattern.
+ * "src/**\/*.ts" → "src/"
+ * "test/**" → "test/"
+ * "*.md" → "" (root)
+ * "package.json" → "package.json" (exact path)
+ */
+export function globToPrefix(glob) {
+    const starIdx = glob.indexOf("*");
+    if (starIdx === -1)
+        return glob; // exact path
+    return glob.substring(0, starIdx);
+}
+/**
+ * Evaluate a gate condition against a PreToolUse input.
+ * Returns true if the condition triggers, false if not, null if too complex.
+ */
+export function evaluateGateCondition(condition, input) {
+    // Pattern: "personal_data_exposure == false"
+    // → check if tool input contains sensitive patterns
+    const boolFalseMatch = condition.match(/^(\w+)\s*==\s*false$/);
+    if (boolFalseMatch) {
+        const metric = boolFalseMatch[1];
+        if (metric === "personal_data_exposure") {
+            const inputStr = JSON.stringify(input.tool_input).toLowerCase();
+            const sensitivePatterns = ["password", "secret", "token", "api_key", "ssn", "credit_card"];
+            return sensitivePatterns.some(p => inputStr.includes(p));
+        }
+        return null; // Unknown boolean metric
+    }
+    // Pattern: "tool_name in ['X', 'Y']"
+    const toolInMatch = condition.match(/^tool_name\s+in\s+\[([^\]]+)\]/);
+    if (toolInMatch) {
+        const tools = toolInMatch[1]
+            .split(",")
+            .map(t => t.trim().replace(/['"]/g, ""));
+        return tools.includes(input.tool_name);
+    }
+    return null; // Too complex
+}
+/**
+ * Resolve a tool filter target to concrete Claude Code tool names.
+ */
+export function resolveToolTarget(target) {
+    if (!target)
+        return null;
+    const toolMappings = {
+        file_modification: ["Edit", "Write", "NotebookEdit"],
+        file_write: ["Write"],
+        file_edit: ["Edit"],
+        code_execution: ["Bash"],
+        shell: ["Bash"],
+        harmful_actions: ["Bash"],
+        unsafe_operations: ["Bash"],
+        data_sharing_external: ["WebFetch", "Bash"],
+    };
+    const tools = toolMappings[target];
+    if (tools)
+        return tools;
+    // PascalCase target → direct tool name
+    if (/^[A-Z][a-zA-Z]+$/.test(target))
+        return [target];
+    return null;
+}
+// ── Internal Helpers ───────────────────────────────────────
+const WRITE_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
+function isWriteTool(toolName) {
+    return WRITE_TOOLS.has(toolName);
+}
+function extractFilePath(input) {
+    const fp = input.tool_input.file_path;
+    if (typeof fp === "string" && fp)
+        return fp;
+    // Bash tool — try to extract from command
+    const cmd = input.tool_input.command;
+    if (typeof cmd === "string")
+        return null; // Can't reliably extract
+    return null;
+}
+/** Convert string to kebab-case (matches agent-md.ts toKebabCase). */
+function toKebabCase(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .toLowerCase();
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Intent DNA — Node.js Hook Runtime
+ *
+ * Public exports for the hook enforcement engine.
+ * Used by the `dna-hook` CLI and importable for programmatic use.
+ */
+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, readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.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, appendAudit, } from "./state.js";

package/dist/hooks/index.js

@@ -0,0 +1,12 @@
+/**
+ * Intent DNA — Node.js Hook Runtime
+ *
+ * Public exports for the hook enforcement engine.
+ * Used by the `dna-hook` CLI and importable for programmatic use.
+ */
+// Protocol types and I/O
+export { readStdin, writeOutput, allowOutput, blockOutput, escalateOutput, silentOutput, } from "./protocol.js";
+// Enforcement engine
+export { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, checkWriteAllowed, globToPrefix, evaluateGateCondition, resolveToolTarget, } from "./enforce.js";
+// State management
+export { resolveStateDir, readWorkflowState, writeWorkflowState, clearWorkflowState, appendAudit, } from "./state.js";

package/dist/hooks/protocol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Intent DNA — Hook Protocol Types
+ *
+ * TypeScript types for Claude Code hook I/O and stdin/stdout utilities.
+ * All hooks read JSON from stdin and write JSON to stdout.
+ *
+ * Protocol reference: docs/references/cc-source-analysis.md §2
+ */
+export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "SubagentStop" | "PreCompact" | "Notification" | "Stop" | "SessionStart";
+/** Base fields present in all hook inputs */
+export interface HookInputBase {
+    cwd?: string;
+    sessionId?: string;
+}
+export interface PreToolUseInput extends HookInputBase {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    agent_type?: string;
+}
+export interface PostToolUseInput extends HookInputBase {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    tool_output?: string;
+    agent_type?: string;
+}
+export interface UserPromptSubmitInput extends HookInputBase {
+    prompt?: string;
+}
+export interface SubagentStopInput extends HookInputBase {
+    agent_name?: string;
+    agent_type?: string;
+}
+export interface PreCompactInput extends HookInputBase {
+}
+export interface NotificationInput extends HookInputBase {
+    title?: string;
+    message?: string;
+}
+export interface StopInput extends HookInputBase {
+    stop_reason?: string;
+}
+export interface SessionStartInput extends HookInputBase {
+    trigger?: string;
+}
+export type HookInput = PreToolUseInput | PostToolUseInput | UserPromptSubmitInput | SubagentStopInput | PreCompactInput | NotificationInput | StopInput | SessionStartInput;
+export interface HookOutput {
+    continue: boolean;
+    decision?: "block" | "allow";
+    reason?: string;
+    suppressOutput?: boolean;
+    hookSpecificOutput?: {
+        hookEventName?: string;
+        additionalContext?: string;
+        permissionDecision?: "ask" | "allow" | "deny";
+    };
+}
+/** Create an allow output, optionally injecting text into the conversation. */
+export declare function allowOutput(additionalContext?: string): HookOutput;
+/** Create a block output with reason. */
+export declare function blockOutput(reason: string): HookOutput;
+/** Create an escalate output (ask user for permission). */
+export declare function escalateOutput(reason: string): HookOutput;
+/** Create a silent allow output (no visible output to user). */
+export declare function silentOutput(): HookOutput;
+/**
+ * Read JSON from stdin with timeout protection.
+ * Returns parsed object on success, empty object on failure (fail-open).
+ */
+export declare function readStdin(timeoutMs?: number): Promise<Record<string, unknown>>;
+/**
+ * Write hook output to stdout as JSON.
+ */
+export declare function writeOutput(output: HookOutput): void;

package/dist/hooks/protocol.js

@@ -0,0 +1,91 @@
+/**
+ * Intent DNA — Hook Protocol Types
+ *
+ * TypeScript types for Claude Code hook I/O and stdin/stdout utilities.
+ * All hooks read JSON from stdin and write JSON to stdout.
+ *
+ * Protocol reference: docs/references/cc-source-analysis.md §2
+ */
+// ── Output Helpers ─────────────────────────────────────────
+/** Create an allow output, optionally injecting text into the conversation. */
+export function allowOutput(additionalContext) {
+    if (additionalContext) {
+        return {
+            continue: true,
+            hookSpecificOutput: { additionalContext },
+        };
+    }
+    return { continue: true };
+}
+/** Create a block output with reason. */
+export function blockOutput(reason) {
+    return {
+        continue: false,
+        decision: "block",
+        reason,
+    };
+}
+/** Create an escalate output (ask user for permission). */
+export function escalateOutput(reason) {
+    return {
+        continue: true,
+        hookSpecificOutput: {
+            permissionDecision: "ask",
+            additionalContext: reason,
+        },
+    };
+}
+/** Create a silent allow output (no visible output to user). */
+export function silentOutput() {
+    return { continue: true, suppressOutput: true };
+}
+// ── Stdin/Stdout I/O ───────────────────────────────────────
+/**
+ * Read JSON from stdin with timeout protection.
+ * Returns parsed object on success, empty object on failure (fail-open).
+ */
+export function readStdin(timeoutMs = 5000) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let settled = false;
+        const finish = (data) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeAllListeners("data");
+            process.stdin.removeAllListeners("end");
+            process.stdin.removeAllListeners("error");
+            resolve(data);
+        };
+        const timer = setTimeout(() => finish({}), timeoutMs);
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        process.stdin.on("end", () => {
+            try {
+                const raw = Buffer.concat(chunks).toString("utf-8").trim();
+                if (!raw) {
+                    finish({});
+                    return;
+                }
+                const parsed = JSON.parse(raw);
+                finish(typeof parsed === "object" && parsed !== null ? parsed : {});
+            }
+            catch {
+                finish({});
+            }
+        });
+        process.stdin.on("error", () => finish({}));
+        // If stdin is already ended (piped and closed)
+        if (process.stdin.readableEnded) {
+            finish({});
+        }
+    });
+}
+/**
+ * Write hook output to stdout as JSON.
+ */
+export function writeOutput(output) {
+    process.stdout.write(JSON.stringify(output) + "\n");
+}

package/dist/hooks/state.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Intent DNA — Hook State System
+ *
+ * Manages `.dna/state/` directory for runtime state tracking:
+ *   - Workflow state (current workflow, step, role — read by hooks)
+ *   - Audit log (violation records in JSON Lines format)
+ *   - Session isolation (per-session state directories)
+ *
+ * All read operations are fail-safe (return null on error, never throw).
+ * All write operations use atomic temp+rename pattern.
+ */
+/** Workflow state written by runtime and read by hooks */
+export interface DNAWorkflowState {
+    active: boolean;
+    workflow: string;
+    current_step: string;
+    current_role: string;
+    iteration: number;
+    session_id: string;
+    started_at: string;
+}
+/** Audit log entry (one per line in JSON Lines format) */
+export interface AuditEntry {
+    timestamp: string;
+    event: string;
+    tool_name?: string;
+    agent_type?: string;
+    message: string;
+    session_id?: string;
+}
+/**
+ * Resolve state directory path.
+ * With session isolation: `.dna/state/sessions/<sessionId>/`
+ * Without: `.dna/state/`
+ */
+export declare function resolveStateDir(projectDir: string, sessionId?: string): string;
+/**
+ * Read current workflow state. Returns null if not found or stale.
+ */
+export declare function readWorkflowState(projectDir: string, sessionId?: string, stalenessMs?: number): Promise<DNAWorkflowState | null>;
+/**
+ * Write workflow state atomically.
+ */
+export declare function writeWorkflowState(projectDir: string, state: DNAWorkflowState, sessionId?: string): Promise<void>;
+/**
+ * Clear workflow state (workflow complete).
+ */
+export declare function clearWorkflowState(projectDir: string, sessionId?: string): Promise<void>;
+/**
+ * Append an entry to the audit log.
+ * Log file: `.dna/audit/violations-YYYY-MM-DD.log` (JSON Lines format)
+ */
+export declare function appendAudit(projectDir: string, entry: AuditEntry): Promise<void>;