@synqa/cli 1.1.1 → 1.2.0

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;
+}

package/dist/main.js

@@ -3,12 +3,20 @@ import { runAgent } from "./agent.js";
 import { ApiError, checkKey } from "./api.js";
 import { announceNotes, freshHistory, runCommand, statusParts } from "./commands.js";
                                                   
-import { looksLikeKey, readConfig, resolveApiKey, writeConfig, configPath } from "./config.js";
+import { API_BASE, looksLikeKey, readConfig, resolveApiKey, resolveProviderKey, writeConfig, configPath } from "./config.js";
 import { EditJournal } from "./journal.js";
 import { isHomeDir, isSensitivePath, unsafeStartDir } from "./paths.js";
                                              
                                   
 import { join } from "node:path";
+import { loadHooks, runHooks, toggleHook } from "./hooks.js";
+                                            
+import { MODE_LABEL, nextMode } from "./modes.js";
+import { providerDef, unlockGate } from "./providers.js";
+import { pickOne, readMasked, streamKeys } from "./select.js";
+                                                       
+import { bashEnv } from "./tools.js";
+import { checkForUpdate, runUpdate } from "./update.js";
 
 // A workspace inside a protected area (~/.dotfiles, ~/.config/nvim, ~/Library/...): every file is
 // refused there, so say why once at start-up instead of leaving the user with refusals.
@@ -18,9 +26,10 @@ export function protectedWorkspaceWarning(cwd        , home         )
 }
 
 // The start-up notes both the session banner and a one-shot run print.
-export function startWarnings(env                                    , cwd        , home         )           {
+// envInUse: false when a saved key is used and SYNQA_API_KEY is ignored (no warning then).
+export function startWarnings(env                                    , cwd        , home         , envInUse = true)           {
   const out           = [];
-  if (env.SYNQA_API_KEY?.trim()) out.push("using the key from SYNQA_API_KEY (not the one saved by synqa login)");
+  if (envInUse && env.SYNQA_API_KEY?.trim()) out.push("using the key from SYNQA_API_KEY (not the one saved by synqa login)");
   const inProtected = protectedWorkspaceWarning(cwd, home);
   if (inProtected) out.push(inProtected);
   return out;
@@ -111,54 +120,31 @@ const BALANCE_TIMEOUT_MS = 2000;
 const HELP = `Usage:
   synqa                     interactive session in the current folder
   synqa "do something"      one-shot task
-  synqa login               save your API key
+  synqa login               save your Synqa API key
 Options:
   -y, --yes                 do not ask before ordinary file writes and edits
                             (shell commands always ask; not allowed in your home folder)
+  --env-key                 use SYNQA_API_KEY (and the other provider key variables)
+                            instead of a key saved by /login
   -m, --model <tier>        blink | sonata | aeon (default blink)
-  -e, --effort <level>      default | low | medium (default default)
+  -e, --effort <level>      default | low | medium | high (default default)
   -h, --help   -v, --version
-In a session, type / for the command menu (/model, /effort, /status, /init, /compact, /undo,
-/clear, /help, /exit).`;
+In a session, type / for the command menu (/model, /effort, /provider, /login, /logout, /status,
+/init, /compact, /undo, /hooks, /update, /clear, /help, /exit). Shift+Tab cycles the permission
+mode (ask before edits, auto-accept edits, plan only).`;
 
-// Said when SYNQA_API_KEY is set: it wins over the key that synqa login saved.
-export const ENV_KEY_NOTE = "SYNQA_API_KEY is set in this shell, so it is used instead of the key saved by synqa login. Remove it (unset SYNQA_API_KEY, and delete the line from ~/.zshrc or ~/.bash_profile) to use the saved key.";
+// Said when SYNQA_API_KEY is set in the shell but a key saved by synqa login or /login exists:
+// the saved key wins (since 1.2.0), so there is nothing to unset.
+export const ENV_KEY_NOTE = "SYNQA_API_KEY is set in this shell and takes effect only because the --env-key flag was passed or no key is saved. A key saved by synqa login or /login wins otherwise.";
 
-// Masked single-line input: nothing typed is echoed.
-export function readSecret(promptText        )                  {
-  return new Promise((resolve, reject) => {
-    const stdin = process.stdin;
-    if (!stdin.isTTY) {
-      reject(new Error("login needs an interactive terminal (or set SYNQA_API_KEY)"));
-      return;
-    }
-    process.stdout.write(promptText);
-    let value = "";
-    stdin.setRawMode(true);
-    stdin.resume();
-    stdin.setEncoding("utf8");
-    const onData = (chunk        ) => {
-      for (const ch of chunk) {
-        if (ch === "\r" || ch === "\n") {
-          stdin.setRawMode(false);
-          stdin.pause();
-          stdin.off("data", onData);
-          process.stdout.write("\n");
-          resolve(value.trim());
-          return;
-        }
-        if (ch === "\u0003") {
-          stdin.setRawMode(false);
-          process.stdout.write("\n");
-          reject(new Error("cancelled"));
-          return;
-        }
-        if (ch === "\u007f" || ch === "\b") value = value.slice(0, -1);
-        else if (ch >= " ") value += ch;
-      }
-    };
-    stdin.on("data", onData);
-  });
+// Masked single-line input on the process terminal: each character shows as a bullet.
+export async function readSecret(promptText        )                  {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) throw new Error("login needs an interactive terminal (or set SYNQA_API_KEY)");
+  const v = await readMasked(promptText, { keys: streamKeys(stdin), out: process.stdout });
+  stdin.pause();
+  if (v === undefined) throw new Error("cancelled");
+  return v;
 }
 
 // The error text can come from the network, so it is sanitized before printing.
@@ -180,18 +166,17 @@ export async function login()                  {
   }
   const file = writeConfig({ ...readConfig(), apiKey: key });
   console.log(`Key verified and saved to ${file}`);
-  const fromEnv = process.env.SYNQA_API_KEY?.trim();
-  if (fromEnv && fromEnv !== key) console.error(`\nWarning: ${ENV_KEY_NOTE}`);
   return 0;
 }
 
-                                                                                                                                 
+                                                                                                                                                  
 
 export function parseArgs(argv          )       {
-  const a       = { allowHome: false, yes: false, model: "", effort: "", help: false, version: false, rest: [] };
+  const a       = { allowHome: false, yes: false, envKey: false, model: "", effort: "", help: false, version: false, rest: [] };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i]          ;
     if (t === "-y" || t === "--yes") a.yes = true;
+    else if (t === "--env-key") a.envKey = true;
     else if (t === "--allow-home") a.allowHome = true; // accepted and ignored since 1.1.1
     else if (t === "-h" || t === "--help") a.help = true;
     else if (t === "-v" || t === "--version") a.version = true;
@@ -202,6 +187,20 @@ export function parseArgs(argv          )       {
   return a;
 }
 
+// Where a session starts: the saved active provider if its credentials are still there, else Synqa Cloud.
+export function startProvider(synqaKey        , env                                    , envKey         )                                                                                                {
+  const cfg = readConfig(env);
+  const id = cfg.activeProvider;
+  const def = id ? providerDef(id) : undefined;
+  if (id && def && id !== "synqa") {
+    const entry = cfg.providers?.[id];
+    const key = resolveProviderKey(id, env, { envKey });
+    const base = id === "custom" ? entry?.baseUrl : def.baseUrl;
+    if (key && base) return { apiKey: key, providerId: def.id, baseUrl: base, modelId: entry?.model };
+  }
+  return { apiKey: synqaKey, providerId: "synqa", baseUrl: API_BASE };
+}
+
 // `input` is the key source; tests pass a stream that ends at once, like `< /dev/null`.
 export async function main(argv          , input            = process.stdin)                  {
   const args = parseArgs(argv);
@@ -216,8 +215,11 @@ export async function main(argv          , input            = process.stdin)
   }
   const yesRefused = homeYesRefusal(process.cwd(), args.yes);
   if (yesRefused) { console.error(yesRefused); return 1; }
-  const apiKey = resolveApiKey();
-  if (!apiKey) {
+  const interactive = Boolean(input.isTTY) && args.rest.length === 0;
+  const synqaKey0 = resolveApiKey(process.env, { envKey: args.envKey }) ?? "";
+  // A terminal session with no usable Synqa key shows the welcome screen and signs in first.
+  const needSignIn = interactive && !looksLikeKey(synqaKey0);
+  if (!synqaKey0 && !interactive) {
     console.error(`No API key. Run "synqa login" or set SYNQA_API_KEY. (config: ${configPath()})`);
     return 1;
   }
@@ -226,9 +228,8 @@ export async function main(argv          , input            = process.stdin)
   const tier = findTier(args.model || readConfig().tier || DEFAULT_TIER);
   if (!tier) { console.error(`Unknown tier "${args.model}". Use blink, sonata or aeon.`); return 1; }
   const effort = args.effort ? findEffort(args.effort) : "default";
-  if (!effort) { console.error(`Unknown effort "${args.effort}". Use default, low or medium.`); return 1; }
+  if (!effort) { console.error(`Unknown effort "${args.effort}". Use default, low, medium or high.`); return 1; }
 
-  const interactive = Boolean(input.isTTY) && args.rest.length === 0;
   // On a terminal the prompt frame reads the keys (for the / menu) and hands them to readline.
   const framed = interactive && ui.tty && ui.unicode;
   let statusLines                 = () => [];
@@ -253,33 +254,72 @@ export async function main(argv          , input            = process.stdin)
     return /^y(es)?$/i.test(ans.trim());
   };
 
+  // The arrow-key controls: every key goes to the selector or the masked prompt, none to readline.
+  const keySource                        = keys ?? (input.isTTY ? streamKeys(input) : undefined);
+  const pick = keySource
+    ?    (items                        , title         ) => pickOne(items, { keys: keySource, out: term, style, unicode: ui.unicode, title })
+    : undefined;
+  const secret = keySource ? (p        ) => readMasked(p, { keys: keySource, out: term, unicode: ui.unicode }) : undefined;
+  const ask = interactive ? async (p        )                              => { try { return (await rl.question(p)).trim(); } catch { return undefined; } } : undefined;
+
   const cwd = process.cwd();
+  const sp = startProvider(synqaKey0, process.env, args.envKey);
   const st               = {
-    apiKey, cwd, tier, effort, history: [], journal: new EditJournal(),
+    apiKey: sp.apiKey, cwd, tier, effort, history: [], journal: new EditJournal(),
     total: { prompt: 0, completion: 0 }, last: { prompt: 0, completion: 0 }, routing: "?", notesChars: 0, notesShown: 0,
+    providerId: sp.providerId, baseUrl: sp.baseUrl, modelId: sp.modelId, mode: "ask",
   };
   st.history = freshHistory(st);
-  const ctx = { cwd, confirm, yes: args.yes, color: style.color, journal: st.journal, show: (t        ) => say(inCard(t)), get notesLoaded() { return st.notesChars > 0; } };
+  const ctx = {
+    cwd, confirm, yes: args.yes, color: style.color, journal: st.journal, show: (t        ) => say(inCard(t)),
+    get notesLoaded() { return st.notesChars > 0; },
+    get mode() { return st.mode; },
+  };
+  const external = () => (st.providerId ?? "synqa") !== "synqa";
+  const providerInfo = () => (external() ? { name: providerDef(st.providerId          )?.name ?? "Custom endpoint", model: st.modelId } : undefined);
+
+  // Hooks: shell commands at SessionStart, PreToolUse, PostToolUse and Stop. They never print errors.
+  const fire = async (event           , payload                                              = {}) => {
+    if (st.mode === "plan" && (event === "PostToolUse" || event === "Stop")) return []; // plan mode runs nothing after the fact
+    try { return await runHooks(loadHooks(cwd), event, { cwd, ...payload }, cwd, { env: bashEnv(process.env) }); } catch { return []; }
+  };
+  const toolHooks = {
+    pre: async (name        , a        ) => {
+      const blocked = (await fire("PreToolUse", { tool: name, input: a.slice(0, 4000) })).find((h) => h.blocked);
+      return blocked ? blocked.reason ?? "stopped by a PreToolUse hook" : undefined;
+    },
+    post: async (name        , a        , result        ) => { await fire("PostToolUse", { tool: name, input: a.slice(0, 4000), result: result.slice(0, 4000) }); },
+  };
 
   // Known balance for the footer and status line; refreshed in the background after each turn.
   let balance          = { kind: "unavailable" };
+  let latestVersion                    ;
   // The status line under the input: only known values (tier, workspace, context, tokens, credit).
   statusLines = () => renderStatusLines({
     tier: st.tier, effort: st.effort, cwd, tokens: st.total.prompt + st.total.completion,
     contextTokens: st.last.prompt || undefined, contextMax: CONTEXT_TOKENS, routing: st.routing, balance,
+    provider: providerInfo(), mode: MODE_LABEL[st.mode ?? "ask"], updateHint: latestVersion ? `update ${latestVersion}: /update` : undefined,
   }, ui);
   const refresh = () => { frame?.redraw(); };
+  // Shift+Tab cycles the permission mode; the footer shows it.
+  if (keys) keys.onShiftTab = () => { st.mode = nextMode(st.mode ?? "ask"); };
   // Raw mode and bracketed paste are always switched off again, also after a crash.
   const { restore, done } = wireSession({ spinner, keys, rl, oneShot: !interactive });
-  process.stdout.on("resize", () => refresh());
-  const loadBalance = async ()                   => balanceFrom(await fetchAccount(apiKey, undefined, BALANCE_TIMEOUT_MS));
+  // 'resize' (not SIGWINCH) fires on Windows, macOS and Linux; a changed width redraws the frame.
+  process.stdout.on("resize", () => { if (frame) frame.onResize(); else refresh(); });
+  // The balance belongs to Synqa Cloud: it is never asked with a secondary provider's key.
+  const loadBalance = async ()                   => {
+    const key = resolveApiKey(process.env, { envKey: args.envKey });
+    return key ? balanceFrom(await fetchAccount(key, undefined, BALANCE_TIMEOUT_MS)) : { kind: "unavailable" };
+  };
   const refreshBalance = () => { void loadBalance().then((b) => { balance = b; }, () => {}); };
 
   const turn = async (text        )                => {
     st.history.push({ role: "user", content: text });
     try {
       const r = await runAgent({
-        apiKey, tier: st.tier, effort: st.effort, history: st.history, ctx,
+        apiKey: st.apiKey, tier: st.tier, effort: st.effort, history: st.history, ctx,
+        baseUrl: external() ? st.baseUrl : undefined, modelId: external() ? st.modelId : undefined, hooks: toolHooks,
         events: chrome
           ? {
             onRequest: () => renderer.requestStart(),
@@ -303,41 +343,74 @@ export async function main(argv          , input            = process.stdin)
         renderer.turnEnd();
         const footer = formatFooter({
           ttftMs: r.ttftMs, tokPerSec: r.tokPerSec, routing: st.routing,
-          creditLeft: balance.kind === "ok" ? balance.account.creditRemaining : undefined,
+          creditLeft: balance.kind === "ok" && !external() ? balance.account.creditRemaining : undefined,
         }, ui);
         if (footer) say(stone(style, footer));
-        refreshBalance();
+        if (!external()) refreshBalance();
       } else {
         process.stdout.write("\n");
       }
     } catch (err) {
-      spinner.stop();
+      spinner.stop(); // the thinking timer ends on an error or an abort too
       const msg = sanitize(err instanceof Error ? err.message : String(err));
-      const envNote = err instanceof ApiError && err.status === 401 && process.env.SYNQA_API_KEY?.trim() ? `\n${ENV_KEY_NOTE}` : "";
+      const envNote = err instanceof ApiError && err.status === 401 && !external() && process.env.SYNQA_API_KEY?.trim() ? `\n${ENV_KEY_NOTE}` : "";
       console.error(`\n${chrome ? accent(style, "error") : "error"}: ${msg}${envNote}`);
     }
+    await fire("Stop", { tokens: st.total.prompt + st.total.completion });
     refresh();
   };
 
+  // Welcome screen and the Synqa-first gate: chat and every other provider stay locked until a
+  // valid Synqa Cloud key is saved. Returns false when the person cancels.
+  const bannerInfo = (locked         ) => ({ version: VERSION, tier: st.tier, effort: st.effort, cwd, notesChars: st.notesChars, balance, warnings: locked ? [] : startWarnings(process.env, cwd, undefined, apiKeyFromEnv()), provider: providerInfo(), locked });
+  const apiKeyFromEnv = () => {
+    const e = process.env.SYNQA_API_KEY?.trim();
+    return Boolean(e) && resolveApiKey(process.env, { envKey: args.envKey }) === e;
+  };
+  const signIn = async ()                   => {
+    if (!secret) return false;
+    say("");
+    for (const line of renderBanner(bannerInfo(true), ui)) say(line);
+    say("");
+    const key = await unlockGate({ secret, print: (m) => say(dim(style, m)) });
+    if (!key) return false;
+    const p = startProvider(key, process.env, args.envKey);
+    st.apiKey = p.apiKey; st.providerId = p.providerId; st.baseUrl = p.baseUrl; st.modelId = p.modelId;
+    st.history = freshHistory(st);
+    say(dim(style, "Signed in to Synqa Cloud."));
+    return true;
+  };
+
   try {
     if (!interactive) {
       const prompt = args.rest.join(" ");
       if (!prompt) { console.error("Nothing to do. Pass a task or run in a terminal."); return 1; }
       announceNotes(st, say);
-      for (const w of startWarnings(process.env, cwd)) console.error(`Warning: ${w}`);
+      for (const w of startWarnings(process.env, cwd, undefined, apiKeyFromEnv())) console.error(`Warning: ${w}`);
+      await fire("SessionStart", { source: "one-shot" });
       await turn(prompt);
       say(dim(style, formatStatus(statusParts(st))));
       return 0;
     }
 
+    if (needSignIn) {
+      if (!(await signIn())) { say(dim(style, "Not signed in. Run synqa again to sign in to Synqa Cloud.")); return 1; }
+    }
     // The balance may take a moment; the banner waits at most BALANCE_TIMEOUT_MS for it.
-    balance = await loadBalance();
-    const warnings = startWarnings(process.env, cwd);
+    if (!external()) balance = await loadBalance();
     say("");
-    for (const line of renderBanner({ version: VERSION, tier: st.tier, effort: st.effort, cwd, notesChars: st.notesChars, balance, warnings }, ui)) say(line);
+    if (!needSignIn) for (const line of renderBanner(bannerInfo(false), ui)) say(line);
     say("");
     if (!frame) say(dim(style, "Type /help for commands."));
     announceNotes(st, (t) => say(dim(style, t)));
+    await fire("SessionStart", { source: "startup" });
+    // A quiet, short check for a newer release; any failure is silent and nothing waits for it.
+    if (chrome && !process.env.SYNQA_NO_UPDATE_CHECK) void checkForUpdate(VERSION).then((v) => { latestVersion = v; if (v) refresh(); }, () => {});
+    const io = {
+      print: say, confirm, style, ui, pick, secret, ask, envKey: args.envKey,
+      hooks: { list: () => loadHooks(cwd), toggle: (id        ) => toggleHook(cwd, id) },
+      update: { current: VERSION, get latest() { return latestVersion; }, run: () => runUpdate() },
+    };
     for (;;) {
       // Without the frame the status is printed above each prompt instead.
       if (!frame) say(dim(style, formatStatus(statusParts(st))));
@@ -346,9 +419,14 @@ export async function main(argv          , input            = process.stdin)
         line = (frame ? await frame.ask(promptText(ui)) : keys ? await keys.askPlain(`${accent(style, ui.unicode ? "❯" : ">")} `) : await rl.question(`${accent(style, ui.unicode ? "❯" : ">")} `)).trim();
       } catch { break; }
       if (!line) continue;
-      const r = await runCommand(line, st, { print: say, confirm, style, ui });
+      const r = await runCommand(line, st, io);
       refresh();
       if (r.exit) break;
+      if (r.relogin) {
+        // A full logout locks the session: back to the sign-in prompt, nothing else works until then.
+        if (!(await signIn())) { say(dim(style, "Locked. Run synqa again to sign in.")); break; }
+        continue;
+      }
       if (!r.handled) await turn(line);
     }
     return 0;

package/dist/modes.js

@@ -0,0 +1,20 @@
+// Permission modes of the session, cycled with Shift+Tab at the prompt and shown in the footer.
+//   ask    every file write and edit asks first (the default)
+//   auto   file writes and edits inside the workspace are applied without a question, like --yes
+//          (shell commands, secret files and files that can run code later still ask)
+//   plan   no file is written and no command is run: the agent can only read and describe a plan
+export const MODES = ["ask", "auto", "plan"]         ;
+                                                    
+
+export const MODE_LABEL                                 = {
+  ask: "ask before edits",
+  auto: "auto-accept edits",
+  plan: "plan only",
+};
+
+export function nextMode(m                )                 {
+  return MODES[(MODES.indexOf(m) + 1) % MODES.length]                  ;
+}
+
+// Tools that change something; plan mode refuses them.
+export const MUTATING_TOOLS                    = ["write_file", "edit_file", "bash"];