@webinson/peer 0.2.0 → 0.2.2

package/README.md

@@ -15,12 +15,13 @@ and the commands `/peer` and `/peer-list` in `~/.claude/commands`.
 In a Claude Code thread:
 
 - `/peer` shares this thread in your workspace.
+- `/peer <message>` shares it and passes the message on to the agent as your prompt.
 - `/peer stop` ends sharing. Ending the session ends it too.
 - `/peer-list` lists the people who share threads, each thread's state and what it works on,
   and the threads that stopped in the last hours.
 
-The three commands are answered by the hook before the prompt reaches the model, so they cost no
-tokens. `peer list` prints the same list in a terminal.
+`/peer`, `/peer stop` and `/peer-list` are answered by the hook before the prompt reaches the model,
+so they cost no tokens. `peer list` prints the same list in a terminal.
 
 ## What is shared
 
@@ -45,8 +46,13 @@ Claude Code hooks are global: they run in every session. `/peer` is caught by th
 `UserPromptSubmit` hook, which writes `~/.peer/sessions/<session_id>`; the hook writes it because
 only the hook knows the session id. After that the hooks report that thread around each turn
 (`UserPromptSubmit`: working, `Stop`: waiting) and `SessionEnd` reports it stopped and removes the
-mark. A hook never fails or holds up a session: it gives the hub 4 seconds and drops what does not
-go through.
+mark. A hook never fails or holds up a session: it gives the hub 3 seconds and drops what does not
+go through. What the hooks did, without any prompt text, is in `~/.peer/hook.log`.
+
+If `/peer` reaches the model ("the hook did not run"), `peer doctor` checks the sign-in, the hooks in
+Claude Code's settings and the paths they run, and runs the hook the way Claude Code does. An app
+or IDE that starts Claude through the Agent SDK may not load `~/.claude/settings.json`; `claude` in
+a terminal does.
 
 - A resumed or forked session can get a new session id. It is then not shared until `/peer` again.
 - Subagents do not appear: the hooks Peer uses fire for the main thread only.
@@ -56,6 +62,7 @@ go through.
 
 ```
 peer status       who you are, the workspace and the threads this computer shares
+peer doctor       why /peer reaches the model instead of Peer's hook
 peer install      set Claude Code up again
 peer uninstall    remove the hooks and commands from Claude Code
 peer logout       forget the sign-in on this computer

package/bin/peer.mjs

@@ -16,7 +16,11 @@ const CLAUDE = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude
 const SELF = fileURLToPath(import.meta.url);
 // Every hook command this CLI installs carries this, so `peer uninstall` finds exactly its own.
 const HOOK_TAG = "peer-hook";
-const HOOK_TIMEOUT_MS = 4000;
+// Claude Code waits this long for a hook; the hub gets a shorter time so a slow hub never hits the limit.
+const HOOK_TIMEOUT_S = 10;
+const HUB_TIMEOUT_MS = 3000;
+// Why a hook did what it did, without any prompt text: `peer doctor` shows the end of it.
+const HOOK_LOG = path.join(HOME, "hook.log");
 
 const HELP = `peer: share chosen agent threads with your team
 
@@ -24,11 +28,13 @@ const HELP = `peer: share chosen agent threads with your team
                     sign in once and set up Claude Code (/peer, /peer stop, /peer-list)
   peer list         people in the workspace, their shared threads and what they work on
   peer status       who you are, the workspace and the threads this computer shares
+  peer doctor       why /peer reaches the model instead of Peer's hook
   peer install      set up Claude Code again (hooks and the two commands)
   peer uninstall    remove them from Claude Code
   peer logout       forget the sign-in on this computer
 
-In Claude Code: /peer shares the thread, /peer stop ends it, /peer-list shows the list.
+In Claude Code: /peer shares the thread (/peer <message> also sends the message on), /peer stop
+ends it, /peer-list shows the list.
 Only threads where /peer was typed are shared, and only their repository, branch and state:
 never prompts, answers or summaries.`;
 
@@ -84,7 +90,9 @@ async function call(saved, method, route, body, timeoutMs = 15000) {
   }
   if (!response.ok) {
     const message = value?.error?.message ?? value?.message ?? value?.error ?? response.statusText;
-    throw new Error(`${method} ${route}: ${response.status} ${typeof message === "string" ? message : JSON.stringify(message)}`);
+    throw Object.assign(new Error(`${method} ${route}: ${response.status} ${typeof message === "string" ? message : JSON.stringify(message)}`), {
+      status: response.status,
+    });
   }
   return value;
 }
@@ -110,7 +118,7 @@ function workingOn(cwd) {
 }
 
 async function report(saved, session, state, cwd) {
-  await call(saved, "PUT", `/workspaces/${saved.workspace}/agents/${session}`, { agent: "claude-code", state, ...workingOn(cwd) }, HOOK_TIMEOUT_MS - 500);
+  await call(saved, "PUT", `/workspaces/${saved.workspace}/agents/${session}`, { agent: "claude-code", state, ...workingOn(cwd) }, HUB_TIMEOUT_MS);
 }
 
 // ---- the list ----
@@ -172,7 +180,18 @@ async function readStdin() {
 
 // A hook answers Claude Code with JSON on stdout; `block` keeps the prompt from reaching the model.
 const answer = (value) => process.stdout.write(`${JSON.stringify(value)}\n`);
-const block = (reason) => answer({ decision: "block", reason });
+const block = (reason) => {
+  log(`answered ${reason.split("\n")[0].slice(0, 80)}`);
+  answer({ decision: "block", reason });
+};
+
+function log(line) {
+  try {
+    fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
+    if (fs.existsSync(HOOK_LOG) && fs.statSync(HOOK_LOG).size > 64 * 1024) fs.renameSync(HOOK_LOG, `${HOOK_LOG}.1`);
+    fs.appendFileSync(HOOK_LOG, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+  } catch {}
+}
 
 async function hook(event) {
   const input = await readStdin();
@@ -183,7 +202,8 @@ async function hook(event) {
 
   if (event === "prompt") {
     const prompt = String(input.prompt ?? "").trim();
-    const command = /^\/peer(?:\s+(\S+))?\s*$/.exec(prompt);
+    const command = /^\/peer(?:\s+([\s\S]*))?$/.exec(prompt);
+    const argument = command?.[1]?.trim() ?? "";
     if (prompt === "/peer-list") {
       let saved;
       try {
@@ -200,22 +220,23 @@ async function hook(event) {
       } catch (error) {
         return block(`Peer: ${error.message}`);
       }
-      if (command[1] === "stop") {
+      if (argument === "stop") {
         fs.rmSync(marker, { force: true });
         if (!shared) return block("Peer: this thread was not shared.");
         await report(saved, session, "stopped", input.cwd).catch(() => {});
         return block("Peer: this thread is no longer shared.");
       }
-      if (command[1]) return block("Peer: use /peer to share this thread, /peer stop to end it, /peer-list for the list.");
+      // `/peer <message>` shares the thread and lets the message through: the command hands it to the model.
       writeJson(marker, { workspace: saved.workspace, sharedAt: new Date().toISOString() });
       const where = workingOn(input.cwd);
-      try {
-        await report(saved, session, "idle", input.cwd);
-      } catch (error) {
-        return block(`Peer: shared, but the hub did not answer yet (${error.message}). The next turn tries again.`);
-      }
       const what = [where.repository, where.branch].filter(Boolean).join(" @ ");
-      return block(`Peer: this thread is shared in ${saved.workspace}${what ? ` as ${what}` : ""}. Teammates see its repository, branch and state, nothing of the conversation. /peer stop ends it.`);
+      const sharedText = `Peer: this thread is shared in ${saved.workspace}${what ? ` as ${what}` : ""}. Teammates see its repository, branch and state, nothing of the conversation. /peer stop ends it.`;
+      let hubError;
+      await report(saved, session, argument ? "working" : "idle", input.cwd).catch((error) => (hubError = error));
+      const said = hubError ? `Peer: shared, but the hub did not answer yet (${hubError.message}). The next turn tries again.` : sharedText;
+      if (!argument) return block(said);
+      log("answered /peer with a message: shared, message passed on");
+      return answer({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: `${SHARED_NOTE}\n${said}` } });
     }
     if (shared) await reportQuietly(session, "working", input.cwd);
     return;
@@ -241,20 +262,25 @@ async function reportQuietly(session, state, cwd) {
 const SETTINGS = path.join(CLAUDE, "settings.json");
 const COMMANDS = path.join(CLAUDE, "commands");
 
+// The hook's note to the model when `/peer <message>` shares a thread; peer.md looks for it.
+const SHARED_NOTE = "[Peer's hook ran]";
+
 const COMMAND_FILES = {
   "peer.md": `---
-description: Share this thread on Peer (/peer), or stop sharing it (/peer stop)
-argument-hint: "[stop]"
+description: Share this thread on Peer (/peer), share it and go on (/peer <message>), or stop sharing it (/peer stop)
+argument-hint: "[message | stop]"
 ---
-Peer's hook handles this command before it reaches you, so you should not be reading it. If you are,
-the hook did not run: tell the person to run \`peer install\` in a terminal and open a new session.
-Do nothing else.
+$ARGUMENTS
+
+(From Peer, not from the person: if a note from Peer's hook, starting with ${SHARED_NOTE}, says this thread is now
+shared, say so in one short line, then treat the text above as the person's message. If there is no such note, the
+hook did not run or did not answer in time: tell the person to run \`peer doctor\` in a terminal, which says why.)
 `,
   "peer-list.md": `---
 description: List the people in your Peer workspace and the agent threads they share
 ---
 Peer's hook answers this command before it reaches you, so you should not be reading it. If you are,
-the hook did not run: tell the person to run \`peer install\` in a terminal and open a new session.
+the hook did not run or did not answer in time: tell the person to run \`peer doctor\` in a terminal, which says why.
 Do nothing else.
 `,
 };
@@ -285,7 +311,7 @@ function install() {
   settings.hooks ??= {};
   for (const [event, name] of [["UserPromptSubmit", "prompt"], ["Stop", "stop"], ["SessionEnd", "end"]]) {
     settings.hooks[event] ??= [];
-    settings.hooks[event].push({ hooks: [{ type: "command", command: hookCommand(name), timeout: HOOK_TIMEOUT_MS / 1000 }] });
+    settings.hooks[event].push({ hooks: [{ type: "command", command: hookCommand(name), timeout: HOOK_TIMEOUT_S }] });
   }
   writeJson(SETTINGS, settings, 0o644);
   fs.mkdirSync(COMMANDS, { recursive: true });
@@ -317,8 +343,13 @@ async function login(args) {
   const ask = readline.createInterface({ input: process.stdin, output: process.stderr });
   try {
     const email = args[0] ?? (await ask.question("Your work email: ")).trim();
-    const started = await call({ hub }, "POST", "/auth/email/start", { email });
-    const code = started.code ?? (await ask.question(`Code from the email to ${started.email}: `)).trim();
+    // A code sent a moment ago still holds: the hub then sends no new one, and the last email's code is asked for.
+    const started = await call({ hub }, "POST", "/auth/email/start", { email }).catch((error) => {
+      if (error.status !== 429) throw error;
+      return { email, sent: false };
+    });
+    const which = started.sent === false ? "the last email" : "the email";
+    const code = started.code ?? (await ask.question(`Code from ${which} to ${started.email}: `)).trim();
     const finished = await call({ hub }, "POST", "/auth/email/verify", { email: started.email, code });
     const saved = { hub, email: finished.email ?? started.email, session: finished.session };
     const me = await call(saved, "GET", "/me");
@@ -360,6 +391,89 @@ function status() {
   console.log(shared.length ? `Threads shared from this computer: ${shared.join(", ")}` : "No thread shared from this computer.");
 }
 
+// ---- peer doctor: why /peer reaches the model instead of the hook ----
+
+async function doctor() {
+  let problems = 0;
+  const ok = (text) => console.log(`  ok    ${text}`);
+  const bad = (text) => {
+    problems += 1;
+    console.log(`  FIX   ${text}`);
+  };
+  console.log(`peer ${readJson(path.join(path.dirname(SELF), "..", "package.json"))?.version ?? "?"} at ${SELF}, node ${process.version}`);
+
+  const saved = config();
+  if (!saved?.session || !saved?.workspace) bad("not signed in: run `peer login`");
+  else {
+    try {
+      const me = await call(saved, "GET", "/me", undefined, HUB_TIMEOUT_MS);
+      if ((me.workspaces ?? []).some((w) => w.slug === saved.workspace)) ok(`signed in to ${saved.hub} as ${saved.email}, workspace ${saved.workspace}`);
+      else bad(`workspace ${saved.workspace} does not list ${saved.email} (removed, or the workspace is gone): run \`peer login\``);
+    } catch (error) {
+      bad(`the hub does not accept the sign-in or does not answer (${error.message}): run \`peer login\``);
+    }
+  }
+
+  try {
+    const version = execFileSync("claude", ["--version"], { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    ok(`Claude Code ${version} (Peer is tested with 2.1.316)`);
+  } catch {
+    console.log("  ?     `claude` is not on this terminal's PATH, so its version is unknown");
+  }
+
+  const settings = readJson(SETTINGS);
+  const ours = [];
+  for (const [event, groups] of Object.entries(settings?.hooks ?? {})) {
+    for (const group of groups) for (const h of group.hooks ?? []) if (String(h.command ?? "").includes(HOOK_TAG)) ours.push({ event, ...h });
+  }
+  const events = ["UserPromptSubmit", "Stop", "SessionEnd"];
+  const missing = events.filter((e) => !ours.some((h) => h.event === e));
+  if (!settings) bad(`no ${SETTINGS}: run \`peer install\``);
+  else if (missing.length) bad(`${SETTINGS} lacks Peer's ${missing.join(", ")} hook: run \`peer install\``);
+  else ok(`hooks in ${SETTINGS}`);
+  for (const h of ours) {
+    const paths = [...String(h.command).matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+    const gone = paths.filter((p) => !fs.existsSync(p));
+    if (gone.length) bad(`the ${h.event} hook runs ${gone.join(" and ")}, which no longer exists: run \`peer install\` again`);
+  }
+  for (const file of [SETTINGS, path.join(CLAUDE, "settings.local.json"), "/Library/Application Support/ClaudeCode/managed-settings.json", "/etc/claude-code/managed-settings.json"]) {
+    const read = readJson(file);
+    if (read?.disableAllHooks) bad(`${file} sets disableAllHooks: Claude Code runs no hooks at all`);
+    if (read?.allowManagedHooksOnly) bad(`${file} sets allowManagedHooksOnly: only an administrator's hooks run`);
+  }
+  if (process.env.CLAUDE_CONFIG_DIR) console.log(`  note  CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR}: Claude Code must run with the same value`);
+  const commands = Object.keys(COMMAND_FILES).filter((name) => fs.existsSync(path.join(COMMANDS, name)));
+  if (commands.length === Object.keys(COMMAND_FILES).length) ok(`/peer and /peer-list in ${COMMANDS}`);
+  else bad(`commands missing in ${COMMANDS}: run \`peer install\``);
+
+  // The hook Claude Code would run, run here: a /peer-list must come back answered within Claude's limit.
+  const prompt = ours.find((h) => h.event === "UserPromptSubmit");
+  if (prompt) {
+    const started = Date.now();
+    try {
+      const out = execFileSync("/bin/sh", ["-c", prompt.command], {
+        encoding: "utf8",
+        timeout: HOOK_TIMEOUT_S * 1000,
+        input: JSON.stringify({ session_id: "peer-doctor", cwd: process.cwd(), hook_event_name: "UserPromptSubmit", prompt: "/peer-list" }),
+      });
+      const took = Date.now() - started;
+      if (JSON.parse(out || "{}").decision === "block") ok(`the hook answers /peer-list in ${took} ms (Claude Code waits ${HOOK_TIMEOUT_S} s)`);
+      else bad(`the hook ran but did not answer /peer-list: ${out.slice(0, 200)}`);
+    } catch (error) {
+      bad(`the hook failed when run as Claude Code runs it (${Date.now() - started} ms): ${String(error.stderr || error.message).split("\n")[0]}`);
+    }
+  }
+
+  const lines = fs.existsSync(HOOK_LOG) ? fs.readFileSync(HOOK_LOG, "utf8").trim().split("\n").slice(-5) : [];
+  if (lines.length) console.log(`\nLast hook runs (${HOOK_LOG}):\n${lines.map((l) => `  ${l}`).join("\n")}`);
+  console.log(
+    problems
+      ? `\n${problems} thing(s) to fix. Then start a new Claude Code session.`
+      : "\nPeer is set up here. If /peer still reaches the model, Claude Code is not loading your user settings: an app or IDE that runs Claude through the Agent SDK may ignore ~/.claude/settings.json. Start `claude` in a terminal and try /peer there.",
+  );
+  if (problems) process.exitCode = 1;
+}
+
 // ---- main ----
 
 const [command, ...args] = process.argv.slice(2);
@@ -377,6 +491,9 @@ try {
     case "status":
       status();
       break;
+    case "doctor":
+      await doctor();
+      break;
     case "install":
       signedIn();
       install();
@@ -386,7 +503,7 @@ try {
       break;
     case "hook":
       // A hook never breaks the person's session: whatever goes wrong, it exits 0.
-      await hook(args[0]).catch(() => {});
+      await hook(args[0]).catch((error) => log(`hook ${args[0]} failed: ${error?.message ?? error}`));
       break;
     case undefined:
     case "help":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webinson/peer",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Share chosen Claude Code threads with your team: who has agents running and on what.",
   "license": "MIT",
   "type": "module",