vigiles 2.5.0 → 3.0.0

package/skills/strengthen/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: strengthen
+description: Upgrade guidance() rules to enforce() by finding existing linter rules that match
+disable-model-invocation: true
+---
+
+Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.
+
+## Instructions
+
+### Step 0: Choose Mode
+
+Ask the user:
+
+> **Auto or interactive?**
+>
+> - **Auto** — I'll apply all safe changes (direct replacements where the rule is already enabled), commit, and show you the diff. Risky changes (require config edits or plugin installs) go in a summary for you to review.
+> - **Interactive** — I'll present each suggestion and you pick which ones to apply.
+
+Default to interactive if the user doesn't specify.
+
+### Step 1: Discover What's Installed
+
+Run `npx vigiles generate-types` to get the full list of enabled linter rules in the project. Read `.vigiles/generated.d.ts` to see every rule available across all detected linters.
+
+Note which linter prefixes appear in the generated types (e.g., `EslintRule`, `RuffRule`). You'll only need reference docs for detected linters.
+
+### Step 2: Find All Guidance Rules
+
+Find all `.spec.ts` files in the project (`**/*.md.spec.ts`). For each file, identify every `guidance()` rule.
+
+### Step 3: Match Against Generated Types (Fast Path)
+
+For each guidance rule, check if an enabled rule in `.vigiles/generated.d.ts` directly matches. This is the fast, deterministic path — no doc reading needed.
+
+Look for:
+
+- **Exact rule name in text** — guidance says "no-console" and `no-console` is in EslintRule
+- **Semantic match** — guidance says "don't use console.log" and `no-console` is available
+- **Rule description match** — guidance says "unused variables" and `no-unused-vars` or `@typescript-eslint/no-unused-vars` is available
+
+If a match is found and the rule is in the generated types (meaning it's already enabled), this is a **direct replacement** — no config changes needed.
+
+### Step 4: Read Linter Docs (Slow Path)
+
+For guidance rules that didn't match in Step 3, read the linter reference docs for the project's detected linters:
+
+- ESLint → `../linter-docs/eslint.md`
+- Stylelint → `../linter-docs/stylelint.md`
+- Ruff → `../linter-docs/ruff.md`
+- Pylint → `../linter-docs/pylint.md`
+- RuboCop → `../linter-docs/rubocop.md`
+- Clippy → `../linter-docs/clippy.md`
+
+**Only read docs for linters the project actually uses.** Skip docs for linters with no rules in generated types.
+
+Check the plugin tables and decision matrices. The guidance text may describe a pattern covered by:
+
+- A plugin rule that's installed but not enabled
+- A plugin that's not installed yet
+- A `no-restricted-*` config pattern (see Step 4b)
+
+### Step 4b: `no-restricted-*` Patterns
+
+Many guidance rules can be enforced via built-in linter config without a custom rule. This is the most common strengthen pattern — "don't do X" maps to a restriction config.
+
+**ESLint:**
+
+```js
+// "Don't import from internal modules"
+"no-restricted-imports": ["error", {
+  patterns: [{ group: ["src/internal/*"], message: "Use the public API." }]
+}],
+
+// "Don't call console.log"
+"no-restricted-syntax": ["error", {
+  selector: 'CallExpression[callee.object.name="console"]',
+  message: "Use the project logger."
+}],
+
+// "Don't use moment.js"
+"no-restricted-imports": ["error", {
+  paths: [{ name: "moment", message: "Use dayjs instead." }]
+}],
+```
+
+**Ruff:**
+
+```toml
+# "Don't use os.system"
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"os.system".msg = "Use subprocess.run instead."
+```
+
+**RuboCop:**
+
+```yaml
+# "Don't use puts in production" — if Rails/Output doesn't fit
+Custom/NoPuts:
+  Enabled: true
+```
+
+When suggesting a `no-restricted-*` change:
+
+1. Show the exact config edit needed (which file, which section)
+2. Show the `enforce()` rule that references it
+3. Note that this changes linter config, not just the spec
+
+### Step 5: Present Suggestions
+
+Group the output into tiers:
+
+**Tier 1: Direct replacements** (rule already enabled — zero risk)
+
+```typescript
+// Before
+"no-console": guidance("Use structured logger instead of console.log"),
+// After
+"no-console": enforce("eslint/no-console", "Use structured logger instead of console.log"),
+```
+
+**Tier 2: Config-backed** (rule exists but needs config options)
+
+```typescript
+// Spec change:
+"no-moment": enforce("eslint/no-restricted-imports", "Use dayjs instead of moment."),
+
+// Config change needed (eslint.config.mjs):
+"no-restricted-imports": ["error", {
+  paths: [{ name: "moment", message: "Use dayjs instead." }]
+}],
+```
+
+**Tier 3: Plugin install needed**
+
+```
+"cognitive-complexity": guidance("Keep functions simple")
+→ Install eslint-plugin-sonarjs, enable sonarjs/cognitive-complexity
+→ enforce("eslint/sonarjs/cognitive-complexity", "Keep functions simple")
+```
+
+**Tier 4: No match** (stays as guidance, or candidate for `/pr-to-lint-rule`)
+
+```
+"research-first": guidance("Google unfamiliar APIs first.")
+→ No linter rule can enforce this. Stays as guidance.
+→ Want me to run /pr-to-lint-rule to create a custom rule?
+```
+
+### Step 6: Apply Changes
+
+**In auto mode:**
+
+1. Apply all Tier 1 changes (edit spec files, replace `guidance()` with `enforce()`)
+2. Run `npm run build && npx vigiles compile` to verify each change compiles
+3. If any compilation fails, revert that specific change and report the error
+4. Commit all successful changes
+5. Present Tier 2-4 as a summary for the user to review
+
+**In interactive mode:**
+
+1. Present all tiers
+2. Ask the user which suggestions to apply
+3. For approved Tier 2 changes: edit the linter config, then edit the spec
+4. Run `npm run build && npx vigiles compile` to verify
+5. If compilation fails, report the error and revert
+
+**For Tier 4 (no match):** Ask the user if they want to run `/pr-to-lint-rule` for any of the unmatched rules to create custom rules.

package/skills/test-harness/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: test-harness
+description: Install vigiles and test a Claude Code harness — hooks, skills, settings, CLAUDE.md — by picking the right tier (unit / deterministic / eval) and writing a test that passes. Use when the user wants to check that a hook fires or blocks, that a skill triggers, that injected context lands, or that a harness change moves what the agent does.
+---
+
+Test the Claude Code **harness** — the hooks, skills, settings, and CLAUDE.md that
+steer an agent — as the assembled machine it ships as. vigiles gives three tiers,
+cheapest first; this skill picks the right one, writes the test, and runs it.
+
+The guiding rule: **start at the cheapest tier that can answer the question, and
+climb only when it genuinely can't.** Two of the three tiers need no model and no
+API key, so they run on every commit for free — reach for the paid real-model
+tier only when the question actually requires a real model.
+
+## Step 0 — Pick the tier (the judgment call)
+
+Match what you're testing to the cheapest tier that can answer it:
+
+| What you're testing                                                                                                                    | Tier              | Cost                                             | API                                                                                           |
+| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| "Does this hook block/allow event X?" — pure hook logic, **every** event type (incl. Edit/Write, PreCompact, SessionEnd, SubagentStop) | **Unit**          | free, milliseconds, no `claude`                  | `runHook`                                                                                     |
+| "Is the hook actually **wired into** the assembled plugin and does it fire in a real session?"                                         | **Deterministic** | free, no API key (real `claude` + scripted mock) | `runHarnessTest` + `scriptModel`                                                              |
+| "Did the injected context (a SessionStart hook, a `/command`) actually **reach the model**?"                                           | **Deterministic** | free, no API key                                 | `runHarnessTest` → `trace.modelRequests` / `assertRequestContains`                            |
+| "Does this skill's **description trigger** when it should (recall) **and stay quiet** when it shouldn't (precision)?"                  | **Eval**          | **paid** (real model)                            | `measureTriggerRate` (+ `irrelevantPrompts`) → `assertTriggerRate({ min, maxFalsePositive })` |
+| "Does this harness change **move what the agent does**?" (A/B, signal vs noise)                                                        | **Eval**          | **paid** (real model)                            | `runEval` + `assertSignificant`                                                               |
+
+Most harness questions — block/allow, wired-in, context-landed — never need a
+model. Only "does the model trigger / behave differently" needs the eval tier.
+
+If the unit and deterministic tiers can both answer it, **prefer unit**: it's
+faster and reaches events the deterministic mock can't drive.
+
+## Step 1 — Ensure vigiles is installed
+
+Check whether `vigiles` is a dependency (`package.json`), and install it as a
+dev dependency if not:
+
+```bash
+npm i -D vigiles    # or: pnpm add -D vigiles / yarn add -D vigiles
+```
+
+The deterministic tier additionally needs the `claude` CLI on PATH (no API key):
+`npm i -g @anthropic-ai/claude-code`. The eval tier needs model auth. If the
+`claude` CLI is missing, you can still write and run **unit**-tier tests.
+
+## Step 2 — Locate the harness surface to test
+
+Find what the project actually ships, in this order:
+
+1. `.claude/settings.json` / `.claude/settings.local.json` — inline `hooks`.
+2. `.claude-plugin/plugin.json` — a plugin manifest (`hooks`, `skills`, `agents`, `mcpServers`).
+3. `hooks/hooks.json` — the plugin hooks convention (e.g. obra/superpowers).
+4. `skills/<name>/SKILL.md`, `agents/<name>.md`, `commands/<name>.md`.
+
+Pick one concrete thing to pin down — a specific `PreToolUse` hook, a specific
+`SessionStart` injection, a specific skill.
+
+## Step 3 — Write the test for the chosen tier
+
+**Unit (`runHook`)** — hand a hook a synthesized event, assert the decision:
+
+```ts
+import { runHook, assertHookBlocked } from "vigiles/testing";
+
+const r = runHook(hookCommand, {
+  hook_event_name: "PreToolUse",
+  tool_name: "Bash",
+  tool_input: { command: "git commit --no-verify" },
+});
+assertHookBlocked(r); // exit 2 / decision:"block" / permissionDecision:"deny"
+```
+
+Testing a hook you didn't write (a vendored third-party script)? Mark it
+`{ trusted: false }` and it runs confined under bubblewrap by default (read-only
+host, cleared env, no network egress). Add `{ recordEgress: true }` to also
+**record** what it tries to reach — `r.egress` plus `assertNoEgress(r)` /
+`assertEgressOnly(r, [...])` — the supply-chain check for "what does this skill
+phone home to / install from?". When the hook's setup needs a _real_ install,
+`{ egress: { allow: ["registry.npmjs.org"] } }` lets it reach only that
+allowlist (a packet-layer `nft` wall, so a raw socket off-list is dropped too) →
+`r.egress` (allowed hosts) + `r.egressDropped`. Be precise about the boundaries:
+see
+[`docs/sandboxing.md`](../../docs/sandboxing.md) (it blocks destruction and
+egress, but does NOT isolate reads of host files, and only under bwrap).
+
+**Deterministic (`runHarnessTest`)** — load the real plugin, drive a scripted
+mock model, assert the hook fired (or the context landed):
+
+```ts
+import {
+  runHarnessTest,
+  scriptModel,
+  assertHookFired,
+  assertRequestContains,
+} from "vigiles/testing";
+
+const r = await runHarnessTest({
+  pluginDir: "./", // or { settings: { hooks: {...} } }
+  transcript: true,
+  model: scriptModel([{ text: "ok" }]),
+});
+assertHookFired(r, "SessionStart");
+assertRequestContains(r, "expected injected text"); // did it actually land?
+```
+
+**Eval (`runEval`)** — A/B the change on vs off across real-model trials, then
+gate on significance, not eyeballing:
+
+```ts
+import { runEval, assertSignificant } from "vigiles/testing";
+
+const report = await runEval({
+  arms: { off: {}, on: { pluginDir: "./" } },
+  task: "…a task the harness change should affect…",
+  measure: (ctx) => ({ ok: /* a bare predicate over the trace */ true }),
+  trials: 6,
+  cache: "readwrite",
+});
+assertSignificant(report, { baseline: "off", arm: "on", metric: "ok" });
+```
+
+## Step 4 — Run it
+
+In a runner (node:test / vitest / jest) the tests are plain async functions. Or
+use the zero-setup CLI, which discovers and runs the files:
+
+```bash
+npx vigiles test                 # *.harness.{mjs,ts} — unit + deterministic, no API key
+npx vigiles eval --trials=6      # *.eval.{mjs,ts} — real model (local / nightly, not CI)
+```
+
+Unit-tier `runHook` tests need no `claude` and **always run** — write and run them
+even with no `claude` installed. A tier that genuinely can't run reports a loud
+`⊘ SKIPPED` (tallied separately, never a fake `✓`); a standalone script emits one
+via `skip(reason)` from `vigiles/testing`. A skip passes by default, but in a CI
+job that asserts the capability is present, run **`vigiles test --no-skip`** so a
+skipped tier fails — a green-with-skips is untested surface. Keep unit +
+deterministic tests in CI (free); run evals locally or on a schedule with auth.
+
+## When the user didn't say what to test
+
+Don't ask them to specify — **pick something real and demonstrate.** Scan the
+harness surface (Step 2), choose the cheapest meaningful test, write it, run it,
+and show the result. Good default picks, in order:
+
+1. A `PreToolUse` hook → **unit-test** that it blocks the thing it's meant to block (and allows a safe sibling).
+2. A `SessionStart` hook that injects context → **deterministic** test that the text actually reaches the model (`assertRequestContains`).
+3. A skill → **deterministic** test that it resolves via `pluginDir`, then offer the paid `measureTriggerRate` eval as a follow-up.
+
+Then say which tier you used and why, and offer to climb a tier if the cheaper
+test can't fully answer their question.
+
+## Reference
+
+The full guide — every tier, testing skills for real, "fired ≠ landed", the
+safe-by-default sandbox, the coverage matrix, and how it compares to promptfoo —
+is in [`docs/harness-testing.md`](../../docs/harness-testing.md).

package/dist/action.d.ts

@@ -1,7 +0,0 @@
-/**
- * GitHub Action entry point for vigiles.
- *
- * Runs `compile` or `audit` depending on the action input.
- */
-export {};
-//# sourceMappingURL=action.d.ts.map

package/dist/action.js

@@ -1,180 +0,0 @@
-"use strict";
-/**
- * GitHub Action entry point for vigiles.
- *
- * Runs `compile` or `audit` depending on the action input.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const node_child_process_1 = require("node:child_process");
-const glob_1 = require("glob");
-const compile_js_1 = require("./compile.js");
-// ---------------------------------------------------------------------------
-// Read action inputs
-// ---------------------------------------------------------------------------
-const command = process.env["INPUT_COMMAND"] ?? "audit";
-const pathsInput = process.env["INPUT_PATHS"];
-const maxRulesInput = process.env["INPUT_MAX-RULES"] ?? process.env["INPUT_MAX_RULES"];
-const catalogOnly = (process.env["INPUT_CATALOG-ONLY"] ??
-    process.env["INPUT_CATALOG_ONLY"] ??
-    "false") === "true";
-const maxRules = maxRulesInput ? Number(maxRulesInput) : undefined;
-// ---------------------------------------------------------------------------
-// Spec loading (from compiled dist/)
-// ---------------------------------------------------------------------------
-async function loadSpec(specPath) {
-    // Try several resolution strategies:
-    // 1. Replace /src/ with /dist/ (standard TS project layout)
-    // 2. Look under dist/ directly (root-level specs like CLAUDE.md.spec.ts)
-    // 3. Use the .js extension in-place (pre-compiled specs)
-    const jsName = specPath.replace(/\.ts$/, ".js");
-    const candidates = [
-        (0, node_path_1.resolve)(process.cwd(), jsName.replace(/\/src\//, "/dist/")),
-        (0, node_path_1.resolve)(process.cwd(), "dist", jsName),
-        (0, node_path_1.resolve)(process.cwd(), jsName),
-    ];
-    // Deduplicate (candidate 1 and 3 may match when there's no /src/)
-    const unique = [...new Set(candidates)];
-    for (const distPath of unique) {
-        if (!(0, node_fs_1.existsSync)(distPath))
-            continue;
-        try {
-            const mod = (await import(distPath));
-            // CJS modules (TypeScript with module: "Node16", no "type":
-            // "module") produce `exports["default"] = spec`, so dynamic
-            // import wraps it as `{ default: { default: spec } }`. Unwrap
-            // the double-default when present.
-            const raw = mod.default;
-            if (raw && typeof raw === "object" && "default" in raw) {
-                return raw.default;
-            }
-            return raw;
-        }
-        catch {
-            continue;
-        }
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-async function runCompile() {
-    const specs = pathsInput
-        ? pathsInput
-            .split(",")
-            .map((p) => p.trim())
-            .filter(Boolean)
-        : (0, glob_1.globSync)("**/*.spec.ts", { ignore: ["node_modules/**", "dist/**"] });
-    if (specs.length === 0) {
-        console.log("No .spec.ts files found.");
-        return true;
-    }
-    let allValid = true;
-    const basePath = process.cwd();
-    for (const specPath of specs) {
-        const spec = await loadSpec(specPath);
-        if (!spec) {
-            console.log(`::error file=${specPath}::Failed to load spec`);
-            allValid = false;
-            continue;
-        }
-        if (spec._specType === "claude") {
-            const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
-            const { markdown, errors, targets } = (0, compile_js_1.compileClaude)(spec, {
-                basePath,
-                specFile: specPath,
-                maxRules,
-                catalogOnly,
-            });
-            if (errors.length > 0) {
-                for (const err of errors) {
-                    console.log(`::error file=${specPath}::${err.message}`);
-                }
-                allValid = false;
-            }
-            // Write primary target
-            (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
-            const outputNames = [primaryOutput];
-            // Write additional targets with swapped heading + recomputed hash
-            for (const t of targets.slice(1)) {
-                const body = markdown
-                    .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
-                    .replace(/^# [^\n]+/, `# ${t}`);
-                const additional = (0, compile_js_1.addHash)(body, specPath);
-                const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
-                const targetPath = dir + t;
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), additional);
-                outputNames.push(targetPath);
-            }
-            console.log(`Compiled: ${specPath} → ${outputNames.join(", ")}`);
-        }
-        else if (spec._specType === "skill") {
-            const outputPath = specPath.replace(/\.spec\.ts$/, "");
-            const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
-                basePath,
-                specFile: specPath,
-            });
-            if (errors.length > 0) {
-                for (const err of errors) {
-                    console.log(`::error file=${specPath}::${err.message}`);
-                }
-                allValid = false;
-            }
-            (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
-            console.log(`Compiled: ${specPath} → ${outputPath}`);
-        }
-    }
-    return allValid;
-}
-function runAudit() {
-    // Delegate to the CLI so the action always runs the full audit flow
-    // (hash verification, spec validation, duplicate detection, coverage
-    // report, strengthen suggestions). Previously this only ran
-    // checkFileHash, which silently skipped everything else.
-    const files = pathsInput
-        ? pathsInput
-            .split(",")
-            .map((p) => p.trim())
-            .filter(Boolean)
-        : [];
-    const cliPath = (0, node_path_1.resolve)(__dirname, "cli.js");
-    const args = ["audit", ...files];
-    const result = (0, node_child_process_1.spawnSync)(process.execPath, [cliPath, ...args], {
-        stdio: "inherit",
-        env: {
-            ...process.env,
-            // Ensure the CLI emits GitHub annotations during the action run
-            GITHUB_ACTIONS: process.env.GITHUB_ACTIONS ?? "true",
-        },
-    });
-    if (result.error) {
-        console.log(`::error::Failed to run vigiles audit: ${result.error.message}`);
-        return false;
-    }
-    // Exit codes: 0 clean, 1 warnings, 2 hard errors.
-    return result.status === 0;
-}
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-void (async () => {
-    let valid;
-    if (command === "compile") {
-        valid = await runCompile();
-    }
-    else if (command === "audit") {
-        valid = runAudit();
-    }
-    else {
-        console.log(`::error::Unknown vigiles command "${command}". Valid commands: compile, audit.`);
-        process.exit(1);
-    }
-    console.log(`::set-output name=valid::${String(valid)}`);
-    if (!valid) {
-        console.log("::error::vigiles failed — see errors above");
-        process.exit(1);
-    }
-})();
-//# sourceMappingURL=action.js.map

package/dist/refs.d.ts

@@ -1,44 +0,0 @@
-/** An inline code span with its 1-based source line. */
-export interface Span {
-    readonly text: string;
-    readonly line: number;
-}
-/**
- * Extract inline code spans, skipping fenced code blocks (R1). Returns each
- * span's trimmed text and 1-based line.
- */
-export declare function inlineSpans(markdown: string): Span[];
-/** A parsed file-qualified reference. */
-export interface SymbolRef {
-    readonly file: string;
-    readonly symbol: string;
-    readonly line: number;
-}
-/** A reference that failed verification. */
-export interface SymbolRefError extends SymbolRef {
-    readonly reason: string;
-}
-/** Extract the `vigiles:symbol` references from a markdown file. */
-export declare function symbolRefs(markdown: string): SymbolRef[];
-/**
- * Verify the file-qualified symbol references in a markdown file: the named
- * file must exist and define the named symbol. `basePath` is the directory the
- * paths resolve against (the instruction file's own directory).
- */
-export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
-/**
- * Whether a span looks like a *code reference* that ought to carry a
- * file-qualified mark — a scoped name, or an identifier that isn't a bare
- * lowercase prose word. A function-call form `` `foo(args)` `` is treated as a
- * reference to its callee `foo`. Paths/filenames are excluded (they are `file`
- * refs).
- */
-export declare function isCodeShaped(text: string): boolean;
-/**
- * Code-shaped inline references that are NOT yet marked — the spans the
- * enforcement hook makes the agent mark as `` `vigiles:symbol path.ext#symbol` ``
- * or opt out of with `<!-- vigiles:ignore -->` (or `<!-- vigiles:ignore-file -->`
- * for the whole file).
- */
-export declare function unmarkedCodeRefs(markdown: string): Span[];
-//# sourceMappingURL=refs.d.ts.map

package/dist/run-hook.d.ts

@@ -1,77 +0,0 @@
-/** A hook event payload (the JSON Claude Code writes to the hook's stdin). */
-export interface HookInput {
-    /** e.g. "PreToolUse", "PostToolUse", "Stop", "SessionStart", "PreCompact". */
-    readonly hook_event_name?: string;
-    /** PreToolUse/PostToolUse. */
-    readonly tool_name?: string;
-    readonly tool_input?: unknown;
-    readonly tool_response?: unknown;
-    /** UserPromptSubmit. */
-    readonly prompt?: string;
-    /** SessionStart. */
-    readonly source?: string;
-    /** Stop / SubagentStop. */
-    readonly stop_hook_active?: boolean;
-    /** Any other event-specific fields. */
-    readonly [k: string]: unknown;
-}
-/** The JSON a hook may print on stdout (all fields optional). */
-export interface HookOutput {
-    readonly decision?: "approve" | "block";
-    readonly reason?: string;
-    readonly continue?: boolean;
-    readonly stopReason?: string;
-    readonly suppressOutput?: boolean;
-    readonly systemMessage?: string;
-    readonly hookSpecificOutput?: {
-        readonly hookEventName?: string;
-        readonly permissionDecision?: "allow" | "deny" | "ask";
-        readonly permissionDecisionReason?: string;
-        readonly additionalContext?: string;
-    };
-    readonly [k: string]: unknown;
-}
-export interface RunHookOptions {
-    /** Working directory for the hook process. Default: a value won't be set. */
-    readonly cwd?: string;
-    /** Extra env vars (merged over process.env). `{cwd}` in values is left as-is. */
-    readonly env?: Record<string, string>;
-    /** Per-run timeout ms. Default 10000. */
-    readonly timeoutMs?: number;
-}
-export interface HookRunResult {
-    readonly exitCode: number;
-    readonly stdout: string;
-    readonly stderr: string;
-    /** Parsed stdout JSON if the hook emitted a JSON decision, else null. */
-    readonly json: HookOutput | null;
-    /**
-     * Normalized decision: a deny/block via exit 2, `decision:"block"`, or
-     * `permissionDecision:"deny"` all set `blocked = true`.
-     */
-    readonly blocked: boolean;
-    /**
-     * The decision the hook expressed, preferring the structured
-     * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
-     * ("approve"|"block"), else undefined.
-     */
-    readonly decision: HookOutput["decision"] | "allow" | "deny" | "ask" | undefined;
-}
-/** Parse stdout as a hook JSON decision (pure, testable without a process). */
-export declare function parseHookOutput(stdout: string): HookOutput | null;
-/**
- * Decide whether a hook result blocked, and the normalized decision. Pure, so
- * the policy is unit-testable independent of spawning anything.
- */
-export declare function decideHook(exitCode: number, json: HookOutput | null): {
-    blocked: boolean;
-    decision: HookRunResult["decision"];
-};
-/**
- * Run a hook command, piping `input` as JSON to its stdin, and report the exit
- * code + parsed decision. Synchronous (so it can be used inside an eval's
- * `measure` too). `command` is run through a shell, so the same command string a
- * plugin ships (with args / env refs) works verbatim.
- */
-export declare function runHook(command: string, input: HookInput, opts?: RunHookOptions): HookRunResult;
-//# sourceMappingURL=run-hook.d.ts.map