@hasna/hooks 0.9.2 → 0.9.3

package/bin/hooks-mcp.js

@@ -2679,6 +2679,79 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/lib/registration.ts
 init_resolve();
+
+// src/lib/mementos-options.ts
+function validateMementosRegistration(name, value) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || !Object.hasOwn(value, "enabled") || Object.keys(value).some((key) => key !== "enabled" && key !== "secretRef") || name.replace(/^hook-/, "") !== "mementos-context" || typeof value.enabled !== "boolean") {
+    throw new Error("Mementos options require the mementos-context hook and an explicit enable/disable choice.");
+  }
+  if (value.secretRef !== undefined && (!value.enabled || typeof value.secretRef !== "string" || value.secretRef.length > 256 || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9_.-]*){1,12}$/.test(value.secretRef))) {
+    throw new Error("OpenRouter requires an enabled Mementos hook and a valid Secrets reference, never a key value.");
+  }
+}
+function mementosRegistrationFromFlags(name, flags) {
+  if (!flags.enableMementos && !flags.disableMementos && flags.openrouterSecretRef === undefined)
+    return;
+  if (Boolean(flags.enableMementos) === Boolean(flags.disableMementos)) {
+    throw new Error("Choose exactly one of --enable-mementos or --disable-mementos.");
+  }
+  const value = { enabled: flags.enableMementos === true, ...flags.openrouterSecretRef !== undefined ? { secretRef: flags.openrouterSecretRef } : {} };
+  validateMementosRegistration(name, value);
+  return value;
+}
+function mementosCommandSuffix(value) {
+  validateMementosRegistration("mementos-context", value);
+  if (!value)
+    return "";
+  return value.enabled ? ` --enable-mementos${value.secretRef ? ` --openrouter-secret-ref ${value.secretRef}` : ""}` : " --disable-mementos";
+}
+function retainedMementosRegistration(commands) {
+  const values = commands.filter((command) => /^hooks run mementos-context(?:\s|$)/.test(command)).map((command) => {
+    const args = command.trim().split(/\s+/).slice(3);
+    const flags = {};
+    const seen = new Set;
+    while (args.length) {
+      const key = args.shift();
+      if (seen.has(key))
+        throw new Error("Ambiguous Mementos registration; specify its enablement explicitly.");
+      seen.add(key);
+      if (key === "--profile" && /^[\w-]+$/.test(args[0] ?? ""))
+        args.shift();
+      else if (key === "--enable-mementos")
+        flags.enableMementos = true;
+      else if (key === "--disable-mementos")
+        flags.disableMementos = true;
+      else if (key === "--openrouter-secret-ref" && args.length)
+        flags.openrouterSecretRef = args.shift();
+      else
+        throw new Error("Unrecognized Mementos registration options; specify its enablement explicitly.");
+    }
+    return mementosRegistrationFromFlags("mementos-context", flags);
+  });
+  if (new Set(values.map((value) => JSON.stringify(value))).size > 1) {
+    throw new Error("Conflicting Mementos registrations; specify its enablement explicitly.");
+  }
+  return values[0];
+}
+
+// src/lib/registration.ts
+var REGISTRATION_COMMAND_RE = /^(?:hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?|hook-([\w-]+))$/;
+function registrationName(command) {
+  if (typeof command !== "string")
+    return;
+  if (/^hooks run mementos-context(?:\s|$)/.test(command.trim())) {
+    try {
+      retainedMementosRegistration([command.trim()]);
+      return "mementos-context";
+    } catch {
+      return;
+    }
+  }
+  const match = command.trim().match(REGISTRATION_COMMAND_RE);
+  return match ? match[1] ?? match[2] : undefined;
+}
 function matchersOverlap(a, b) {
   return a === b || a.includes(b) || b.includes(a);
 }
@@ -3130,12 +3203,13 @@ function codewithStatusMessage(name) {
       return `Running ${name}`;
   }
 }
-function buildCodewithTomlFragment(name, profile) {
+function buildCodewithTomlFragment(name, profile, mementos) {
   const shortName = shortHookName(name);
   const meta = resolveHookMeta(shortName);
   if (!meta)
     throw new Error(`Hook '${shortName}' not found`);
-  const command = profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`;
+  validateMementosRegistration(shortName, mementos);
+  const command = (profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`) + mementosCommandSuffix(mementos);
   const matcher = codewithMatcher(meta.matcher);
   const fragments = [];
   for (const event of getHookEvents(meta)) {
@@ -3217,14 +3291,14 @@ function detectRewriteConflict(name, scope, target, lookup = getHook) {
   }
   return;
 }
-function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath) {
+function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath, mementos) {
   const shortName = shortHookName(name);
   if (!hookExists(shortName)) {
     return { hook: shortName, success: false, error: `Hook '${shortName}' not found`, target };
   }
   if (target === "codewith") {
     try {
-      const fragment = buildCodewithTomlFragment(shortName, profile);
+      const fragment = buildCodewithTomlFragment(shortName, profile, mementos);
       if (codewithMode !== "write") {
         return {
           hook: shortName,
@@ -3281,7 +3355,7 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
     if (rewriteConflict) {
       return { hook: shortName, success: false, error: `Refused: ${rewriteConflict}`, scope, target };
     }
-    registerHook(shortName, scope, target, profile);
+    registerHook(shortName, scope, target, profile, mementos);
     return {
       hook: shortName,
       success: true,
@@ -3300,7 +3374,12 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
   }
 }
 function installHook(name, options = {}) {
-  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath } = options;
+  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath, mementos } = options;
+  try {
+    validateMementosRegistration(name, mementos);
+  } catch (error) {
+    return { hook: name, success: false, target, error: error instanceof Error ? error.message : "Invalid Mementos options" };
+  }
   if (!/^[\w-]+$/.test(name) || profile !== undefined && !/^[\w-]+$/.test(profile)) {
     return { hook: name, success: false, error: "Hook and profile names must contain only letters, digits, underscores or hyphens.", target };
   }
@@ -3318,7 +3397,7 @@ function installHook(name, options = {}) {
         };
       }
     }
-    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile);
+    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile, "fragment", undefined, mementos);
     if (!claudeResult.success) {
       return {
         ...claudeResult,
@@ -3326,7 +3405,7 @@ function installHook(name, options = {}) {
         target: "all"
       };
     }
-    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath);
+    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath, mementos);
     if (!codewithResult.success) {
       return {
         ...codewithResult,
@@ -3336,9 +3415,9 @@ function installHook(name, options = {}) {
     }
     return { ...claudeResult, target: "all" };
   }
-  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath);
+  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath, mementos);
 }
-function registerHook(name, scope = "global", target = "claude", profile) {
+function registerHook(name, scope = "global", target = "claude", profile, mementos) {
   const meta = resolveHookMeta(name);
   if (!meta)
     return;
@@ -3356,8 +3435,9 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   const settings = readSettings(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
+  const retained = name === "mementos-context" && mementos === undefined ? retainedMementosRegistration(Object.values(settings.hooks).flatMap((groups) => Array.isArray(groups) ? groups.flatMap((group) => Array.isArray(group.hooks) ? group.hooks.map((hook) => hook.command).filter((command) => typeof command === "string") : []) : [])) : undefined;
   removeHookFromAllEvents(settings, name);
-  const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
+  const hookCommand = (profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`) + mementosCommandSuffix(mementos ?? retained);
   for (const eventKey of uniqueEventKeys) {
     if (!settings.hooks[eventKey])
       settings.hooks[eventKey] = [];
@@ -3399,10 +3479,12 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   if (target === "codewith") {
     const config = readCodewithConfig(scope);
     const registered2 = [];
-    const re = /command\s*=\s*["']hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?["']/g;
+    const re = /^\s*command\s*=\s*["']([^"'\n]+)["']\s*$/gm;
     let match;
     while (match = re.exec(config)) {
-      registered2.push(match[1]);
+      const name = registrationName(match[1]);
+      if (name)
+        registered2.push(name);
     }
     return [...new Set(registered2)];
   }
@@ -3413,12 +3495,9 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   for (const eventKey of Object.keys(settings.hooks)) {
     for (const entry of settings.hooks[eventKey]) {
       for (const hook of entry.hooks || []) {
-        const newMatch = hook.command?.match(/^hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?$/);
-        const oldMatch = hook.command?.match(/^hook-([\w-]+)$/);
-        const match = newMatch || oldMatch;
-        if (match) {
-          registered.push(match[1]);
-        }
+        const name = registrationName(hook.command);
+        if (name)
+          registered.push(name);
       }
     }
   }

package/bin/index.js

@@ -4500,10 +4500,84 @@ var init_resolve = __esm(() => {
   init_manifest();
 });
 
+// src/lib/mementos-options.ts
+function validateMementosRegistration(name, value) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || !Object.hasOwn(value, "enabled") || Object.keys(value).some((key) => key !== "enabled" && key !== "secretRef") || name.replace(/^hook-/, "") !== "mementos-context" || typeof value.enabled !== "boolean") {
+    throw new Error("Mementos options require the mementos-context hook and an explicit enable/disable choice.");
+  }
+  if (value.secretRef !== undefined && (!value.enabled || typeof value.secretRef !== "string" || value.secretRef.length > 256 || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9_.-]*){1,12}$/.test(value.secretRef))) {
+    throw new Error("OpenRouter requires an enabled Mementos hook and a valid Secrets reference, never a key value.");
+  }
+}
+function mementosRegistrationFromFlags(name, flags) {
+  if (!flags.enableMementos && !flags.disableMementos && flags.openrouterSecretRef === undefined)
+    return;
+  if (Boolean(flags.enableMementos) === Boolean(flags.disableMementos)) {
+    throw new Error("Choose exactly one of --enable-mementos or --disable-mementos.");
+  }
+  const value = { enabled: flags.enableMementos === true, ...flags.openrouterSecretRef !== undefined ? { secretRef: flags.openrouterSecretRef } : {} };
+  validateMementosRegistration(name, value);
+  return value;
+}
+function mementosCommandSuffix(value) {
+  validateMementosRegistration("mementos-context", value);
+  if (!value)
+    return "";
+  return value.enabled ? ` --enable-mementos${value.secretRef ? ` --openrouter-secret-ref ${value.secretRef}` : ""}` : " --disable-mementos";
+}
+function retainedMementosRegistration(commands) {
+  const values = commands.filter((command) => /^hooks run mementos-context(?:\s|$)/.test(command)).map((command) => {
+    const args = command.trim().split(/\s+/).slice(3);
+    const flags = {};
+    const seen = new Set;
+    while (args.length) {
+      const key = args.shift();
+      if (seen.has(key))
+        throw new Error("Ambiguous Mementos registration; specify its enablement explicitly.");
+      seen.add(key);
+      if (key === "--profile" && /^[\w-]+$/.test(args[0] ?? ""))
+        args.shift();
+      else if (key === "--enable-mementos")
+        flags.enableMementos = true;
+      else if (key === "--disable-mementos")
+        flags.disableMementos = true;
+      else if (key === "--openrouter-secret-ref" && args.length)
+        flags.openrouterSecretRef = args.shift();
+      else
+        throw new Error("Unrecognized Mementos registration options; specify its enablement explicitly.");
+    }
+    return mementosRegistrationFromFlags("mementos-context", flags);
+  });
+  if (new Set(values.map((value) => JSON.stringify(value))).size > 1) {
+    throw new Error("Conflicting Mementos registrations; specify its enablement explicitly.");
+  }
+  return values[0];
+}
+function mementosRunEnvironment(env, value) {
+  validateMementosRegistration("mementos-context", value);
+  if (!value)
+    return env;
+  return {
+    ...env,
+    HOOKS_MEMENTOS_ENABLED: value.enabled && env.HOOKS_MEMENTOS_ENABLED !== "0" ? "1" : "0",
+    ...value.secretRef ? { HOOKS_MEMENTOS_OPENROUTER_SECRET_REF: value.secretRef } : {}
+  };
+}
+
 // src/lib/registration.ts
 function registrationName(command) {
   if (typeof command !== "string")
     return;
+  if (/^hooks run mementos-context(?:\s|$)/.test(command.trim())) {
+    try {
+      retainedMementosRegistration([command.trim()]);
+      return "mementos-context";
+    } catch {
+      return;
+    }
+  }
   const match = command.trim().match(REGISTRATION_COMMAND_RE);
   return match ? match[1] ?? match[2] : undefined;
 }
@@ -5483,12 +5557,13 @@ function codewithStatusMessage(name) {
       return `Running ${name}`;
   }
 }
-function buildCodewithTomlFragment(name, profile) {
+function buildCodewithTomlFragment(name, profile, mementos) {
   const shortName = shortHookName(name);
   const meta = resolveHookMeta(shortName);
   if (!meta)
     throw new Error(`Hook '${shortName}' not found`);
-  const command = profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`;
+  validateMementosRegistration(shortName, mementos);
+  const command = (profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`) + mementosCommandSuffix(mementos);
   const matcher = codewithMatcher(meta.matcher);
   const fragments = [];
   for (const event of getHookEvents(meta)) {
@@ -5570,14 +5645,14 @@ function detectRewriteConflict(name, scope, target, lookup = getHook) {
   }
   return;
 }
-function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath) {
+function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath, mementos) {
   const shortName = shortHookName(name);
   if (!hookExists(shortName)) {
     return { hook: shortName, success: false, error: `Hook '${shortName}' not found`, target };
   }
   if (target === "codewith") {
     try {
-      const fragment = buildCodewithTomlFragment(shortName, profile);
+      const fragment = buildCodewithTomlFragment(shortName, profile, mementos);
       if (codewithMode !== "write") {
         return {
           hook: shortName,
@@ -5634,7 +5709,7 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
     if (rewriteConflict) {
       return { hook: shortName, success: false, error: `Refused: ${rewriteConflict}`, scope, target };
     }
-    registerHook(shortName, scope, target, profile);
+    registerHook(shortName, scope, target, profile, mementos);
     return {
       hook: shortName,
       success: true,
@@ -5653,7 +5728,12 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
   }
 }
 function installHook(name, options = {}) {
-  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath } = options;
+  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath, mementos } = options;
+  try {
+    validateMementosRegistration(name, mementos);
+  } catch (error) {
+    return { hook: name, success: false, target, error: error instanceof Error ? error.message : "Invalid Mementos options" };
+  }
   if (!/^[\w-]+$/.test(name) || profile !== undefined && !/^[\w-]+$/.test(profile)) {
     return { hook: name, success: false, error: "Hook and profile names must contain only letters, digits, underscores or hyphens.", target };
   }
@@ -5671,7 +5751,7 @@ function installHook(name, options = {}) {
         };
       }
     }
-    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile);
+    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile, "fragment", undefined, mementos);
     if (!claudeResult.success) {
       return {
         ...claudeResult,
@@ -5679,7 +5759,7 @@ function installHook(name, options = {}) {
         target: "all"
       };
     }
-    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath);
+    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath, mementos);
     if (!codewithResult.success) {
       return {
         ...codewithResult,
@@ -5689,9 +5769,9 @@ function installHook(name, options = {}) {
     }
     return { ...claudeResult, target: "all" };
   }
-  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath);
+  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath, mementos);
 }
-function registerHook(name, scope = "global", target = "claude", profile) {
+function registerHook(name, scope = "global", target = "claude", profile, mementos) {
   const meta = resolveHookMeta(name);
   if (!meta)
     return;
@@ -5709,8 +5789,9 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   const settings = readSettings(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
+  const retained = name === "mementos-context" && mementos === undefined ? retainedMementosRegistration(Object.values(settings.hooks).flatMap((groups) => Array.isArray(groups) ? groups.flatMap((group) => Array.isArray(group.hooks) ? group.hooks.map((hook) => hook.command).filter((command) => typeof command === "string") : []) : [])) : undefined;
   removeHookFromAllEvents(settings, name);
-  const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
+  const hookCommand = (profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`) + mementosCommandSuffix(mementos ?? retained);
   for (const eventKey of uniqueEventKeys) {
     if (!settings.hooks[eventKey])
       settings.hooks[eventKey] = [];
@@ -5755,10 +5836,12 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   if (target === "codewith") {
     const config = readCodewithConfig(scope);
     const registered2 = [];
-    const re = /command\s*=\s*["']hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?["']/g;
+    const re = /^\s*command\s*=\s*["']([^"'\n]+)["']\s*$/gm;
     let match;
     while (match = re.exec(config)) {
-      registered2.push(match[1]);
+      const name = registrationName(match[1]);
+      if (name)
+        registered2.push(name);
     }
     return [...new Set(registered2)];
   }
@@ -5769,12 +5852,9 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   for (const eventKey of Object.keys(settings.hooks)) {
     for (const entry of settings.hooks[eventKey]) {
       for (const hook of entry.hooks || []) {
-        const newMatch = hook.command?.match(/^hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?$/);
-        const oldMatch = hook.command?.match(/^hook-([\w-]+)$/);
-        const match = newMatch || oldMatch;
-        if (match) {
-          registered.push(match[1]);
-        }
+        const name = registrationName(hook.command);
+        if (name)
+          registered.push(name);
       }
     }
   }
@@ -5876,7 +5956,7 @@ function pruneStaleRegistrations(scope = "global") {
 }
 function removeCodewithHookEntry(configText, name) {
   const sections = configText.split(/\n\s*\n/);
-  const nameRe = new RegExp(`^command\\s*=\\s*"hooks run ${escapeRegExp(name)}(?:\\s+--profile\\s+[\\w-]+)?"$`);
+  const commandRe = /^command\s*=\s*"([^"\n]+)"$/;
   const entryHeaderRe = /^\[\[hooks\.([\w]+)\.hooks\]\]$/;
   const eventHeaderRe = /^\[\[hooks\.([\w]+)\]\]$/;
   const eventsWithEntries = new Set;
@@ -5889,7 +5969,7 @@ function removeCodewithHookEntry(configText, name) {
     if (entryMatch) {
       const event = entryMatch[1];
       eventsWithEntries.add(event);
-      if (lines.some((line) => nameRe.test(line.trim()))) {
+      if (lines.some((line) => registrationName(commandRe.exec(line.trim())?.[1]) === name)) {
         removed = true;
         continue;
       }
@@ -13135,7 +13215,15 @@ program2.command("init").description("Register a new agent profile with a unique
   console.log(`    hooks install gitguard --profile ${profile.agent_id}`);
   console.log();
 });
-program2.command("run").argument("<hook>", "Hook to run").option("--profile <id>", "Agent profile ID").description("Execute a hook (called by AI coding agents)").action(async (hook, options) => {
+program2.command("run").argument("<hook>", "Hook to run").option("--profile <id>", "Agent profile ID").option("--enable-mementos", "Enable mementos-context for this invocation (provider assistance remains separately opt-in)").option("--disable-mementos", "Disable mementos-context for this invocation").option("--openrouter-secret-ref <reference>", "Secrets reference for the enabled Mementos hook; never a key value").description("Execute a hook (called by AI coding agents)").action(async (hook, options) => {
+  let mementos;
+  try {
+    mementos = mementosRegistrationFromFlags(hook, options);
+  } catch (error) {
+    console.error(JSON.stringify({ error: error instanceof Error ? error.message : "Invalid Mementos options" }));
+    process.exitCode = 1;
+    return;
+  }
   const { resolveHook: resolveHook2, resolveScriptPath: resolveScriptPath2 } = await Promise.resolve().then(() => (init_resolve(), exports_resolve));
   const { sha256Of: sha256Of2, checkScriptHash: checkScriptHash2 } = await Promise.resolve().then(() => (init_store(), exports_store));
   const { recordHookRun: recordHookRun2, resolveEventType: resolveEventType2 } = await Promise.resolve().then(() => (init_db_writer(), exports_db_writer));
@@ -13195,7 +13283,7 @@ program2.command("run").argument("<hook>", "Hook to run").option("--profile <id>
       content,
       args,
       stdin: hookStdin,
-      env: process.env,
+      env: mementosRunEnvironment(process.env, mementos),
       timeout
     }));
   } catch (err) {
@@ -13255,7 +13343,7 @@ program2.command("run").argument("<hook>", "Hook to run").option("--profile <id>
     process.stderr.write(stderr);
   process.exit(exitCode);
 });
-program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).option("-a, --all", "Install all available hooks", false).option("-c, --category <category>", "Install all hooks in a category").option("-g, --global", "Install globally (~/.claude/settings.json)", false).option("-p, --project", "Install for current project (.claude/settings.json)", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith, codex, all (default: claude)", "claude").option("--profile <id>", "Agent profile ID to scope hooks to").option("--dry-run", "Preview what would be installed without writing to settings", false).option("--apply-codewith", "Explicitly append Codewith TOML to a config file (prefer configs for managed configs)", false).option("--codewith-config <path>", "Explicit Codewith config path required with --apply-codewith").option("-j, --json", "Output as JSON", false).description("Install one or more hooks (registry names, local paths, git URLs, manifest URLs, or <name>@<version> pinned installs)").action(async (hooks, options) => {
+program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).option("-a, --all", "Install all available hooks", false).option("-c, --category <category>", "Install all hooks in a category").option("-g, --global", "Install globally (~/.claude/settings.json)", false).option("-p, --project", "Install for current project (.claude/settings.json)", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith, codex, all (default: claude)", "claude").option("--profile <id>", "Agent profile ID to scope hooks to").option("--enable-mementos", "Persistently enable mementos-context (provider assistance remains separately opt-in)").option("--disable-mementos", "Persistently disable mementos-context").option("--openrouter-secret-ref <reference>", "Secrets reference for the enabled Mementos hook; never a key value").option("--dry-run", "Preview what would be installed without writing to settings", false).option("--apply-codewith", "Explicitly append Codewith TOML to a config file (prefer configs for managed configs)", false).option("--codewith-config <path>", "Explicit Codewith config path required with --apply-codewith").option("-j, --json", "Output as JSON", false).description("Install one or more hooks (registry names, local paths, git URLs, manifest URLs, or <name>@<version> pinned installs)").action(async (hooks, options) => {
   const scope = resolveScope(options);
   const target = resolveTarget(options);
   let toInstall = hooks;
@@ -13279,6 +13367,18 @@ program2.command("install").alias("add").argument("[hooks...]", "Hooks to instal
     render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
     return;
   }
+  let mementos;
+  try {
+    mementos = mementosRegistrationFromFlags(toInstall.length === 1 ? toInstall[0] : "", options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid Mementos options";
+    if (options.json)
+      console.log(JSON.stringify({ error: message, applied: false }));
+    else
+      console.error(message);
+    process.exitCode = 1;
+    return;
+  }
   if (options.applyCodewith && (target === "codewith" || target === "all") && !options.codewithConfig) {
     const message = "--apply-codewith requires --codewith-config <path>; refusing to write default ~/.codewith/config.toml.";
     if (options.json) {
@@ -13317,6 +13417,7 @@ program2.command("install").alias("add").argument("[hooks...]", "Hooks to instal
       console.log(JSON.stringify({
         dryRun: true,
         would_install: known,
+        ...mementos ? { mementos } : {},
         custom_sources: customSources,
         pinned: pinnedRequests.map((p) => `${p.pinned.name}@${p.pinned.version}`),
         unknown,
@@ -13421,7 +13522,8 @@ Dry run \u2014 would install (${scope}, ${target}):
       target,
       profile: options.profile,
       codewithMode: options.applyCodewith ? "write" : "fragment",
-      codewithConfigPath: options.codewithConfig
+      codewithConfigPath: options.codewithConfig,
+      mementos
     });
     results.push(result);
   }

package/dist/index.js

@@ -7445,7 +7445,78 @@ function resolveHook(name) {
 // src/lib/installer.ts
 init_manifest();
 
+// src/lib/mementos-options.ts
+function validateMementosRegistration(name, value) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || !Object.hasOwn(value, "enabled") || Object.keys(value).some((key) => key !== "enabled" && key !== "secretRef") || name.replace(/^hook-/, "") !== "mementos-context" || typeof value.enabled !== "boolean") {
+    throw new Error("Mementos options require the mementos-context hook and an explicit enable/disable choice.");
+  }
+  if (value.secretRef !== undefined && (!value.enabled || typeof value.secretRef !== "string" || value.secretRef.length > 256 || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9_.-]*){1,12}$/.test(value.secretRef))) {
+    throw new Error("OpenRouter requires an enabled Mementos hook and a valid Secrets reference, never a key value.");
+  }
+}
+function mementosRegistrationFromFlags(name, flags) {
+  if (!flags.enableMementos && !flags.disableMementos && flags.openrouterSecretRef === undefined)
+    return;
+  if (Boolean(flags.enableMementos) === Boolean(flags.disableMementos)) {
+    throw new Error("Choose exactly one of --enable-mementos or --disable-mementos.");
+  }
+  const value = { enabled: flags.enableMementos === true, ...flags.openrouterSecretRef !== undefined ? { secretRef: flags.openrouterSecretRef } : {} };
+  validateMementosRegistration(name, value);
+  return value;
+}
+function mementosCommandSuffix(value) {
+  validateMementosRegistration("mementos-context", value);
+  if (!value)
+    return "";
+  return value.enabled ? ` --enable-mementos${value.secretRef ? ` --openrouter-secret-ref ${value.secretRef}` : ""}` : " --disable-mementos";
+}
+function retainedMementosRegistration(commands) {
+  const values = commands.filter((command) => /^hooks run mementos-context(?:\s|$)/.test(command)).map((command) => {
+    const args = command.trim().split(/\s+/).slice(3);
+    const flags = {};
+    const seen = new Set;
+    while (args.length) {
+      const key = args.shift();
+      if (seen.has(key))
+        throw new Error("Ambiguous Mementos registration; specify its enablement explicitly.");
+      seen.add(key);
+      if (key === "--profile" && /^[\w-]+$/.test(args[0] ?? ""))
+        args.shift();
+      else if (key === "--enable-mementos")
+        flags.enableMementos = true;
+      else if (key === "--disable-mementos")
+        flags.disableMementos = true;
+      else if (key === "--openrouter-secret-ref" && args.length)
+        flags.openrouterSecretRef = args.shift();
+      else
+        throw new Error("Unrecognized Mementos registration options; specify its enablement explicitly.");
+    }
+    return mementosRegistrationFromFlags("mementos-context", flags);
+  });
+  if (new Set(values.map((value) => JSON.stringify(value))).size > 1) {
+    throw new Error("Conflicting Mementos registrations; specify its enablement explicitly.");
+  }
+  return values[0];
+}
+
 // src/lib/registration.ts
+var REGISTRATION_COMMAND_RE = /^(?:hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?|hook-([\w-]+))$/;
+function registrationName(command) {
+  if (typeof command !== "string")
+    return;
+  if (/^hooks run mementos-context(?:\s|$)/.test(command.trim())) {
+    try {
+      retainedMementosRegistration([command.trim()]);
+      return "mementos-context";
+    } catch {
+      return;
+    }
+  }
+  const match = command.trim().match(REGISTRATION_COMMAND_RE);
+  return match ? match[1] ?? match[2] : undefined;
+}
 function matchersOverlap(a, b) {
   return a === b || a.includes(b) || b.includes(a);
 }
@@ -7711,12 +7782,13 @@ function codewithStatusMessage(name) {
       return `Running ${name}`;
   }
 }
-function buildCodewithTomlFragment(name, profile) {
+function buildCodewithTomlFragment(name, profile, mementos) {
   const shortName = shortHookName(name);
   const meta = resolveHookMeta(shortName);
   if (!meta)
     throw new Error(`Hook '${shortName}' not found`);
-  const command = profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`;
+  validateMementosRegistration(shortName, mementos);
+  const command = (profile ? `hooks run ${shortName} --profile ${profile}` : `hooks run ${shortName}`) + mementosCommandSuffix(mementos);
   const matcher = codewithMatcher(meta.matcher);
   const fragments = [];
   for (const event of getHookEvents(meta)) {
@@ -7798,14 +7870,14 @@ function detectRewriteConflict(name, scope, target, lookup = getHook) {
   }
   return;
 }
-function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath) {
+function installForTarget(name, scope, overwrite, target, profile, codewithMode = "fragment", codewithConfigPath, mementos) {
   const shortName = shortHookName(name);
   if (!hookExists(shortName)) {
     return { hook: shortName, success: false, error: `Hook '${shortName}' not found`, target };
   }
   if (target === "codewith") {
     try {
-      const fragment = buildCodewithTomlFragment(shortName, profile);
+      const fragment = buildCodewithTomlFragment(shortName, profile, mementos);
       if (codewithMode !== "write") {
         return {
           hook: shortName,
@@ -7862,7 +7934,7 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
     if (rewriteConflict) {
       return { hook: shortName, success: false, error: `Refused: ${rewriteConflict}`, scope, target };
     }
-    registerHook(shortName, scope, target, profile);
+    registerHook(shortName, scope, target, profile, mementos);
     return {
       hook: shortName,
       success: true,
@@ -7881,7 +7953,12 @@ function installForTarget(name, scope, overwrite, target, profile, codewithMode
   }
 }
 function installHook(name, options = {}) {
-  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath } = options;
+  const { scope = "global", overwrite = false, target = "claude", profile, codewithMode = "fragment", codewithConfigPath, mementos } = options;
+  try {
+    validateMementosRegistration(name, mementos);
+  } catch (error) {
+    return { hook: name, success: false, target, error: error instanceof Error ? error.message : "Invalid Mementos options" };
+  }
   if (!/^[\w-]+$/.test(name) || profile !== undefined && !/^[\w-]+$/.test(profile)) {
     return { hook: name, success: false, error: "Hook and profile names must contain only letters, digits, underscores or hyphens.", target };
   }
@@ -7899,7 +7976,7 @@ function installHook(name, options = {}) {
         };
       }
     }
-    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile);
+    const claudeResult = installForTarget(name, scope, overwrite, "claude", profile, "fragment", undefined, mementos);
     if (!claudeResult.success) {
       return {
         ...claudeResult,
@@ -7907,7 +7984,7 @@ function installHook(name, options = {}) {
         target: "all"
       };
     }
-    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath);
+    const codewithResult = installForTarget(name, scope, overwrite, "codewith", profile, codewithMode, codewithConfigPath, mementos);
     if (!codewithResult.success) {
       return {
         ...codewithResult,
@@ -7917,9 +7994,9 @@ function installHook(name, options = {}) {
     }
     return { ...claudeResult, target: "all" };
   }
-  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath);
+  return installForTarget(name, scope, overwrite, target, profile, codewithMode, codewithConfigPath, mementos);
 }
-function registerHook(name, scope = "global", target = "claude", profile) {
+function registerHook(name, scope = "global", target = "claude", profile, mementos) {
   const meta = resolveHookMeta(name);
   if (!meta)
     return;
@@ -7937,8 +8014,9 @@ function registerHook(name, scope = "global", target = "claude", profile) {
   const settings = readSettings(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
+  const retained = name === "mementos-context" && mementos === undefined ? retainedMementosRegistration(Object.values(settings.hooks).flatMap((groups) => Array.isArray(groups) ? groups.flatMap((group) => Array.isArray(group.hooks) ? group.hooks.map((hook) => hook.command).filter((command) => typeof command === "string") : []) : [])) : undefined;
   removeHookFromAllEvents(settings, name);
-  const hookCommand = profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`;
+  const hookCommand = (profile ? `hooks run ${name} --profile ${profile}` : `hooks run ${name}`) + mementosCommandSuffix(mementos ?? retained);
   for (const eventKey of uniqueEventKeys) {
     if (!settings.hooks[eventKey])
       settings.hooks[eventKey] = [];
@@ -7983,10 +8061,12 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   if (target === "codewith") {
     const config = readCodewithConfig(scope);
     const registered2 = [];
-    const re = /command\s*=\s*["']hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?["']/g;
+    const re = /^\s*command\s*=\s*["']([^"'\n]+)["']\s*$/gm;
     let match;
     while (match = re.exec(config)) {
-      registered2.push(match[1]);
+      const name = registrationName(match[1]);
+      if (name)
+        registered2.push(name);
     }
     return [...new Set(registered2)];
   }
@@ -7997,12 +8077,9 @@ function getRegisteredHooksForTarget(scope = "global", target = "claude") {
   for (const eventKey of Object.keys(settings.hooks)) {
     for (const entry of settings.hooks[eventKey]) {
       for (const hook of entry.hooks || []) {
-        const newMatch = hook.command?.match(/^hooks run ([\w-]+)(?:\s+--profile\s+[\w-]+)?$/);
-        const oldMatch = hook.command?.match(/^hook-([\w-]+)$/);
-        const match = newMatch || oldMatch;
-        if (match) {
-          registered.push(match[1]);
-        }
+        const name = registrationName(hook.command);
+        if (name)
+          registered.push(name);
       }
     }
   }
@@ -8036,7 +8113,7 @@ function removeHookForTarget(name, scope, target) {
 var JSON_SETTINGS_TARGETS = ["claude", "gemini", "codex"];
 function removeCodewithHookEntry(configText, name) {
   const sections = configText.split(/\n\s*\n/);
-  const nameRe = new RegExp(`^command\\s*=\\s*"hooks run ${escapeRegExp(name)}(?:\\s+--profile\\s+[\\w-]+)?"$`);
+  const commandRe = /^command\s*=\s*"([^"\n]+)"$/;
   const entryHeaderRe = /^\[\[hooks\.([\w]+)\.hooks\]\]$/;
   const eventHeaderRe = /^\[\[hooks\.([\w]+)\]\]$/;
   const eventsWithEntries = new Set;
@@ -8049,7 +8126,7 @@ function removeCodewithHookEntry(configText, name) {
     if (entryMatch) {
       const event = entryMatch[1];
       eventsWithEntries.add(event);
-      if (lines.some((line) => nameRe.test(line.trim()))) {
+      if (lines.some((line) => registrationName(commandRe.exec(line.trim())?.[1]) === name)) {
         removed = true;
         continue;
       }

package/dist/lib/installer.d.ts

@@ -11,6 +11,7 @@
  */
 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" | "codex" | "all";
 type SingleTarget = Exclude<Target, "all">;
@@ -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

@@ -22,8 +22,22 @@ 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:
+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
@@ -45,6 +59,18 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.2",
+  "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": {