@peterxiaoyang/superspec 0.1.7 → 0.1.9

package/README.md

@@ -82,6 +82,8 @@ superspec init --scope project
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
 
+初始化还会安装托管的 `.codex/hooks.json`。它会让 Codex 在写文件前、工具执行后、子智能体启动和停止时调用 SuperSpec，做检查和记录。
+
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
 ```powershell
@@ -157,6 +159,18 @@ openspec/changes/<变更ID>/.superspec/
 `.superspec/` 要不要提交到 git，由你的团队决定。
 如果不提交，删掉后就没有 git 历史可以恢复。
 
+## Hook 会做什么
+
+SuperSpec 安装的 hook 会在几个关键时机运行：
+
+- 写文件前：检查是否会改到 SuperSpec 的过程记录、提前归档、绕过任务检查，或写到当前任务不该写的地方
+- 工具执行后：如果刚跑的是测试或验证命令，就记录这次结果
+- 子智能体启动和停止时：记录这次子智能体运行的基本信息
+
+这些 hook 的默认超时时间是 `120` 秒。这个时间限制的是 hook 自己的检查过程，不限制 `npm test`、构建命令或子智能体本身能运行多久。
+
+hook 不是安全沙箱。它能减少误操作、拦住一部分明显会破坏流程记录的写入，并留下审计线索；但不能保证阻止所有绕过，也不能把记录变成不可伪造的安全证明。
+
 ## 重要边界
 
 SuperSpec 能让流程更规范，但它不是安全锁。
@@ -175,7 +189,7 @@ SuperSpec 能让流程更规范，但它不是安全锁。
 - 阻止恶意伪造记录
 - 替代正式的安全审计、合规审计或法律证明
 
-也就是说，SuperSpec v1 是“流程纪律工具”，不是“强制安全系统”。
+也就是说，SuperSpec 目前是“流程纪律 + 审计辅助工具”，不是“强制安全系统”。hook 会增强可见性和一部分写入检查，但它仍然不能替代正式的安全控制。
 
 ## 常用命令
 
@@ -223,6 +237,7 @@ superspec doctor
 
 ```text
 .codex/
+  hooks.json
   skills/superspec-explore/
   skills/superspec-propose/
   skills/superspec-apply/

package/adapters/codex/install-map.json

@@ -27,6 +27,11 @@
       "source": "templates/workflow/skills/superspec-archive/SKILL.md",
       "target": ".codex/skills/superspec-archive/SKILL.md"
     },
+    {
+      "kind": "hook",
+      "source": "templates/hooks/codex-hooks.json",
+      "target": ".codex/hooks.json"
+    },
     {
       "kind": "prompt",
       "source": "templates/workflow/prompts/architect.md",

package/bin/superspec-hook.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntry } from "./launch.js";
+
+await runEntry("../dist/superspec_hook.js", "main_hook");

package/dist/src/archive.js

@@ -35,6 +35,8 @@ function write_text(path, text) {
 function excluded_manifest_entry(relPath) {
     if (relPath.endsWith(STATE_LOCK_FILENAME) || relPath.endsWith("superspec-state.tmp"))
         return true;
+    if (relPath === ".superspec/hook-runtime" || relPath.startsWith(".superspec/hook-runtime/"))
+        return true;
     if (relPath === ".superspec/artifacts/archive-preservation.json")
         return true;
     return false;

package/dist/src/cli_args.d.ts

@@ -9,6 +9,11 @@ export type ParsedArgs = {
     task_id?: string;
     test_id?: string;
     phase?: "red" | "characterization" | "green";
+    event_ref?: string;
+    workflow?: string;
+    entrypoint_token?: string;
+    end_reason?: string;
+    lifecycle_token?: string;
     role?: string;
     evidence_kind?: string;
     round?: number;

package/dist/src/cli_args.js

@@ -11,6 +11,8 @@ const SIMPLE_COMMANDS = [
     "check-verify-ready",
     "check-archive-ready",
     "check-archived",
+    "hook-health",
+    "hook-session-status",
 ];
 const COMMANDS = [
     "init",
@@ -27,6 +29,13 @@ const COMMANDS = [
     "apply-code-review-packet",
     "apply-verify-packet",
     "ledger-render",
+    "hook-check-write",
+    "hook-check-command",
+    "hook-record-test",
+    "hook-record-subagent-start",
+    "hook-record-subagent-stop",
+    "hook-session-begin",
+    "hook-session-end",
 ];
 const COMMAND_LIST = COMMANDS.join(",");
 const COMMAND_CHOICES = COMMANDS.map((item) => `'${item}'`).join(", ");
@@ -61,6 +70,13 @@ function requiredValueFlags(command) {
         flags.push("--task-id", "--executor-report-ref", "--task-code-review-report-ref", "--green-test-run-evidence-ref");
     if (command === "ledger-render")
         flags.push("--gate");
+    if (command === "hook-check-write" || command === "hook-check-command" || command === "hook-record-test"
+        || command === "hook-record-subagent-start" || command === "hook-record-subagent-stop")
+        flags.push("--event-ref");
+    if (command === "hook-session-begin")
+        flags.push("--workflow", "--entrypoint-token");
+    if (command === "hook-session-end")
+        flags.push("--reason");
     return flags;
 }
 function requiredBooleanFlags(command) {
@@ -84,6 +100,8 @@ function optionalValueFlags(command) {
         return ["--red-test-run-evidence-ref", "--characterization-test-run-evidence-ref"];
     if (command === "ledger-render")
         return ["--round"];
+    if (command === "hook-session-end")
+        return ["--lifecycle-token"];
     return [];
 }
 function formatUsage(command) {
@@ -376,6 +394,29 @@ export function parse_argv(argv) {
             throw new GuardError("--round 必须是大于等于 1 的整数");
         return { command, change, gate, round };
     }
+    if (command === "hook-check-write" || command === "hook-check-command" || command === "hook-record-test"
+        || command === "hook-record-subagent-start" || command === "hook-record-subagent-stop") {
+        const eventRef = getValue("--event-ref");
+        if (!eventRef)
+            throw new Error("缺少必填参数 --event-ref");
+        return { command, change, format, event_ref: eventRef };
+    }
+    if (command === "hook-session-begin") {
+        const workflow = getValue("--workflow");
+        const entrypointToken = getValue("--entrypoint-token");
+        if (!workflow)
+            throw new Error("缺少必填参数 --workflow");
+        if (!entrypointToken)
+            throw new Error("缺少必填参数 --entrypoint-token");
+        return { command, change, format, workflow, entrypoint_token: entrypointToken };
+    }
+    if (command === "hook-session-end") {
+        const endReason = getValue("--reason");
+        const lifecycleToken = getValue("--lifecycle-token");
+        if (!endReason)
+            throw new Error("缺少必填参数 --reason");
+        return { command, change, format, end_reason: endReason, lifecycle_token: lifecycleToken ?? "" };
+    }
     if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete") {
         const taskId = getValue("--task-id");
         if (!taskId)

package/dist/src/core.js

@@ -23,6 +23,7 @@ import { dirty_worktree_paths, dirty_worktree_reasons, dirty_write_scope_red_rea
 import { append_ledger, load_state, compute_fingerprints, prepare_recomputed_state_write, read_ledger_text, record_supersede_ledger_events, restore_state_snapshot_locked, state_corrupt_reasons, state_file, state_file_corrupt, state_stale_reasons, force_unlock_state, with_state_lock, write_prepared_state_locked, } from "./state.js";
 import { archive_manifest_path, begin_archive_preservation_bundle, check_archived, preset_upgrade_reasons, preset_upgrade_required_from_context, write_archive_preservation_bundle, } from "./archive.js";
 import { check_archive_ready, check_apply_ready, check_artifact, check_init, check_superspec_gate, check_review_complete, check_review_ready, check_task_complete, check_task_edit, check_task_reopen, check_verify_complete, evidence_schema_guard, superspec_agent_reasons, superspec_workflow_skill_reasons, openspec_cli_capability_reasons, openspec_init_reasons, } from "./gates.js";
+import { hookCheckCommand, hookCheckWrite, hookHealth, hookRecordSubagentStart, hookRecordSubagentStop, hookRecordTest, hookSessionBegin, hookSessionEnd, hookSessionStatus, } from "./hooks/guard_api.js";
 const RETRY_WAIT = new Int32Array(new SharedArrayBuffer(4));
 const DEFAULT_MAX_STATE_WRITE_RETRIES = 5;
 function sleep_ms(ms) {
@@ -42,6 +43,39 @@ export function load_context(change) {
     const evidences = index_evidence(changeRoot);
     return [status, repoRoot, changeRoot, evidences];
 }
+function is_hook_command(command) {
+    return command === "hook-check-write"
+        || command === "hook-check-command"
+        || command === "hook-record-test"
+        || command === "hook-record-subagent-start"
+        || command === "hook-record-subagent-stop"
+        || command === "hook-health"
+        || command === "hook-session-begin"
+        || command === "hook-session-status"
+        || command === "hook-session-end";
+}
+function dispatch_hook_command(args) {
+    const change = args.change;
+    if (args.command === "hook-check-write")
+        return [hookCheckWrite(change, args.event_ref ?? ""), "hook"];
+    if (args.command === "hook-check-command")
+        return [hookCheckCommand(change, args.event_ref ?? ""), "hook"];
+    if (args.command === "hook-record-test")
+        return [hookRecordTest(change, args.event_ref ?? ""), "hook"];
+    if (args.command === "hook-record-subagent-start")
+        return [hookRecordSubagentStart(change, args.event_ref ?? ""), "hook"];
+    if (args.command === "hook-record-subagent-stop")
+        return [hookRecordSubagentStop(change, args.event_ref ?? ""), "hook"];
+    if (args.command === "hook-health")
+        return [hookHealth(change), "hook"];
+    if (args.command === "hook-session-begin")
+        return [hookSessionBegin(change, args.workflow ?? "", args.entrypoint_token ?? ""), "hook"];
+    if (args.command === "hook-session-status")
+        return [hookSessionStatus(change), "hook"];
+    if (args.command === "hook-session-end")
+        return [hookSessionEnd(change, args.end_reason ?? "", args.lifecycle_token ?? ""), "hook"];
+    throw new GuardError(`unknown hook command: ${args.command}`);
+}
 export function cmd_status(change) {
     const [status, repoRoot, changeRoot] = runtime.load_context(change);
     const amap = artifact_status_map(status);
@@ -117,6 +151,8 @@ export function cmd_init_summary(change, changeRoot, decision) {
 function dispatch_once(args) {
     const change = args.change;
     const cmd = args.command;
+    if (is_hook_command(cmd))
+        return dispatch_hook_command(args);
     if (cmd === "check-archived")
         return [check_archived(change, repo_root_from_cwd()), "archive"];
     const [status, repoRoot, changeRoot, evidences] = runtime.load_context(change);

package/dist/src/evidence.js

@@ -5,6 +5,7 @@ import { normalize_gate } from "./openspec.js";
 import { superspec_dir } from "./paths.js";
 import { findings_schema_reasons, review_digest_schema_reasons, standing_authorization_schema_reasons, user_decision_schema_reasons, } from "./disclosure.js";
 import { pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, worker_test_run_reasons, } from "./apply_worker_chain.js";
+import { strictRoleRunlogReasons, strictRuntimeEvidenceReasons } from "./hooks/validation.js";
 function file_ref_reasons(baseRoot, ev, field, code) {
     const problems = [];
     const raw = ev[field];
@@ -509,6 +510,7 @@ export function validate_evidence_schema(ev, change, changeRoot, repoRoot) {
         problems.push(...human_confirmation_reasons(ev));
     if (ev.kind === "test_run")
         problems.push(...test_run_reasons(ev, changeRoot));
+    problems.push(...strictRuntimeEvidenceReasons(ev));
     if (ev.kind === "apply_worker_chain")
         problems.push(...apply_worker_chain_reasons(ev, changeRoot));
     // DISC Phase 1: disclosure evidence kinds and reviewer findings[] are schema-checked fail-closed.
@@ -556,6 +558,7 @@ export function validate_evidence_schema(ev, change, changeRoot, repoRoot) {
         const targetRoot = ev.kind === "source_guidance" ? repoRoot : changeRoot;
         problems.push(...role_target_ref_reasons(ev, targetRoot));
         problems.push(...output_ref_target_overlap_reasons(ev, changeRoot, targetRoot));
+        problems.push(...strictRoleRunlogReasons(changeRoot, ev));
     }
     if (ev.kind === "source_guidance") {
         if (!REVIEW_GUIDANCE_ROLES.includes(String(ev.agent_role))) {

package/dist/src/gates.js

@@ -3,6 +3,7 @@ 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, 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";
@@ -427,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)

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[];