roger-roger 0.1.0

package/skills/roger-roger/scripts/hooks.mjs

@@ -0,0 +1,420 @@
+// Hooks: the agent's own program telling us something, rather than the model deciding to.
+//
+// The skill covers everything the model says through roger-roger. What it misses is when the agent
+// asks in the terminal instead — Claude Code's own question dialog (AskUserQuestion), or a plan to
+// approve — and sits there waiting for someone who has walked off. Claude Code shows those as
+// prompts, and can run a command of ours around every prompt, so the ping comes from there.
+//
+// Three Claude Code hooks work together:
+//
+//   PermissionRequest  fires the instant a prompt is about to show, with the tool and its input.
+//                      We only note it down — the user may well be at the keyboard.
+//   Notification       (`permission_prompt`) fires once the prompt has sat for about six seconds
+//                      with nobody typing. That is Claude Code's own "the user is away", so this is
+//                      where the ping goes out, described with what the first hook noted. Questions
+//                      always ping; leave to run a command only with `setup --permission-pings on`.
+//   PostToolUse        (questions only) fires once the user has answered in the terminal, and turns
+//                      the Slack message into what they chose, so it doesn't sit there asking.
+//
+// All run in the background (`async`), so a slow Slack never holds up the prompt. This file is the
+// pure part — what to say, and how to edit settings.json — plus the file plumbing for installing.
+// OpenCode and Codex have their own adapters (hooks-opencode.mjs, hooks-codex.mjs) that turn their
+// events into the same `permission` steps, so everything past reading the payload is shared.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** A permission request older than this is not the one on screen any more. */
+export const REQUEST_TTL_MS = 10 * 60_000;
+/** How many recent requests a session remembers; parallel tool calls can queue several. */
+const KEEP_REQUESTS = 5;
+const MAX_DETAIL = 500;
+
+const str = (v) => (typeof v === "string" ? v.trim() : "");
+
+// ---------------------------------------------------------------- describing a request
+
+/** A path relative to the project when it is inside it: shorter to read on a phone. */
+function shortPath(file, cwd) {
+  const f = str(file);
+  if (!f || !cwd) return f;
+  const rel = path.relative(cwd, f);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : f;
+}
+
+/** `mcp__github__create_issue` → { server: "github", tool: "create_issue" }. */
+function mcpParts(name) {
+  const m = /^mcp__(.+?)__(.+)$/.exec(name);
+  return m ? { server: m[1], tool: m[2] } : null;
+}
+
+function compactJson(input) {
+  if (input === undefined || input === null) return "";
+  try {
+    const json = JSON.stringify(input);
+    return json === "{}" ? "" : json;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * What a tool call is, in words: `action` finishes "I need your permission to …", `detail` is the
+ * thing itself (a command, a path, a URL), `why` is the agent's own description when it gave one.
+ */
+export function describeTool(toolName, input = {}, cwd = "") {
+  const tool = str(toolName);
+  const i = input && typeof input === "object" ? input : {};
+  const mcp = mcpParts(tool);
+  if (mcp) return { action: `use the ${mcp.server} tool ${mcp.tool.replace(/_/g, " ")}`, detail: compactJson(i), why: "" };
+  switch (tool) {
+    case "Bash":
+    case "PowerShell":
+      return { action: "run a command", detail: str(i.command), why: str(i.description) };
+    case "Edit":
+    case "MultiEdit":
+      return { action: "edit a file", detail: shortPath(i.file_path, cwd), why: "" };
+    case "Write":
+      return { action: "write a file", detail: shortPath(i.file_path, cwd), why: "" };
+    case "NotebookEdit":
+      return { action: "edit a notebook", detail: shortPath(i.notebook_path, cwd), why: "" };
+    case "Read":
+      return { action: "read a file", detail: shortPath(i.file_path, cwd), why: "" };
+    case "Glob":
+    case "Grep":
+      return { action: "search files", detail: [str(i.pattern), shortPath(i.path, cwd)].filter(Boolean).join("  in  "), why: "" };
+    case "WebFetch":
+      return { action: "fetch a web page", detail: str(i.url), why: "" };
+    case "WebSearch":
+      return { action: "search the web", detail: str(i.query), why: "" };
+    case "Agent":
+    case "Task":
+      return { action: "start a subagent", detail: str(i.description) || str(i.prompt), why: "" };
+    // OpenCode's own permission names, for the ones that aren't a tool.
+    case "external_directory":
+      return { action: "work outside the project", detail: (i.patterns ?? []).join("\n"), why: "" };
+    case "doom_loop":
+      return { action: "keep going after repeating itself", detail: "", why: "" };
+    case "":
+      return { action: "continue", detail: "", why: "" };
+    default:
+      return { action: `use ${tool}`, detail: compactJson(i), why: "" };
+  }
+}
+
+/** Something safe to put inside a Slack code block. */
+function codeBlock(text) {
+  const clipped = text.length > MAX_DETAIL ? `${text.slice(0, MAX_DETAIL)}…` : text;
+  return "```" + clipped.replace(/```/g, "'''") + "```";
+}
+
+/**
+ * Tools that are the agent asking the user something, rather than asking leave to act. Claude Code
+ * shows them as prompts too, so the same hooks see them; they are the ones worth a ping by default.
+ */
+export const QUESTION_TOOLS = ["AskUserQuestion", "ExitPlanMode"];
+export const isQuestion = (tool) => QUESTION_TOOLS.includes(tool);
+
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max).trimEnd()}…` : text);
+const quote = (text) => text.split("\n").map((l) => `>${l}`).join("\n");
+
+/** AskUserQuestion's questions, tidied: [{ question, options: [label], multi }]. */
+export function questionsOf(input) {
+  const list = Array.isArray(input?.questions) ? input.questions : [];
+  return list
+    .map((q) => ({
+      question: str(q?.question),
+      options: (Array.isArray(q?.options) ? q.options : []).map((o) => str(typeof o === "string" ? o : o?.label)).filter(Boolean),
+      multi: Boolean(q?.multiSelect),
+    }))
+    .filter((q) => q.question);
+}
+
+/** A sentence that is fine to say out loud: tags and markdown out, one line, not too long. */
+function speakable(text, max = 200) {
+  return clip(str(text).replace(/[`*_>#]/g, "").replace(/\s+/g, " "), max);
+}
+
+/**
+ * The notification for a prompt: `kind`, `message` for Slack, `say` for speech. `request` is what
+ * the PermissionRequest hook noted, when it did; without it (a sandboxed network request, say, which
+ * Claude Code asks about without that hook) Claude Code's own notification text is used.
+ */
+export function permissionNotice({ request = null, notice = "", cwd = "" } = {}) {
+  if (request?.tool === "AskUserQuestion") {
+    const questions = questionsOf(request.input);
+    const blocks = questions.map((q) => quote([`*${q.question}*`, ...q.options.map((o) => `• ${o}`)].join("\n")));
+    const heading = questions.length > 1 ? `*Has ${questions.length} questions for you*` : "*Has a question for you*";
+    return {
+      kind: "input",
+      message: [heading, ...blocks, "_Answer in the terminal._"].join("\n"),
+      say: questions.length
+        ? `[neutral] I have a question for you. ${speakable(questions[0].question)}${questions.length > 1 ? ` And ${questions.length - 1} more.` : ""}`
+        : "[neutral] I have a question for you. It's in the terminal.",
+    };
+  }
+  if (request?.tool === "ExitPlanMode") {
+    const plan = str(request.input?.plan);
+    return {
+      kind: "input",
+      message: ["*Has a plan ready for you to approve*", ...(plan ? [quote(clip(plan, 1200))] : []), "_Approve it in the terminal._"].join("\n"),
+      say: "[neutral] My plan is ready. It needs your approval in the terminal.",
+    };
+  }
+  if (!request) {
+    const text = str(notice) || "Claude needs your permission to continue.";
+    return {
+      kind: "blocked",
+      message: `*Waiting for your permission.* ${text}\n_Answer it in the terminal._`,
+      say: "[serious] I need your permission to continue. It's waiting in the terminal.",
+    };
+  }
+  const { action, detail, why } = describeTool(request.tool, request.input, cwd);
+  const lines = [`*Waiting for your permission* to ${action}${why ? `: ${why}` : "."}`];
+  if (detail) lines.push(codeBlock(detail));
+  lines.push("_Answer it in the terminal._");
+  return {
+    kind: "blocked",
+    message: lines.join("\n"),
+    say: `[serious] I need your permission to ${action}. It's waiting in the terminal.`,
+  };
+}
+
+/**
+ * The answers to an AskUserQuestion, from whatever PostToolUse carried. Claude Code documents an
+ * `answers` map (question text → label, several joined with commas) on the tool's input; the
+ * response is checked too, since that is where a tool's result normally is.
+ */
+export function answersOf(input, response) {
+  const joined = (a) => (Array.isArray(a) ? a.map(String).join(", ") : str(String(a ?? "")));
+  // OpenCode answers in order, one list of labels per question.
+  if (Array.isArray(response?.answers)) {
+    const questions = questionsOf(input);
+    return Object.fromEntries(response.answers.map((a, i) => [questions[i]?.question ?? "", joined(a)]).filter(([q]) => q));
+  }
+  for (const source of [response?.answers, input?.answers]) {
+    if (source && typeof source === "object" && !Array.isArray(source)) {
+      const entries = Object.entries(source).map(([q, a]) => [str(q), joined(a)]);
+      if (entries.length) return Object.fromEntries(entries);
+    }
+  }
+  return {};
+}
+
+/**
+ * What the Slack message turns into once the user has dealt with it in the terminal. `outcome` is
+ * how: answered (the default), dismissed, or — for leave to act — allowed or denied.
+ */
+export function answeredNotice(request, response, outcome = "answered") {
+  if (outcome === "dismissed") return { message: "*Dismissed in the terminal.*" };
+  if (outcome === "allowed") return { message: "*Allowed in the terminal.*" };
+  if (outcome === "denied") return { message: "*Denied in the terminal.*" };
+  if (request?.tool === "ExitPlanMode") return { message: "*Plan approved in the terminal.*" };
+  const answers = answersOf(request?.input, response);
+  const lines = questionsOf(request?.input).map((q) => quote(`${q.question}\n*${answers[q.question] || "answered"}*`));
+  return { message: ["*Answered in the terminal.*", ...lines].join("\n") };
+}
+
+/** Remember a request, dropping stale ones and keeping only the last few. */
+export function rememberRequest(requests = [], request, now = Date.now()) {
+  const fresh = (requests ?? []).filter((r) => now - Date.parse(r.at) < REQUEST_TTL_MS);
+  return [...fresh, request].slice(-KEEP_REQUESTS);
+}
+
+/**
+ * Which remembered request a prompt notification is about. Claude Code's text names the tool
+ * ("Claude needs your permission to use Bash"), so prefer the newest un-pinged request for that
+ * tool; otherwise the newest un-pinged one. Null when there's nothing fitting — then the ping is
+ * still sent, with Claude Code's own words.
+ */
+export function matchRequest(requests = [], notice = "", now = Date.now()) {
+  const open = (requests ?? []).filter((r) => !r.pingedAt && !r.answeredAt && now - Date.parse(r.at) < REQUEST_TTL_MS);
+  if (!open.length) return null;
+  const text = str(notice).toLowerCase();
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const named = open.filter((r) => r.tool && new RegExp(`\\buse ${escape(r.tool.toLowerCase())}(?![\\w])`).test(text));
+  return (named.length ? named : open).at(-1);
+}
+
+// ---------------------------------------------------------------- reading what Claude Code sends
+
+/**
+ * Turn a Claude Code hook payload into a `permission` command, or null for anything we don't act on.
+ * The payload is whatever arrived on stdin, so nothing about its shape is taken on trust.
+ */
+export function claudeHookRequest(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const sessionId = str(payload.session_id);
+  if (!sessionId) return null;
+  const cwd = str(payload.cwd);
+  const base = { sessionId, cwd };
+  if (payload.hook_event_name === "PermissionRequest") {
+    const tool = str(payload.tool_name);
+    if (!tool) return null;
+    const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+    return { ...base, args: { event: "request", tool, input, cwd } };
+  }
+  if (payload.hook_event_name === "Notification" && payload.notification_type === "permission_prompt") {
+    return { ...base, args: { event: "prompt", notice: str(payload.message), cwd } };
+  }
+  if (payload.hook_event_name === "PostToolUse" && isQuestion(str(payload.tool_name))) {
+    const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+    const response = payload.tool_response && typeof payload.tool_response === "object" ? payload.tool_response : {};
+    return { ...base, args: { event: "answered", tool: str(payload.tool_name), input, response, cwd } };
+  }
+  return null;
+}
+
+/** Read the hook's JSON from stdin. Gives up quietly: a hook must never hang the agent. */
+export function readStdin(stream = process.stdin, timeoutMs = 3_000) {
+  return new Promise((resolve) => {
+    if (stream.isTTY) return resolve(null);
+    let raw = "";
+    const finish = () => {
+      clearTimeout(timer);
+      try {
+        resolve(raw.trim() ? JSON.parse(raw) : null);
+      } catch {
+        resolve(null);
+      }
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => (raw += chunk));
+    stream.on("end", finish);
+    stream.on("error", finish);
+  });
+}
+
+// ---------------------------------------------------------------- installing into Claude Code
+
+/** ~/.claude/settings.json, or wherever CLAUDE_CONFIG_DIR puts it. */
+export function claudeSettingsPath(env = process.env) {
+  const dir = str(env.CLAUDE_CONFIG_DIR) || path.join(os.homedir(), ".claude");
+  return path.join(dir, "settings.json");
+}
+
+/** The hook command: node, this script, `hook claude`. Exec form, so no shell quoting on any OS. */
+export function claudeHookCommand(script) {
+  return { type: "command", command: "node", args: [script.split(path.sep).join("/"), "hook", "claude"], async: true };
+}
+
+/** One of ours: any copy of roger-roger.mjs run with `hook`, wherever the skill was installed. */
+export function isOurHook(hook) {
+  const args = Array.isArray(hook?.args) ? hook.args.map(String) : [];
+  const i = args.findIndex((a) => /(^|[\\/])roger-roger\.mjs$/.test(a));
+  if (i !== -1 && args[i + 1] === "hook") return true;
+  // A shell-form entry someone wrote by hand, same idea.
+  return typeof hook?.command === "string" && /roger-roger\.mjs["']?\s+hook\b/.test(hook.command);
+}
+
+// PermissionRequest notes every prompt, Notification pings about one, PostToolUse closes it once the
+// user has answered in the terminal — only for questions, so it doesn't run after every tool call.
+const OUR_EVENTS = { PermissionRequest: null, Notification: "permission_prompt", PostToolUse: QUESTION_TOOLS.join("|") };
+
+/** Settings with every roger-roger hook taken out, and empty groups and events tidied away. */
+export function withoutOurHooks(settings) {
+  const next = structuredClone(settings ?? {});
+  if (!next.hooks || typeof next.hooks !== "object") return next;
+  for (const [event, groups] of Object.entries(next.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = groups
+      .map((g) => (Array.isArray(g?.hooks) ? { ...g, hooks: g.hooks.filter((h) => !isOurHook(h)) } : g))
+      .filter((g) => !Array.isArray(g?.hooks) || g.hooks.length);
+    if (kept.length) next.hooks[event] = kept;
+    else delete next.hooks[event];
+  }
+  if (!Object.keys(next.hooks).length) delete next.hooks;
+  return next;
+}
+
+/**
+ * Settings with our hooks in, replacing any older copy of them and leaving everything else be.
+ * Claude Code's by default; Codex's hooks.json has the same layout, with its own events and handler.
+ */
+export function withOurHooks(settings, script, { events = OUR_EVENTS, handler = claudeHookCommand } = {}) {
+  const next = withoutOurHooks(settings);
+  next.hooks ??= {};
+  for (const [event, matcher] of Object.entries(events)) {
+    const group = { ...(matcher ? { matcher } : {}), hooks: [handler(script)] };
+    next.hooks[event] = [...(Array.isArray(next.hooks[event]) ? next.hooks[event] : []), group];
+  }
+  return next;
+}
+
+/** The script a hook of ours runs: its first argument, or the quoted path in a shell command. */
+function scriptOf(hook) {
+  if (Array.isArray(hook?.args) && hook.args[0]) return String(hook.args[0]);
+  const quoted = /(['"])((?:(?!\1).)*roger-roger\.mjs)\1/.exec(String(hook?.command ?? ""));
+  return quoted ? quoted[2].replace(/''/g, "'") : hook?.command ?? null;
+}
+
+/** What is installed: which events have a hook of ours, and which script each one runs. */
+export function ourHooks(settings) {
+  const found = {};
+  for (const [event, groups] of Object.entries(settings?.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      for (const h of Array.isArray(g?.hooks) ? g.hooks : []) {
+        if (isOurHook(h)) found[event] = { matcher: g.matcher ?? null, script: scriptOf(h) };
+      }
+    }
+  }
+  return found;
+}
+
+export function readSettings(file) {
+  if (!fs.existsSync(file)) return {};
+  const raw = fs.readFileSync(file, "utf8");
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    // Never overwrite a file we can't read: it is the user's, and it holds far more than hooks.
+    throw new Error(`${file} is not valid JSON (${e.message}); fix it, then run this again`);
+  }
+}
+
+export function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.roger-roger.bak`);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, file);
+}
+
+export function claudeStatus({ env = process.env, script } = {}) {
+  const file = claudeSettingsPath(env);
+  const found = ourHooks(readSettings(file));
+  const events = Object.keys(OUR_EVENTS);
+  const installed = events.every((e) => found[e]);
+  const scripts = [...new Set(Object.values(found).map((f) => f.script))];
+  return {
+    agent: "claude",
+    settings: file,
+    installed,
+    partial: !installed && events.some((e) => found[e]),
+    hooks: found,
+    ...(scripts.length ? { script: scripts[0], scriptExists: scripts.every((s) => s && fs.existsSync(s)) } : {}),
+    ...(script && scripts.length && scripts.some((s) => path.resolve(s) !== path.resolve(script)) ? { note: "installed from a different copy of the skill; `hooks install` points them at this one" } : {}),
+  };
+}
+
+export function installClaude({ env = process.env, script }) {
+  const file = claudeSettingsPath(env);
+  const before = readSettings(file);
+  const after = withOurHooks(before, script);
+  const changed = JSON.stringify(before) !== JSON.stringify(after);
+  if (changed) writeSettings(file, after);
+  return { ...claudeStatus({ env, script }), changed, ...(changed && fs.existsSync(`${file}.roger-roger.bak`) ? { backup: `${file}.roger-roger.bak` } : {}) };
+}
+
+export function uninstallClaude({ env = process.env } = {}) {
+  const file = claudeSettingsPath(env);
+  const before = readSettings(file);
+  const after = withoutOurHooks(before);
+  const changed = JSON.stringify(before) !== JSON.stringify(after);
+  if (changed) writeSettings(file, after);
+  return { ...claudeStatus({ env }), changed };
+}