@mnemonik/claude-code-hooks 0.1.0

package/dist/hook.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Mnemonik forcing-functions dispatcher for Claude Code hooks.
+ *
+ * Single Node script handling PreToolUse on Edit/Write/NotebookEdit/Bash and
+ * PostToolUse on Edit/Write/NotebookEdit. Reads Claude Code's hook payload on
+ * stdin, writes a decision JSON on stdout, exits 0 on success / 0 on
+ * fail-open / 0 on bypass. Never exits non-zero in advisory mode.
+ *
+ * Wired into .claude/settings.json by `mnemonik-claude-code-hooks install`.
+ */
+export {};

package/dist/hook.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * Mnemonik forcing-functions dispatcher for Claude Code hooks.
+ *
+ * Single Node script handling PreToolUse on Edit/Write/NotebookEdit/Bash and
+ * PostToolUse on Edit/Write/NotebookEdit. Reads Claude Code's hook payload on
+ * stdin, writes a decision JSON on stdout, exits 0 on success / 0 on
+ * fail-open / 0 on bypass. Never exits non-zero in advisory mode.
+ *
+ * Wired into .claude/settings.json by `mnemonik-claude-code-hooks install`.
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { stdin, stdout, stderr, exit } from 'node:process';
+import { isNonInteractive, parseBypass, resolveConfig } from './lib/env.js';
+import { fetchSnapshot, reportBypass } from './lib/http.js';
+import { BUILT_IN_DESTRUCTIVE, matchCommand, tokenize } from './lib/shellTokens.js';
+const POLICY_DEDUP_WINDOW_MS = 60_000;
+const MUST_CONFIRM_DEDUP_WINDOW_MS = 60_000;
+// ─── Decision writers ──────────────────────────────────────────────────────
+function writeDecision(decision) {
+    if (decision !== null) {
+        stdout.write(JSON.stringify(decision));
+    }
+    exit(0);
+}
+function writeAllow() {
+    exit(0);
+}
+function writeAdvisoryNote(message) {
+    stderr.write(`mnemonik-hook: ${message}\n`);
+    exit(0);
+}
+// ─── stdin reader ──────────────────────────────────────────────────────────
+async function readStdin() {
+    return new Promise((res) => {
+        let buf = '';
+        stdin.setEncoding('utf8');
+        stdin.on('data', (chunk) => {
+            buf += chunk;
+            // Soft cap: if Claude ever ships a huge transcript we don't want to OOM.
+            if (buf.length > 1_048_576) {
+                res(null);
+            }
+        });
+        stdin.on('end', () => {
+            try {
+                res(JSON.parse(buf));
+            }
+            catch {
+                res(null);
+            }
+        });
+        stdin.on('error', () => res(null));
+    });
+}
+// ─── Edit / Write / NotebookEdit gate ──────────────────────────────────────
+/**
+ * Heuristic soft-pass for trivial Edit-tool changes — the dispatcher's own
+ * check, not the agent's claim. Only applied to the Edit tool (NotebookEdit
+ * and Write don't surface a diff that lets us measure triviality).
+ *
+ * Trivial means both old_string and new_string are:
+ *   - single-line (no embedded newlines),
+ *   - ≤ 100 chars,
+ *   - within 40% of each other in length.
+ *
+ * This is the kind of edit where forcing file_context buys nothing — fixing
+ * a typo in a comment, swapping a single identifier, tweaking whitespace.
+ * Anything multi-line or large enough to plausibly change behaviour fails
+ * the heuristic and goes through the normal gate.
+ */
+function isTrivialEdit(toolName, toolInput) {
+    if (toolName !== 'Edit')
+        return false;
+    if (!toolInput)
+        return false;
+    const oldStr = typeof toolInput.old_string === 'string' ? toolInput.old_string : null;
+    const newStr = typeof toolInput.new_string === 'string' ? toolInput.new_string : null;
+    if (oldStr === null || newStr === null)
+        return false;
+    if (oldStr.includes('\n') || newStr.includes('\n'))
+        return false;
+    if (oldStr.length === 0 || newStr.length === 0)
+        return false;
+    if (oldStr.length > 100 || newStr.length > 100)
+        return false;
+    const longer = Math.max(oldStr.length, newStr.length);
+    const shorter = Math.min(oldStr.length, newStr.length);
+    if (shorter / longer < 0.6)
+        return false;
+    return true;
+}
+function resolveTargetFile(toolName, toolInput, cwd) {
+    if (!toolInput)
+        return null;
+    // Edit / Write expose `file_path`; NotebookEdit uses `notebook_path`. We
+    // accept both so the same dispatcher works across tool variants.
+    const raw = typeof toolInput.file_path === 'string'
+        ? toolInput.file_path
+        : typeof toolInput.notebook_path === 'string'
+            ? toolInput.notebook_path
+            : null;
+    if (!raw)
+        return null;
+    return isAbsolute(raw) ? raw : resolve(cwd, raw);
+}
+async function handlePreEdit(input, config) {
+    const mode = config.forcingFunctions.preEditGate;
+    if (mode === 'off')
+        writeAllow();
+    const target = resolveTargetFile(input.tool_name ?? '', input.tool_input, input.cwd);
+    // New file → nothing to ground on. The agent can't have read prior context
+    // for a path that doesn't exist yet.
+    if (target && !existsSync(target))
+        writeAllow();
+    // Trivial edit soft-pass — measured from the diff itself, not the agent's
+    // claim. Cheap & conservative: only the Edit tool with a small single-line
+    // delta qualifies. Saves a server round-trip on every typo / rename.
+    if (isTrivialEdit(input.tool_name ?? '', input.tool_input))
+        writeAllow();
+    if (!config.apiKey) {
+        writeAdvisoryNote('MNEMONIK_API_KEY missing — fail-open. Run mnemonik-claude-code-hooks install.');
+    }
+    const snapshot = await fetchSnapshot({
+        server: config.server,
+        apiKey: config.apiKey,
+        cwd: input.cwd,
+        claudeSessionId: input.session_id,
+    });
+    if (!snapshot) {
+        writeAdvisoryNote('mnemonik server unreachable — fail-open.');
+    }
+    // No active session means the agent hasn't bootstrapped Mnemonik yet. We
+    // never block under that condition — bootstrap-first is enforced by other
+    // mechanisms.
+    if (!snapshot.ok)
+        writeAllow();
+    // Coverage check uses absolute path equality. The server stores whatever
+    // path the agent passed to file_context, so we accept either absolute or
+    // cwd-relative form.
+    if (target) {
+        const relative = target.startsWith(input.cwd) ? target.slice(input.cwd.length + 1) : target;
+        const covered = snapshot.coveredFiles.includes(target) || snapshot.coveredFiles.includes(relative);
+        if (covered)
+            writeAllow();
+    }
+    if (mode === 'advisory') {
+        // Advisory: tell the agent what's missing but don't block.
+        const additionalContext = target
+            ? [
+                `Mnemonik: file_context has not been called for "${target}" in this session.`,
+                'Recommended: call mnemonik.file_context({ filePaths: ["' +
+                    target +
+                    '"] }) before editing — it surfaces past bugs, decisions, and gotchas for the file.',
+                'This message will become an error when forcing-functions is set to "enforce" (currently advisory).',
+            ].join(' ')
+            : 'Mnemonik: this edit was not preceded by a file_context call. Advisory only.';
+        const decision = {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                additionalContext,
+            },
+        };
+        writeDecision(decision);
+    }
+    // mode === 'enforce'
+    const denyReason = target
+        ? [
+            'MNEMONIK_FILE_CONTEXT_REQUIRED',
+            `Edit blocked: file_context has not been called for ${target} in this session.`,
+            `Fix: call mnemonik.file_context({ filePaths: ["${target}"] }) first.`,
+            "Bypass: set MNEMONIK_BYPASS_HOOKS=1 + MNEMONIK_BYPASS_TYPE=<typo|formatting|regenerated|already_grounded|other> (logged; 'other' additionally requires MNEMONIK_BYPASS_DETAIL of 50-200 chars).",
+        ].join('\n')
+        : 'MNEMONIK_FILE_CONTEXT_REQUIRED — no target file resolvable from tool_input.';
+    const decision = {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: denyReason,
+        },
+    };
+    writeDecision(decision);
+}
+// ─── Bash gate ─────────────────────────────────────────────────────────────
+async function handlePreBash(input, config) {
+    const mode = config.forcingFunctions.preBashGate;
+    if (mode === 'off')
+        writeAllow();
+    const command = typeof input.tool_input?.command === 'string' ? input.tool_input.command : '';
+    if (!command.trim())
+        writeAllow();
+    if (!config.apiKey) {
+        writeAdvisoryNote('MNEMONIK_API_KEY missing — fail-open. Run mnemonik-claude-code-hooks install.');
+    }
+    const snapshot = await fetchSnapshot({
+        server: config.server,
+        apiKey: config.apiKey,
+        cwd: input.cwd,
+        claudeSessionId: input.session_id,
+    });
+    if (!snapshot) {
+        writeAdvisoryNote('mnemonik server unreachable — fail-open.');
+    }
+    // Always include the built-in destructive set; project policies extend it.
+    // We only act on patterns from forbiddenCommand and mustConfirm — defaultMode
+    // is informational and doesn't gate.
+    const projectForbidden = snapshot.policies.forbiddenCommand.map((p) => p.pattern);
+    const projectMustConfirm = snapshot.policies.mustConfirm.map((p) => p.pattern);
+    const forbiddenPatterns = [...BUILT_IN_DESTRUCTIVE, ...projectForbidden];
+    const { commands } = tokenize(command);
+    let forbiddenHit = null;
+    let mustConfirmHit = null;
+    for (const tokens of commands) {
+        forbiddenHit = forbiddenHit ?? matchCommand(tokens, forbiddenPatterns);
+        mustConfirmHit = mustConfirmHit ?? matchCommand(tokens, projectMustConfirm);
+        if (forbiddenHit && mustConfirmHit)
+            break;
+    }
+    // No matches → nothing for the gate to do.
+    if (!forbiddenHit && !mustConfirmHit)
+        writeAllow();
+    // De-dup: if the agent JUST issued a manual policy({action:'check'}) for
+    // the same pattern, or just emitted a mustConfirm pause, don't nag again.
+    const now = snapshot.now;
+    const checkedRecently = (pattern) => {
+        const ts = snapshot.recentPolicyChecks[pattern];
+        return typeof ts === 'number' && now - ts < POLICY_DEDUP_WINDOW_MS;
+    };
+    const pausedRecently = typeof snapshot.mustConfirmPauseAt === 'number' &&
+        now - snapshot.mustConfirmPauseAt < MUST_CONFIRM_DEDUP_WINDOW_MS;
+    const hit = forbiddenHit ?? mustConfirmHit;
+    if (forbiddenHit && checkedRecently(forbiddenHit))
+        writeAllow();
+    if (mustConfirmHit && (checkedRecently(mustConfirmHit) || pausedRecently))
+        writeAllow();
+    if (mode === 'advisory') {
+        const kind = forbiddenHit ? 'forbiddenCommand' : 'mustConfirm';
+        const additionalContext = [
+            `Mnemonik policy hit (${kind}): pattern "${hit}" matched the command.`,
+            'Recommended: call mnemonik.policy({ action: "check", command: "' +
+                command +
+                '" }) to confirm before running, or emit a mustConfirm pause summarising the action and waiting for the user.',
+            'This message will become an error when forcing-functions is set to "enforce" (currently advisory).',
+        ].join(' ');
+        const decision = {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                additionalContext,
+            },
+        };
+        writeDecision(decision);
+    }
+    // mode === 'enforce'
+    const denyReason = [
+        'MNEMONIK_POLICY_GATE',
+        `Bash blocked: pattern "${hit}" requires a manual policy check or mustConfirm pause first.`,
+        'Fix: call mnemonik.policy({ action: "check", command }) and act on the response, or emit a mustConfirm summary and wait for the user.',
+        "Bypass: MNEMONIK_BYPASS_HOOKS=1 + MNEMONIK_BYPASS_TYPE=<typo|formatting|regenerated|already_grounded|other>; 'other' additionally requires MNEMONIK_BYPASS_DETAIL 50-200 chars.",
+    ].join('\n');
+    const decision = {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: denyReason,
+        },
+    };
+    writeDecision(decision);
+}
+// ─── PostToolUse: keep server's filesEdited fresh ──────────────────────────
+async function handlePostEdit(input, config) {
+    // Best-effort track-ide-edit — fire-and-forget, always allow.
+    try {
+        if (!config.apiKey)
+            writeAllow();
+        const filePath = resolveTargetFile(input.tool_name ?? '', input.tool_input, input.cwd);
+        if (!filePath)
+            writeAllow();
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 1500);
+        await fetch(`${config.server}/api/v1/session/track-ide-edit`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${config.apiKey}` },
+            body: JSON.stringify({ sessionId: input.session_id, filePath }),
+            signal: ac.signal,
+        }).catch(() => undefined);
+        clearTimeout(timer);
+    }
+    catch {
+        // Never block on PostToolUse.
+    }
+    writeAllow();
+}
+// ─── Top-level dispatcher ──────────────────────────────────────────────────
+async function dispatch(input) {
+    // CI / non-interactive — always allow, never block.
+    if (isNonInteractive())
+        writeAllow();
+    const bypass = parseBypass();
+    if (bypass.invalidReason) {
+        // Malformed bypass envelope: refuse to honour it AND tell the agent why
+        // via stderr so the bypass can't be silently broken.
+        stderr.write(`mnemonik-hook: invalid bypass envelope — ${bypass.invalidReason}\n`);
+    }
+    const config = await resolveConfig(input.cwd);
+    if (bypass.active && config.apiKey) {
+        void reportBypass({
+            server: config.server,
+            apiKey: config.apiKey,
+            cwd: input.cwd,
+            claudeSessionId: input.session_id,
+            tool: input.tool_name ?? 'unknown',
+            bypassType: bypass.type ?? 'unknown',
+            detail: bypass.detail,
+        });
+        writeAllow();
+    }
+    switch (input.hook_event_name) {
+        case 'PreToolUse': {
+            const tool = input.tool_name ?? '';
+            if (tool === 'Edit' || tool === 'Write' || tool === 'NotebookEdit') {
+                await handlePreEdit(input, config);
+            }
+            if (tool === 'Bash') {
+                await handlePreBash(input, config);
+            }
+            writeAllow();
+            break;
+        }
+        case 'PostToolUse': {
+            const tool = input.tool_name ?? '';
+            if (tool === 'Edit' || tool === 'Write' || tool === 'NotebookEdit') {
+                await handlePostEdit(input, config);
+            }
+            writeAllow();
+            break;
+        }
+        default:
+            // SessionStart / Stop / etc — no-op for now; reserved for future phases.
+            writeAllow();
+    }
+}
+(async () => {
+    try {
+        const input = await readStdin();
+        if (!input)
+            writeAllow();
+        await dispatch(input);
+    }
+    catch (err) {
+        stderr.write(`mnemonik-hook: dispatcher error (fail-open) — ${err instanceof Error ? err.message : String(err)}\n`);
+        writeAllow();
+    }
+})();
+//# sourceMappingURL=hook.js.map

package/dist/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"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"}

package/dist/install.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * `mnemonik-claude-code-hooks install` — wires the dispatcher into
+ * .claude/settings.json without clobbering the user's existing config.
+ *
+ * What it does:
+ *   1. Resolves the dispatcher path (this package's dist/hook.js).
+ *   2. Reads (or creates) .claude/settings.json at the cwd.
+ *   3. Merges PreToolUse/PostToolUse entries pointing at `node <dispatcher>`,
+ *      removing any prior mnemonik-managed entries first so re-running the
+ *      installer is idempotent.
+ *   4. Writes the file back, preserving any unrelated user config.
+ *
+ * No npm dependencies — uses Node 20 builtins only. Safe to run from any
+ * project root; never touches files outside `.claude/`.
+ */
+export {};

package/dist/install.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * `mnemonik-claude-code-hooks install` — wires the dispatcher into
+ * .claude/settings.json without clobbering the user's existing config.
+ *
+ * What it does:
+ *   1. Resolves the dispatcher path (this package's dist/hook.js).
+ *   2. Reads (or creates) .claude/settings.json at the cwd.
+ *   3. Merges PreToolUse/PostToolUse entries pointing at `node <dispatcher>`,
+ *      removing any prior mnemonik-managed entries first so re-running the
+ *      installer is idempotent.
+ *   4. Writes the file back, preserving any unrelated user config.
+ *
+ * No npm dependencies — uses Node 20 builtins only. Safe to run from any
+ * project root; never touches files outside `.claude/`.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HOOK_TAG = 'mnemonik-claude-code-hooks';
+function resolveDispatcherPath() {
+    // dist/install.js → dist/hook.js
+    const here = fileURLToPath(import.meta.url);
+    return resolve(dirname(here), 'hook.js');
+}
+function buildHookEntry(dispatcher) {
+    return {
+        type: 'command',
+        command: `node ${JSON.stringify(dispatcher)}`,
+        timeout: 5,
+    };
+}
+function isMnemonikEntry(entry) {
+    // We tag both via the matcher and the dispatcher path so re-runs find us
+    // even if the user changed the matcher manually.
+    if (entry.matcher === HOOK_TAG)
+        return true;
+    return Boolean(entry.hooks?.some((h) => typeof h.command === 'string' && h.command.includes('claude-code-hooks')));
+}
+function patchHookGroup(groups, matcher, entry) {
+    const filtered = (groups ?? []).filter((g) => !isMnemonikEntry(g));
+    filtered.push({ matcher, hooks: [entry] });
+    return filtered;
+}
+async function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Could not parse ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function writeSettings(path, settings) {
+    await mkdir(dirname(path), { recursive: true });
+    // Preserve a trailing newline since prettier-style users rely on it.
+    await writeFile(path, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+async function main() {
+    const cwd = process.cwd();
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    const dispatcher = resolveDispatcherPath();
+    if (!existsSync(dispatcher)) {
+        console.error(`mnemonik-claude-code-hooks: dispatcher not found at ${dispatcher}. Did the package install correctly?`);
+        return 1;
+    }
+    const settings = await readSettings(settingsPath);
+    const hooks = (settings.hooks ?? {});
+    const entry = buildHookEntry(dispatcher);
+    // PreToolUse — guard Edit / Write / NotebookEdit / Bash.
+    hooks.PreToolUse = patchHookGroup(hooks.PreToolUse, 'Edit|Write|NotebookEdit|Bash', entry);
+    // PostToolUse — keep filesEdited fresh after Edit / Write / NotebookEdit.
+    hooks.PostToolUse = patchHookGroup(hooks.PostToolUse, 'Edit|Write|NotebookEdit', entry);
+    settings.hooks = hooks;
+    await writeSettings(settingsPath, settings);
+    console.log([
+        `mnemonik-claude-code-hooks: wired into ${settingsPath}`,
+        `  PreToolUse  → Edit|Write|NotebookEdit|Bash`,
+        `  PostToolUse → Edit|Write|NotebookEdit`,
+        `  dispatcher  → ${dispatcher}`,
+        ``,
+        `Default mode is ADVISORY (no edits will be blocked). To switch to enforce,`,
+        `add to .mnemonik.json:`,
+        `  { "forcingFunctions": { "preEditGate": "enforce" } }`,
+        ``,
+        `Bypass for trivial edits:`,
+        `  MNEMONIK_BYPASS_HOOKS=1 MNEMONIK_BYPASS_TYPE=typo claude ...`,
+    ].join('\n'));
+    return 0;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(`mnemonik-claude-code-hooks: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/lib/env.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Environment helpers: CI detection, bypass parsing, config resolution.
+ */
+import { type BypassEnvelope, type HookConfig } from './types.js';
+/**
+ * CI / non-interactive contexts must never block. We mirror the husky
+ * pre-push pattern already used elsewhere: any of these wins.
+ */
+export declare function isNonInteractive(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Parse the bypass envelope. Refuses any malformed combination — we'd rather
+ * fail-open silently than honour a typoed escape hatch indefinitely.
+ *
+ * Required when active:
+ *   MNEMONIK_BYPASS_HOOKS=1
+ *   MNEMONIK_BYPASS_TYPE=<typo|formatting|regenerated|already_grounded|other>
+ *   MNEMONIK_BYPASS_DETAIL=<50–200 chars>  (only when type=other)
+ */
+export declare function parseBypass(env?: NodeJS.ProcessEnv): BypassEnvelope;
+/**
+ * Resolve hook config from layered sources, in priority order:
+ *
+ *   1. Env vars (MNEMONIK_API_KEY, MNEMONIK_SERVER) — let users override per-shell.
+ *   2. ~/.mnemonik/scanner.json — already the source of truth for the scanner
+ *      daemon, so reusing it means users with the scanner working are wired
+ *      for hooks for free.
+ *   3. <cwd>/.mnemonik.json — for the per-project `forcingFunctions` block.
+ *
+ * Missing API key returns `apiKey: null` rather than throwing — the dispatcher
+ * fail-opens with a stderr warning so a misconfigured machine never breaks
+ * the user's workflow.
+ */
+export declare function resolveConfig(cwd: string, env?: NodeJS.ProcessEnv): Promise<HookConfig>;

package/dist/lib/env.js

@@ -0,0 +1,106 @@
+/**
+ * Environment helpers: CI detection, bypass parsing, config resolution.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { DEFAULT_FORCING_FUNCTIONS, DEFAULT_SERVER, } from './types.js';
+const VALID_BYPASS_TYPES = new Set([
+    'typo',
+    'formatting',
+    'regenerated',
+    'already_grounded',
+    'other',
+]);
+/**
+ * CI / non-interactive contexts must never block. We mirror the husky
+ * pre-push pattern already used elsewhere: any of these wins.
+ */
+export function isNonInteractive(env = process.env) {
+    if (env.CI === 'true')
+        return true;
+    if (env.GITHUB_ACTIONS === 'true')
+        return true;
+    if (env.MNEMONIK_NONINTERACTIVE === '1')
+        return true;
+    return false;
+}
+/**
+ * Parse the bypass envelope. Refuses any malformed combination — we'd rather
+ * fail-open silently than honour a typoed escape hatch indefinitely.
+ *
+ * Required when active:
+ *   MNEMONIK_BYPASS_HOOKS=1
+ *   MNEMONIK_BYPASS_TYPE=<typo|formatting|regenerated|already_grounded|other>
+ *   MNEMONIK_BYPASS_DETAIL=<50–200 chars>  (only when type=other)
+ */
+export function parseBypass(env = process.env) {
+    if (env.MNEMONIK_BYPASS_HOOKS !== '1') {
+        return { active: false, type: null, detail: null, invalidReason: null };
+    }
+    const rawType = (env.MNEMONIK_BYPASS_TYPE ?? '').trim().toLowerCase();
+    if (!rawType) {
+        return {
+            active: false,
+            type: null,
+            detail: null,
+            invalidReason: 'MNEMONIK_BYPASS_TYPE is required when MNEMONIK_BYPASS_HOOKS=1',
+        };
+    }
+    if (!VALID_BYPASS_TYPES.has(rawType)) {
+        return {
+            active: false,
+            type: null,
+            detail: null,
+            invalidReason: `MNEMONIK_BYPASS_TYPE must be one of ${[...VALID_BYPASS_TYPES].join('|')}`,
+        };
+    }
+    const type = rawType;
+    if (type === 'other') {
+        const detail = (env.MNEMONIK_BYPASS_DETAIL ?? '').trim();
+        if (detail.length < 50 || detail.length > 200) {
+            return {
+                active: false,
+                type: null,
+                detail: null,
+                invalidReason: "MNEMONIK_BYPASS_TYPE='other' requires MNEMONIK_BYPASS_DETAIL of 50–200 chars",
+            };
+        }
+        return { active: true, type, detail, invalidReason: null };
+    }
+    return { active: true, type, detail: null, invalidReason: null };
+}
+async function readJson(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve hook config from layered sources, in priority order:
+ *
+ *   1. Env vars (MNEMONIK_API_KEY, MNEMONIK_SERVER) — let users override per-shell.
+ *   2. ~/.mnemonik/scanner.json — already the source of truth for the scanner
+ *      daemon, so reusing it means users with the scanner working are wired
+ *      for hooks for free.
+ *   3. <cwd>/.mnemonik.json — for the per-project `forcingFunctions` block.
+ *
+ * Missing API key returns `apiKey: null` rather than throwing — the dispatcher
+ * fail-opens with a stderr warning so a misconfigured machine never breaks
+ * the user's workflow.
+ */
+export async function resolveConfig(cwd, env = process.env) {
+    const scanner = await readJson(join(homedir(), '.mnemonik', 'scanner.json'));
+    const projectConfig = await readJson(join(cwd, '.mnemonik.json'));
+    const apiKey = env.MNEMONIK_API_KEY?.trim() || scanner?.apiKey?.trim() || null;
+    const server = (env.MNEMONIK_SERVER?.trim() || scanner?.server?.trim() || DEFAULT_SERVER).replace(/\/$/, '');
+    const forcingFunctions = {
+        ...DEFAULT_FORCING_FUNCTIONS,
+        ...(projectConfig?.forcingFunctions ?? {}),
+    };
+    return { apiKey, server, forcingFunctions };
+}
+//# sourceMappingURL=env.js.map

package/dist/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"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"}

package/dist/lib/http.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tiny HTTP client for the hook → Mnemonik server path. Hard 2-second budget;
+ * any timeout / network error returns null so the dispatcher fails open.
+ *
+ * Uses Node 20's global `fetch` — zero npm dependencies on the runtime side.
+ */
+import type { SnapshotResponse } from './types.js';
+export interface FetchSnapshotInput {
+    server: string;
+    apiKey: string;
+    cwd: string;
+    claudeSessionId: string;
+}
+export declare function fetchSnapshot(input: FetchSnapshotInput): Promise<SnapshotResponse | null>;
+/**
+ * Fire-and-forget bypass telemetry. We always write to a local audit log and
+ * additionally try to POST it to the server, but neither failure is allowed
+ * to delay or block the hook decision.
+ */
+export interface ReportBypassInput {
+    server: string;
+    apiKey: string | null;
+    cwd: string;
+    claudeSessionId: string;
+    tool: string;
+    bypassType: string;
+    detail: string | null;
+}
+export declare function reportBypass(input: ReportBypassInput): Promise<void>;

package/dist/lib/http.js

@@ -0,0 +1,63 @@
+/**
+ * Tiny HTTP client for the hook → Mnemonik server path. Hard 2-second budget;
+ * any timeout / network error returns null so the dispatcher fails open.
+ *
+ * Uses Node 20's global `fetch` — zero npm dependencies on the runtime side.
+ */
+const TIMEOUT_MS = 2000;
+export async function fetchSnapshot(input) {
+    const url = `${input.server.replace(/\/$/, '')}/api/v1/hooks/snapshot`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${input.apiKey}`,
+            },
+            body: JSON.stringify({ cwd: input.cwd, claudeSessionId: input.claudeSessionId }),
+            signal: ac.signal,
+        });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function reportBypass(input) {
+    if (!input.apiKey)
+        return;
+    const url = `${input.server.replace(/\/$/, '')}/api/v1/hooks/bypass`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+    try {
+        await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${input.apiKey}`,
+            },
+            body: JSON.stringify({
+                cwd: input.cwd,
+                claudeSessionId: input.claudeSessionId,
+                tool: input.tool,
+                bypassType: input.bypassType,
+                detail: input.detail,
+            }),
+            signal: ac.signal,
+        });
+    }
+    catch {
+        // Telemetry must not crash the hook.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,GAAG,IAAI,CAAC;AASxB,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAyB;IAC3D,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,wBAAwB,CAAC;IACvE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE;aACxC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;YAChF,MAAM,EAAE,EAAE,CAAC,MAAM;SAClB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAwB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO;IAC1B,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC;IACrE,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,GAAG,EAAE;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE;aACxC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,eAAe,EAAE,KAAK,CAAC,eAAe;gBACtC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC;YACF,MAAM,EAAE,EAAE,CAAC,MAAM;SAClB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;IACvC,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/lib/shellTokens.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tiny shell tokenizer good enough for matching destructive Bash patterns.
+ *
+ * Why not a full shell parser? Because:
+ *   - We only need to recognise patterns like `git push origin main` or
+ *     `rm -rf /`, not interpret pipes, redirects, command substitution, or
+ *     shell builtins.
+ *   - A full parser introduces a runtime dep — the dispatcher is meant to
+ *     be a single self-contained file with zero npm dependencies.
+ *   - The regex-only approach is the false-positive trap the plan explicitly
+ *     calls out (e.g. matching `rm -rf` inside a string literal). We avoid
+ *     that by tokenising first and only matching tokens, never substrings.
+ *
+ * Limitations the caller MUST know:
+ *   - Single-quoted strings are kept verbatim as one token (correct).
+ *   - Double-quoted strings keep their content but $expansion is NOT resolved.
+ *   - Backticks / $(...) are tokenised as raw text, not recursed into.
+ *   - Pipes / redirects / && / || split commands so each side can be matched
+ *     independently — the result is a list of token arrays, one per command.
+ */
+export interface TokenizeResult {
+    /** Each entry is one command in a pipeline / sequence. */
+    commands: string[][];
+}
+export declare function tokenize(input: string): TokenizeResult;
+/**
+ * Match a token sequence against a project policy pattern.
+ *
+ * Patterns can be:
+ *   - Plain phrases like "git push origin main" — substring-matched against
+ *     the joined command after tokenisation. Whitespace-normalised both sides.
+ *   - Glob-ish wildcards like "git push *" → "*" matches any single token.
+ *   - Regex: when the pattern starts with "/" and ends with "/" or "/i",
+ *     the inner expression is compiled and run against the joined command.
+ *
+ * Returning the matched pattern (verbatim) lets the dispatcher key bypass
+ * telemetry / dedup against `recentPolicyChecks` exactly.
+ */
+export declare function matchCommand(commandTokens: string[], patterns: string[]): string | null;
+/**
+ * Built-in destructive patterns. Project-level policies extend this set;
+ * they're never shrunk, so a project can only ADD restrictions to what's
+ * here, never remove them.
+ *
+ * Kept intentionally narrow — only commands where the cost of asking is
+ * small and the cost of NOT asking is large.
+ */
+export declare const BUILT_IN_DESTRUCTIVE: readonly string[];

package/dist/lib/shellTokens.js

@@ -0,0 +1,181 @@
+/**
+ * Tiny shell tokenizer good enough for matching destructive Bash patterns.
+ *
+ * Why not a full shell parser? Because:
+ *   - We only need to recognise patterns like `git push origin main` or
+ *     `rm -rf /`, not interpret pipes, redirects, command substitution, or
+ *     shell builtins.
+ *   - A full parser introduces a runtime dep — the dispatcher is meant to
+ *     be a single self-contained file with zero npm dependencies.
+ *   - The regex-only approach is the false-positive trap the plan explicitly
+ *     calls out (e.g. matching `rm -rf` inside a string literal). We avoid
+ *     that by tokenising first and only matching tokens, never substrings.
+ *
+ * Limitations the caller MUST know:
+ *   - Single-quoted strings are kept verbatim as one token (correct).
+ *   - Double-quoted strings keep their content but $expansion is NOT resolved.
+ *   - Backticks / $(...) are tokenised as raw text, not recursed into.
+ *   - Pipes / redirects / && / || split commands so each side can be matched
+ *     independently — the result is a list of token arrays, one per command.
+ */
+const META_TOKENS = new Set(['|', '||', '&&', ';', '&', '>', '>>', '<', '<<']);
+export function tokenize(input) {
+    const commands = [];
+    let current = [];
+    let buf = '';
+    let mode = 'normal';
+    const flushToken = () => {
+        if (buf.length > 0) {
+            current.push(buf);
+            buf = '';
+        }
+    };
+    const flushCommand = () => {
+        flushToken();
+        if (current.length > 0)
+            commands.push(current);
+        current = [];
+    };
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        if (mode === 'single') {
+            if (c === "'") {
+                mode = 'normal';
+            }
+            else {
+                buf += c;
+            }
+            continue;
+        }
+        if (mode === 'double') {
+            if (c === '"') {
+                mode = 'normal';
+            }
+            else if (c === '\\' && i + 1 < input.length) {
+                // Handle escaped quotes inside double-quoted strings.
+                buf += input[++i];
+            }
+            else {
+                buf += c;
+            }
+            continue;
+        }
+        // mode === 'normal'
+        if (c === "'") {
+            mode = 'single';
+            continue;
+        }
+        if (c === '"') {
+            mode = 'double';
+            continue;
+        }
+        if (c === '\\' && i + 1 < input.length) {
+            buf += input[++i];
+            continue;
+        }
+        if (c === ' ' || c === '\t' || c === '\n') {
+            flushToken();
+            continue;
+        }
+        // Two-char meta tokens we recognise.
+        if ((c === '|' && input[i + 1] === '|') ||
+            (c === '&' && input[i + 1] === '&') ||
+            (c === '>' && input[i + 1] === '>') ||
+            (c === '<' && input[i + 1] === '<')) {
+            flushCommand();
+            i++;
+            continue;
+        }
+        if (c === '|' || c === ';' || c === '&') {
+            flushCommand();
+            continue;
+        }
+        if (c === '>' || c === '<') {
+            flushCommand();
+            continue;
+        }
+        buf += c;
+    }
+    flushCommand();
+    return { commands };
+}
+/**
+ * Match a token sequence against a project policy pattern.
+ *
+ * Patterns can be:
+ *   - Plain phrases like "git push origin main" — substring-matched against
+ *     the joined command after tokenisation. Whitespace-normalised both sides.
+ *   - Glob-ish wildcards like "git push *" → "*" matches any single token.
+ *   - Regex: when the pattern starts with "/" and ends with "/" or "/i",
+ *     the inner expression is compiled and run against the joined command.
+ *
+ * Returning the matched pattern (verbatim) lets the dispatcher key bypass
+ * telemetry / dedup against `recentPolicyChecks` exactly.
+ */
+export function matchCommand(commandTokens, patterns) {
+    if (commandTokens.length === 0 || patterns.length === 0)
+        return null;
+    const joined = commandTokens.join(' ').trim();
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern)
+            continue;
+        if (pattern.startsWith('/')) {
+            // /regex/ or /regex/i
+            const tail = pattern.endsWith('/i') ? '/i' : pattern.endsWith('/') ? '/' : null;
+            if (!tail)
+                continue;
+            const body = pattern.slice(1, pattern.length - tail.length);
+            try {
+                const re = new RegExp(body, tail === '/i' ? 'i' : '');
+                if (re.test(joined))
+                    return pattern;
+            }
+            catch {
+                // Invalid regex pattern — skip rather than crash.
+            }
+            continue;
+        }
+        if (pattern.includes('*')) {
+            const escapedSegments = pattern
+                .split('*')
+                .map((seg) => seg.replace(/[.+?^${}()|[\]\\]/g, '\\$&'));
+            const re = new RegExp(`^${escapedSegments.join('.*')}$`);
+            if (re.test(joined))
+                return pattern;
+            continue;
+        }
+        // Plain substring — common case for forbiddenCommand patterns like
+        // "git push origin main".
+        if (joined.includes(pattern))
+            return pattern;
+    }
+    return null;
+}
+/**
+ * Built-in destructive patterns. Project-level policies extend this set;
+ * they're never shrunk, so a project can only ADD restrictions to what's
+ * here, never remove them.
+ *
+ * Kept intentionally narrow — only commands where the cost of asking is
+ * small and the cost of NOT asking is large.
+ */
+export const BUILT_IN_DESTRUCTIVE = [
+    'git push origin main',
+    'git push origin master',
+    'git push --force',
+    'git reset --hard',
+    'git merge main',
+    'git merge master',
+    'git branch -D',
+    'npm publish',
+    'pnpm publish',
+    'yarn publish',
+    'docker rm',
+    'docker rmi',
+    'kubectl delete',
+    'rm -rf /',
+    'rm -rf ~',
+    'rm -rf $HOME',
+];
+//# sourceMappingURL=shellTokens.js.map

package/dist/lib/shellTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellTokens.js","sourceRoot":"","sources":["../../src/lib/shellTokens.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Claude Code hook protocol — only the fields this dispatcher actually reads.
+ * Spec: https://docs.claude.com/en/docs/claude-code/hooks
+ *
+ * We intentionally stay narrow: extra fields the host may ship are ignored
+ * silently so newer Claude Code versions don't break the dispatcher.
+ */
+export type HookEventName = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'UserPromptSubmit' | 'Notification' | 'PreCompact' | 'SessionEnd';
+export interface HookInput {
+    session_id: string;
+    transcript_path?: string;
+    cwd: string;
+    hook_event_name: HookEventName;
+    permission_mode?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: Record<string, unknown>;
+    tool_use_id?: string;
+}
+/** PreToolUse decision shape recognised by Claude Code. */
+export type PermissionDecision = 'allow' | 'deny' | 'ask' | 'defer';
+export interface PreToolUseDecision {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision?: PermissionDecision;
+        permissionDecisionReason?: string;
+        additionalContext?: string;
+        updatedInput?: Record<string, unknown>;
+    };
+}
+export interface PostToolUseDecision {
+    hookSpecificOutput: {
+        hookEventName: 'PostToolUse';
+        additionalContext?: string;
+    };
+}
+/** Bypass envelope wired through MNEMONIK_BYPASS_HOOKS=1. */
+export type BypassType = 'typo' | 'formatting' | 'regenerated' | 'already_grounded' | 'other';
+export interface BypassEnvelope {
+    active: boolean;
+    type: BypassType | null;
+    detail: string | null;
+    /** When non-null, the bypass envelope was malformed and the gate must NOT
+     *  honour it — we'd rather fail open silently than silently let a typo
+     *  in MNEMONIK_BYPASS_TYPE turn into a permanent escape hatch. */
+    invalidReason: string | null;
+}
+/** Server snapshot returned by /api/v1/hooks/snapshot. */
+export interface SnapshotResponse {
+    ok: boolean;
+    reason?: 'unauthorized' | 'no_project' | 'no_active_session';
+    coveredFiles: string[];
+    editedFiles: string[];
+    mustConfirmPauseAt: number | null;
+    recentPolicyChecks: Record<string, number>;
+    policies: {
+        forbiddenCommand: Array<{
+            pattern: string;
+            description: string;
+        }>;
+        mustConfirm: Array<{
+            pattern: string;
+            description: string;
+            replacement: string | null;
+        }>;
+    };
+    sessionsMerged: number;
+    now: number;
+}
+/** Minimal config read from .mnemonik.json + ~/.mnemonik/scanner.json. */
+export interface HookConfig {
+    apiKey: string | null;
+    server: string;
+    forcingFunctions: {
+        preEditGate: 'advisory' | 'enforce' | 'off';
+        preBashGate: 'advisory' | 'enforce' | 'off';
+        advisoryAutoFetch: boolean;
+    };
+}
+export declare const DEFAULT_FORCING_FUNCTIONS: HookConfig['forcingFunctions'];
+export declare const DEFAULT_SERVER = "https://api.mnemonik.dev";

package/dist/lib/types.js

@@ -0,0 +1,16 @@
+/**
+ * Claude Code hook protocol — only the fields this dispatcher actually reads.
+ * Spec: https://docs.claude.com/en/docs/claude-code/hooks
+ *
+ * We intentionally stay narrow: extra fields the host may ship are ignored
+ * silently so newer Claude Code versions don't break the dispatcher.
+ */
+export const DEFAULT_FORCING_FUNCTIONS = {
+    // Advisory at first ship — the plan only flips enforce by default at v4.0
+    // if dogfood telemetry shows bypass rate <5% and false-positive rate <1%.
+    preEditGate: 'advisory',
+    preBashGate: 'advisory',
+    advisoryAutoFetch: true,
+};
+export const DEFAULT_SERVER = 'https://api.mnemonik.dev';
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwFH,MAAM,CAAC,MAAM,yBAAyB,GAAmC;IACvE,0EAA0E;IAC1E,0EAA0E;IAC1E,WAAW,EAAE,UAAU;IACvB,WAAW,EAAE,UAAU;IACvB,iBAAiB,EAAE,IAAI;CACxB,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mnemonik/claude-code-hooks",
+  "version": "0.1.0",
+  "description": "Claude Code PreToolUse / PostToolUse hooks for Mnemonik forcing-functions (advisory grounding gate). filesToWrite delivery of skill/rules/.mnemonik.json continues to flow for ALL clients including Claude Code — this package adds host-side hook gating only. Versioned independently from the @mnemonik/server release cadence (mirrors @mnemonik/scanner).",
+  "type": "module",
+  "bin": {
+    "mnemonik-claude-code-hooks": "dist/install.js"
+  },
+  "main": "dist/install.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mnemonik",
+    "claude-code",
+    "hooks"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^22.0.0"
+  }
+}