@peterxiaoyang/superspec 0.1.6 → 0.1.8

package/dist/src/gates.js

@@ -3,12 +3,14 @@ import { join, relative } from "node:path";
 import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
 import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
+import { hookInitReasons } from "./hooks/health.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
 import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
-import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, find_pass, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
+import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
-import { apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, compute_apply_worker_freshness, fingerprint_matches, pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, pre_edit_evidence_ref_reasons, read_pinned_artifact_json, worker_input_ref_digest, worker_test_run_reasons, } from "./apply_worker_chain.js";
+import { fingerprint_matches, } from "./apply_worker_chain.js";
+import { apply_worker_chain_lifecycle_reasons as shared_apply_worker_chain_lifecycle_reasons, apply_worker_chain_lifecycle_state, serial_completion_green, } from "./apply_worker_chain_lifecycle.js";
 function action_list(...items) {
     return [...new Set(items.filter((item) => typeof item === "string" && item.length > 0))];
 }
@@ -426,8 +428,7 @@ export function check_init(change, status, repoRoot, changeRoot) {
     if (!Array.isArray(status.applyRequires) || !new Set(status.applyRequires).has("tasks")) {
         reasons.push(reason("unexpected_apply_requires", "OpenSpec applyRequires must include native tasks artifact"));
     }
-    if (existsSync(join(repoRoot, ".codex", "hooks.json")))
-        reasons.push(reason("v1_hook_artifact_present", ".codex/hooks.json belongs to superspec v2"));
+    reasons.push(...hookInitReasons(repoRoot));
     if (existsSync(join(repoRoot, "openspec", "schemas", "superspec")))
         reasons.push(reason("custom_superspec_schema_present", "openspec/schemas/superspec is not part of superspec v1 overlay"));
     if (reasons.length > 0)
@@ -1145,259 +1146,8 @@ export function check_task_edit(change, status, changeRoot, evidences, taskId) {
     }
     return allow(change, gate, { task_id: taskId });
 }
-function pinned_artifact_ref_matches(changeRoot, refItem, role, taskId, chainId, kind = "worker_report") {
-    return shared_pinned_artifact_ref_reasons(changeRoot, refItem, `${role}_ref`, { kind, role, taskId, chainId }).length === 0;
-}
-function executor_worker_test_run_refs_valid(changeRoot, ev, taskId, chainId) {
-    return worker_test_run_reasons(changeRoot, ev, taskId, chainId).length === 0;
-}
-function report_origin_matches(refItem, expected) {
-    return isObject(refItem) && typeof expected === "string" && refItem.origin_packet_fingerprint === expected;
-}
-function report_input_refs_match(refItem, refs) {
-    return isObject(refItem) && refItem.input_ref_digest === worker_input_ref_digest(refs);
-}
-function report_input_digest_matches(refItem, expectedDigest) {
-    return isObject(refItem) && refItem.input_ref_digest === expectedDigest;
-}
-function chain_green_ids(ev) {
-    if (Array.isArray(ev.green_test_run_evidence_refs)) {
-        return ev.green_test_run_evidence_refs.map(String).filter(Boolean).sort();
-    }
-    const greenId = isObject(ev.green_test_run_evidence_ref)
-        ? String(ev.green_test_run_evidence_ref.evidence_id ?? "")
-        : String(ev.green_test_run_evidence_ref ?? "");
-    return greenId ? [greenId] : [];
-}
-function active_pre_edit_input_refs(evidences, active) {
-    const preIds = Array.isArray(active.pre_edit_evidence_refs) ? active.pre_edit_evidence_refs.map(String) : [];
-    return preIds.map((evidenceId) => {
-        const ev = live_pass(evidences, { kind: "test_run" }).find((item) => String(item.evidence_id ?? "") === evidenceId);
-        return ev
-            ? { kind: "test_run", evidence_id: evidenceId, phase: ev.phase, semantic_status: ev.semantic_status }
-            : { kind: "test_run", evidence_id: evidenceId };
-    });
-}
-function closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId) {
-    const active = live_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId })
-        .find((item) => item.chain_state === "active" && item.apply_worker_chain_id === chainId);
-    if (!active)
-        return false;
-    if (pre_edit_evidence_ref_reasons(evidences, active, taskId).length > 0)
-        return false;
-    if (!pinned_artifact_ref_matches(changeRoot, ev.executor_report_ref, "executor", taskId, chainId))
-        return false;
-    if (!pinned_artifact_ref_matches(changeRoot, ev.task_code_review_report_ref, "code-reviewer", taskId, chainId))
-        return false;
-    if (!pinned_artifact_ref_matches(changeRoot, ev.verifier_report_ref, "verifier", taskId, chainId))
-        return false;
-    if (!report_origin_matches(ev.executor_report_ref, active.executor_packet_fingerprint))
-        return false;
-    if (!report_input_digest_matches(ev.executor_report_ref, apply_worker_executor_input_ref_digest(evidences, active)))
-        return false;
-    if (!report_input_refs_match(ev.task_code_review_report_ref, [ev.executor_report_ref]))
-        return false;
-    if (typeof ev.observed_freshness_fingerprint !== "string" && !(isObject(ev.observed_freshness_fingerprint) && typeof ev.observed_freshness_fingerprint.fingerprint_digest === "string"))
-        return false;
-    const verifierReport = read_pinned_artifact_json(changeRoot, ev.verifier_report_ref);
-    const verifierObserved = verifierReport?.observed_freshness_fingerprint ?? (isObject(ev.verifier_report_ref) ? ev.verifier_report_ref.observed_freshness_fingerprint : undefined);
-    if (!fingerprint_matches(verifierObserved, ev.observed_freshness_fingerprint))
-        return false;
-    const greenIds = chain_green_ids(ev);
-    if (greenIds.length === 0)
-        return false;
-    const greenRuns = greenIds.map((greenId) => live_pass(evidences, { gate: "task_complete", kind: "test_run", task_id: taskId }).find((item) => (String(item.evidence_id ?? "") === greenId
-        && item.semantic_status === "expected_success"
-        && (item.phase === undefined || item.phase === "green")
-        && item.apply_execution_chain === "executor_worker"
-        && item.apply_worker_chain_id === chainId
-        && executor_worker_test_run_refs_valid(changeRoot, item, taskId, chainId)))).filter((item) => isObject(item));
-    if (greenRuns.length !== greenIds.length)
-        return false;
-    if (!report_input_refs_match(ev.verifier_report_ref, [
-        ev.executor_report_ref,
-        ev.task_code_review_report_ref,
-        ...greenRuns.map((green) => ({ kind: "test_run", evidence_id: String(green.evidence_id ?? ""), phase: green.phase, semantic_status: green.semantic_status })),
-        ...active_pre_edit_input_refs(evidences, active),
-    ]))
-        return false;
-    const currentFreshness = compute_apply_worker_freshness(repoRoot, changeRoot, evidences, taskId, chainId, {
-        executor_report_ref: ev.executor_report_ref,
-        task_code_review_report_ref: ev.task_code_review_report_ref,
-        green_test_run_evidence_ref: greenIds[0],
-        green_test_run_evidence_refs: greenIds,
-        verifier_report_ref: ev.verifier_report_ref,
-    });
-    if (Array.isArray(currentFreshness.unexpected_guard_owned_dirty_paths) && currentFreshness.unexpected_guard_owned_dirty_paths.length > 0)
-        return false;
-    if (Array.isArray(currentFreshness.protected_dirty_paths) && currentFreshness.protected_dirty_paths.length > 0)
-        return false;
-    if (!greenRuns.every((green) => fingerprint_matches(green.implementation_fingerprint, currentFreshness.implementation_fingerprint)))
-        return false;
-    if (!fingerprint_matches(isObject(ev.task_code_review_report_ref) ? ev.task_code_review_report_ref.observed_implementation_fingerprint : undefined, currentFreshness.implementation_fingerprint))
-        return false;
-    return fingerprint_matches(currentFreshness, verifierObserved);
-}
-function pinned_takeover_baseline_valid(changeRoot, refItem, taskId, chainId) {
-    return shared_pinned_artifact_ref_reasons(changeRoot, refItem, "serial_takeover_baseline_ref", { kind: "status_report", role: "verifier", taskId, chainId }).length === 0;
-}
-function abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, active, taskId, chainId) {
-    if (!active)
-        return false;
-    if ("restored_implementation_fingerprint" in ev) {
-        const activeScope = Array.isArray(active.declared_task_write_scope) ? active.declared_task_write_scope.map(String).filter(Boolean) : [];
-        const current = apply_worker_implementation_fingerprint(repoRoot, changeRoot, [], { declaredTaskWriteScope: activeScope });
-        if (fingerprint_matches(ev.restored_implementation_fingerprint, active.source_implementation_fingerprint)
-            && fingerprint_matches(current, active.source_implementation_fingerprint))
-            return true;
-    }
-    if ("serial_takeover_baseline_ref" in ev) {
-        return pinned_takeover_baseline_valid(changeRoot, ev.serial_takeover_baseline_ref, taskId, chainId)
-            && Array.isArray(ev.successor_green_evidence_refs)
-            && ev.successor_green_evidence_refs.length > 0
-            && ev.successor_green_evidence_refs.every((item) => typeof item === "string" && item.length > 0);
-    }
-    return false;
-}
-function serial_completion_green(ev) {
-    return (ev.runner_origin === undefined || ev.runner_origin === "main-thread")
-        && ev.apply_execution_chain !== "executor_worker"
-        && typeof ev.apply_worker_chain_id !== "string";
-}
-function apply_worker_chain_completion_state(repoRoot, changeRoot, evidences, taskId) {
-    const chains = find_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId });
-    const activeByChain = new Map();
-    const activeCounts = new Map();
-    for (const ev of chains) {
-        if (String(ev.chain_state ?? "") !== "active")
-            continue;
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        if (!chainId)
-            continue;
-        const bucket = activeCounts.get(chainId) ?? [];
-        bucket.push(ev);
-        activeCounts.set(chainId, bucket);
-        if (!activeByChain.has(chainId))
-            activeByChain.set(chainId, ev);
-    }
-    const chainIdsWithActive = new Set([...activeByChain.keys()]);
-    const chainIdsWithTerminal = new Set(chains
-        .filter((ev) => {
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        if (!chainId)
-            return false;
-        if (String(ev.chain_state ?? "") === "closed")
-            return closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
-        if (String(ev.chain_state ?? "") === "abandoned")
-            return abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, activeByChain.get(chainId), taskId, chainId);
-        return false;
-    })
-        .map((ev) => String(ev.apply_worker_chain_id ?? ""))
-        .filter(Boolean));
-    const chainIdsWithOpenActive = new Set([...activeByChain.keys()].filter((chainId) => !chainIdsWithTerminal.has(chainId)));
-    const validClosedChainIds = new Set(chains
-        .filter((ev) => {
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        return chainId
-            && String(ev.chain_state ?? "") === "closed"
-            && closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
-    })
-        .map((ev) => String(ev.apply_worker_chain_id ?? ""))
-        .filter(Boolean));
-    const validClosedGreenEvidenceIds = new Set(chains
-        .filter((ev) => {
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        return chainId
-            && String(ev.chain_state ?? "") === "closed"
-            && closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
-    })
-        .flatMap(chain_green_ids));
-    const takeoverBaselines = [];
-    const reasons = [];
-    const duplicateActives = [...activeCounts.entries()]
-        .filter(([chainId]) => chainIdsWithOpenActive.has(chainId))
-        .map(([, items]) => items)
-        .filter((items) => items.length > 1)
-        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
-        .filter(Boolean)
-        .sort();
-    const openActiveValues = [...chainIdsWithOpenActive].map((chainId) => activeByChain.get(chainId)).filter((ev) => isObject(ev));
-    const parallelActives = openActiveValues.length > 1
-        ? openActiveValues.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")).filter(Boolean).sort()
-        : [];
-    const activeConflicts = [...new Set([...duplicateActives, ...parallelActives])].sort();
-    if (activeConflicts.length > 0) {
-        reasons.push(reason("apply_worker_chain_active_conflict", `task ${taskId} has conflicting active apply worker chain markers: ${renderList(activeConflicts)}`, activeConflicts));
-    }
-    const terminalsByChain = new Map();
-    for (const ev of chains) {
-        const state = String(ev.chain_state ?? "");
-        if (state !== "closed" && state !== "abandoned")
-            continue;
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        if (!chainId)
-            continue;
-        const bucket = terminalsByChain.get(chainId) ?? [];
-        bucket.push(ev);
-        terminalsByChain.set(chainId, bucket);
-    }
-    const duplicateTerminals = [...terminalsByChain.values()]
-        .filter((items) => items.length > 1)
-        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
-        .filter(Boolean)
-        .sort();
-    if (duplicateTerminals.length > 0) {
-        reasons.push(reason("apply_worker_chain_terminal_conflict", `task ${taskId} has duplicate apply worker chain terminal markers: ${renderList(duplicateTerminals)}`, duplicateTerminals));
-    }
-    const invalidTerminals = chains
-        .filter((ev) => String(ev.chain_state ?? "") === "closed" || String(ev.chain_state ?? "") === "abandoned")
-        .filter((ev) => {
-        const chainId = String(ev.apply_worker_chain_id ?? "");
-        if (!chainId)
-            return true;
-        if (String(ev.chain_state ?? "") === "closed")
-            return !closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
-        const valid = abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, activeByChain.get(chainId), taskId, chainId);
-        if (valid && isObject(ev.serial_takeover_baseline_ref)) {
-            const baseline = read_pinned_artifact_json(changeRoot, ev.serial_takeover_baseline_ref);
-            if (baseline?.implementation_fingerprint !== undefined) {
-                takeoverBaselines.push({
-                    fingerprint: baseline.implementation_fingerprint,
-                    successorGreenRefs: Array.isArray(ev.successor_green_evidence_refs) ? ev.successor_green_evidence_refs.map(String).filter(Boolean) : [],
-                });
-            }
-        }
-        return !valid;
-    })
-        .map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? ""))
-        .filter(Boolean)
-        .sort();
-    if (invalidTerminals.length > 0) {
-        reasons.push(reason("apply_worker_chain_terminal_invalid", `task ${taskId} has invalid apply worker chain terminal markers: ${renderList(invalidTerminals)}`, invalidTerminals));
-    }
-    for (const chainId of [...chainIdsWithOpenActive].sort()) {
-        if (!chainIdsWithTerminal.has(chainId)) {
-            reasons.push(reason("apply_worker_chain_active", `task ${taskId} has active apply worker chain and cannot use non-chain task completion: ${chainId}`, [chainId]));
-        }
-    }
-    for (const ev of evidences) {
-        if (!isObject(ev) || ev._invalid || ev.status !== "pass" || ev.task_id !== taskId)
-            continue;
-        const chainId = typeof ev.apply_worker_chain_id === "string" ? ev.apply_worker_chain_id : "";
-        if (!chainId)
-            continue;
-        if (!chainIdsWithActive.has(chainId)) {
-            reasons.push(reason("apply_worker_chain_missing_active", `task ${taskId} references apply_worker_chain_id=${repr(chainId)} without a matching active marker`, [chainId]));
-        }
-    }
-    if (duplicateTerminals.length > 0 || activeConflicts.length > 0) {
-        validClosedChainIds.clear();
-        validClosedGreenEvidenceIds.clear();
-    }
-    return { reasons, validClosedChainIds, validClosedGreenEvidenceIds, takeoverBaselines };
-}
 export function apply_worker_chain_lifecycle_reasons(repoRoot, changeRoot, evidences, taskId) {
-    return apply_worker_chain_completion_state(repoRoot, changeRoot, evidences, taskId).reasons;
+    return shared_apply_worker_chain_lifecycle_reasons(repoRoot, changeRoot, evidences, taskId);
 }
 export function check_task_complete(change, status, changeRoot, evidences, taskId) {
     const gate = "task_complete";
@@ -1413,8 +1163,8 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
     const task = parse_tasks(changeRoot)[taskId];
     if (!task)
         return block(change, gate, [reason("unknown_task", `task ${taskId} not found`)], { task_id: taskId });
-    const workerChainState = apply_worker_chain_completion_state(get_repo_root(status), changeRoot, evidences, taskId);
-    reasons.push(...workerChainState.reasons);
+    const workerChainState = apply_worker_chain_lifecycle_state(get_repo_root(status), changeRoot, evidences, taskId);
+    reasons.push(...workerChainState.completionReasons);
     const reopenHistory = task_reopen_history(evidences, taskId);
     if (task.checked && reopenHistory.pass.length > 1) {
         reasons.push(reason("reopen_lifecycle_exhausted", `task ${taskId} has multiple task_reopen histories in this change; v1 allows at most one`, [taskId]));

package/dist/src/hooks/adapter.d.ts

@@ -0,0 +1,5 @@
+export declare function runHookAdapter(argv?: string[], stdin?: string): {
+    code: number;
+    stdout: string;
+    stderr: string;
+};

package/dist/src/hooks/adapter.js

@@ -0,0 +1,311 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { isObject } from "../util.js";
+import { hookCheckCommand, hookCheckWrite, hookRecordSubagentStart, hookRecordSubagentStop, hookRecordTest, } from "./guard_api.js";
+import { commandLooksLikeTestValidation, extractWriteIntent, isSuperSpecTrustRootPath } from "./policy_event.js";
+function parseArgs(argv) {
+    let change = process.env.SUPERSPEC_CHANGE || null;
+    for (let idx = 0; idx < argv.length; idx += 1) {
+        if (argv[idx] === "--change")
+            change = argv[idx + 1] || null;
+    }
+    return { change };
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readJson(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function validReasonArray(value) {
+    return Array.isArray(value) && value.every((item) => (isObject(item)
+        && typeof item.code === "string"
+        && item.code.length > 0
+        && typeof item.message === "string"
+        && item.message.length > 0
+        && Array.isArray(item.refs)
+        && item.refs.every((ref) => typeof ref === "string")));
+}
+function validActiveSessionRecord(path, change, repoRoot, event) {
+    const record = readJson(path);
+    if (!record)
+        return false;
+    if (record.schema_version !== 2 || record.kind !== "hook_active_session")
+        return false;
+    if (record.trust !== "audit-only" && record.trust !== "trusted")
+        return false;
+    if (record.strict_profile !== "available" && record.strict_profile !== "unavailable")
+        return false;
+    if (record.change_id !== change)
+        return false;
+    if (resolve(String(record.repo_root ?? "")) !== resolve(repoRoot))
+        return false;
+    if (typeof record.session_id !== "string" || !record.session_id)
+        return false;
+    if (!validReasonArray(record.audit_only_reasons))
+        return false;
+    const eventSessionId = typeof event.session_id === "string" && event.session_id ? event.session_id : "";
+    const auditRepoChangeLeaseFallback = record.trust === "audit-only"
+        && record.strict_profile === "unavailable"
+        && record.session_id === "manual-cli-session";
+    if (eventSessionId && record.session_id !== eventSessionId && !auditRepoChangeLeaseFallback)
+        return false;
+    const expiresAt = Date.parse(String(record.expires_at ?? ""));
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now())
+        return false;
+    return true;
+}
+function inferChangeFromActiveSessions(event) {
+    const repoRoot = findRepoRootFromCwd(event);
+    const changesDir = join(repoRoot, "openspec", "changes");
+    if (!isDir(changesDir))
+        return { state: "none" };
+    const candidates = readdirSync(changesDir).filter((change) => {
+        const runtimeDir = join(changesDir, change, ".superspec", "hook-runtime");
+        const activeDir = join(changesDir, change, ".superspec", "hook-runtime", "active-sessions");
+        if (isDir(activeDir) && readdirSync(activeDir).some((name) => (name.endsWith(".json") && validActiveSessionRecord(join(activeDir, name), change, repoRoot, event))))
+            return true;
+        return isDir(runtimeDir);
+    });
+    const unique = [...new Set(candidates)];
+    if (unique.length === 1)
+        return { state: "unique", change: unique[0] };
+    if (unique.length > 1)
+        return { state: "ambiguous", changes: unique.sort() };
+    return { state: "none" };
+}
+function cwdRoot(event) {
+    return typeof event.cwd === "string" && event.cwd ? resolve(event.cwd) : process.cwd();
+}
+function findRepoRootFromCwd(event) {
+    let dir = cwdRoot(event);
+    while (true) {
+        if ((isDir(join(dir, "openspec")) || isDir(join(dir, ".codex"))) && statMaybe(join(dir, "package.json")) === "file")
+            return dir;
+        if (isDir(join(dir, "openspec", "changes")) || isDir(join(dir, ".codex")))
+            return dir;
+        if (statMaybe(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return cwdRoot(event);
+        dir = parent;
+    }
+}
+function passThrough(message) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: message,
+        },
+    };
+}
+function statMaybe(path) {
+    try {
+        const st = statSync(path);
+        if (st.isFile())
+            return "file";
+        if (st.isDirectory())
+            return "dir";
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function denyPreToolUse(reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    };
+}
+function isTestValidationCommand(event) {
+    if (String(event.tool_name ?? "") !== "Bash")
+        return false;
+    const toolInput = isObject(event.tool_input) ? event.tool_input : {};
+    const command = typeof toolInput.command === "string" ? toolInput.command : "";
+    return commandLooksLikeTestValidation(command);
+}
+function inertPostToolUseOutput() {
+    return {
+        systemMessage: "SuperSpec hook ignored non-test command; no test telemetry was recorded.",
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: "SuperSpec runtime telemetry is inert for non-test commands.",
+        },
+    };
+}
+function noChangeFallback(event, inference) {
+    if (String(event.hook_event_name ?? "PreToolUse") !== "PreToolUse") {
+        return { systemMessage: "SuperSpec hook inert: SUPERSPEC_CHANGE/--change not set" };
+    }
+    const intent = extractWriteIntent(event, findRepoRootFromCwd(event));
+    const writeCapable = intent.target_paths.length > 0
+        || intent.archive_command
+        || intent.internal_hook_writer_command
+        || intent.unsupported_write_surface
+        || intent.shell_write_command
+        || intent.reasons.length > 0
+        || ["apply_patch", "Edit", "Write"].includes(String(event.tool_name ?? ""));
+    if (inference.state === "ambiguous" && writeCapable) {
+        return denyPreToolUse(`blocked by SuperSpec hook policy: multiple active SuperSpec sessions (${inference.changes.join(", ")}); set SUPERSPEC_CHANGE or close stale leases`);
+    }
+    if (intent.internal_hook_writer_command) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: internal hook writer invocation requires Guard-owned hook authority");
+    }
+    if (intent.unsafe_lifecycle_termination_command) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: hook session cancellation requires trusted terminal authority");
+    }
+    if (intent.reasons.some((item) => item.code === "target_path_outside_repo")) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: write target escapes the current repository root");
+    }
+    if (intent.reasons.some((item) => item.code === "protected_trust_root_link_source")) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: link source points at a SuperSpec trust root");
+    }
+    if (intent.reasons.some((item) => item.code === "shell_path_may_touch_trust_root")) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: shell-expanded path may touch SuperSpec trust roots");
+    }
+    if (intent.reasons.some((item) => item.code === "curl_config_write_target_unknown")) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: curl config-driven writes have unknown targets");
+    }
+    if (intent.reasons.some((item) => item.code === "curl_write_target_unknown")) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: curl write options have unknown targets");
+    }
+    if (intent.target_paths.some((path) => isSuperSpecTrustRootPath(path))) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: direct writes to SuperSpec trust roots require an active Guard context");
+    }
+    if (intent.shell_write_command && intent.trust_root_text_matches.length > 0) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: pathless write-capable command appears to touch SuperSpec trust roots");
+    }
+    if (intent.archive_command) {
+        return denyPreToolUse("blocked by SuperSpec hook policy: openspec archive requires an active Guard context and archive_ready allow");
+    }
+    return passThrough("SuperSpec hook inert: SUPERSPEC_CHANGE/--change not set");
+}
+function preToolUseOutput(decision) {
+    if (!decision.allowed) {
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: decision.block_reasons.map((item) => item.message).join("; ") || "blocked by SuperSpec hook policy",
+            },
+        };
+    }
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: `SuperSpec hook ${decision.enforcement}; strict_profile=${decision.strict_profile}; trust=${decision.trust}`,
+        },
+    };
+}
+function postToolUseOutput(decision) {
+    return {
+        systemMessage: `SuperSpec hook telemetry recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: `SuperSpec runtime evidence is ${decision.strict_profile === "available" ? "runtime-verified" : "audit-only"}.`,
+        },
+    };
+}
+function subagentOutput(decision, eventName) {
+    return {
+        systemMessage: `SuperSpec ${eventName} runlog recorded as ${decision.trust}; strict_profile=${decision.strict_profile}`,
+    };
+}
+function writeTempEvent(event) {
+    const path = join(tmpdir(), `superspec-hook-event-${randomUUID()}.json`);
+    writeFileSync(path, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    return path;
+}
+function validateHookEvent(event) {
+    const eventName = typeof event.hook_event_name === "string" ? event.hook_event_name : "";
+    if (!eventName)
+        return "hook event missing required hook_event_name";
+    if (!["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop"].includes(eventName)) {
+        return `unsupported hook_event_name: ${eventName}`;
+    }
+    if (typeof event.cwd !== "string" || !event.cwd)
+        return "hook event missing required cwd";
+    if (eventName === "PreToolUse") {
+        if (typeof event.tool_name !== "string" || !event.tool_name)
+            return "PreToolUse hook event missing required tool_name";
+        if (!isObject(event.tool_input))
+            return "PreToolUse hook event missing required tool_input object";
+    }
+    return null;
+}
+export function runHookAdapter(argv = process.argv.slice(2), stdin = readFileSync(0, "utf8")) {
+    const parsedArgs = parseArgs(argv);
+    let event;
+    try {
+        if (!stdin.trim())
+            throw new Error("hook stdin is empty");
+        const parsed = JSON.parse(stdin);
+        if (!isObject(parsed))
+            throw new Error("hook stdin must be a JSON object");
+        event = parsed;
+        const validationError = validateHookEvent(event);
+        if (validationError)
+            throw new Error(validationError);
+    }
+    catch (err) {
+        return { code: 2, stdout: "", stderr: `SuperSpec hook event parse failed: ${err.message}\n` };
+    }
+    const inference = parsedArgs.change ? { state: "unique", change: parsedArgs.change } : inferChangeFromActiveSessions(event);
+    const change = inference.state === "unique" ? inference.change : null;
+    if (!change) {
+        const payload = noChangeFallback(event, inference);
+        return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+    }
+    const eventRef = writeTempEvent(event);
+    try {
+        const eventName = String(event.hook_event_name ?? "");
+        let payload;
+        if (eventName === "PreToolUse") {
+            const toolName = String(event.tool_name ?? "");
+            const decision = toolName === "Bash" ? hookCheckCommand(change, eventRef) : hookCheckWrite(change, eventRef);
+            payload = preToolUseOutput(decision);
+        }
+        else if (eventName === "PostToolUse") {
+            payload = isTestValidationCommand(event) ? postToolUseOutput(hookRecordTest(change, eventRef)) : inertPostToolUseOutput();
+        }
+        else if (eventName === "SubagentStart") {
+            payload = subagentOutput(hookRecordSubagentStart(change, eventRef), "SubagentStart");
+        }
+        else if (eventName === "SubagentStop") {
+            payload = subagentOutput(hookRecordSubagentStop(change, eventRef), "SubagentStop");
+        }
+        else {
+            payload = { systemMessage: `SuperSpec hook ignored unsupported event ${eventName}` };
+        }
+        return { code: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+    }
+    catch (err) {
+        return { code: 2, stdout: "", stderr: `SuperSpec hook failed closed: ${err.message}\n` };
+    }
+    finally {
+        try {
+            unlinkSync(resolve(eventRef));
+        }
+        catch {
+            // best effort temp cleanup
+        }
+    }
+}

package/dist/src/hooks/guard_api.d.ts

@@ -0,0 +1,12 @@
+import type { Reason } from "../util.ts";
+import type { HookDecision } from "./types.ts";
+export declare function hookCheckWrite(change: string, eventRef: string): HookDecision;
+export declare function hookCheckCommand(change: string, eventRef: string): HookDecision;
+export declare function hookHealth(change: string): HookDecision;
+export declare function hookSessionBegin(change: string, workflow: string, _entrypointToken: string): HookDecision;
+export declare function hookSessionStatus(change: string): HookDecision;
+export declare function hookSessionEnd(change: string, endReason: string, _lifecycleToken: string): HookDecision;
+export declare function hookRecordTest(change: string, eventRef: string): HookDecision;
+export declare function hookRecordSubagentStart(change: string, eventRef: string): HookDecision;
+export declare function hookRecordSubagentStop(change: string, eventRef: string): HookDecision;
+export declare function hookInitReasons(repoRoot: string): Reason[];