@tiens.nguyen/gu-cli 1.0.740 → 1.0.742

package/coding-key-prompt.mjs

@@ -24,6 +24,8 @@ const identity = (s) => s;
  * and on Ctrl+K to replace one — and they were two hand-written copies of the same idea. A hint
  * added to one of them would have left the other exactly as confusing.
  */
+import { keyInUse } from "./server-keys.mjs";
+
 export const SECRET_KEY_HINT = "type or paste the key, then press Enter — it stays masked";
 
 /**
@@ -217,13 +219,26 @@ export function codingKeyFallbackLine(kj, jobId = "") {
  * when a choice HAS been made, and when only one key exists — with one there is nothing to
  * choose, and a warning on a correct setup is how warnings stop being read.
  */
-export function unchosenKeyWarning({ codingKind = "", codingUrl = "", selectedKeyId = "", keys = null } = {}) {
+export function unchosenKeyWarning({ codingKind = "", codingUrl = "", selectedKeyId = "", keys = null, backendId = "" } = {}) {
   const quiet = { warn: false, using: null, why: "" };
   // Local Ollama and MLX need no credential; the Ollama cloud does.
   if (!codingNeedsKey(codingKind, codingUrl)) return quiet;
-  if (!Array.isArray(keys) || keys.length < 2) return quiet;
+  if (!Array.isArray(keys)) return quiet;
   if (String(selectedKeyId ?? "").trim()) return quiet;
-  return { warn: true, using: keys[0], why: "none-chosen" };
+  // KEYS BELONG TO A SERVER (#245). Reported: the bar said "key not chosen" beside ollama.com while
+  // the key picker showed its one key, hsbc_ollama, "(in use)" — because this counted all seven keys
+  // on the ACCOUNT (Anthropic, OpenAI, …) where the API only ever chooses among THIS server's keys.
+  // With the server known: its keys, else the keys tied to no server; and a server default IS a
+  // choice. Without it (an older caller) the old account-wide count stands.
+  if (backendId) {
+    const own = keys.filter((k) => k && k.backendId === backendId);
+    const pool = own.length ? own : keys.filter((k) => k && !k.backendId);
+    if (own.some((k) => k.default)) return quiet;
+    if (pool.length < 2) return quiet;
+    return { warn: true, using: keyInUse(keys, backendId) ?? pool[0], why: "none-chosen", count: pool.length };
+  }
+  if (keys.length < 2) return quiet;
+  return { warn: true, using: keys[0], why: "none-chosen", count: keys.length };
 }
 
 /**
@@ -245,14 +260,14 @@ export function unchosenKeyWarning({ codingKind = "", codingUrl = "", selectedKe
  * qualified ("<kind>::<model>", task #123) stores the bare form and is still a valid pick.
  */
 /** The folder's coder — its kind AND its URL, which together decide whether it needs a key. */
-export function effectiveCoder({ sessionCodingModel = "", choices = null, defaultKind = "", defaultUrl = "" } = {}) {
+export function effectiveCoder({ sessionCodingModel = "", choices = null, defaultKind = "", defaultUrl = "", defaultBackendId = "" } = {}) {
   const want = String(sessionCodingModel ?? "").trim();
   const list = Array.isArray(choices) ? choices : [];
   if (want) {
     const hit = list.find((c) => c?.id === want || c?.model === want);
-    if (hit) return { kind: String(hit.kind ?? ""), url: String(hit.url ?? "") };
+    if (hit) return { kind: String(hit.kind ?? ""), url: String(hit.url ?? ""), backendId: String(hit.backendId ?? "") };
   }
-  return { kind: String(defaultKind ?? ""), url: String(defaultUrl ?? "") };
+  return { kind: String(defaultKind ?? ""), url: String(defaultUrl ?? ""), backendId: String(defaultBackendId ?? "") };
 }
 
 export function effectiveCoderKind({

package/gonext_agent_chat.py

@@ -7251,6 +7251,32 @@ def run_agent_chat(cfg):
                      + (_sk_req or "(nothing more — do what the skill describes)"))
         _log(f"skill invoked: {_sk['name']}")
 
+    # HOOKS (task #270): onStart on the first turn of a gu session, onAsk on every question. What
+    # they print goes in beside the task; exit 2 from onAsk stops the turn before any model call.
+    import gu_hooks as _hooks_mod
+    _hooks = _hooks_mod.from_cfg(cfg, _log)
+    _hook_context = ""
+    if _hooks:
+        _hr_parts, _hr_warn = [], []
+        if _hooks.has("onStart") and _hooks_mod.is_new_session(_hooks.cwd or "", _hooks.session_id):
+            _r = _hooks.run("onStart", {"source": "startup"})
+            _hr_parts.append(_r.text)
+            _hr_warn += _r.warnings
+        if _hooks.has("onAsk"):
+            _r = _hooks.run("onAsk", {"question": latest_user_text})
+            _hr_warn += _r.warnings
+            if _r.blocked:
+                _emit({"type": "final", "text": f"Stopped by your onAsk hook: {_r.blocked}"})
+                return
+            _hr_parts.append(_r.text)
+        for _w in _hr_warn:
+            _emit({"type": "step", "text": f"⚠ {_w}"})
+        _hook_context = "\n\n".join(p for p in _hr_parts if p.strip())
+        if _hook_context:
+            _log(f"hooks added {len(_hook_context)} chars of context")
+            task_text += ("\n\nCONTEXT FROM YOUR gu HOOKS (onStart/onAsk — background, not the "
+                          f"request itself):\n{_hook_context}")
+
     # Walk prior turns newest-first, keeping condensed lines until the budget is
     # spent, then restore chronological (oldest→newest) order.
     history_lines = []
@@ -8153,7 +8179,10 @@ def run_agent_chat(cfg):
         # told to manage; a model that believes otherwise turns "own the environment" into
         # "write the user instructions for owning it" — see _machine_context.
         + _machine_context(_sys_platform(), _sys_arch(), _WS_ACTIVE or "")
-        + "WORK LIKE A SENIOR DEVELOPER — you OWN the task until it DEMONSTRABLY works:\n"
+        # "the task you were GIVEN": ownership is of the request, not of everything it mentions.
+        # `create task "only keep logo on flash screen"` asks for a RECORD; read as "own the logo
+        # change", the agent saved the task and then went on to do it (scaffold rule 8).
+        + "WORK LIKE A SENIOR DEVELOPER — you OWN the task you were GIVEN until it DEMONSTRABLY works:\n"
         "    * OUTCOME over exit code: a command exiting 0 is NOT the goal. After any "
         "state-changing step (start/build/install/edit), VERIFY the intended EFFECT "
         "(server responds, artifact exists, test green, file contains the change) before "
@@ -8409,8 +8438,9 @@ def run_agent_chat(cfg):
         # Task #90: ~25-token echo of the autonomy contract at the highest-attention spot
         # (recency — right next to the task), reinforcing the full directive that lives in
         # the cached reference above. Workspace/coding mode only.
-        + ("Remember: FINISH it yourself — fix blockers, VERIFY the outcome, then "
-           "final_answer with evidence; never hand the task back.\n"
+        + ("Remember: FINISH what was asked yourself — fix blockers, VERIFY the outcome, then "
+           "final_answer with evidence; never hand the task back. If it only asks to RECORD work "
+           "(create a task, a note, a plan), recording it IS the task — do not start the work.\n"
            if _WS_AVAILABLE else "")
         + "\nTASK (answer THIS, choose the tool that fits it):\n"
         f"{task_text}\n"
@@ -12487,6 +12517,11 @@ def run_agent_chat(cfg):
             for _note in _mcp_notes:
                 _emit({"type": "step", "text": _note})
             agent_tools += _mcp_mod.build_tools(_mcp_conn, _SmolTool, _mcp_approve)
+        # onToolDone (task #270): after every tool the hooks' matchers name — MCP tools included.
+        if _hooks:
+            _n_wrapped = _hooks_mod.wrap_tools(agent_tools, _hooks)
+            if _n_wrapped:
+                _log(f"onToolDone hooks on {_n_wrapped} tool(s)")
         # Fill in the numbered tool list now that the REAL tool objects exist — see
         # _render_numbered_tool_list and the {{TOOL_LIST}} placeholder left in tool_hint.
         task_with_hint = task_with_hint.replace(
@@ -12661,6 +12696,12 @@ def run_agent_chat(cfg):
         final_text = _strip_tool_tags(str(result).strip()) or "[No result]"
         _log(f"done (deterministic, no summarizer call): {len(final_text)} chars")
         _emit({"type": "final", "text": final_text})
+        # onTurnEnd (task #270): after the answer is out, so a slow hook never delays it.
+        if _hooks and _hooks.has("onTurnEnd"):
+            _te = _hooks.run("onTurnEnd", {"question": latest_user_text, "answer": final_text,
+                                           "partial": bool(_maxsteps_partial.get("hit"))})
+            for _w in _te.warnings:
+                _log(f"onTurnEnd: {_w}")
         # Clear the step checkpoint ONLY on a genuinely complete finish (the model's own
         # final_answer, or a deterministic PDF delivery) — that content is now in the
         # answer pushed to conversation history, so the raw trace is no longer needed.

package/gu-cli.mjs

@@ -35,6 +35,7 @@ import OpenAI from "openai";
 import { resolvePython } from "./platform-tools.mjs";
 import { skillsForTurn } from "./skills.mjs";
 import { mcpForTurn } from "./mcp-config.mjs";
+import { hooksForTurn, sessionForTurn } from "./hooks-config.mjs";
 
 /** The `skills` / `mcp` fields of one job's agent config (task #269). A broken config is a log
  *  line, never a failed turn — the turn runs without them. */
@@ -52,6 +53,18 @@ function skillsAndMcpForJob(cwd) {
   } catch (e) {
     console.log(`[gu-worker] MCP servers skipped: ${e?.message || e}`);
   }
+  // Hooks (task #270): yours, plus the project's once approved; and the terminal session this
+  // turn belongs to, so the agent knows when onStart is due.
+  try {
+    const hooks = hooksForTurn({ cwd });
+    if (Object.keys(hooks).length) {
+      out.hooks = hooks;
+      const session = sessionForTurn(cwd);
+      if (session) out.hookSession = session;
+    }
+  } catch (e) {
+    console.log(`[gu-worker] hooks skipped: ${e?.message || e}`);
+  }
   return out;
 }
 
@@ -254,6 +267,16 @@ if (args[0] === "mcp") {
   process.exit(code);
 }
 
+if (args[0] === "hooks") {
+  // #270. Hooks from a shell — same code as /hooks in the terminal UI.
+  const { runHooksCommand } = await import("./hooks-command.mjs");
+  const code = await runHooksCommand(args.slice(1), {
+    cwd: process.cwd(),
+    print: (line, kind) => (kind === "warn" ? console.error(line) : console.log(line)),
+  });
+  process.exit(code);
+}
+
 if (args[0] === "full-log") {
   // #250. An administrator switches Enable Full Log (#249) from a terminal — after typing an admin
   // token minted on the web admin page. Same code as /full-log in the terminal UI.

package/gu-repl.mjs

@@ -35,7 +35,7 @@ import { dirname, join, resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PassThrough } from "node:stream";
 import { createInterface } from "node:readline";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import dotenv from "dotenv";
 // Pure layout arithmetic for every in-place block (bottom bar, live status, pickers) — kept
@@ -117,11 +117,14 @@ import {
   identityRow,
   CANCEL_LINE,
   shouldCancelPrompt,
+  rankSlashCommands,
+  slashMenuWindow,
 } from "./terminal-layout.mjs";
 import { completedFlush } from "./completed-flush.mjs";
 import { discoverSkills, matchSkillCommand } from "./skills.mjs";
 import { addAllowRule, listServers as listMcpServers } from "./mcp-config.mjs";
 import { unapprovedProjectServers } from "./mcp-command.mjs";
+import { readHooks } from "./hooks-config.mjs";
 import { codingBannerLabel, isOllamaCloudUrl, SECRET_KEY_HINT } from "./coding-key-prompt.mjs";
 import { codingChoiceTags, coderDisplayName, coderWhere, whereOfActiveCoder } from "./coding-choice-tags.mjs";
 import {
@@ -535,7 +538,7 @@ const argv = process.argv.slice(2);
 // process.argv and exits inside its own subcommand branch, before it ever starts polling.
 const CLI_SUBCOMMANDS = [
   "status", "start", "stop", "restart", "logs", "doctor", "login", "set", "rag",
-  "clear", "reset", "api", "token-usage", "tokens", "token", "full-log", "mcp",
+  "clear", "reset", "api", "token-usage", "tokens", "token", "full-log", "mcp", "hooks",
 ];
 // `gu logz` USED TO START THE REPL (task #181). Silently: an unrecognised word was not in
 // the list, so it fell through to "no subcommand given" and a full agent session opened in that
@@ -810,6 +813,7 @@ const COMMANDS = [
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/full-log", usage: "/full-log [on|off|status] [account]", desc: "administrators: Enable Full Log for an account — asks for an admin token from the web admin page first" },
+  { name: "/hooks", usage: "/hooks [list|approve|unapprove]", desc: "hooks: commands gu runs on onStart, onAsk, onToolDone, onTurnEnd — list them, approve this project's" },
   { name: "/mcp", usage: "/mcp [list|tools|add|remove|enable|disable|approve|allow|disallow|reconnect]", desc: "MCP servers: see which connect, add one (asks step by step), choose which tools run without asking" },
   { name: "/help", desc: "list these commands" },
   { name: "/exit", aliases: ["/quit"], desc: "quit" },
@@ -1680,14 +1684,28 @@ function slashOverlaySeq(line, cursor, menu, cols) {
 }
 
 // Redraw the input line AND the command menu below it, fully in place.
+// A short WINDOW over the ranked matches, not the whole registry (task #271): a bare "/" used to
+// draw every command and skill at once. ↑/↓ move through ALL matches and the window follows.
+let slashTop = 0;
+function slashMenuRows(cmds, sel, win, line) {
+  if (!cmds.length) {
+    return [dim(`  no command matches ${line.trim().split(/\s+/)[0]} — /help lists them all`)];
+  }
+  const rows = hintRows(cmds.slice(win.from, win.to), sel - win.from);
+  if (win.above) rows.splice(1, 0, dim(`  ⋯ ${win.above} more above`));
+  if (win.below) rows.push(dim(`  ⋯ ${win.below} more — keep typing to narrow`));
+  return rows;
+}
 function renderSlashOverlay(sel) {
   const line = rl.line;
-  const cmds = filteredCommands(line);
+  const cmds = rankSlashCommands(allCommands(), line);
   slashNames = cmds.map((c) => c.name);
   if (sel >= cmds.length) sel = cmds.length - 1;
   slashSel = sel;
   slashPrefix = line;
-  const menu = hintRows(cmds, sel);
+  const win = slashMenuWindow(cmds.length, sel, slashTop);
+  slashTop = win.top;
+  const menu = slashMenuRows(cmds, sel, win, line);
   if (!slashOverlayActive) {
     slashOverlayActive = true;
     slashNeutralizeHistory();
@@ -1712,6 +1730,7 @@ function closeSlashOverlay() {
   slashOverlayActive = false;
   slashHintRows = 0;
   slashSel = -1;
+  slashTop = 0;
   slashNames = [];
   slashRestoreHistory();
 }
@@ -4436,6 +4455,23 @@ async function loadSessionUnfinishedTask(cwd) {
  * `mutate` receives the parsed object and may return a replacement or mutate in place.
  */
 let _sessionWrite = Promise.resolve();
+/**
+ * Mark the start of a gu session in this folder's session file (task #270). The worker reads the
+ * id back (hooks-config.mjs sessionForTurn) and the agent runs onStart hooks on the first turn it
+ * sees it — which is how "a session started" reaches the agent with nothing added to the API.
+ */
+async function startHookSession(cwd) {
+  try {
+    await updateSessionFile(cwd, (s) => {
+      s.hookSessionId = randomUUID();
+      s.hookSessionStartedAt = new Date().toISOString();
+      return s;
+    });
+  } catch {
+    /* no session file = no onStart this time, never a failed start */
+  }
+}
+
 async function updateSessionFile(cwd, mutate) {
   const run = async () => {
     let raw = {};
@@ -6215,6 +6251,8 @@ async function chooseModel() {
       codingKind: "openai",
       selectedKeyId: sessionCodingKeyId,
       keys: keysNow,
+      // Only THIS server's keys are a choice to make (#245) — not every key on the account.
+      backendId: ks.backendId,
     }).warn;
     const line = codingKeyLine({
       keys: keysNow,
@@ -10756,6 +10794,15 @@ async function main() {
       for (const w of discoverSkills({ cwd: process.cwd(), reserved: COMMAND_NAMES }).warnings) {
         console.log(GUTTER + yellow(w));
       }
+      // Hooks (task #270): a Claude Code event name, a broken file, or project hooks waiting.
+      const hk = readHooks({ cwd: process.cwd() });
+      for (const w of hk.warnings) console.log(GUTTER + yellow(w));
+      if (hk.projectPending) {
+        console.log(
+          GUTTER + yellow("This folder's .gonext/settings.json has hooks that will not run until you approve them.") +
+            "\n" + GUTTER + dim("  /hooks shows the commands · /hooks approve")
+        );
+      }
       const waiting = unapprovedProjectServers(process.cwd());
       if (waiting.length) {
         console.log(
@@ -10931,11 +10978,12 @@ async function main() {
           // machine an Ollama coder, which needs no key — while the folder was on gpt-5. Reading
           // it directly made this check answer about a coder nobody was using, and the mark only
           // appeared after /model, which re-probes WITH the override.
-          const { kind, url } = effectiveCoder({
+          const { kind, url, backendId } = effectiveCoder({
             sessionCodingModel,
             choices: probe?.codingChoices,
             defaultKind: p?.codingKind,
             defaultUrl: probe?.codingChoices?.find?.((c) => c?.isDefault)?.url ?? "",
+            defaultBackendId: probe?.codingChoices?.find?.((c) => c?.isDefault)?.backendId ?? "",
           });
           const allKeys =
             codingNeedsKey(kind, url) && !sessionCodingKeyId ? await fetchCodingKeys() : null;
@@ -10944,6 +10992,7 @@ async function main() {
             codingUrl: url,
             selectedKeyId: sessionCodingKeyId,
             keys: allKeys,
+            backendId,
           });
           // THE BAR CARRIES IT TOO, from the same decision — a line printed at startup scrolls
           // away within a few turns, and the report was precisely that the warning has to be
@@ -10951,7 +11000,7 @@ async function main() {
           keyChoicePending = w.warn;
           if (w.warn) {
             console.log(
-              GUTTER + orange(`  ${allKeys.length} API keys stored and this folder has not chosen one`) +
+              GUTTER + orange(`  ${w.count} API keys for this server and this folder has not chosen one`) +
                 dim(` — using ${w.using.name} ····${w.using.tail}.`)
             );
             console.log(GUTTER + dim("  ctrl+k picks the right one; a wrong key fails mid-task.\n"));
@@ -11065,6 +11114,8 @@ async function main() {
 
   const cwd = resolve(process.cwd());
   const history = await loadSession(cwd);
+  // A new gu session (task #270): the agent runs onStart hooks on the first turn it sees this id.
+  await startHookSession(cwd);
   if (history.length > 0) {
     const turns = history.filter((m) => m.role === "user").length;
     console.log(
@@ -11323,6 +11374,16 @@ async function main() {
       await runMcpSlashCommand(line);
       continue;
     }
+    if (line === "/hooks" || line.startsWith("/hooks ")) {
+      const { runHooksCommand } = await import("./hooks-command.mjs");
+      const style = { ok: accent, warn: yellow, dim };
+      await runHooksCommand(line.split(/\s+/).slice(1), {
+        cwd: process.cwd(),
+        print: (l, kind) => console.log(GUTTER + (style[kind] ?? ((x) => x))(l)),
+      });
+      console.log("");
+      continue;
+    }
     if (line === "/proxy" || line.startsWith("/proxy ")) {
       await runProxyCommand(line);
       continue;
@@ -11415,6 +11476,7 @@ async function main() {
     if (line === "/reset" || line === "/new") {
       history.length = 0;
       await clearSession(cwd);
+      await startHookSession(cwd); // a fresh session: onStart hooks run again (#270)
       console.log(GUTTER + dim("Session cleared — starting fresh.\n"));
       continue;
     }

package/gu_hooks.py

@@ -0,0 +1,231 @@
+"""Hooks for the gu agent (task #270): commands gu runs at fixed moments of a turn.
+
+    onStart     the first turn of a gu session (gu started, or /reset)
+    onAsk       every question, before the agent starts on it
+    onToolDone  after a tool the matcher names (gu's tool names: edit_file, grep_repo, mcp__…)
+    onTurnEnd   after the answer has been sent
+
+gu's own names and gu's own tool names, deliberately not Claude Code's. The worker hands the agent
+the hooks that apply (hooks-config.mjs: yours, plus a project's only once approved) and the
+session this turn belongs to.
+
+A HOOK IS A COMMAND. It gets one JSON object on stdin and may answer on stdout:
+    {"additionalContext": "..."}   added for the model (onStart, onAsk; onToolDone: after the result)
+    plain text                     the same as additionalContext
+    exit code 2                    stop: onAsk stops the turn, onToolDone tells the model; stderr is why
+A hook that fails any other way, or runs past its timeout, is a warning — never a failed turn.
+
+WHAT A HOOK SEES: its own env on a short whitelist of this process's (the worker's env carries gu's
+credentials), plus GU_PROJECT_DIR and GU_HOOK_EVENT. It runs in the project folder.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from typing import Any, Callable
+
+EVENTS = ("onStart", "onAsk", "onToolDone", "onTurnEnd")
+DEFAULT_TIMEOUT_S = 30
+CONTEXT_CAP_CHARS = 6000
+_ENV_KEEP = ("PATH", "HOME", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TEMP", "TMP", "SHELL", "USER",
+             "USERNAME", "LOGNAME", "TERM", "SYSTEMROOT", "APPDATA", "LOCALAPPDATA", "USERPROFILE",
+             "PROGRAMDATA", "PATHEXT", "COMSPEC", "VIRTUAL_ENV", "PYTHONIOENCODING")
+_PLAIN_MATCHER = re.compile(r"^[A-Za-z0-9_\-| ,]*$")
+
+
+def matches(matcher: str | None, value: str) -> bool:
+    """Empty or "*" = everything. Letters, digits, _ - and | = an exact list. Anything else = a regex."""
+    m = (matcher or "").strip()
+    if m in ("", "*"):
+        return True
+    if _PLAIN_MATCHER.match(m):
+        return value in {x.strip() for x in re.split(r"[|,]", m) if x.strip()}
+    try:
+        return re.search(m, value) is not None
+    except re.error:
+        return False
+
+
+class HookResult:
+    def __init__(self):
+        self.context: list[str] = []
+        self.blocked: str | None = None
+        self.warnings: list[str] = []
+        self.ran = 0
+
+    @property
+    def text(self) -> str:
+        t = "\n\n".join(c for c in self.context if c.strip())
+        return t[:CONTEXT_CAP_CHARS] + ("\n… [hook output cut]" if len(t) > CONTEXT_CAP_CHARS else "")
+
+
+class HookRunner:
+    def __init__(self, hooks: dict, cwd: str | None, session_id: str,
+                 log: Callable[[str], None] = lambda s: None):
+        self.hooks = hooks if isinstance(hooks, dict) else {}
+        self.cwd = cwd if cwd and os.path.isdir(cwd) else None
+        self.session_id = session_id or "unknown"
+        self.log = log
+
+    def has(self, event: str) -> bool:
+        return bool(self.hooks.get(event))
+
+    def matcher_union(self, event: str) -> list[str]:
+        return [g.get("matcher", "") for g in self.hooks.get(event) or [] if isinstance(g, dict)]
+
+    def _env(self, event: str, extra: dict | None) -> dict:
+        env = {k: os.environ[k] for k in _ENV_KEEP if k in os.environ}
+        env.setdefault("PYTHONIOENCODING", "utf-8")
+        env["GU_PROJECT_DIR"] = self.cwd or ""
+        env["GU_HOOK_EVENT"] = event
+        for k, v in (extra or {}).items():
+            env[str(k)] = str(v)
+        return env
+
+    def run(self, event: str, payload: dict, match_value: str = "") -> HookResult:
+        res = HookResult()
+        if event not in EVENTS:
+            return res
+        body = {"event": event, "session_id": self.session_id, "cwd": self.cwd or "", **payload}
+        data = json.dumps(body, ensure_ascii=False, default=str)
+        for group in self.hooks.get(event) or []:
+            if not isinstance(group, dict) or not matches(group.get("matcher"), match_value):
+                continue
+            for h in group.get("hooks") or []:
+                if not isinstance(h, dict) or (h.get("type") or "command") != "command" or not h.get("command"):
+                    continue
+                self._one(event, h, data, res)
+        return res
+
+    def _one(self, event: str, h: dict, data: str, res: HookResult) -> None:
+        cmd = str(h["command"])
+        args = [str(a) for a in (h.get("args") or [])]
+        timeout = float(h.get("timeout") or DEFAULT_TIMEOUT_S)
+        label = os.path.basename(args[-1] if args else cmd.split()[0])
+        t0 = time.time()
+        res.ran += 1
+        try:
+            p = subprocess.run([cmd, *args] if args else cmd, shell=not args, input=data,
+                               capture_output=True, text=True, encoding="utf-8", errors="replace",
+                               timeout=timeout, cwd=self.cwd, env=self._env(event, h.get("env")))
+        except subprocess.TimeoutExpired:
+            res.warnings.append(f"{event} hook {label} took longer than {timeout:.0f}s and was stopped")
+            self.log(f"hook {event} {label}: timeout {timeout:.0f}s")
+            return
+        except OSError as e:
+            res.warnings.append(f"{event} hook {label} could not start: {e.strerror or e}")
+            self.log(f"hook {event} {label}: could not start")
+            return
+        ms = int((time.time() - t0) * 1000)
+        out = (p.stdout or "").strip()
+        err = (p.stderr or "").strip()
+        # Sizes only: a hook's output is conversation content, and the log is content-free (#249).
+        self.log(f"hook {event} {label}: exit {p.returncode} in {ms}ms, {len(out)} chars out")
+        if p.returncode == 2:
+            res.blocked = err or f"the {event} hook {label} said no"
+            return
+        if p.returncode != 0:
+            tail = err.splitlines()[-1][:200] if err else ""
+            res.warnings.append(f"{event} hook {label} failed (exit {p.returncode})" + (f": {tail}" if tail else ""))
+            return
+        if not out:
+            return
+        try:
+            obj = json.loads(out)
+        except ValueError:
+            res.context.append(out)  # plain text = context
+            return
+        if isinstance(obj, dict):
+            if str(obj.get("decision", "")).lower() == "block":
+                res.blocked = str(obj.get("reason") or err or f"the {event} hook {label} said no")
+                return
+            ctx = obj.get("additionalContext")
+            if isinstance(ctx, str) and ctx.strip():
+                res.context.append(ctx)
+
+
+# ---- onStart: once per session ---------------------------------------------------------------
+
+def _state_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".gonext", "hooks-state.json")
+
+
+def is_new_session(cwd: str, session_id: str, path: str | None = None) -> bool:
+    """True the first time this session is seen for this folder — and records it."""
+    path = path or _state_path()
+    key = os.path.realpath(cwd or "")
+    try:
+        with open(path, encoding="utf-8") as fh:
+            state = json.load(fh)
+        if not isinstance(state, dict):
+            state = {}
+    except (OSError, ValueError):
+        state = {}
+    if state.get(key) == session_id:
+        return False
+    state[key] = session_id
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = f"{path}.{os.getpid()}.tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(state, fh, indent=2)
+        os.replace(tmp, path)
+    except OSError:
+        pass
+    return True
+
+
+# ---- onToolDone: wrapping the agent's tools ---------------------------------------------------
+
+def wrap_tools(tools: list, runner: HookRunner, clip: int = 4000) -> int:
+    """Run onToolDone after every tool a matcher names. Returns how many tools were wrapped. Hook
+    context is appended to the tool's result; a block (exit 2) is appended as a message."""
+    if not runner.has("onToolDone"):
+        return 0
+    matchers = runner.matcher_union("onToolDone")
+    n = 0
+    for t in tools:
+        name = getattr(t, "name", "")
+        if not name or name == "final_answer" or not any(matches(m, name) for m in matchers):
+            continue
+        orig = t.forward
+        order = list((getattr(t, "inputs", None) or {}).keys())
+
+        def forward(*pos, _orig=orig, _name=name, _order=order, **kw):
+            result = _orig(*pos, **kw)
+            args = dict(kw)
+            for k, v in zip(_order, pos):
+                args.setdefault(k, v)
+            text = str(result)
+            r = runner.run("onToolDone", {"tool_name": _name, "tool_input": args,
+                                          "tool_result": text[:clip]}, match_value=_name)
+            extra = []
+            if r.blocked:
+                extra.append(f"[onToolDone hook] {r.blocked}")
+            if r.text:
+                extra.append(f"[onToolDone hook]\n{r.text}")
+            return f"{result}\n\n" + "\n".join(extra) if extra and isinstance(result, str) else result
+
+        t.forward = forward
+        n += 1
+    return n
+
+
+def from_cfg(cfg: dict, log: Callable[[str], None]) -> HookRunner | None:
+    hooks = cfg.get("hooks")
+    if not isinstance(hooks, dict) or not any(hooks.get(e) for e in EVENTS):
+        return None
+    sess = cfg.get("hookSession") if isinstance(cfg.get("hookSession"), dict) else {}
+    cwd = (cfg.get("activeWorkspace") or "").strip() or None
+    if sess.get("id"):
+        return HookRunner(hooks, cwd, str(sess["id"]), log)
+    # No terminal session (the web, or a terminal older than hooks). The job id would be a NEW
+    # "session" every turn — onStart on every question — so onStart is skipped, and the other
+    # events share one id per day, which keeps the memory hook's steps together.
+    import datetime
+    runner = HookRunner(hooks, cwd, "gu-" + datetime.date.today().isoformat(), log)
+    runner.hooks = {k: v for k, v in runner.hooks.items() if k != "onStart"}
+    return runner

package/hooks-command.mjs

@@ -0,0 +1,71 @@
+/**
+ * `gu hooks …` and `/hooks …` — ONE code path (task #270).
+ *
+ *   list        every hook for this folder: yours, and the project's with whether it is approved
+ *   approve     run this project's hooks (as they are now — an edit needs approving again)
+ *   unapprove   stop running them
+ */
+import { HOOK_EVENTS, describeHook, readHooks, approveProjectHooks, userSettingsPath } from "./hooks-config.mjs";
+
+export const HOOKS_USAGE = "gu hooks [list|approve|unapprove]";
+
+function printGroups(hooks, print, indent = "  ") {
+  for (const ev of HOOK_EVENTS) {
+    for (const g of hooks[ev] ?? []) {
+      const on = g.matcher ? `  (tools: ${g.matcher})` : "";
+      for (const h of g.hooks) print(`${indent}${ev.padEnd(11)} ${describeHook(h)}${on}`);
+    }
+  }
+}
+
+export async function runHooksCommand(words, { cwd = process.cwd(), print = console.log } = {}) {
+  const sub = String((words ?? [])[0] ?? "list").toLowerCase();
+  try {
+    if (sub === "list" || sub === "ls") {
+      const r = readHooks({ cwd });
+      for (const w of r.warnings) print(w, "warn");
+      const nUser = Object.keys(r.user).length;
+      const nProj = Object.keys(r.project).length;
+      if (!nUser && !nProj) {
+        print("No hooks.");
+        print(`Add them under "hooks" in ${userSettingsPath()} — events: ${HOOK_EVENTS.join(", ")}.`, "dim");
+        return 0;
+      }
+      if (nUser) {
+        print(`Yours (${userSettingsPath()}):`, "ok");
+        printGroups(r.user, (l) => print(l, "dim"));
+      }
+      if (nProj) {
+        print(
+          r.projectApproved
+            ? "This project's (./.gonext/settings.json) — approved:"
+            : "This project's (./.gonext/settings.json) — NOT running until you approve them:",
+          r.projectApproved ? "ok" : "warn"
+        );
+        printGroups(r.project, (l) => print(l, "dim"));
+        if (!r.projectApproved) print("Check the commands above, then:  /hooks approve", "dim");
+      }
+      return 0;
+    }
+    if (sub === "approve" || sub === "unapprove") {
+      const r = readHooks({ cwd });
+      if (!Object.keys(r.project).length) {
+        print("This folder has no hooks of its own (./.gonext/settings.json).", "warn");
+        return 1;
+      }
+      approveProjectHooks({ cwd, approve: sub === "approve" });
+      print(
+        sub === "approve"
+          ? "Approved: this project's hooks run from the next turn. Editing them needs approving again."
+          : "This project's hooks will not run here.",
+        "ok"
+      );
+      return 0;
+    }
+    print(`unknown "${sub}" — ${HOOKS_USAGE}`, "warn");
+    return 2;
+  } catch (e) {
+    print(e?.message || String(e), "warn");
+    return 1;
+  }
+}

package/hooks-config.mjs

@@ -0,0 +1,172 @@
+/**
+ * HOOKS — commands gu runs at fixed moments of a turn (task #270). Where they are set, and which
+ * ones a turn gets.
+ *
+ *   ~/.gonext/settings.json            yours, every folder
+ *   <project>/.gonext/settings.json    this project's — run only once you approve them here
+ *
+ *   { "hooks": { "<event>": [ { "matcher": "edit_file|create_file",
+ *                               "hooks": [ { "type": "command", "command": "python3",
+ *                                            "args": ["/path/hook.py"], "timeout": 30 } ] } ] } }
+ *
+ * gu's OWN event names — onStart, onAsk, onToolDone, onTurnEnd — and gu's own tool names in
+ * matchers (edit_file, grep_repo, mcp__<server>__<tool>). Claude Code's names (SessionStart, …) are
+ * recognised only to say what to write instead: a hook filed under a name gu never fires would
+ * otherwise fail in silence.
+ *
+ * A PROJECT'S HOOKS ARE COMMANDS THAT CAME WITH THE REPOSITORY, so they never run until you approve
+ * them for that folder — and the approval is of their exact content (a hash): an edited hooks
+ * block needs approving again. The approval lives in YOUR settings file, never the project's.
+ *
+ * THE SESSION. onStart fires on the first turn of a gu session. The terminal writes a new session
+ * id into the folder's session file when it starts (and on /reset); sessionForTurn reads it back so
+ * the agent can tell "new session" from "next turn" with nothing added to the API.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const HOOK_EVENTS = ["onStart", "onAsk", "onToolDone", "onTurnEnd"];
+/** Claude Code's names → gu's. Only used to tell the user what to rename. */
+export const CLAUDE_EVENT_NAMES = {
+  SessionStart: "onStart",
+  UserPromptSubmit: "onAsk",
+  PostToolUse: "onToolDone",
+  Stop: "onTurnEnd",
+};
+
+export const userSettingsPath = (home = homedir()) => join(home, ".gonext", "settings.json");
+export const projectSettingsPath = (cwd) => join(cwd, ".gonext", "settings.json");
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+function readJson(file) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return { data: null };
+  }
+  try {
+    const data = JSON.parse(text);
+    return isObj(data) ? { data } : { data: null, error: "not a JSON object" };
+  } catch (e) {
+    return { data: null, error: `not valid JSON (${e.message})` };
+  }
+}
+
+/** A settings file's hooks, cleaned: only gu events, only command hooks. → { hooks, warnings } */
+export function cleanHooks(raw, where) {
+  const hooks = {};
+  const warnings = [];
+  if (!isObj(raw)) return { hooks, warnings };
+  for (const [event, groups] of Object.entries(raw)) {
+    if (!HOOK_EVENTS.includes(event)) {
+      const gu = CLAUDE_EVENT_NAMES[event];
+      warnings.push(
+        gu
+          ? `${where}: "${event}" is Claude Code's name — gu calls it "${gu}". Skipped until renamed.`
+          : `${where}: "${event}" is not a gu hook event (${HOOK_EVENTS.join(", ")}). Skipped.`
+      );
+      continue;
+    }
+    const kept = [];
+    for (const g of Array.isArray(groups) ? groups : []) {
+      if (!isObj(g)) continue;
+      const hs = (Array.isArray(g.hooks) ? g.hooks : [])
+        .filter((h) => isObj(h) && (h.type ?? "command") === "command" && String(h.command ?? "").trim())
+        .map((h) => ({
+          type: "command",
+          command: String(h.command),
+          ...(Array.isArray(h.args) ? { args: h.args.map(String) } : {}),
+          ...(Number.isFinite(h.timeout) && h.timeout > 0 ? { timeout: h.timeout } : {}),
+          ...(isObj(h.env) ? { env: Object.fromEntries(Object.entries(h.env).map(([k, v]) => [k, String(v)])) } : {}),
+        }));
+      if (hs.length) kept.push({ matcher: String(g.matcher ?? ""), hooks: hs });
+    }
+    if (kept.length) hooks[event] = kept;
+  }
+  return { hooks, warnings };
+}
+
+/** The exact content being approved — any edit changes it. */
+export function hooksFingerprint(hooks) {
+  return createHash("sha256").update(JSON.stringify(hooks ?? {})).digest("hex").slice(0, 16);
+}
+
+/** → { user, project, projectApproved, projectPending, warnings } */
+export function readHooks({ cwd, home = homedir() } = {}) {
+  const warnings = [];
+  const u = readJson(userSettingsPath(home));
+  if (u.error) warnings.push(`${userSettingsPath(home)} is ${u.error} — its hooks are skipped`);
+  const user = cleanHooks(u.data?.hooks, "~/.gonext/settings.json");
+  warnings.push(...user.warnings);
+  let project = { hooks: {}, warnings: [] };
+  let projectApproved = false;
+  if (cwd && resolve(projectSettingsPath(cwd)) !== resolve(userSettingsPath(home))) {
+    const p = readJson(projectSettingsPath(cwd));
+    if (p.error) warnings.push(`${projectSettingsPath(cwd)} is ${p.error} — its hooks are skipped`);
+    project = cleanHooks(p.data?.hooks, ".gonext/settings.json");
+    warnings.push(...project.warnings);
+    const approved = u.data?.approvedProjectHooks?.[resolve(cwd)];
+    projectApproved = Object.keys(project.hooks).length > 0 && approved === hooksFingerprint(project.hooks);
+  }
+  const hasProject = Object.keys(project.hooks).length > 0;
+  return {
+    user: user.hooks,
+    project: project.hooks,
+    projectApproved,
+    projectPending: hasProject && !projectApproved,
+    warnings,
+  };
+}
+
+/** What one turn runs: yours first, then the project's when approved. */
+export function hooksForTurn({ cwd, home = homedir() } = {}) {
+  const r = readHooks({ cwd, home });
+  const out = {};
+  for (const ev of HOOK_EVENTS) {
+    const groups = [...(r.user[ev] ?? []), ...(r.projectApproved ? r.project[ev] ?? [] : [])];
+    if (groups.length) out[ev] = groups;
+  }
+  return out;
+}
+
+/** Approve (or withdraw) this folder's hooks, as they are right now. */
+export function approveProjectHooks({ cwd, home = homedir(), approve = true }) {
+  const r = readHooks({ cwd, home });
+  const file = userSettingsPath(home);
+  const { data, error } = readJson(file);
+  if (error) throw new Error(`${file} is ${error} — fix or remove it first`);
+  const raw = data ?? {};
+  raw.approvedProjectHooks = isObj(raw.approvedProjectHooks) ? raw.approvedProjectHooks : {};
+  if (approve) raw.approvedProjectHooks[resolve(cwd)] = hooksFingerprint(r.project);
+  else delete raw.approvedProjectHooks[resolve(cwd)];
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(raw, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  renameSync(tmp, file);
+  return r.project;
+}
+
+/* ---------------------------------------------------------------- the session ------------ */
+
+/** The terminal's per-folder session file — the same name gu-repl.mjs uses. */
+export function sessionFileFor(cwd, home = homedir()) {
+  const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 32);
+  return join(home, ".gonext", "sessions", `${hash}.json`);
+}
+
+/** → { id, startedAt } | null. null = no terminal session (the web, or an older terminal). */
+export function sessionForTurn(cwd, home = homedir()) {
+  if (!cwd) return null;
+  const { data } = readJson(sessionFileFor(cwd, home));
+  const id = data?.hookSessionId;
+  return typeof id === "string" && id ? { id, startedAt: String(data.hookSessionStartedAt ?? "") } : null;
+}
+
+/** Describe one hook for a list: the command and its args, as one line. */
+export function describeHook(h) {
+  return [h.command, ...(h.args ?? [])].map((w) => (/\s/.test(w) ? JSON.stringify(w) : w)).join(" ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.740",
+  "version": "1.0.742",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -92,10 +92,13 @@
     "skills.mjs",
     "mcp-config.mjs",
     "mcp-command.mjs",
+    "hooks-config.mjs",
+    "hooks-command.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
     "gu_mcp.py",
     "gu_skills.py",
+    "gu_hooks.py",
     "prompt_scaffold_check.py",
     "gonext_transcribe.py",
     "gonext_mlx_embed.py",

package/terminal-layout.mjs

@@ -2653,3 +2653,51 @@ export function shouldCancelPrompt(awaiting, key) {
   if (key.ctrl) return false;
   return key.sequence === "\u001b";
 }
+
+/**
+ * THE SLASH MENU SHOWS A FEW, AND NARROWS AS YOU TYPE (task #271), the way Claude Code's does.
+ *
+ * A bare "/" used to print every command at once: sixteen built-ins plus every skill, most of them
+ * settings nobody touches twice, so the one you wanted was somewhere in a wall of text. Now the
+ * menu is a short window (SLASH_MENU_ROWS) over the ranked matches, ↑/↓ scroll it, and each typed
+ * character narrows it. /help still prints everything.
+ *
+ * MATCHING, best first, so the command whose name you are typing is always on top:
+ *   0  the name starts with it            /mo     → /model
+ *   1  a word of the name starts with it  /model  → then /agent-model, /embed-model
+ *   2  the name contains it               /del    → /model …
+ *   3  the description contains it        /coding → /model ("switch the CODING model"); 3+ chars
+ * Only the first word counts: "/proxy set" is /proxy with an argument. No match → [] (the menu
+ * says so), never "everything", which is what it used to fall back to.
+ */
+export const SLASH_MENU_ROWS = 6;
+
+export function rankSlashCommands(cmds, typed) {
+  const list = cmds ?? [];
+  const word = String(typed ?? "").trim().split(/\s+/)[0].toLowerCase().replace(/^\//, "");
+  if (!word) return list.slice();
+  const scored = [];
+  list.forEach((c, i) => {
+    const names = [c.name, ...(c.aliases ?? [])].map((n) => String(n).toLowerCase().replace(/^\//, ""));
+    let score = -1;
+    if (names.some((n) => n.startsWith(word))) score = 0;
+    else if (names.some((n) => n.split(/[-_]/).some((part) => part.startsWith(word)))) score = 1;
+    else if (names.some((n) => n.includes(word))) score = 2;
+    else if (word.length >= 3 && String(c.desc ?? "").toLowerCase().includes(word)) score = 3;
+    if (score >= 0) scored.push({ c, score, i });
+  });
+  scored.sort((a, b) => a.score - b.score || a.i - b.i);
+  return scored.map((s) => s.c);
+}
+
+/**
+ * Which slice of the ranked list is on screen. `sel` -1 = nothing highlighted (window at the top).
+ * → { from, to, above, below, top } — above/below are how many are hidden on each side.
+ */
+export function slashMenuWindow(total, sel, top, rows = SLASH_MENU_ROWS) {
+  const n = Math.max(0, total);
+  if (n <= rows) return { from: 0, to: n, above: 0, below: 0, top: 0 };
+  // listWindow spends two of its rows on the indicators; give it room for exactly `rows` items.
+  const w = listWindow(n, sel < 0 ? 0 : sel, sel < 0 ? 0 : top, rows + 2);
+  return { from: w.from, to: w.to, above: w.above, below: w.below, top: w.top };
+}