@hasna/hooks 0.9.0 → 0.9.2

package/dist/storage.js

@@ -458,6 +458,18 @@ function runRetention(db, days) {
 import { Database } from "bun:sqlite";
 import { existsSync as existsSync3, mkdirSync, cpSync } from "fs";
 import { join as join3 } from "path";
+function refuseLocalStore(message) {
+  localStoreRefusal = message;
+}
+function allowLocalStore() {
+  localStoreRefusal = null;
+}
+function isLocalStoreRefused() {
+  return localStoreRefusal !== null;
+}
+function localStoreRefusalMessage() {
+  return localStoreRefusal;
+}
 function resolveDataDir() {
   const effective = getEffectiveDataRoot();
   const oldDir = join3(getHomeDir(), ".hooks");
@@ -481,6 +493,8 @@ function ensureDir(dbPath) {
   }
 }
 function getDb() {
+  if (localStoreRefusal !== null)
+    throw new Error(localStoreRefusal);
   if (instance)
     return instance;
   const dbPath = getDbPath();
@@ -506,7 +520,7 @@ function getDb() {
   }
   return instance;
 }
-var instance = null;
+var instance = null, localStoreRefusal = null;
 var init_db = __esm(() => {
   init_app_home();
   init_migrations();

package/hooks/hook-mementos-context/README.md

@@ -0,0 +1,80 @@
+# Mementos prompt context
+
+Optional `UserPromptSubmit` context for Codex, Claude Code and Codewith. Mementos
+retrieves existing memories from an explicitly resolved project. If decision
+assistance is enabled, the configured provider judges relevance; it does not
+generate memories, authorize actions or change stored records.
+
+Install compatible `@hasna/mementos` and `@hasna/hooks` CLIs, then register:
+
+```sh
+hooks install mementos-context --target codex
+# Review the exact registration in Codex /hooks before trusting it.
+# Claude Code: use --target claude.
+# Codewith: --target codewith emits a TOML fragment for its config owner.
+```
+
+Codex registration writes `~/.codex/hooks.json` (or `.codex/hooks.json` with
+`--project`). It preserves unrelated entries and refuses malformed or changed
+settings. It does not change `config.toml`, project trust or native hook trust.
+Codex skips an untrusted or modified definition until reviewed. `--target all`
+retains the existing Claude/Codewith install group; select Codex explicitly.
+Use `hooks list --registered --target codex` and
+`hooks remove mementos-context --target codex` to inspect or remove registration.
+
+The hook does nothing until its calling process sets `HOOKS_MEMENTOS_ENABLED=1`.
+For example, start a fresh Codex CLI from a shell with:
+
+```sh
+export HOOKS_MEMENTOS_ENABLED=1
+export HOOKS_MEMENTOS_PROJECT=my-project
+codex
+```
+
+`my-project` must resolve to an existing Mementos project ID, name or registered
+path. Without this override, the native event's `cwd` is the project reference.
+An unknown project returns no context. Shared memories span sessions; the native
+session ID is not automatically applied as a retrieval filter. Existing running
+clients do not acquire newly exported environment variables.
+
+Provider assistance is independently opt-in. For OpenRouter:
+
+```sh
+mementos decisions configure --provider openrouter --model typesafe/jev-1.13
+mementos decisions enable --retrieval
+export HOOKS_MEMENTOS_OPENROUTER_SECRET_REF=example/openrouter/key
+```
+
+The reference must name an existing key available through the optional Secrets
+CLI. The hook invokes `secrets exec <reference> --as OPENROUTER_API_KEY -- mementos
+prompt-context ...`; the key reaches only the Mementos consumer. Do not place key
+values in hook commands, profiles or settings. Hooks' environment credential
+filter remains in force. Without a provider or key, baseline retrieval works.
+Provider enablement permits sending the redacted prompt and bounded memory
+excerpts to that provider; redaction is heuristic, so select the intended scope.
+
+| Environment variable (prefix `HOOKS_MEMENTOS_`) | Default / meaning |
+| --- | --- |
+| `ENABLED` | Unset; only `1` enables execution |
+| `PROJECT` | Native event `cwd`; explicit registered project reference |
+| `SCOPE` | `shared`; `private` or `working` require both filters below |
+| `AGENT_ID`, `SESSION_ID` | Optional explicit Mementos retrieval filters |
+| `TAGS` | Optional JSON array of up to 10 tags |
+| `MAX_ITEMS`, `MAX_CANDIDATES` | 3 selected / 12 retrieved; bounds 10 / 20 |
+| `MAX_TOKENS` | 1000, estimated as UTF-8 bytes / 4; hard maximum 8192 bytes |
+| `MIN_RELEVANCE` | 0.5; applied only to successful provider judgments |
+| `TIMEOUT_MS` | 3500; total child deadline adds 1000 ms, maximum 11000 ms |
+| `COMMAND` | `mementos`; optional executable path, never a shell expression |
+| `OPENROUTER_SECRET_REF` | Unset; optional Secrets key reference |
+
+The hook reads at most 32 KiB of native input and 24 KiB of CLI output, inserts at
+most 8 KiB of context, and always continues the prompt. Provider failure falls
+back to the retrieved order; retrieval/configuration failure inserts nothing.
+Context is quoted JSON with record IDs, versions, scope and source, explicitly
+labelled untrusted reference data. Jev scores are advisory and are not guaranteed
+to be identical across repeated requests.
+
+Mementos owns the retrieval operation (`mementos prompt-context --help`). Hooks
+owns registration and execution. No watcher, channel consumer or web interface
+is required. Installed registration, native trust and actual event execution are
+separate states; use a native prompt event to verify the final integration.

package/hooks/hook-mementos-context/src/hook.ts

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+
+const INPUT_BYTES = 32768;
+const OUTPUT_BYTES = 24576;
+const CONTEXT_BYTES = 8192;
+type HookOutput = { continue: true; hookSpecificOutput?: { hookEventName: "UserPromptSubmit"; additionalContext: string } };
+type Invocation = { command: string; args: string[]; input: string; timeoutMs: number };
+type Executor = (invocation: Invocation) => Promise<string | null>;
+const pass = (): HookOutput => ({ continue: true });
+
+function numberOption(env: NodeJS.ProcessEnv, name: string, fallback: number, min: number, max: number, integer = true): number {
+  const raw = env[`HOOKS_MEMENTOS_${name}`];
+  const value = raw === undefined ? fallback : Number(raw);
+  if (!Number.isFinite(value) || (integer && !Number.isInteger(value)) || value < min || value > max) throw new Error("invalid_configuration");
+  return value;
+}
+
+export function buildInvocation(raw: unknown, env: NodeJS.ProcessEnv): Invocation | null {
+  if (env.HOOKS_MEMENTOS_ENABLED !== "1" || !raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const event = raw as Record<string, unknown>;
+  if (event.hook_event_name !== "UserPromptSubmit" || typeof event.prompt !== "string" || !event.prompt.trim() || event.prompt.length > 4096) return null;
+  const project = env.HOOKS_MEMENTOS_PROJECT ?? event.cwd;
+  if (typeof project !== "string" || !project.trim() || project.length > 4096 || /[\u0000-\u001f]/.test(project)) return null;
+  const timeout = numberOption(env, "TIMEOUT_MS", 3500, 100, 10000);
+  // Shared memory spans sessions. Native session_id is deliberately not a retrieval filter.
+  const input = JSON.stringify({
+    prompt: event.prompt, project, scope: env.HOOKS_MEMENTOS_SCOPE ?? "shared",
+    agent_id: env.HOOKS_MEMENTOS_AGENT_ID, session_id: env.HOOKS_MEMENTOS_SESSION_ID,
+    tags: env.HOOKS_MEMENTOS_TAGS === undefined ? undefined : JSON.parse(env.HOOKS_MEMENTOS_TAGS),
+  });
+  if (Buffer.byteLength(input) > INPUT_BYTES) return null;
+  const args = ["prompt-context", "--enabled", "--input", "-",
+    "--max-items", String(numberOption(env, "MAX_ITEMS", 3, 1, 10)),
+    "--max-candidates", String(numberOption(env, "MAX_CANDIDATES", 12, 1, 20)),
+    "--max-tokens", String(numberOption(env, "MAX_TOKENS", 1000, 128, 2048)),
+    "--min-relevance", String(numberOption(env, "MIN_RELEVANCE", 0.5, 0, 1, false)),
+    "--timeout-ms", String(timeout)];
+  const command = env.HOOKS_MEMENTOS_COMMAND ?? "mementos";
+  // This is one executable, never a shell expression or a command-line string.
+  if (!command || /[\u0000-\u001f]/.test(command)) return null;
+  const secretRef = env.HOOKS_MEMENTOS_OPENROUTER_SECRET_REF;
+  if (secretRef !== undefined) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9_.-]*){1,12}$/.test(secretRef) || secretRef.length > 256) return null;
+    return { command: "secrets", args: ["exec", secretRef, "--as", "OPENROUTER_API_KEY", "--", command, ...args], input, timeoutMs: timeout + 1000 };
+  }
+  return { command, args, input, timeoutMs: timeout + 1000 };
+}
+
+/** Bound only the freshly spawned Mementos/Secrets child tree owned by this invocation. */
+export const execute: Executor = invocation => new Promise(resolve => {
+  let child: ReturnType<typeof spawn>;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let settled = false;
+  let size = 0;
+  const parts: Buffer[] = [];
+  const finish = (value: string | null) => {
+    if (settled) return;
+    settled = true;
+    if (timer) clearTimeout(timer);
+    resolve(value);
+  };
+  const abort = () => {
+    if (settled) return;
+    try {
+      if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL");
+      else child.kill("SIGKILL");
+    } catch { /* child may already have exited */ }
+    finish(null);
+  };
+  try {
+    child = spawn(invocation.command, invocation.args, {
+      stdio: ["pipe", "pipe", "ignore"], shell: false, detached: process.platform !== "win32", env: process.env,
+    });
+    timer = setTimeout(abort, invocation.timeoutMs);
+    child.stdout!.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > OUTPUT_BYTES) abort();
+      else parts.push(Buffer.from(chunk));
+    });
+    child.stdin!.on("error", abort);
+    child.on("error", () => finish(null));
+    child.on("close", code => finish(code === 0 ? Buffer.concat(parts).toString("utf8") : null));
+    child.stdin!.end(invocation.input);
+  } catch { finish(null); }
+});
+
+export async function buildHookOutput(raw: unknown, executor: Executor = execute, env: NodeJS.ProcessEnv = process.env): Promise<HookOutput> {
+  try {
+    const invocation = buildInvocation(raw, env);
+    if (!invocation) return pass();
+    const output = await executor(invocation);
+    if (!output || Buffer.byteLength(output) > OUTPUT_BYTES) return pass();
+    const receipt = JSON.parse(output);
+    if (receipt?.contract !== "mementos.prompt-context.v1" || receipt.status !== "ready" || receipt.advisory !== true
+      || typeof receipt.context !== "string" || !receipt.context || Buffer.byteLength(receipt.context) > CONTEXT_BYTES
+      || receipt.context_bytes !== Buffer.byteLength(receipt.context) || !Array.isArray(receipt.items) || receipt.items.length < 1 || receipt.items.length > 10) return pass();
+    return { continue: true, hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: receipt.context } };
+  } catch { return pass(); }
+}
+
+export async function run(): Promise<void> {
+  let output: HookOutput = pass();
+  try {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length;
+      if (bytes > INPUT_BYTES) throw new Error("input_limit");
+      chunks.push(Buffer.from(chunk));
+    }
+    output = await buildHookOutput(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+  } catch { /* Hook failures never block the user's prompt. */ }
+  process.stdout.write(JSON.stringify(output) + "\n");
+}
+
+if (import.meta.main) void run();

package/hooks/hook-trash-guard/README.md

@@ -94,8 +94,7 @@ advisory warning.
 The registration is written with `timeout: 5`. The harness's documented
 default is 600s, and a hook that times out **does not block** — only a verdict
 already on stdout does. Five seconds is several orders of magnitude above this
-hook's measured cost (a single-pass lexer, no process spawns, no I/O beyond
-one `statSync` per PATH entry).
+hook's measured cost (a bounded lexer and a 500 ms identity check against a verified package binary).
 
 ## Known limitations
 
@@ -111,8 +110,7 @@ The guard is a best-effort **text** classifier, not an execution sandbox.
   here.
 - **A hook only ever sees the agent's own tool calls.** It cannot stop a file
   being deleted by another process, by a build tool, by a script the agent
-  runs, or by `unlink(2)` called directly. Coverage is the Bash tool, wave 1,
-  nothing else — `Write`/`Edit` pre-image capture is wave 2.
+  runs, or by `unlink(2)` called directly. Bash `rm` is rewritten, and native `apply_patch` whole-file deletion is refused with an instruction to call Trash first. Ordinary `Write`/`Edit` pre-image capture is not implemented.
 - **Nested and generated commands escape it.** `bash -c`, `eval`, `make`,
   `npm run`, a `Dockerfile`, a heredoc-fed interpreter: the hook can only see
   that a shell string mentions a delete verb and refuse it, never redirect
@@ -128,5 +126,22 @@ The guard is a best-effort **text** classifier, not an execution sandbox.
 ## Configuration
 
 None. The home directory comes from `os.homedir()`; the trash binary is
-resolved by scanning `PATH` for an executable `trash` and rewriting to the
+resolved by scanning `PATH` for a verified `@hasna/trash` package and its `--identity` protocol and rewriting to the
 absolute path found, so the rewritten command does not depend on `PATH` again.
+
+## Native Codex and Claude
+
+The guard emits their documented `PreToolUse` decision contract, including a
+complete `updatedInput.command`. No-op hooks emit no output. Codex unified exec
+also matches `Bash`; a `Delete File` patch must use `trash put` first. Configure
+Codex in `~/.codex/hooks.json` with matcher
+`^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$` and the command
+`hooks run trash-guard`, with hook timeout 5 seconds. Preserve other registrations
+and refuse a second overlapping input-rewriting hook. Claude registration uses
+`hooks install trash-guard --target claude`. The command rewrite defaults to
+600 seconds for upload and verification, preserving an explicitly supplied timeout.
+
+After installation, prove the native harness actually executes the rewritten
+command using a disposable file and a hosted entry/restore receipt; a hook JSON
+response alone does not prove interception. Other harnesses can use the Trash
+CLI/MCP directly; this hook does not claim their native interception.

package/hooks/hook-trash-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trash-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Codewith-native Trash Guard hook for @hasna/hooks",
   "type": "module",
   "main": "./src/hook.ts",

package/hooks/hook-trash-guard/src/hook.ts

@@ -47,8 +47,9 @@
  */
 
 import { homedir } from "os";
-import { isAbsolute, join, normalize, resolve, sep } from "path";
-import { statSync } from "fs";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "path";
+import { readFileSync, realpathSync, statSync } from "fs";
+import { spawnSync } from "node:child_process";
 import {
   SYSTEM_PROTECTED_ROOTS,
   getCommand,
@@ -63,10 +64,10 @@ const RULE = "trash-guard";
 
 /**
  * Default Bash-tool timeout (ms) re-supplied on the rewrite. The rewritten
- * command is a same-device move, not a byte copy, so it is fast; an explicit
+ * command uploads and verifies the hosted capsule before source cleanup; an explicit
  * value keeps the rewritten tool_input complete.
  */
-const DEFAULT_TIMEOUT_MS = 120000;
+const DEFAULT_TIMEOUT_MS = 600000;
 
 /** Description supplied only when the model did not provide one. */
 const DEFAULT_DESCRIPTION = "Delete via trash guard (rm intercepted and made recoverable)";
@@ -864,22 +865,37 @@ function gitHasDryRun(segment: Segment, verbIndex: number): boolean {
 /* ------------------------------------------------------------------ */
 
 /**
- * Locate the `trash` executable on PATH and return its absolute path, or null
- * when there is nothing to redirect to. Presence only — the guard decision
- * never waits on the binary, its store, or a network.
+ * A command called trash may be Apple's unrelated system utility. Resolve
+ * package provenance before executing a bounded, credential-free identity
+ * probe. Never invoke an unknown executable merely to discover what it is.
  */
 export function findTrashBinary(env: NodeJS.ProcessEnv = process.env): string | null {
   const pathValue = env.PATH ?? "";
-  for (const dir of pathValue.split(":")) {
-    if (!dir) continue;
-    // resolve(): a relative PATH entry still yields the absolute path the
-    // rewrite must use, so the rewritten command never depends on PATH again.
+  const deadline = Date.now() + 2_000;
+  for (const dir of pathValue.split(":").slice(0, 64)) {
+    if (!isAbsolute(dir) || Date.now() >= deadline) continue;
     const candidate = resolve(dir, "trash");
     try {
       const stat = statSync(candidate);
-      if (stat.isFile() && (stat.mode & 0o111) !== 0) return candidate;
+      if (!stat.isFile() || (stat.mode & 0o111) === 0 || (stat.mode & 0o022) !== 0) continue;
+      const executable = realpathSync(candidate);
+      const packageRoot = resolve(dirname(executable), "../..");
+      const manifestPath = join(packageRoot, "package.json");
+      const manifestStat = statSync(manifestPath);
+      if (!manifestStat.isFile() || manifestStat.size > 16_384 || (manifestStat.mode & 0o022) !== 0) continue;
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (manifest.name !== "@hasna/trash" || typeof manifest.version !== "string" ||
+          typeof manifest.bin?.trash !== "string" || realpathSync(resolve(packageRoot, manifest.bin.trash)) !== executable) continue;
+      const probe = spawnSync(candidate, ["--identity"], {
+        encoding: "utf8", timeout: Math.max(1, Math.min(500, deadline - Date.now())), maxBuffer: 2_048,
+        env: { PATH: pathValue }, stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (probe.error || probe.status !== 0) continue;
+      const identity = JSON.parse(probe.stdout);
+      if (identity.name === "@hasna/trash" && identity.version === manifest.version &&
+          identity.guardProtocol === "hasna.trash.guard.v1") return candidate;
     } catch {
-      // not there — keep looking
+      // Missing, unrelated, malformed or unresponsive packages are not targets.
     }
   }
   return null;
@@ -1004,10 +1020,18 @@ function resolveTrash(deps: GuardDependencies): { path: string | null; error: st
 }
 
 const ABSENT_REASON =
-  "[trash-guard] `trash` is not on PATH, so this `rm` cannot be redirected into a recoverable delete — and an unrecoverable delete is never allowed, so the command is refused rather than run. Install @hasna/trash (`npm install -g @hasna/trash`), which puts the binary on PATH, then re-run the same command: it is then rewritten to `trash guard` and the files land in trash instead of disappearing.";
+  "[trash-guard] No verified @hasna/trash guard was found on PATH. This deletion is refused. Install the current @hasna/trash package with Bun and run its setup; the operating-system trash utility is not a compatible guard.";
 
 export function evaluate(input: CodewithHookInput, deps: GuardDependencies): CodewithHookOutput {
   if (input.hook_event_name !== "PreToolUse") return { continue: true };
+  if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name ?? "")) {
+    const patch = input.tool_input?.command;
+    if (typeof patch !== "string") return deny("[trash-guard] Unreadable patch input; deletion safety cannot be checked.");
+    if (/^\s*\*\*\* Delete File:/m.test(patch)) {
+      return deny("[trash-guard] Delete File would bypass recoverable deletion. First use `trash put -- <path>` or the trash_put MCP tool, then submit any remaining edits without the deletion block.");
+    }
+    return { continue: true };
+  }
   if (input.tool_name !== "Bash") return { continue: true };
 
   // A command we cannot READ is a payload we cannot verify, and the harness
@@ -1089,7 +1113,7 @@ export function evaluate(input: CodewithHookInput, deps: GuardDependencies): Cod
 
 /** Verdict used when the hook itself fails: refuse anything that could delete. */
 export function fallbackVerdict(command: string): CodewithHookOutput {
-  return mentionsDeleteVerb(command)
+  return mentionsDeleteVerb(command) || /^\s*\*\*\* Delete File:/m.test(command)
     ? deny(
         "[trash-guard] The hook failed while classifying this command, so it cannot be proven free of an unredirected delete. Re-run the delete as a plain `rm -- <path>` command.",
       )
@@ -1101,10 +1125,14 @@ export async function run(): Promise<void> {
   const command = getCommand(input);
   try {
     const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
-    respond(evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary }));
+    const verdict = evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary });
+    // Native Codex rejects `continue` in PreToolUse JSON. Silence is the
+    // documented no-op for both Codex and Claude; emit only actual decisions.
+    if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
   } catch (error) {
     warn(`${RULE} failed: ${error instanceof Error ? error.message : String(error)}`);
-    respond(fallbackVerdict(command));
+    const verdict = fallbackVerdict(command);
+    if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
   }
 }
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
     "hooks": "bin/index.js",
+    "hooks-mcp": "bin/hooks-mcp.js",
     "hooks-serve": "bin/serve.js"
   },
   "exports": {
@@ -12,6 +13,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
+    },
     "./storage": {
       "types": "./dist/storage.d.ts",
       "import": "./dist/storage.js"
@@ -20,7 +25,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
+    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "dev": "bun run ./src/cli/index.tsx",
     "test": "bun test",
@@ -84,12 +89,13 @@
     "!hooks/**/*.test.ts",
     "!hooks/**/tsconfig.json"
   ],
-  "homepage": "https://github.com/hasna/hooks#readme",
+  "homepage": "https://github.com/hasna/apps/tree/main/apps/hooks#readme",
   "bugs": {
-    "url": "https://github.com/hasna/hooks/issues"
+    "url": "https://github.com/hasna/apps/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/hooks.git"
+    "url": "https://github.com/hasna/apps.git",
+    "directory": "apps/hooks"
   }
 }

package/scripts/validate-package.ts

@@ -173,15 +173,27 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
     const dataDir = join(workspace, "data");
     const binIndex = join(packageDir, "bin", "index.js");
     const binServe = join(packageDir, "bin", "serve.js");
+    const binMcp = join(packageDir, "bin", "hooks-mcp.js");
+    const sdkBundle = join(packageDir, "dist", "sdk", "index.js");
     if (!existsSync(binIndex)) throw new Error(`packed tarball is missing bin/index.js (CLI bin)`);
     if (!existsSync(binServe)) throw new Error(`packed tarball is missing bin/serve.js (serve bin)`);
+    if (!existsSync(binMcp)) throw new Error(`packed tarball is missing bin/hooks-mcp.js (MCP bin)`);
+    if (!existsSync(sdkBundle)) throw new Error(`packed tarball is missing dist/sdk/index.js (./sdk export)`);
 
+    // Hermetic route: the smoke lanes below exercise the on-box store on
+    // purpose, so they opt in explicitly (hasna/apps#1720 — without the
+    // opt-in `hooks run` and `hooks-mcp` fail closed, which the fail-closed
+    // lane checks separately) and keep the station's Keychain out of it.
     const env = {
       ...process.env,
+      HASNA_STATION: "no-such-station",
+      HASNA_HOOKS_LOCAL: "1",
       HASNA_HOOKS_DATA_DIR: dataDir,
       HASNA_HOOKS_DB_PATH: join(dataDir, "hooks.db"),
       NO_COLOR: "1",
     };
+    const failClosedEnv = { ...env };
+    delete (failClosedEnv as Record<string, string | undefined>).HASNA_HOOKS_LOCAL;
 
     // 1. CLI help.
     const help = spawnSync("bun", ["run", binIndex, "--help"], { cwd: smokeDir, env, encoding: "utf8" });
@@ -210,8 +222,22 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
       await new Promise((r) => setTimeout(r, 100));
     }
 
-    // 3. MCP stdio startup: an initialize handshake must get a response.
-    const mcpProc = spawn("bun", ["run", binIndex, "mcp", "--stdio"], {
+    // 2b. Fail-closed lane (hasna/apps#1720): with nothing configured the
+    // packed CLI and the packed hooks-mcp bin exit non-zero, name the
+    // credential tiers + the opt-in on stderr, and create no local store.
+    const failClosedHome = join(workspace, "failclosed-home");
+    const fcEnv = { ...failClosedEnv, HOME: failClosedHome, HASNA_HOOKS_DATA_DIR: join(failClosedHome, "data"), HASNA_HOOKS_DB_PATH: join(failClosedHome, "data", "hooks.db") };
+    for (const [label, argv] of [["packed CLI `hooks categories`", [binIndex, "categories"]], ["packed hooks-mcp", [binMcp]]] as Array<[string, string[]]>) {
+      const fc = spawnSync("bun", ["run", ...argv], { cwd: smokeDir, env: fcEnv, encoding: "utf8", input: "", timeout: 20000 });
+      if (fc.status === 0) throw new Error(`${label} exited 0 with nothing configured (must fail closed)`);
+      if (!/HASNA_HOOKS_LOCAL=1/.test(fc.stderr) || !/hasna\.credentials\.hooks\.api-key/.test(fc.stderr)) {
+        throw new Error(`${label} refusal did not name the tiers + opt-in: ${fc.stderr.slice(0, 300)}`);
+      }
+      if (existsSync(join(failClosedHome, "data", "hooks.db"))) throw new Error(`${label} created hooks.db while failing closed`);
+    }
+
+    // 3. MCP stdio startup (explicit local opt-in): an initialize handshake must get a response.
+    const mcpProc = spawn("bun", ["run", binMcp], {
       cwd: smokeDir,
       env,
       stdio: ["pipe", "pipe", "pipe"],
@@ -252,11 +278,12 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
       // pg link is best-effort; the import below will fail loudly if needed.
     }
     const sdkSmoke = join(smokeDir, "sdk-smoke.ts");
-    await writeFile(sdkSmoke, `import { HOOKS, getStorageStatus } from "@hasna/hooks";\nimport { getStorageStatus as ss } from "@hasna/hooks/storage";\nconsole.log(JSON.stringify({ count: HOOKS.length, backend: getStorageStatus().backend, ss: ss().backend }));\n`);
+    await writeFile(sdkSmoke, `import { HOOKS, getStorageStatus } from "@hasna/hooks";\nimport { getStorageStatus as ss } from "@hasna/hooks/storage";\nimport { HooksClient, createHooksClient } from "@hasna/hooks/sdk";\nlet sdk = "threw";\ntry { createHooksClient({ env: { HASNA_STATION: "no-such-station" }, credentials: { keychain: { enabled: false } } }); sdk = "returned"; } catch (e) { sdk = /REMOTE_API_/.test(String(e)) ? "fail-closed" : "threw"; }\nconsole.log(JSON.stringify({ count: HOOKS.length, backend: getStorageStatus().backend, ss: ss().backend, sdk, hasClient: typeof HooksClient === "function" }));\n`);
     const sdk = spawnSync("bun", ["run", sdkSmoke], { cwd: smokeDir, env, encoding: "utf8", timeout: 20000 });
     if (sdk.status !== 0) throw new Error(`packed SDK import failed: ${sdk.stderr}`);
-    const sdkOut = JSON.parse(sdk.stdout.trim()) as { count: number; backend: string };
+    const sdkOut = JSON.parse(sdk.stdout.trim()) as { count: number; backend: string; sdk: string; hasClient: boolean };
     if (typeof sdkOut.count !== "number" || sdkOut.count <= 0) throw new Error(`packed SDK import returned count ${sdkOut.count}`);
+    if (sdkOut.sdk !== "fail-closed" || !sdkOut.hasClient) throw new Error(`packed ./sdk export did not fail closed with nothing configured: ${JSON.stringify(sdkOut)}`);
 
     // 5. One bundled-hook run from the packed artifact (isolated data dir;
     // first run self-trusts, then executes).