@synqa/cli 1.1.0 → 1.2.0

package/dist/commands.js

@@ -13,8 +13,19 @@ import { sanitize } from "./sanitize.js";
 import { groupDigits } from "./statusbar.js";
                                                   
 import { CONTEXT_TOKENS, EFFORTS, findEffort, findTier, TIERS } from "./tiers.js";
+import { MODE_LABEL } from "./modes.js";
+                                                 
+import { describeHook } from "./hooks.js";
+                                       
+import { fetchModelIds, logout, modelItems, providerDef, providerMenu } from "./providers.js";
+                                                                              
+import { API_BASE, saveProvider } from "./config.js";
+import { sanitizeModelId } from "./sanitize.js";
+                                            
                                                       
                                         
+import { renderHelp, SLASH_HELP, unknownCommandHint } from "./prompt.js";
+                                  
 
                             
                  
@@ -30,29 +41,35 @@ import { CONTEXT_TOKENS, EFFORTS, findEffort, findTier, TIERS } from "./tiers.js
                      
                                                                               
                                                             
+                                                                         
+                                   
+                                                                                          
+                                                                       
   
 
                          
                              
                                                   
                
+                                                                        
                       
                      
+                                                                                                  
+                                                                                      
+                                                                           
+                                                                        
+                                                                                                 
+                                
+                                                                      
+                                                                        
   
 
-                                                                 
+// relogin: a full logout locked the session; the caller shows the sign-in prompt again.
+                                                                                    
+
+export { SLASH_HELP };
 
-export const SLASH_HELP = [
-  "/model blink|sonata|aeon       switch tier",
-  "/effort default|low|medium     set reasoning effort",
-  "/status                        tier, routing, session tokens, credit and weekly pool",
-  "/init                          write a starter AGENTS.md for this project",
-  "/compact                       summarize the conversation to save context",
-  "/undo                          revert the last file the agent wrote (not shell commands)",
-  "/clear                         start a fresh conversation",
-  "/help                          this text",
-  "/exit                          leave",
-].join("\n");
+export const isExternal = (st              )          => (st.providerId ?? "synqa") !== "synqa";
 
 export function statusParts(st              )              {
   return {
@@ -69,7 +86,7 @@ export function statusParts(st              )              {
 export function systemMessage(st              , tier       = st.tier)          {
   const notes = loadNotes(st.cwd);
   st.notesChars = notes.length;
-  return { role: "system", content: systemPrompt(tier, st.cwd, notes) };
+  return { role: "system", content: systemPrompt(tier, st.cwd, notes, isExternal(st)) };
 }
 
 export function freshHistory(st              )            {
@@ -88,12 +105,15 @@ const errText = (err         ) => sanitize(err instanceof Error ? err.message :
 async function cmdStatus(st              , io           )                {
   const u = st.total;
   io.print([
-    `Tier      ${st.tier.display} (${st.tier.id})`,
+    isExternal(st) ? `Provider  ${providerDef(st.providerId          )?.name ?? "custom"}, model ${sanitize(st.modelId ?? "?")}` : `Tier      ${st.tier.display} (${st.tier.id})`,
+    `Mode      ${MODE_LABEL[st.mode ?? "ask"]}`,
     `Routing   ${st.routing}`,
     `Effort    ${st.effort}`,
     `Session   ${groupDigits(u.prompt + u.completion)} tokens (${groupDigits(u.prompt)} in, ${groupDigits(u.completion)} out)`,
     st.last.prompt > 0 ? `Context   ${groupDigits(st.last.prompt)} of ${groupDigits(CONTEXT_TOKENS)} used by the last request` : "Context   no request yet",
   ].join("\n"));
+  // The balance belongs to Synqa Cloud: a secondary provider's key is never sent there.
+  if (isExternal(st)) return;
   const r = await fetchAccount(st.apiKey, io.fetchFn);
   io.print(r.ok ? formatAccount(r.account).join("\n") : `Balance   unavailable: ${sanitize(r.message)}`);
 }
@@ -120,7 +140,7 @@ async function cmdCompact(st              , io           )                {
   if (st.history.length <= 1) { io.print("Nothing to compact yet."); return; }
   io.print("Compacting the conversation...");
   try {
-    const r = await compactHistory({ apiKey: st.apiKey, tier: st.tier, history: st.history, effort: st.effort, fetchFn: io.fetchFn, now: io.now });
+    const r = await compactHistory({ apiKey: st.apiKey, tier: st.tier, baseUrl: st.baseUrl, modelId: st.modelId, history: st.history, effort: st.effort, fetchFn: io.fetchFn, now: io.now });
     st.history = r.history;
     if (r.usage) {
       st.total = { prompt: st.total.prompt + r.usage.prompt, completion: st.total.completion + r.usage.completion };
@@ -131,6 +151,93 @@ async function cmdCompact(st              , io           )                {
   }
 }
 
+// The provider helpers need the arrow-key controls; without a terminal they are unavailable.
+function providerIO(st              , io           )                         {
+  const { pick, secret, ask } = io;
+  if (!pick || !secret || !ask) return undefined;
+  return { print: io.print, pick, secret, ask, fetchFn: io.fetchFn, env: io.env, envKey: io.envKey };
+}
+
+const session = (st              )                  => {
+  st.providerId ??= "synqa";
+  st.baseUrl ??= API_BASE;
+  return st                                  ;
+};
+
+async function cmdModel(st              , io           , arg        )                {
+  if (!isExternal(st)) {
+    const t = arg ? findTier(arg) : undefined;
+    if (arg && !t) { io.print(`Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); return; }
+    let chosen = t;
+    if (!arg) {
+      if (!io.pick) { io.print(`Tier is ${st.tier.display}. Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); return; }
+      const key = await io.pick(modelItems("synqa"), "Choose a model");
+      if (key === undefined) { io.print("Cancelled."); return; }
+      chosen = findTier(key);
+    }
+    if (!chosen) return;
+    st.tier = chosen;
+    st.history[0] = systemMessage(st, chosen);
+    io.print(`Switched to ${chosen.display}.`);
+    return;
+  }
+  const id = st.providerId              ;
+  let model = arg ? sanitizeModelId(arg) : undefined;
+  if (!arg) {
+    if (!io.pick) { io.print(`Model is ${sanitize(st.modelId ?? "?")}. Pass a model id: /model <id>`); return; }
+    let fetched                      ;
+    try {
+      fetched = await fetchModelIds(st.baseUrl          , st.apiKey, io.fetchFn);
+    } catch {
+      fetched = undefined; // the curated defaults are offered instead
+    }
+    const items = modelItems(id, fetched);
+    if (items.length === 0) { io.print("No models to choose from. Pass a model id: /model <id>"); return; }
+    const initial = Math.max(0, items.findIndex((i) => i.value === st.modelId));
+    model = await io.pick(items.map((i, n) => ({ ...i, hint: n === initial ? "(current)" : undefined })), "Choose a model");
+    if (model === undefined) { io.print("Cancelled."); return; }
+  }
+  if (!model) { io.print("That is not a usable model id."); return; }
+  st.modelId = model;
+  try { saveProvider(id, { model }, io.env); } catch { /* the choice still applies to this session */ }
+  io.print(`Model set to ${model}.`);
+}
+
+async function cmdEffort(st              , io           , arg        )                {
+  if (!arg) {
+    if (!io.pick) { io.print(`Effort is ${st.effort}. Choose one of: ${EFFORTS.join(", ")}`); return; }
+    const e = await io.pick(EFFORTS.map((x) => ({ label: x, value: x, hint: x === st.effort ? "(current)" : undefined })), "Reasoning effort");
+    if (e === undefined) { io.print("Cancelled."); return; }
+    st.effort = e;
+    io.print(`Reasoning effort set to ${e}.`);
+    return;
+  }
+  const e = findEffort(arg);
+  if (!e) { io.print(`Choose one of: ${EFFORTS.join(", ")}`); return; }
+  st.effort = e;
+  io.print(`Reasoning effort set to ${e}.`);
+}
+
+async function cmdHooks(io           )                {
+  const hooks = io.hooks?.list() ?? [];
+  if (hooks.length === 0) {
+    io.print("No hooks. Add .synqa/hooks.json in the project (off until you switch it on here) or hooks.json in your Synqa config folder. Events: SessionStart, PreToolUse, PostToolUse, Stop.");
+    return;
+  }
+  if (!io.pick) { io.print(hooks.map(describeHook).join("\n")); return; }
+  const id = await io.pick(hooks.map((h) => ({ label: describeHook(h), value: h.id })), "Hooks: Enter toggles one");
+  if (id === undefined) return;
+  const now = io.hooks?.toggle(id);
+  io.print(now === undefined ? "No such hook." : `Hook is now ${now ? "on" : "off"}.`);
+}
+
+async function cmdUpdate(io           )                {
+  if (!io.update) { io.print("Update from a terminal: npm install -g @synqa/cli@latest"); return; }
+  io.print(io.update.latest ? `Updating ${io.update.current} to ${sanitize(io.update.latest)} ...` : "Running npm install -g @synqa/cli@latest ...");
+  const code = await io.update.run();
+  io.print(code === 0 ? "Updated. Restart synqa to use the new version." : `The update failed (exit ${code}). Run it yourself: npm install -g @synqa/cli@latest`);
+}
+
 export async function runCommand(line        , st              , io           )                         {
   const [first = "", ...args] = line.trim().split(/\s+/);
   // A first word like /usr/bin/foo is a path in a question, not a command.
@@ -141,30 +248,43 @@ export async function runCommand(line        , st              , io           )
     case "/quit":
       return { handled: true, exit: true };
     case "/help":
-      io.print(SLASH_HELP);
+      io.print(io.ui ? renderHelp(io.ui).join("\n") : SLASH_HELP);
       break;
     case "/clear":
       st.history = freshHistory(st);
       io.print("Conversation cleared.");
       announceNotes(st, io.print);
       break;
-    case "/model": {
-      if (!arg) { io.print(`Tier is ${st.tier.display}. Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); break; }
-      const t = findTier(arg);
-      if (!t) { io.print(`Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); break; }
-      st.tier = t;
-      st.history[0] = systemMessage(st, t);
-      io.print(`Switched to ${t.display}.`);
+    case "/model":
+      await cmdModel(st, io, arg);
+      break;
+    case "/effort":
+      await cmdEffort(st, io, arg);
+      break;
+    case "/provider":
+    case "/login": {
+      const pio = providerIO(st, io);
+      if (!pio) { io.print("This needs an interactive terminal."); break; }
+      if (await providerMenu(session(st), pio, arg)) {
+        st.history[0] = systemMessage(st);
+        io.print(isExternal(st) ? `Active: ${providerDef(st.providerId          )?.name} ${st.modelId ?? ""}`.trim() : `Active: Synqa Cloud ${st.tier.display}`);
+      }
       break;
     }
-    case "/effort": {
-      if (!arg) { io.print(`Effort is ${st.effort}. Choose one of: ${EFFORTS.join(", ")}`); break; }
-      const e = findEffort(arg);
-      if (!e) { io.print(`Choose one of: ${EFFORTS.join(", ")}`); break; }
-      st.effort = e;
-      io.print(`Reasoning effort set to ${e}.`);
+    case "/logout": {
+      const pio = providerIO(st, io);
+      if (!pio) { io.print("This needs an interactive terminal."); break; }
+      const out = await logout(session(st), pio);
+      if (out) st.history[0] = systemMessage(st);
+      if (out === "locked") return { handled: true, relogin: true };
       break;
     }
+    case "/hooks":
+      await cmdHooks(io);
+      break;
+    case "/update":
+      await cmdUpdate(io);
+      break;
     case "/status":
       await cmdStatus(st, io);
       break;
@@ -184,7 +304,7 @@ export async function runCommand(line        , st              , io           )
       await cmdUndo(st, io);
       break;
     default:
-      io.print("Unknown command. /help lists them.");
+      io.print(unknownCommandHint(first));
   }
   return { handled: true };
 }

package/dist/compact.js

@@ -51,6 +51,8 @@ export const approxTokens = (history           )         => Math.ceil(JSON.strin
                               
                  
              
+                                                      
+                                       
                      
                   
                       
@@ -64,7 +66,8 @@ export async function compactHistory(o                )
   if (!text.trim()) throw new Error("nothing to compact");
   const r = await chat({
     apiKey: o.apiKey,
-    model: o.tier.id,
+    model: o.modelId ?? o.tier.id,
+    baseUrl: o.baseUrl,
     messages: [
       { role: "system", content: COMPACT_PROMPT },
       { role: "user", content: text },

package/dist/config.js

@@ -7,7 +7,17 @@ export const API_BASE = "https://api.synqa.ca/v1";
 export const ACCOUNT_URL = `${API_BASE}/account`;
 export const DASHBOARD_URL = "https://synqa.ca/client-dashboard";
 
-                                                        
+// A secondary provider the user chose themselves (OpenCode, a bring-your-own router key, a custom
+// endpoint). Keys live in the same private file as the Synqa key and never leave this machine
+// except to that provider's own base URL.
+                                                                                  
+                      
+                  
+                
+                                                                          
+                                            
+                                                                                                                      
+  
 
 export function configDir(env                                     = process.env)         {
   // SYNQA_CONFIG_DIR is honoured only under the node test runner (NODE_TEST_CONTEXT is set);
@@ -29,11 +39,21 @@ export function readConfig(env                                     = process.env
   }
 }
 
-// Directory 0700, file 0600, enforced even when they already existed with looser modes.
+// chmod does nothing useful on Windows file systems and may fail there: the mode is best effort
+// on win32 and enforced everywhere else.
+function tryChmod(path        , mode        , platform         = process.platform)       {
+  try {
+    chmodSync(path, mode);
+  } catch (err) {
+    if (platform !== "win32") throw err;
+  }
+}
+
+// Directory 0700, file 0600, enforced even when they already existed with looser modes (POSIX).
 export function writeConfig(config        , env                                     = process.env)         {
   const dir = configDir(env);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
-  chmodSync(dir, 0o700);
+  tryChmod(dir, 0o700);
   const file = configPath(env);
   // The key is never written into a pre-existing file: create a fresh 0600 temp file ("wx"
   // fails if it exists) in the 0700 directory, then rename it over the target.
@@ -46,7 +66,7 @@ export function writeConfig(config        , env
     } finally {
       closeSync(fd);
     }
-    chmodSync(tmp, 0o600);
+    tryChmod(tmp, 0o600);
     renameSync(tmp, file);
     renamed = true;
   } finally {
@@ -56,11 +76,34 @@ export function writeConfig(config        , env
   return file;
 }
 
-// The env var wins over the saved key.
-export function resolveApiKey(env                                     = process.env)                     {
-  const fromEnv = env.SYNQA_API_KEY?.trim();
-  if (fromEnv) return fromEnv;
-  return readConfig(env).apiKey;
+// Since 1.2.0 a key saved by /login or synqa login wins over SYNQA_API_KEY, so nobody has to
+// unset a shell variable to use the key they just saved. The environment is the fallback when
+// nothing is saved, and wins only when the caller passes the explicit --env-key flag.
+export function resolveApiKey(env                                     = process.env, opts                       = {})                     {
+  const fromEnv = env.SYNQA_API_KEY?.trim() || undefined;
+  const saved = readConfig(env).apiKey?.trim() || undefined;
+  return opts.envKey ? fromEnv ?? saved : saved ?? fromEnv;
+}
+
+// The environment variable a secondary provider's key may come from.
+export const PROVIDER_ENV                         = {
+  "opencode-go": "OPENCODE_API_KEY",
+  "opencode-zen": "OPENCODE_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+};
+
+// The same priority for a secondary provider.
+export function resolveProviderKey(id        , env                                     = process.env, opts                       = {})                     {
+  const name = PROVIDER_ENV[id];
+  const fromEnv = name ? env[name]?.trim() || undefined : undefined;
+  const saved = readConfig(env).providers?.[id]?.apiKey?.trim() || undefined;
+  return opts.envKey ? fromEnv ?? saved : saved ?? fromEnv;
+}
+
+// Merge-writes one secondary provider into the file.
+export function saveProvider(id        , entry               , env                                     = process.env)         {
+  const cfg = readConfig(env);
+  return writeConfig({ ...cfg, providers: { ...cfg.providers, [id]: { ...cfg.providers?.[id], ...entry } } }, env);
 }
 
 export function looksLikeKey(key        )          {

package/dist/hooks.js

@@ -0,0 +1,219 @@
+// Hooks: shell commands that run at SessionStart, PreToolUse, PostToolUse and Stop.
+//
+// Two files, merged: .synqa/hooks.json in the project and hooks.json in the user config folder.
+//   { "hooks": { "PreToolUse": [ { "matcher": "write_file|edit_file", "command": "python check.py" } ],
+//                "Stop": [ "echo done" ] } }
+// A hook gets a JSON description of the event on stdin. A PreToolUse hook blocks the tool by
+// exiting with code 2 or by printing {"decision":"block","reason":"..."}; any other output, JSON
+// or not, is ignored without a message. A hook that fails to start, fails or times out never
+// stops the session and never prints an error at start-up.
+//
+// A project file is repository content, so project hooks start switched OFF until the person
+// turns them on with /hooks; user hooks start on.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+import { configDir, readConfig, writeConfig } from "./config.js";
+import { sanitize } from "./sanitize.js";
+
+export const HOOK_EVENTS = ["SessionStart", "PreToolUse", "PostToolUse", "Stop"]         ;
+                                                     
+
+                    
+                                                                                                     
+                            
+                   
+                  
+                   
+                    
+                   
+  
+
+                                              
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_OUTPUT = 64 * 1024;
+
+export const projectHooksPath = (cwd        ) => join(cwd, ".synqa", "hooks.json");
+export const userHooksPath = (env      = process.env) => join(configDir(env), "hooks.json");
+
+function readJson(path        )          {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined; // missing or malformed: no hooks, no noise
+  }
+}
+
+// The project root a project hook is approved for: the real path, else the resolved one.
+function canonicalRoot(cwd        )         {
+  const abs = resolve(cwd);
+  try { return realpathSync(abs); } catch { return abs; }
+}
+
+function parseFile(raw         , scope                    , state                         , projectRoot = "")         {
+  if (!raw || typeof raw !== "object") return [];
+  const root = raw                           ;
+  const table = (root.hooks && typeof root.hooks === "object" ? root.hooks : root)                           ;
+  const out         = [];
+  for (const event of HOOK_EVENTS) {
+    const list = table[event];
+    if (!Array.isArray(list)) continue;
+    list.forEach((entry, index) => {
+      const e = typeof entry === "string" ? { command: entry } : (entry                                  );
+      if (!e || typeof e.command !== "string" || e.command.trim() === "") return;
+      const command = e.command.trim();
+      const t = typeof e.timeout === "number" && e.timeout > 0 ? Math.min(e.timeout, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
+      const matcher = typeof e.matcher === "string" && e.matcher !== "" ? e.matcher : undefined;
+      // A project hook id binds the approval to the project root and the exact entry (command,
+      // matcher, timeout): another project or any edit gives a new id, which is off until approved.
+      const id = scope === "project"
+        ? `project:${event}:${index}:${createHash("sha256").update(JSON.stringify([projectRoot, command, matcher ?? null, t])).digest("hex")}`
+        : `${scope}:${event}:${index}:${createHash("sha1").update(command).digest("hex").slice(0, 6)}`;
+      out.push({
+        id, scope, event, command, timeoutMs: t,
+        matcher,
+        enabled: state[id] ?? scope === "user",
+      });
+    });
+  }
+  return out;
+}
+
+export function loadHooks(cwd        , env      = process.env)         {
+  const state = readConfig(env).hooksState ?? {};
+  return [
+    ...parseFile(readJson(userHooksPath(env)), "user", state),
+    ...parseFile(readJson(projectHooksPath(cwd)), "project", state, canonicalRoot(cwd)),
+  ];
+}
+
+// Flips one hook on or off and saves the choice. Returns the new state, or undefined for an unknown id.
+export function toggleHook(cwd        , id        , env      = process.env)                      {
+  const hook = loadHooks(cwd, env).find((h) => h.id === id);
+  if (!hook) return undefined;
+  const cfg = readConfig(env);
+  const enabled = !hook.enabled;
+  writeConfig({ ...cfg, hooksState: { ...cfg.hooksState, [id]: enabled } }, env);
+  return enabled;
+}
+
+export function describeHook(h      )         {
+  const cmd = sanitize(h.command).slice(0, 60);
+  return `${h.event}${h.matcher ? ` [${sanitize(h.matcher).slice(0, 30)}]` : ""}  ${cmd}  (${h.scope}, ${h.enabled ? "on" : "off"})`;
+}
+
+// ---------------------------------------------------------------- python fallback
+
+// Is `name` an executable on PATH? Windows also tries the PATHEXT suffixes.
+export function onPath(name        , env      = process.env, platform         = process.platform)          {
+  const path = env.PATH ?? env.Path ?? "";
+  const exts = platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)] : [""];
+  for (const dir of path.split(platform === "win32" ? ";" : delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      const p = join(dir, name + ext);
+      try {
+        if (existsSync(p) && statSync(p).isFile()) return true;
+      } catch {
+        // unreadable entry: keep looking
+      }
+    }
+  }
+  return false;
+}
+
+// A command that starts with `python` runs with `python3` (or `py` on Windows) when plain python
+// is not on PATH. Only the first word is rewritten.
+export function resolveHookCommand(
+  command        , platform         = process.platform, has                            = (n) => onPath(n, process.env, platform),
+)         {
+  const m = /^(\s*)(python(?:\.exe)?)(?=\s|$)/i.exec(command);
+  if (!m || has("python")) return command;
+  const candidates = platform === "win32" ? ["python3", "py"] : ["python3"];
+  const found = candidates.find((c) => has(c));
+  return found ? (m[1] ?? "") + found + command.slice(m[0].length) : command;
+}
+
+// ---------------------------------------------------------------- running
+
+                                                                                                                                
+
+                       
+                    
+                                  
+                                                                                
+                         
+  
+
+// Reads {"decision":"block"} / {"block":true} out of free-form output; anything else is not a decision.
+export function parseDecision(output        )                                        {
+  const text = output.trim();
+  if (!text.startsWith("{")) return { blocked: false };
+  try {
+    const j = JSON.parse(text)                           ;
+    const d = typeof j.decision === "string" ? j.decision.toLowerCase() : "";
+    if (d === "block" || d === "deny" || j.block === true) {
+      return { blocked: true, reason: typeof j.reason === "string" ? sanitize(j.reason).slice(0, 300) : undefined };
+    }
+  } catch {
+    // not JSON after all: ignored
+  }
+  return { blocked: false };
+}
+
+function hookEnv(env     , platform        )      {
+  return platform === "win32" ? { ...env, NoDefaultCurrentDirectoryInExePath: "1" } : env;
+}
+
+export function runHook(hook      , payload         , cwd        , d          = {})                      {
+  const platform = d.platform ?? process.platform;
+  const command = resolveHookCommand(hook.command, platform, d.has);
+  const done = (r                     )             => ({ hook, code: null, output: "", blocked: false, ...r });
+  return new Promise((resolve) => {
+    let out = "";
+    let settled = false;
+    const finish = (r            ) => { if (!settled) { settled = true; clearTimeout(timer); resolve(r); } };
+    let child;
+    try {
+      child = (d.spawnFn ?? spawn)(command, { cwd, shell: true, env: hookEnv(d.env ?? process.env, platform), stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+    } catch (err) {
+      resolve(done({ error: sanitize(err instanceof Error ? err.message : String(err)) }));
+      return;
+    }
+    const timer = setTimeout(() => { try { child.kill(); } catch { /* already gone */ } finish(done({ error: "timed out", output: out })); }, hook.timeoutMs);
+    (timer                          ).unref?.();
+    child.stdout?.on("data", (c        ) => { if (out.length < MAX_OUTPUT) out += c.toString("utf8"); });
+    child.on("error", (err       ) => finish(done({ error: sanitize(err.message) })));
+    child.on("close", (code               ) => {
+      const dec = parseDecision(out);
+      const exit2 = code === 2;
+      finish(done({ code, output: out, blocked: hook.event === "PreToolUse" && (exit2 || dec.blocked), reason: dec.reason }));
+    });
+    child.stdin?.on("error", () => {});
+    try {
+      child.stdin?.end(JSON.stringify(payload) + "\n");
+    } catch {
+      // a hook that does not read stdin is fine
+    }
+  });
+}
+
+// Runs every enabled hook of `event` (matching the tool name for the tool events), one after the
+// other. Never throws.
+export async function runHooks(hooks                 , event           , payload                                             , cwd        , d          = {})                        {
+  const out               = [];
+  for (const h of hooks) {
+    if (!h.enabled || h.event !== event) continue;
+    if (h.matcher && payload.tool !== undefined) {
+      try {
+        if (!new RegExp(`^(?:${h.matcher})$`).test(payload.tool)) continue;
+      } catch {
+        continue; // a bad pattern matches nothing
+      }
+    }
+    out.push(await runHook(h, { event, ...payload }, cwd, d));
+  }
+  return out;
+}