clay-server 5.2.0-beta.5 → 5.2.0-beta.7

package/lib/yoke/acp-agent-profiles.js

@@ -9,8 +9,9 @@ var execFile = require("child_process").execFile;
 var execFileSync = require("child_process").execFileSync;
 
 function findOnPath(binaryName, overrideName) {
-  var overridePath = overrideName && process.env[overrideName];
-  if (overridePath && fs.existsSync(overridePath)) return overridePath;
+  var discovery = require("./discovery");
+  var overridePath = overrideName && discovery.explicitEntry(process.env, overrideName, false);
+  if (overridePath !== undefined && overrideName) return overridePath;
   try {
     var command = process.platform === "win32" ? "where" : "which";
     var out = execFileSync(command, [binaryName], {
@@ -18,7 +19,8 @@ function findOnPath(binaryName, overrideName) {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],
     });
-    return out.trim().split(/\r?\n/)[0] || null;
+    var resolved = out.trim().split(/\r?\n/)[0] || null;
+    return discovery.validEntry(resolved, false) ? resolved : null;
   } catch (e) {
     return null;
   }

package/lib/yoke/adapters/antigravity.js

@@ -3,19 +3,7 @@ var childProcess = require("child_process");
 var readline = require("readline");
 var skillDiscovery = require("../skill-discovery");
 
-function findBinary() {
-  if (process.env.ANTIGRAVITY_CLI_PATH) return process.env.ANTIGRAVITY_CLI_PATH;
-  try {
-    var command = process.platform === "win32" ? "where" : "which";
-    return childProcess.execFileSync(command, ["agy"], {
-      encoding: "utf8",
-      timeout: 3000,
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim().split(/\r?\n/)[0] || null;
-  } catch (e) {
-    return null;
-  }
-}
+var findBinary = require("../providers/antigravity-executable").resolve;
 
 function modelValue(model) {
   if (typeof model === "string") return model;
@@ -427,7 +415,8 @@ function createAntigravityAdapter(opts) {
   var adapter = {
     vendor: "antigravity",
     init: async function(initOpts) {
-      if (!binaryPath) binaryPath = findBinary();
+      if (opts.linuxUser || initOpts && initOpts.linuxUser) throw new Error("Antigravity does not support mapped OS-user execution.");
+      if (!binaryPath) binaryPath = findBinary({ env: initOpts && initOpts.env || opts.env || process.env });
       if (!binaryPath) throw new Error("Antigravity CLI binary not found: agy");
       var fetched = opts._fetchModels ? await opts._fetchModels(binaryPath, cwd) : await fetchModels(binaryPath, cwd);
       if (fetched && fetched.length) cachedModels = fetched;

package/lib/yoke/adapters/claude-query-contract.js

@@ -0,0 +1,9 @@
+// Init-free provider transport obligations, shared by the registry and adapter.
+module.exports = {
+  questionInput: function(name, input) { return name === "AskUserQuestion" ? input : null; },
+  toolTransport: "sdk-mcp",
+  catalogLifetime: "query",
+  permissionModes: ["auto"],
+  mcpPermissionOverrides: true,
+  interruptionMessage: "Interrupted · What should Claude do instead?",
+};

package/lib/yoke/adapters/claude.js

@@ -528,7 +528,7 @@ function flattenEvent(raw) {
   // --- rate_limit_event ---
   if (raw.type === "rate_limit_event" && raw.rate_limit_info) {
     base.yokeType = "rate_limit";
-    base.rateLimitInfo = raw.rate_limit_info;
+    base.rateLimitInfo = Object.assign({}, raw.rate_limit_info, { isUsingOverage: raw.rate_limit_info.isUsingOverage === true || raw.rate_limit_info.overageInUse === true });
     return base;
   }
 
@@ -1543,43 +1543,7 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
 
 // --- Adapter factory ---
 
-function resolveClaudeBinaryPath() {
-  // 1. Explicit env var override
-  if (process.env.CLAUDE_CODE_PATH && fs.existsSync(process.env.CLAUDE_CODE_PATH)) {
-    return process.env.CLAUDE_CODE_PATH;
-  }
-
-  // 2. `which claude` in the daemon's PATH
-  try {
-    var result = require("child_process").execSync("which claude", { encoding: "utf8", timeout: 5000 }).trim();
-    if (result && fs.existsSync(result)) return result;
-  } catch (e) {}
-
-  // 3. Common per-user and system locations (best-effort fallback for the daemon user)
-  var home = process.env.HOME || "";
-  var candidates = [];
-  if (home) {
-    candidates.push(home + "/.npm-global/bin/claude");
-    candidates.push(home + "/.local/bin/claude");
-    candidates.push(home + "/.volta/bin/claude");
-    candidates.push(home + "/.bun/bin/claude");
-    candidates.push(home + "/bin/claude");
-  }
-  candidates.push("/usr/local/bin/claude");
-  candidates.push("/usr/bin/claude");
-  candidates.push("/opt/homebrew/bin/claude");
-  for (var i = 0; i < candidates.length; i++) {
-    try { if (fs.existsSync(candidates[i])) return candidates[i]; } catch (e) {}
-  }
-
-  // 4. Bundled CLI entry from the SDK's peer
-  try {
-    var resolved = require.resolve("@anthropic-ai/claude-code/cli.js");
-    if (resolved && fs.existsSync(resolved)) return resolved;
-  } catch (e) {}
-
-  return null;
-}
+var resolveClaudeBinaryPath = require("../providers/claude-executable").resolve;
 
 function createClaudeAdapter(opts) {
   var _cwd = (opts && opts.cwd) || process.cwd();
@@ -1592,6 +1556,7 @@ function createClaudeAdapter(opts) {
 
   var adapter = {
     vendor: "claude",
+    queryContract: require("./claude-query-contract"),
     userInputCapability: { mode: "native", native: true, transport: "AskUserQuestion/onElicitation" },
 
     // Path to worker script (sdk-bridge uses this to spawn worker processes)
@@ -1678,7 +1643,7 @@ function createClaudeAdapter(opts) {
 
             try {
               var models = await stream.supportedModels();
-              result.models = models || [];
+              result.models = require("../providers/claude-model-descriptions").list(models);
               _cachedModels = result.models;
             } catch (e) {
               // supportedModels may fail, models list will be empty
@@ -1993,7 +1958,7 @@ function createClaudeAdapter(opts) {
           warmupDone = true;
           var r = msg.result || {};
           resolve({
-            models: r.models || [],
+            models: require("../providers/claude-model-descriptions").list(r.models),
             defaultModel: r.model || "",
             skills: r.skills || [],
             slashCommands: r.slashCommands || [],
@@ -2110,7 +2075,7 @@ function createClaudeAdapter(opts) {
 
             try {
               var models = await stream.supportedModels();
-              result.models = models || [];
+              result.models = require("../providers/claude-model-descriptions").list(models);
               _cachedModels = result.models;
             } catch (e) {
               // supportedModels may fail, models list will be empty
@@ -2161,7 +2126,7 @@ function createClaudeAdapter(opts) {
           warmupDone = true;
           var r = msg.result || {};
           resolve({
-            models: r.models || [],
+            models: require("../providers/claude-model-descriptions").list(r.models),
             defaultModel: r.model || "",
             skills: r.skills || [],
             slashCommands: r.slashCommands || [],

package/lib/yoke/adapters/codex-query-contract.js

@@ -0,0 +1,24 @@
+// Codex restores dynamic definitions from the original thread catalog.
+// Keep persisted legacy field names here so old conversations remain readable.
+var fields = {
+  schedules: "codexDynamicToolCatalogVersion",
+  questions: "codexUserInputToolCatalogVersion",
+  browser: "codexSharedBrowserToolCatalogVersion",
+  issues: "codexIssuesToolCatalogVersion",
+  knowledge: "codexYouToolCatalogVersion",
+  linear: "codexLinearToolCatalogVersion",
+};
+module.exports = {
+  toolTransport: "dynamic",
+  catalogLifetime: "conversation",
+  externalToolTransport: "dynamic",
+  defaultUserInputMode: "fallback",
+  questionGuidance: require("../user-input-guidance").codexQuestionGuidance,
+  catalogVersion: function (session, family) { return Number(session[fields[family]] || 0); },
+  recordCatalog: function (session, versions) {
+    Object.keys(versions).forEach(function (family) {
+      if (fields[family]) session[fields[family]] = versions[family];
+    });
+  },
+  staleCatalogReason: "This Codex conversation predates Clay's scheduled-task tool catalog. Start a new conversation to use the assisted interview; manual task creation remains available here.",
+};

package/lib/yoke/adapters/codex.js

@@ -1682,6 +1682,7 @@ function createCodexAdapter(opts) {
   var adapter = {
     vendor: "codex",
     queryBoundToolCapability: CODEX_QUERY_BOUND_TOOL_CAPABILITY,
+    queryContract: require("./codex-query-contract"),
     userInputCapability: { mode: "native", native: true, transport: "item/tool/requestUserInput" },
 
     init: function(initOpts) {

package/lib/yoke/adapters/kiro.js

@@ -279,7 +279,7 @@ function flattenUpdate(update, state) {
 
   // Token usage
   if (type === "usage_update") {
-    if (typeof update.used === "number") state.lastInputTokens = update.used;
+    if (typeof update.used === "number") { state.lastInputTokens = update.used; state.contextMeasurement = "observed"; }
     if (typeof update.size === "number") state.contextWindow = update.size;
     return events;
   }
@@ -294,6 +294,7 @@ function flattenUpdate(update, state) {
       if (typeof percentage !== "number") percentage = kiroMeta.usagePercentage;
       if (typeof percentage === "number" && state.contextWindow) {
         state.lastInputTokens = Math.round(state.contextWindow * percentage / 100);
+        state.contextMeasurement = "estimated";
       }
     }
     return events;
@@ -782,6 +783,7 @@ function createKiroQueryHandle(acp, queryOpts) {
     getContextUsage: function() {
       return Promise.resolve(state.lastInputTokens != null ? {
         input_tokens: state.lastInputTokens,
+        measurement: state.contextMeasurement || "observed",
         contextWindow: state.contextWindow || null,
       } : null);
     },

package/lib/yoke/adapters/muse-query-contract.js

@@ -0,0 +1,7 @@
+// Muse's sessionMcp configuration is supplied on both start and resume.
+module.exports = {
+  toolTransport: "stdio-mcp",
+  catalogLifetime: "query",
+  permissionModes: ["auto"],
+  interruptionMessage: "Interrupted · What should Muse do instead?",
+};

package/lib/yoke/adapters/muse.js

@@ -0,0 +1,122 @@
+var museQuery = require("../muse-query");
+var runtimeTools = require("../muse-runtime");
+var findMusePath = require("../providers/muse-executable").resolve;
+
+function createMuseAdapter(opts) {
+  opts = opts || {};
+  var adapter = {
+    vendor: "muse",
+    userInputCapability: { mode: "native", native: true },
+    providerContract: require("../vendor-registry").getVendorInfo("muse"),
+    queryContract: require("./muse-query-contract"),
+    cwd: opts.cwd || process.cwd(),
+    binaryPath: opts._binaryPath || null,
+    sdkPromise: null,
+    catalog: [],
+    clients: new Set(),
+    handles: new Set(),
+    shuttingDown: false,
+    requestTimeoutMs: opts._requestTimeoutMs || 9e4,
+    titleTimeoutMs: opts._titleTimeoutMs || 15e3,
+    shutdownTimeoutMs: opts._shutdownTimeoutMs == null ? 1e3 : opts._shutdownTimeoutMs
+  };
+  adapter.loadSdk = function() {
+    if (opts._sdk) return Promise.resolve(opts._sdk);
+    if (!adapter.sdkPromise) adapter.sdkPromise = import("@muse-code/sdk");
+    return adapter.sdkPromise;
+  };
+  adapter.init = async function(initOpts) {
+    if (opts.osUsers || opts.linuxUser || initOpts && (initOpts.linuxUser || initOpts.osUsers)) throw new Error("Muse Code does not support OS-owner isolation");
+    if (!adapter.binaryPath) adapter.binaryPath = findMusePath();
+    if (!adapter.binaryPath) throw new Error("Muse Code binary not found: muse. Install Muse Code or set MUSE_CODE_PATH.");
+    await adapter.loadSdk();
+    return {
+      models: [],
+      defaultModel: null,
+      skills: [],
+      slashCommands: [],
+      fastModeState: null,
+      capabilities: {
+        effort: true,
+        midSessionModelSwitch: true,
+        fork: true,
+        rollback: false,
+        sessionListing: true,
+        sessionRename: true,
+        thinking: true,
+        betas: false,
+        rewind: false,
+        sessionResume: true,
+        promptSuggestions: false,
+        elicitation: false,
+        fileCheckpointing: false,
+        contextCompacting: true,
+        queryBoundTools: {
+          mode: "stdio-mcp",
+          source: "@muse-code/sdk SessionConfig.mcpServers"
+        },
+        skillSharing: true,
+        toolPolicy: [ "ask", "allow-all" ]
+      }
+    };
+  };
+  adapter.supportedModels = async function() {
+    if (adapter.shuttingDown) throw new Error("Muse Code adapter is shutting down");
+    if (!adapter.binaryPath) await adapter.init();
+    var sdk = await adapter.loadSdk();
+    if (adapter.shuttingDown) throw new Error("Muse Code adapter is shutting down");
+    var runtime = runtimeTools.createRuntime(adapter, sdk, {
+      command: adapter.binaryPath,
+      args: [ "serve" ],
+      cwd: adapter.cwd,
+      env: Object.assign({}, process.env)
+    });
+    runtime.fail = function(error) {
+      runtime.close().catch(function(closeError) {
+        adapter.lastCloseError = closeError;
+      });
+    };
+    try {
+      var spawned = await runtime.initialize();
+      adapter.catalog = runtimeTools.normalizeCatalog(await runtime.waitRequest(spawned.connection.request("model/list", {})));
+      return adapter.catalog.slice();
+    } finally {
+      await runtime.close();
+    }
+  };
+  adapter.createToolServer = function() {
+    return null;
+  };
+  adapter.createQuery = async function(queryOpts) {
+    if (opts.osUsers || opts.linuxUser || queryOpts && queryOpts.linuxUser) throw new Error("Muse Code does not support OS-owner isolation");
+    if (!adapter.binaryPath) await adapter.init(queryOpts || {});
+    if (adapter.shuttingDown) throw new Error("Muse Code adapter is shutting down");
+    return museQuery.createMuseQueryHandle(adapter, queryOpts || {});
+  };
+  adapter.generateTitle = function(messages, titleOpts) {
+    return require("../title-query").generateTitle(adapter, messages, Object.assign({}, titleOpts, { timeoutMs: adapter.titleTimeoutMs }),
+      { skipProjectInstructions: true, skipSkills: true, adapterOptions: { MUSE: { readOnly: true, mcpServers: [] } } });
+  };
+  adapter.shutdown = async function() {
+    adapter.shuttingDown = true;
+    var results = await Promise.allSettled(Array.from(adapter.handles).map(function(handle) {
+      return handle.close();
+    }).concat(Array.from(adapter.clients).map(function(runtime) {
+      return runtime.close();
+    })));
+    var failed = results.find(function(result) {
+      return result.status === "rejected";
+    });
+    if (failed) throw failed.reason;
+    return true;
+  };
+  require("../muse-services").attach(adapter);
+  return adapter;
+}
+
+module.exports = {
+  createMuseAdapter: createMuseAdapter,
+  findMusePath: findMusePath,
+  isAuthError: runtimeTools.isAuthError,
+  chooseApprovalDecision: require("../muse-policy").chooseApprovalDecision
+};

package/lib/yoke/auth-events.js

@@ -0,0 +1,17 @@
+function loginPrompt(event, preview, provider) {
+  if (event.cost && event.cost !== 0 || String(preview || '').length >= 100) return false;
+  var text = String(preview || '').trim();
+  if (/not logged in/i.test(text) && /\/login/i.test(text)) return true;
+  var policy = require('./provider-contract').resolve(provider);
+  return typeof policy.authenticationReply === 'function' && policy.authenticationReply(text);
+}
+function authenticationReply(text) { return /^Failed to authenticate: OAuth session expired and could not be refreshed\.?$/i.test(text); }
+function isAuthenticationError(detail) {
+  var text = String(detail || '').toLowerCase();
+  return /not logged in|unauthenticated|authentication|sign in|log in|please login/.test(text);
+}
+function normalize(event, preview, provider) {
+  if (!event || event.yokeType !== "result") return event;
+  return Object.assign({}, event, { authenticationRequired: event.authenticationRequired === true || loginPrompt(event, preview, provider) });
+}
+module.exports = { normalize: normalize, loginPrompt: loginPrompt, authenticationReply: authenticationReply, isAuthenticationError: isAuthenticationError };

package/lib/yoke/claude-hook-installer.js

@@ -0,0 +1,271 @@
+// claude-hook-installer.js
+//
+// Registers Clay's notification webhook in `~/.claude/settings.json` so the
+// `claude` CLI fires a request to the Clay daemon whenever it surfaces a
+// Notification (permission requests, idle prompts, etc.). This is what makes
+// TUI sessions feel like first-class Clay sessions: the user gets the same
+// toasts and push notifications they would in GUI mode.
+//
+// Design notes:
+//   - Settings merge is idempotent: existing hooks are preserved, ours are
+//     identified by a marker substring so re-runs don't duplicate them.
+//   - The hook command uses curl with --max-time / --connect-timeout so that
+//     a downed daemon can't stall claude's UI for more than ~1s.
+//   - Multi-user mode: caller passes one home directory per OS user; we
+//     write each user's own settings.json so per-user filtering works.
+
+var fs = require("fs");
+var path = require("path");
+var { buildClayBashAllowPatterns, isClayManagedBashPattern } = require("../safe-bash-commands");
+
+// Substring that uniquely identifies a Clay-installed hook entry so we can
+// safely remove/replace it without touching user-authored hooks.
+var CLAY_HOOK_MARKER = "clay:tui-notify";
+
+// Allow-patterns Clay manages in ~/.claude/settings.json `permissions.allow`.
+// The Bash(...) patterns are GENERATED from safe-bash-commands.js so this
+// list and sdk-bridge.js `checkToolWhitelist` can never drift - there is one
+// source of truth for which bash commands Clay auto-approves.
+//
+// Pattern syntax note: claude 2.x uses the space-wildcard form `Bash(cmd *)`
+// for prefix matching. The older colon form `Bash(cmd:*)` is flagged as
+// legacy in the CLI and no longer reliably matches argument-bearing commands
+// (the TUI kept prompting for read-only invocations like `ls -la`). The
+// generator emits the modern form plus a bare `Bash(cmd)` for zero-arg use.
+//
+// User-authored entries are preserved -- on re-install we only strip patterns
+// that are Clay-managed (current generated list or the legacy colon shape).
+var CLAY_MANAGED_ALLOW = [
+  // Read-only built-in tools (no side effects).
+  "Read", "Glob", "Grep", "WebFetch", "WebSearch",
+
+  // Clay's own MCP servers. Strictly read/safe by design.
+  "mcp__clay-browser__browser_watch_tab",
+  "mcp__clay-browser__browser_unwatch_tab",
+  "mcp__clay-debate__propose_debate",
+  "mcp__clay-mate-creation__propose_mate",
+  "mcp__clay-history__*",
+  "mcp__clay-workspace__read_current_context",
+  "mcp__clay-workspace__read_selected_context",
+  "mcp__clay-workspace__open_context_conversation",
+  "mcp__clay-workspace__read_context_navigation_receipt",
+  "mcp__clay-workspace__read_owner_screen",
+  "mcp__clay-workspace__inspect_owner_screen_change",
+  "mcp__clay-workspace__control_owner_screen",
+  "mcp__clay-workspace__inspect_project_control",
+  "mcp__clay-workspace__control_project_lifecycle",
+  "mcp__clay-workspace__discover_product_controls",
+  "mcp__clay-workspace__list_owned_mates",
+  "mcp__clay-workspace__begin_schedule_control_interview",
+  "mcp__clay-workspace__read_schedule_controls",
+  "mcp__clay-workspace__inspect_schedule_change",
+  "mcp__clay-workspace__control_schedules",
+  "mcp__clay-workspace__read_mate_chat_control",
+  "mcp__clay-workspace__inspect_mate_chat_change",
+  "mcp__clay-workspace__control_mate_chat",
+  "mcp__clay-workspace__read_project_workspace",
+  "mcp__clay-workspace__read_workspace_receipt",
+  "mcp__clay-workspace__inspect_workspace_change",
+  "mcp__clay-workspace__control_project_workspace",
+  "mcp__clay-workspace__read_project_records",
+  "mcp__clay-workspace__inspect_project_record_change",
+  "mcp__clay-workspace__control_project_records",
+  "mcp__clay-workspace__read_mate_knowledge_control",
+  "mcp__clay-workspace__inspect_mate_knowledge_change",
+  "mcp__clay-workspace__control_mate_knowledge",
+  "mcp__clay-workspace__inspect_mate_control",
+  "mcp__clay-workspace__control_mate_lifecycle",
+  "mcp__clay-workspace__inspect_session_control",
+  "mcp__clay-workspace__control_project_session",
+  "mcp__clay-workspace__list_projects",
+  "mcp__clay-workspace__list_project_sessions",
+  "mcp__clay-workspace__search_project_history",
+  "mcp__clay-workspace__read_project_session",
+  "mcp__clay-workspace__search_workspace_history",
+  "mcp__clay-workspace__list_workspace_activity",
+  "mcp__clay-workspace__propose_project_assignment",
+  "mcp__clay-workspace__propose_project_follow_up",
+  "mcp__clay-workspace__get_assignment_status",
+  "mcp__clay-tools__clay_tool_list",
+  "mcp__clay-tools__clay_tool_snapshot",
+  "mcp__clay-tools__clay_tool_act",
+  "mcp__clay-tools__clay_tool_set",
+  "mcp__clay-tools__clay_tool_source",
+  // Email: read-side only. Send / reply / mark_read still prompt.
+  "mcp__clay-email__clay_read_email",
+  "mcp__clay-email__clay_read_email_body",
+  "mcp__clay-email__clay_search_email",
+  "mcp__clay-email__clay_list_labels",
+].concat(buildClayBashAllowPatterns());
+
+function buildHookCommand(notifyUrl) {
+  // Read stdin once (the JSON Claude Code pipes in), then post it. --max-time
+  // and --connect-timeout cap total hook latency around ~1s even if the
+  // daemon is down. --insecure (-k) is needed because Clay's optional TLS
+  // mode uses a locally generated CA that curl won't trust by default;
+  // safe to skip verification since we're going to 127.0.0.1. Output is
+  // silenced so it doesn't leak into the TUI. The marker comment keeps the
+  // entry recognizable when we re-merge.
+  var insecure = notifyUrl.indexOf("https://") === 0 ? " --insecure" : "";
+  return "curl --silent --show-error --max-time 1 --connect-timeout 1" + insecure +
+    " -X POST -H 'Content-Type: application/json' --data-binary @- " +
+    JSON.stringify(notifyUrl) + " > /dev/null 2>&1 # " + CLAY_HOOK_MARKER;
+}
+
+function readSettings(settingsPath) {
+  try {
+    var raw = fs.readFileSync(settingsPath, "utf8");
+    return JSON.parse(raw);
+  } catch (e) {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath, data) {
+  var dir = path.dirname(settingsPath);
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + "\n");
+}
+
+// Merge our Notification hook into the user's settings.json without
+// clobbering anything else. Returns true if the file changed.
+function mergeHook(settingsPath, command) {
+  var data = readSettings(settingsPath);
+  if (!data.hooks || typeof data.hooks !== "object") data.hooks = {};
+  if (!Array.isArray(data.hooks.Notification)) data.hooks.Notification = [];
+
+  // Strip any prior Clay entries before inserting the fresh one so port /
+  // URL changes propagate cleanly.
+  var before = JSON.stringify(data.hooks.Notification);
+  var cleaned = [];
+  for (var i = 0; i < data.hooks.Notification.length; i++) {
+    var group = data.hooks.Notification[i];
+    if (!group || !Array.isArray(group.hooks)) { cleaned.push(group); continue; }
+    var filtered = group.hooks.filter(function (h) {
+      return !(h && typeof h.command === "string" && h.command.indexOf(CLAY_HOOK_MARKER) !== -1);
+    });
+    if (filtered.length > 0) cleaned.push({ matcher: group.matcher || "", hooks: filtered });
+    else if (group.matcher) cleaned.push(group);
+  }
+  data.hooks.Notification = cleaned;
+
+  data.hooks.Notification.push({
+    matcher: "",
+    hooks: [{ type: "command", command: command }],
+  });
+
+  var after = JSON.stringify(data.hooks.Notification);
+  if (before === after) return false;
+  writeSettings(settingsPath, data);
+  return true;
+}
+
+/**
+ * Install (or refresh) the Notification hook in one or more user home dirs.
+ *
+ * opts:
+ *   notifyUrl  -- full URL Clay listens on, e.g. "http://127.0.0.1:2633/api/tui-notify".
+ *   homeDirs   -- array of absolute paths to user home directories. Each one
+ *                 gets its own settings.json updated. Defaults to [os.homedir()].
+ *
+ * Returns { installed: [paths], errors: [{path, error}] } so the caller can log.
+ */
+function installNotificationHook(opts) {
+  opts = opts || {};
+  var os = require("os");
+  var homes = opts.homeDirs && opts.homeDirs.length ? opts.homeDirs : [os.homedir()];
+  var notifyUrl = opts.notifyUrl;
+  if (!notifyUrl) throw new Error("installNotificationHook: notifyUrl is required");
+
+  var command = buildHookCommand(notifyUrl);
+  var installed = [];
+  var errors = [];
+  for (var i = 0; i < homes.length; i++) {
+    var home = homes[i];
+    if (!home) continue;
+    var settingsPath = path.join(home, ".claude", "settings.json");
+    try {
+      var changed = mergeHook(settingsPath, command);
+      if (changed) installed.push(settingsPath);
+    } catch (e) {
+      errors.push({ path: settingsPath, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { installed: installed, errors: errors };
+}
+
+// Old colon-prefix Bash patterns Clay wrote before claude 2.x: Bash(ls:*),
+// Bash(git status:*), etc. Stripped on upgrade so they don't linger next to
+// the modern space-wildcard form. Modern Clay patterns never contain ":)" so
+// this only catches the deprecated shape; it can't tell a user-authored colon
+// pattern apart, but claude is phasing the colon form out anyway.
+function isLegacyClayPattern(p) {
+  if (typeof p !== "string") return false;
+  if (p.indexOf("Bash(") === 0 && p.indexOf(":*)") !== -1) return true;
+  return false;
+}
+
+// Merge Clay's managed allow-list into permissions.allow without disturbing
+// the user's own entries. "Ours" = exact membership in CLAY_MANAGED_ALLOW
+// (the non-Bash built-in / MCP entries) OR isClayManagedBashPattern (any
+// shape of a bash command we own, so stale variants from older versions get
+// swept) OR the legacy colon shape. Everything else is preserved, then the
+// fresh list is appended. Because the Bash patterns are generated from
+// safe-bash-commands.js, a re-install always writes the current set and can
+// never leave a stale Clay block behind.
+function mergeAllowList(settingsPath, patterns) {
+  var data = readSettings(settingsPath);
+  if (!data.permissions || typeof data.permissions !== "object") data.permissions = {};
+  var allow = Array.isArray(data.permissions.allow) ? data.permissions.allow : [];
+
+  var managedSet = {};
+  for (var i = 0; i < CLAY_MANAGED_ALLOW.length; i++) managedSet[CLAY_MANAGED_ALLOW[i]] = true;
+
+  var preserved = allow.filter(function (p) {
+    if (managedSet[p]) return false;
+    if (isClayManagedBashPattern(p)) return false;
+    if (isLegacyClayPattern(p)) return false;
+    return true;
+  });
+  var next = preserved.concat(patterns);
+
+  var before = JSON.stringify(allow);
+  var after = JSON.stringify(next);
+  if (before === after) return false;
+
+  data.permissions.allow = next;
+  writeSettings(settingsPath, data);
+  return true;
+}
+
+/**
+ * Install (or refresh) Clay's auto-approve patterns into permissions.allow
+ * for one or more user home dirs. Mirrors installNotificationHook's API.
+ */
+function installAllowList(opts) {
+  opts = opts || {};
+  var os = require("os");
+  var homes = opts.homeDirs && opts.homeDirs.length ? opts.homeDirs : [os.homedir()];
+  var patterns = (opts.patterns && opts.patterns.length) ? opts.patterns : CLAY_MANAGED_ALLOW;
+  var installed = [];
+  var errors = [];
+  for (var i = 0; i < homes.length; i++) {
+    var home = homes[i];
+    if (!home) continue;
+    var settingsPath = path.join(home, ".claude", "settings.json");
+    try {
+      var changed = mergeAllowList(settingsPath, patterns);
+      if (changed) installed.push(settingsPath);
+    } catch (e) {
+      errors.push({ path: settingsPath, error: e && e.message ? e.message : String(e) });
+    }
+  }
+  return { installed: installed, errors: errors };
+}
+
+module.exports = {
+  installNotificationHook: installNotificationHook,
+  installAllowList: installAllowList,
+  CLAY_HOOK_MARKER: CLAY_HOOK_MARKER,
+  CLAY_MANAGED_ALLOW: CLAY_MANAGED_ALLOW,
+};