vibe-splain 3.4.1 → 3.5.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <strong>◈ VIBE-SPLAIN</strong>
+  <strong>◈ vibe-splain</strong>
   <br />
   <em>Map architectural DNA and behavioral call-chains in complex codebases.</em>
 </p>
@@ -14,13 +14,13 @@
 
 ---
 
-VIBE-SPLAIN is a high-fidelity **static analysis engine** and MCP server. It uses [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.
+vibe-splain is a high-fidelity **static analysis engine** and MCP server. It uses [Tree-Sitter](https://tree-sitter.github.io/tree-sitter/) to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.
 
-While VIBE-SPLAIN is built on a language-agnostic foundation, the current toolset is **highly optimized for TypeScript and JavaScript** (especially Next.js, Prisma, and tRPC environments).
+While vibe-splain is built on a language-agnostic foundation, the current toolset is **highly optimized for TypeScript and JavaScript** (especially Next.js, Prisma, and tRPC environments).
 
 **Zero LLM calls. Zero API keys. Pure static analysis.**
 
-Your coding agent does all the thinking — VIBE-SPLAIN just gives it the right data.
+Your coding agent does all the thinking — vibe-splain just gives it the right data.
 
 ## Install
 
@@ -28,17 +28,17 @@ Your coding agent does all the thinking — VIBE-SPLAIN just gives it the right
 npx vibe-splain install
 ```
 
-That's it. This patches your coding agent's MCP config so it can call VIBE-SPLAIN's tools. Restart your agent.
+That's it. This patches your coding agent's MCP config so it can call vibe-splain's tools. Restart your agent.
 
 ### Running the Analysis
 
-You don't need to write a complex prompt. VIBE-SPLAIN provides a built-in MCP Prompt called `build_dossier` that automatically tells your agent exactly what to do.
+You don't need to write a complex prompt. vibe-splain provides a built-in MCP Prompt called `build_dossier` that automatically tells your agent exactly what to do.
 
 **In Claude Code / Gemini CLI:**
 Type `/prompt build_dossier` and press enter.
 
 **In Cursor / Windsurf:**
-Open the MCP panel or agent chat, select the `build_dossier` prompt from the VIBE-SPLAIN server, and run it.
+Open the MCP panel or agent chat, select the `build_dossier` prompt from the vibe-splain server, and run it.
 
 Your agent will loop through the high-gravity files, analyze each one, and build an **Architectural Dossier** — a structured set of **Decision Cards** explaining the technical rationale of the code.
 
@@ -71,22 +71,27 @@ Your agent will loop through the high-gravity files, analyze each one, and build
 ```
 
 ### Three Levels of Analysis
-
 1. **Level 0 — Semantic Classification**: Maps files to architectural "pillars" (Auth, Payments, Database, etc.) using import-path heuristics and library signatures.
+2. **Level 1 — Structural Gravity**: Computes `gravity` (0–100) using Tree-Sitter AST analysis — PageRank centrality, fan-in, cyclomatic complexity, public surface, and nesting depth. High-gravity files are the load-bearing hubs of the codebase. (An optional domain-adapter extension point exists for projects that want to add product-specific `behavioralLift`, but no adapters ship with the core — every scan is pure static analysis.)
+3. **Level 2 — Behavioral Traceability**: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies **Critical Functions** (entrypoints, semantic actions, or high-outbound callers).
+
+### Claude Code PreToolUse Hook
 
-2. **Level 1 — Cognitive Complexity**: Tree-Sitter AST analysis computes a complexity score per file based on link density, nesting depth, and mutation counts. Files scoring ≥ 15 are identified as **High-Gravity**.
+`vibe-splain` integrates directly with Claude Code's hook system to prevent AI agents from accidentally breaking your codebase:
 
-3. **Level 2 — Behavioral Traceability**: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies **Critical Functions** (entrypoints, semantic actions, or high-outbound callers) so your agent can trace the exact ripple effect of a code change.
+- **Ultra-Fast Local Gating**: Installs a standalone entrypoint (`dist/hook.js`) that runs in **< 15ms** with zero network calls, avoiding heavy WASM/tree-sitter load overhead.
+- **Hybrid Blast-Radius Logic**: Combines static gravity and substance-based direct dependents to protect important files (e.g. dynamically-loaded execution nodes or central utility modules) even if they lack standard entrypoints.
+- **Developer Friction Suppression**: Automatically demotes generated, minified, or vendored files to a `low` blast-radius, ensuring the agent is never blocked when editing build targets or lockfiles.
+- **Warn-Once session behavior**: If `.vibe-splainer/gate.json` is missing, the hook notifies you exactly once per session to run a project scan, then gracefully gets out of the way.
 
 ## MCP Tools
 
-VIBE-SPLAIN exposes **8 tools** over MCP stdio:
+vibe-splain exposes these core dossier tools over MCP stdio:
 
 | Tool | Purpose |
 |------|---------|
 | `scan_project` | **Call first.** Scans the codebase, returns high-gravity files grouped by pillar. Starts file watcher. |
 | `get_file_context` | Returns full source + import graph neighbors for a specific file. |
-| `get_call_chain` | **New.** Traces function-level call chains (upstream/downstream) to map behavior paths. |
 | `write_decision_card` | Persists a Decision Card (narrative + evidence + optional Mermaid diagram). |
 | `get_strategic_overview` | Returns dossier state without evidence snippets (saves tokens). |
 | `inspect_pillar` | Returns all Decision Cards for a pillar with full evidence. |
@@ -98,8 +103,7 @@ VIBE-SPLAIN exposes **8 tools** over MCP stdio:
 ```
 1. scan_project → get high-gravity files
 2. For each file: get_file_context → read source + neighbors
-3. Trace: use get_call_chain to see what calls what
-4. Synthesize: "WHY does this code exist?"
+3. Synthesize: "WHY does this code exist?"
 5. write_decision_card → persist the narrative
 6. Share the file:// UI link with the user
 ```
@@ -107,10 +111,10 @@ VIBE-SPLAIN exposes **8 tools** over MCP stdio:
 ## How It Works
 
 ### Deep Analysis Pipeline
-Unlike simple regex scanners, VIBE-SPLAIN runs a deterministic **13-stage pipeline**—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.
+Unlike simple regex scanners, vibe-splain runs a deterministic **13-stage pipeline**—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.
 
 ### Semantic Rulesets
-VIBE-SPLAIN uses specialized rulesets to understand framework-specific semantics. Current optimizations include:
+vibe-splain uses specialized rulesets to understand framework-specific semantics. Current optimizations include:
 - **Next.js**: Server Actions, `cookies()`, `headers()`, and App Router conventions.
 - **Database**: Prisma model mutations and raw query patterns.
 - **API**: tRPC procedure calls (`mutate`/`query`) and standard `fetch`/`axios` patterns.
@@ -137,12 +141,14 @@ The UI features:
 
 ```
 packages/
-├── brain/           # @vibe-splain/brain — analysis engine
+├── brain/           # @vibe-splain/brain — repo-agnostic static analysis core
 │   └── src/
-│       ├── scanner.ts    # Tree-Sitter AST analysis (L0 + L1 + L2)
+│       ├── pipeline/
+│       │   └── adapters/ # Optional domain-adapter extension point (none bundled)
+│       ├── scanner.ts    # Tree-Sitter AST analysis (static analysis, graph building)
 │       ├── dossier.ts    # Atomic persistence + UI regeneration
 │       ├── graph.ts      # Import graph read/write
-│       └── watcher.ts    # Chokidar file watcher
+│       └── network/      # Deterministic PreToolUse gate (escalation + gate index)
 ├── cli/             # vibe-splain — MCP server + CLI
 │   └── src/
 │       ├── index.ts          # #!/usr/bin/env node entry
@@ -161,7 +167,7 @@ packages/
 
 ### Key Design Decisions
 
-- **No LLM calls**: VIBE-SPLAIN is a pure static analysis tool. The coding agent provides all synthesis.
+- **No LLM calls**: vibe-splain is a pure static analysis tool. The coding agent provides all synthesis.
 - **`async-mutex`**: All dossier writes are guarded by a mutex with atomic tmp+rename.
 - **`startOnLoad: false`**: Mermaid is initialized manually — never auto-scans the DOM.
 - **`base: './'`**: Vite builds with relative paths so the UI works from `file://` URLs.

package/dist/commands/hook.d.ts

@@ -0,0 +1,9 @@
+export interface HookCommandResult {
+    /** JSON to print to stdout, or null to print nothing (defer / exit 0). */
+    stdout: string | null;
+}
+export declare function findProjectRoot(start: string | undefined): string | null;
+/** Pure-ish core: raw stdin string in, hook decision (as a string or null) out. */
+export declare function runHookCommand(rawStdin: string): Promise<HookCommandResult>;
+/** CLI entrypoint: read all of stdin, run the gate, emit the result. */
+export declare function hookPreToolUseCommand(): Promise<void>;

package/dist/commands/hook.js

@@ -0,0 +1,84 @@
+// `vibe-splain hook pretooluse` — the deterministic PreToolUse gate, wired to stdio.
+//
+// Claude Code pipes a JSON describing the tool call about to run onto stdin; we
+// decide whether to escalate and, if so, write hook JSON to stdout. On a safe
+// edit (or any non-edit tool, unscanned repo, etc.) we print nothing and exit 0,
+// deferring to normal permission flow.
+//
+// NOTE on the console.log ban: that rule protects the MCP *server's* stdout.
+// This is a separate, short-lived process whose stdout IS the hook protocol —
+// writing JSON here is correct. Diagnostics still go to stderr.
+import { existsSync, writeFileSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { tmpdir } from 'os';
+import { decidePreToolUse } from '../hook/preToolUse.js';
+// Walk up from `start` looking for the directory that holds a `.vibe-splainer` scan.
+// Returns null if none is found — an unscanned repo means the gate is inert.
+export function findProjectRoot(start) {
+    let dir = start || process.cwd();
+    // Bound the walk so a stray cwd can't traverse the whole filesystem.
+    for (let i = 0; i < 64; i++) {
+        if (existsSync(join(dir, '.vibe-splainer', 'analysis.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Pure-ish core: raw stdin string in, hook decision (as a string or null) out. */
+export async function runHookCommand(rawStdin) {
+    let input;
+    try {
+        input = JSON.parse(rawStdin);
+    }
+    catch {
+        return { stdout: null }; // malformed input → never block the agent
+    }
+    const root = findProjectRoot(input.cwd);
+    const gatePath = root ? join(root, '.vibe-splainer', 'gate.json') : null;
+    const gateExists = gatePath ? existsSync(gatePath) : false;
+    let gateIndex = null;
+    if (gateExists) {
+        try {
+            gateIndex = JSON.parse(readFileSync(gatePath, 'utf8'));
+        }
+        catch { }
+    }
+    const sessionId = input.session_id || 'default';
+    const warnFile = join(tmpdir(), `vibe-splain-warn-${sessionId}`);
+    const warningShown = existsSync(warnFile);
+    const result = decidePreToolUse(input, gateIndex, { warningShown });
+    if (result.action === 'defer')
+        return { stdout: null };
+    if (!gateIndex && result.action === 'emit') {
+        try {
+            writeFileSync(warnFile, '1');
+        }
+        catch { }
+    }
+    return { stdout: JSON.stringify(result.output) };
+}
+/** CLI entrypoint: read all of stdin, run the gate, emit the result. */
+export async function hookPreToolUseCommand() {
+    const raw = await readStdin();
+    const { stdout } = await runHookCommand(raw);
+    if (stdout)
+        process.stdout.write(stdout);
+    // No stdout on defer; exit code stays 0.
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+//# sourceMappingURL=hook.js.map

package/dist/commands/install.d.ts

@@ -1 +1,6 @@
+/**
+ * Idempotently register the vibe-splain PreToolUse hook in a Claude Code settings object.
+ * Pure: takes a config, returns the same object mutated. Safe to run repeatedly.
+ */
+export declare function addPreToolUseHook(config: Record<string, any>, hookPath?: string): Record<string, any>;
 export declare function installCommand(): Promise<void>;

package/dist/commands/install.js

@@ -1,7 +1,8 @@
 import { readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
+import { fileURLToPath } from 'url';
 function expandPath(p) {
     if (p.startsWith('~')) {
         return join(homedir(), p.slice(1));
@@ -24,8 +25,48 @@ const MCP_ENTRY = {
     command: 'npx',
     args: ['-y', 'vibe-splain', 'serve'],
 };
+// Claude Code PreToolUse hook: deterministically gate edits to high-blast-radius
+// files. Hooks are a Claude Code CLI feature (settings.json) — not Desktop/Cursor.
+const HOOK_MATCHER = 'Edit|Write|MultiEdit';
+const DEFAULT_HOOK_COMMAND = 'npx -y vibe-splain hook pretooluse';
+/**
+ * Idempotently register the vibe-splain PreToolUse hook in a Claude Code settings object.
+ * Pure: takes a config, returns the same object mutated. Safe to run repeatedly.
+ */
+export function addPreToolUseHook(config, hookPath) {
+    if (!config.hooks)
+        config.hooks = {};
+    if (!Array.isArray(config.hooks.PreToolUse))
+        config.hooks.PreToolUse = [];
+    const hookCommand = hookPath ? `node "${hookPath}"` : DEFAULT_HOOK_COMMAND;
+    const already = config.hooks.PreToolUse.some((entry) => Array.isArray(entry?.hooks) &&
+        entry.hooks.some((h) => typeof h?.command === 'string' && (h.command.includes('vibe-splain hook pretooluse') || h.command.includes('hook.js'))));
+    if (already) {
+        // Update existing hook command to the resolved hook.js path
+        config.hooks.PreToolUse = config.hooks.PreToolUse.map((entry) => {
+            if (Array.isArray(entry?.hooks)) {
+                return {
+                    ...entry,
+                    hooks: entry.hooks.map((h) => {
+                        if (typeof h?.command === 'string' && (h.command.includes('vibe-splain hook pretooluse') || h.command.includes('hook.js'))) {
+                            return { ...h, command: hookCommand };
+                        }
+                        return h;
+                    })
+                };
+            }
+            return entry;
+        });
+        return config;
+    }
+    config.hooks.PreToolUse.push({
+        matcher: HOOK_MATCHER,
+        hooks: [{ type: 'command', command: hookCommand }],
+    });
+    return config;
+}
 export async function installCommand() {
-    console.error('\n🔧 VIBE-SPLAIN Installer\n');
+    console.error('\n🔧 vibe-splain Installer\n');
     let patchedCount = 0;
     for (const agent of AGENT_CONFIGS) {
         const resolvedPath = expandPath(agent.path);
@@ -43,17 +84,25 @@ export async function installCommand() {
                 console.error(`    ⚠ Could not parse JSON, skipping`);
                 continue;
             }
-            // Check idempotency
-            if (config.mcpServers?.['vibe-splain']) {
+            // Patch config (idempotent: only write when something actually changes,
+            // so existing users still pick up newly-added pieces like the hook).
+            const before = JSON.stringify(config);
+            if (!config.mcpServers)
+                config.mcpServers = {};
+            if (!config.mcpServers['vibe-splain'])
+                config.mcpServers['vibe-splain'] = MCP_ENTRY;
+            // The PreToolUse gate is a Claude Code CLI feature (settings.json hooks).
+            // Only register it there; Desktop/Gemini/Cursor don't run these hooks.
+            if (agent.name === 'Claude Code CLI') {
+                const __dirname = dirname(fileURLToPath(import.meta.url));
+                const hookPath = join(__dirname, '..', 'hook.js');
+                addPreToolUseHook(config, hookPath);
+            }
+            if (JSON.stringify(config) === before) {
                 console.error(`    ✓ Already configured, skipping`);
                 patchedCount++;
                 continue;
             }
-            // Patch config
-            if (!config.mcpServers) {
-                config.mcpServers = {};
-            }
-            config.mcpServers['vibe-splain'] = MCP_ENTRY;
             await writeFile(resolvedPath, JSON.stringify(config, null, 2), 'utf8');
             console.error(`    ✅ Patched successfully`);
             patchedCount++;

package/dist/export/ExportOrchestrator.js

@@ -1,8 +1,7 @@
-import { readAnalysis, readActionBindings, RecommendationEngine } from '@vibe-splain/brain';
+import { readAnalysis, RecommendationEngine, buildGateIndex } from '@vibe-splain/brain';
 import { ArtifactBundleWriter } from './ArtifactBundleWriter.js';
 import { JsonRenderer } from './renderers/JsonRenderer.js';
 import { HtmlRenderer } from './renderers/HtmlRenderer.js';
-import { DeltaRenderer } from './renderers/DeltaRenderer.js';
 import { AgentMarkdownRenderer } from './renderers/AgentMarkdownRenderer.js';
 import { ValidationRenderer } from './renderers/ValidationRenderer.js';
 import { RawAnalysisRenderer } from './renderers/RawAnalysisRenderer.js';
@@ -20,22 +19,25 @@ export class ExportOrchestrator {
         if (!finalStore) {
             throw new Error('Analysis store not found. Scan the project first.');
         }
-        const bindings = await readActionBindings(this.projectRoot);
         // Aggressive Boilerplate Culling
         for (const p of dossier.pillars) {
             p.decisions = p.decisions.filter(c => !(c.severity === 1 && c.category === 'Convention'));
             p.cardCount = p.decisions.length;
         }
         const viewModel = this.buildViewModel(dossier, finalStore);
-        // Always render JSON, Delta, Validation, and Raw Analysis.
         const artifacts = [];
         artifacts.push(...await new JsonRenderer().render(viewModel, finalStore));
-        artifacts.push(...await new DeltaRenderer().render(viewModel, finalStore));
         artifacts.push(...await new ValidationRenderer().render(viewModel, finalStore));
         artifacts.push(...await new RawAnalysisRenderer().render(viewModel, finalStore));
         if (graph) {
             artifacts.push(...await new GraphRenderer(graph).render(viewModel, finalStore));
         }
+        const gateIndex = buildGateIndex(finalStore);
+        artifacts.push({
+            type: 'gate',
+            path: 'gate.json',
+            content: JSON.stringify(gateIndex, null, 2),
+        });
         // Determine additional formats
         const formats = ['html', 'markdown']; // default
         if (options.format && options.format !== 'json' && options.format !== 'delta') {
@@ -46,7 +48,7 @@ export class ExportOrchestrator {
             artifacts.push(...await new HtmlRenderer().render(viewModel, finalStore));
         }
         if (formats.includes('markdown')) {
-            artifacts.push(...await new AgentMarkdownRenderer(options.budget, bindings).render(viewModel, finalStore));
+            artifacts.push(...await new AgentMarkdownRenderer(options.budget).render(viewModel, finalStore));
         }
         const writer = new ArtifactBundleWriter(this.projectRoot);
         await writer.writeBundle(artifacts);

package/dist/export/renderers/AgentMarkdownRenderer.d.ts

@@ -3,7 +3,6 @@ import type { Renderer } from './Renderer.js';
 import type { Artifact } from '../ArtifactBundleWriter.js';
 export declare class AgentMarkdownRenderer implements Renderer {
     private budget;
-    private bindings;
-    constructor(budget?: number, bindings?: any | null);
+    constructor(budget?: number);
     render(viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
 }

package/dist/export/renderers/AgentMarkdownRenderer.js

@@ -1,9 +1,7 @@
 export class AgentMarkdownRenderer {
     budget;
-    bindings;
-    constructor(budget = 8000, bindings = null) {
+    constructor(budget = 8000) {
         this.budget = budget;
-        this.bindings = bindings;
     }
     render(viewModel, store) {
         let md = `# Architectural Dossier: ${viewModel.projectRoot}\n\n`;
@@ -54,20 +52,6 @@ export class AgentMarkdownRenderer {
                 md += `**Severity**: ${card.severity} | **Category**: ${card.category}\n`;
                 md += `**Narrative**: ${card.narrative}\n`;
             }
-            // Add Function-Level Action Bindings for Tier 1
-            if (this.bindings && this.bindings.files[path]) {
-                const fileBinding = this.bindings.files[path];
-                const criticalFunctions = fileBinding.functions.filter((fn) => fn.semanticActions.length > 0 || fn.isEntrypoint);
-                if (criticalFunctions.length > 0) {
-                    md += `\n**Critical Functions**:\n`;
-                    for (const fn of criticalFunctions) {
-                        md += `- \`${fn.displayName}\` (lines ${fn.startLine}-${fn.endLine})${fn.isEntrypoint ? ' [Entrypoint]' : ''}\n`;
-                        for (const action of fn.semanticActions) {
-                            md += `  - **${action.actionKind}**${action.targetModel ? ` on ${action.targetModel}` : ''}: \`${action.calleeText}\` (line ${action.sourceLine})\n`;
-                        }
-                    }
-                }
-            }
             if (recs.length > 0) {
                 md += `\n**Safe Patch Strategies**:\n`;
                 for (const r of recs) {

package/dist/hook/preToolUse.d.ts

@@ -0,0 +1,30 @@
+import type { EscalationContext } from '@vibe-splain/brain/dist/network/escalation.js';
+import type { GateIndex } from '@vibe-splain/brain/dist/network/gateIndex.js';
+export interface PreToolUseInput {
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        [k: string]: unknown;
+    };
+    cwd?: string;
+    session_id?: string;
+}
+export interface HookOutput {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'ask';
+        permissionDecisionReason?: string;
+        additionalContext?: string;
+        systemMessage?: string;
+    };
+}
+export type HookResult = {
+    action: 'defer';
+} | {
+    action: 'emit';
+    output: HookOutput;
+};
+export declare function decidePreToolUse(input: PreToolUseInput, gateIndex: GateIndex | null, sessionState?: {
+    warningShown?: boolean;
+}): HookResult;
+export declare function formatEscalation(ctx: EscalationContext): string;

package/dist/hook/preToolUse.js

@@ -0,0 +1,81 @@
+// PreToolUse hook decision logic — the deterministic gate.
+//
+// Pure: given the agent's intended tool call and the scan artifact, decide
+// whether to escalate and how. No stdin/stdout, no filesystem — the CLI command
+// wraps this with I/O. This separation is what makes the gate testable against
+// real scanned stores.
+import { buildEscalationContext } from '@vibe-splain/brain/dist/network/escalation.js';
+const DEFER = { action: 'defer' };
+// Only file-editing tools can have a blast radius. Anything else defers.
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+export function decidePreToolUse(input, gateIndex, sessionState) {
+    if (!EDIT_TOOLS.has(input.tool_name ?? ''))
+        return DEFER;
+    if (!gateIndex) {
+        if (sessionState && !sessionState.warningShown) {
+            const warnMsg = "vibe-splain: .vibe-splainer/gate.json is missing. Please run 'vibe-splain scan' to generate the scan architecture and enable tool guarding.";
+            return {
+                action: 'emit',
+                output: {
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'allow',
+                        additionalContext: warnMsg,
+                        systemMessage: warnMsg,
+                    },
+                },
+            };
+        }
+        return DEFER;
+    }
+    const filePath = input.tool_input?.file_path;
+    if (!filePath)
+        return DEFER;
+    const ctx = buildEscalationContext(filePath, gateIndex);
+    if (!ctx || ctx.blastRadius === 'low')
+        return DEFER;
+    const block = formatEscalation(ctx);
+    // high → stop-and-reconsider (human gate). medium → non-blocking awareness:
+    // the agent sees the context on its next request without being interrupted.
+    if (ctx.blastRadius === 'high') {
+        return {
+            action: 'emit',
+            output: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'ask',
+                    permissionDecisionReason: block,
+                    additionalContext: block,
+                },
+            },
+        };
+    }
+    return {
+        action: 'emit',
+        output: {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                additionalContext: block,
+            },
+        },
+    };
+}
+export function formatEscalation(ctx) {
+    const lines = [];
+    lines.push(`vibe-splain: ${ctx.blastRadius} blast radius — ${ctx.targetFile} (gravity ${ctx.gravity}).`);
+    if (ctx.dependentCount > 0) {
+        const shown = ctx.dependents.slice(0, 8);
+        const more = ctx.dependentCount - shown.length;
+        lines.push(`${ctx.dependentCount} file(s) depend on it:`);
+        for (const d of shown)
+            lines.push(`  - ${d}`);
+        if (more > 0)
+            lines.push(`  … (+${more} more)`);
+    }
+    for (const w of ctx.riskWarnings)
+        lines.push(`[${w.level}] ${w.message}`);
+    lines.push(ctx.smallestSafeChange.summary);
+    return lines.join('\n');
+}
+//# sourceMappingURL=preToolUse.js.map

package/dist/hook.d.ts

@@ -0,0 +1 @@
+export declare function findProjectRoot(start: string | undefined): string | null;