@great-arrow/cli 0.1.48 → 0.1.49

package/README.md

@@ -159,6 +159,24 @@ gad mcp install codex
 gad mcp install gemini
 ```
 
+#### Optional: tool suggestions in Claude Code (off by default)
+
+```bash
+gad mcp suggest-tools on        # shows what is sent, then asks [y/N]
+gad mcp suggest-tools on --yes  # non-interactive opt-in
+gad mcp suggest-tools off       # removes only this hook's entry
+gad mcp suggest-tools status
+gad mcp install claude --suggest-tools      # or --no-suggest-tools
+```
+
+When on, a Claude Code `UserPromptSubmit` hook sends each prompt's text (up to
+2,000 characters, nothing else) to greatarrow.ai over your own token and adds
+up to three Great Arrow tool names that may help. The prompt is not stored or
+logged; the hook gives up after 1.5 seconds and never blocks a prompt. It adds
+one entry to `~/.claude/settings.json` and reads its token from
+`~/.great-arrow/hook-config.json` — never from argv or settings.json.
+`gad doctor claude` reports whether it is on.
+
 `gad mcp install codex` writes Codex's native `~/.codex/config.toml` server
 entry and stores the bearer token in `~/.codex/.env`. The entry launches the
 stdio bridge, which detects the current checkout's git origin for every Codex

package/dist/hooks/gad-suggest-tools.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit (opt-in): name up to three Great Arrow tools that may help
+ * with the prompt the user just typed.
+ *
+ * CONTRACT — this runs on EVERY prompt, so it must never block or break one:
+ *  1. Sends ONLY `{ prompt }` — never the session id, transcript path or cwd
+ *     the hook input also carries.
+ *  2. One request, 1.5s deadline; a 2s watchdog bounds the whole run, so
+ *     even a stdin that never closes costs at most that.
+ *  3. On ANY failure (no token, bad stdin, timeout, non-2xx, bad JSON, no
+ *     tools) it prints nothing and exits 0.
+ *
+ * Credential: GAD_API_TOKEN, else the `{ url, token }` in
+ * ~/.great-arrow/hook-config.json that every Great Arrow Claude Code hook
+ * reads (written by `gad mcp suggest-tools on` / `gad doctor claude
+ * --enforce`) — never argv, never settings.json. GAD_BASE_URL overrides the
+ * host. Installed opt-in by `@great-arrow/cli`; what it sends is documented
+ * in docs/MCP_VERSIONING.md → "Opt-in prompt hook".
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEADLINE_MS = 1_500;
+// Watchdog: a host that never closes stdin would otherwise hang the prompt.
+// unref() so it never holds a finished process open.
+setTimeout(() => process.exit(0), 2_000).unref();
+
+async function readStdin() {
+  let data = "";
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function hookConfig() {
+  try {
+    const cfg = JSON.parse(
+      readFileSync(join(homedir(), ".great-arrow", "hook-config.json"), "utf8"),
+    );
+    return cfg && typeof cfg === "object" ? cfg : {};
+  } catch {
+    return {};
+  }
+}
+
+async function main() {
+  const cfg = process.env.GAD_API_TOKEN?.trim() ? {} : hookConfig();
+  const token = (
+    process.env.GAD_API_TOKEN ||
+    (typeof cfg.token === "string" ? cfg.token : "")
+  ).trim();
+  if (!token) return;
+  const input = JSON.parse(await readStdin());
+  const prompt = typeof input?.prompt === "string" ? input.prompt : "";
+  if (!prompt.trim()) return;
+
+  const base = (
+    process.env.GAD_BASE_URL ||
+    (typeof cfg.url === "string" && cfg.url) ||
+    "https://www.greatarrow.ai"
+  ).replace(/\/$/, "");
+  const res = await fetch(`${base}/api/mcp/tools-suggest`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ prompt }),
+    signal: AbortSignal.timeout(DEADLINE_MS),
+  });
+  if (!res.ok) return;
+  const body = await res.json();
+  const names = (Array.isArray(body?.tools) ? body.tools : [])
+    .map((t) => t?.name)
+    .filter((n) => typeof n === "string" && /^[a-z0-9_]+$/.test(n))
+    .slice(0, 3);
+  if (names.length === 0) return;
+
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: `Great Arrow tools that may help: ${names.join(", ")} (call via gad_call_read / gad_call_write or tools_enable)`,
+    },
+  });
+}
+
+let out = "";
+try {
+  out = (await main()) ?? "";
+} catch {
+  // silent-degrade: a suggestion is never worth a broken prompt
+}
+// Exit only once the write has flushed: stdout to a pipe is asynchronous on
+// macOS, and exiting first would drop the context.
+if (out) process.stdout.write(out, () => process.exit(0));
+else process.exit(0);