@hasna/hooks 0.9.1 → 0.9.3

package/dist/lib/codex-settings.d.ts

@@ -0,0 +1,3 @@
+export declare function readCodexSettings(path: string): Record<string, any>;
+/** Preserve the exact read version. Never write trust state or config.toml. */
+export declare function writeCodexSettings(path: string, settings: Record<string, any>): void;

package/dist/lib/installer.d.ts

@@ -11,8 +11,9 @@
  */
 import { type HookEvent, type HookMeta } from "./registry.js";
 import { type StaleRegistration } from "./registration.js";
+import { type MementosRegistration } from "./mementos-options.js";
 export type Scope = "global" | "project";
-export type Target = "claude" | "gemini" | "codewith" | "all";
+export type Target = "claude" | "gemini" | "codewith" | "codex" | "all";
 type SingleTarget = Exclude<Target, "all">;
 export type ConcreteTarget = SingleTarget;
 export type CodewithInstallMode = "fragment" | "write";
@@ -29,6 +30,8 @@ export interface InstallResult {
     configPath?: string;
 }
 export interface InstallOptions {
+    /** Explicit persistent opt-in for mementos-context; omitted updates retain its current choice. */
+    mementos?: MementosRegistration;
     scope?: Scope;
     overwrite?: boolean;
     target?: Target;
@@ -47,7 +50,7 @@ export declare function getHookPath(name: string): string;
 export declare function hookExists(name: string): boolean;
 /** Whether a hook's event can be registered for the given target */
 export declare function isEventSupported(internalEvent: HookEvent, target: SingleTarget): boolean;
-export declare function buildCodewithTomlFragment(name: string, profile?: string): string;
+export declare function buildCodewithTomlFragment(name: string, profile?: string, mementos?: MementosRegistration): string;
 /**
  * The one conflict class that BLOCKS an install: two PreToolUse hooks on
  * overlapping matchers that both rewrite the tool input

package/dist/lib/mementos-options.d.ts

@@ -0,0 +1,16 @@
+/** Persistent opt-in lives in the native hook command, never in a credential file. */
+export interface MementosRegistration {
+    enabled: boolean;
+    secretRef?: string;
+}
+export interface MementosFlags {
+    enableMementos?: boolean;
+    disableMementos?: boolean;
+    openrouterSecretRef?: string;
+}
+export declare function validateMementosRegistration(name: string, value?: MementosRegistration): void;
+export declare function mementosRegistrationFromFlags(name: string, flags: MementosFlags): MementosRegistration | undefined;
+export declare function mementosCommandSuffix(value?: MementosRegistration): string;
+/** Preserve explicit activation across ordinary install --overwrite / update. */
+export declare function retainedMementosRegistration(commands: string[]): MementosRegistration | undefined;
+export declare function mementosRunEnvironment(env: NodeJS.ProcessEnv, value?: MementosRegistration): NodeJS.ProcessEnv;

package/dist/lib/registration.d.ts

@@ -6,6 +6,7 @@
  * an array of { matcher?, hooks: [...] } entries — so a composite event such
  * as 'PreToolUse:Bash' must be split before lookup, never used as a key.
  */
+export declare function registrationName(command: unknown): string | undefined;
 /** A settings registration whose hook name cannot resolve. */
 export interface StaleRegistration {
     /** Settings file the registration lives in. */

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

@@ -0,0 +1,106 @@
+# 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 is off by default. To save a one-time opt-in in the native registration:
+
+```sh
+hooks install mementos-context --target codex --overwrite --enable-mementos
+# Review the changed definition in Codex /hooks before trusting it.
+```
+
+New sessions now run the hook without shell exports. Its project is the session's
+working directory, which must resolve to an existing Mementos project. Routine
+JSON-target registration updates retain this choice. To save a persistent opt-out:
+
+```sh
+hooks install mementos-context --target codex --overwrite --disable-mementos
+```
+
+For a temporary opt-in instead, 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
+```
+
+To persist the reference with activation, replace that export with:
+
+```sh
+hooks install mementos-context --target codex --overwrite --enable-mementos \
+  --openrouter-secret-ref example/openrouter/key
+```
+
+The native command stores only the reference. Existing hook definitions are
+preserved, and native trust is still required after a command changes. Set
+`HOOKS_MEMENTOS_ENABLED=0` to opt out for one session even when its registration
+is enabled. A persistent `--disable-mementos` always disables execution.
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -89,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"
   }
 }