carmoji 0.3.4 → 0.3.6

package/README.md

@@ -46,18 +46,18 @@ approval.
 
 ## Claude Code
 
-Coding in *this* repo works out of the box — the hooks ship in
-[.claude/settings.json](../.claude/settings.json). To get reactions in
-every project:
+To get reactions in every project:
 
 ```sh
-npx carmoji install-claude
+npx carmoji install claude
 ```
 
 merges the hooks into `~/.claude/settings.json`, preserving everything
 already there (a backup is saved to `settings.json.bak` first, reruns are
 no-ops, and a file that doesn't parse is refused untouched). Prefer to do
-it by hand? `npx carmoji claude-config` prints the snippet instead.
+it by hand? `npx carmoji config claude` prints the snippet instead. Every
+command answers `--help`; `npx carmoji hook --help` documents the JSON the
+hook accepts, and `npx carmoji uninstall <tool>|all` takes it all out again.
 
 ## All the other tools
 
@@ -111,6 +111,7 @@ npx carmoji test start       # wakes up, excited
 npx carmoji test edit        # focused typing face
 npx carmoji test run         # nervous side-eye
 npx carmoji test permission  # pleading + floating "?"
+npx carmoji test approval    # Allow/Deny card; waits and prints your tap
 npx carmoji test done        # celebration with hearts
 npx carmoji test error       # dizzy collapse
 npx carmoji test end         # contented sigh
@@ -152,22 +153,31 @@ cache-write tokens; cache reads excluded). It's your real consumption, not
 an official percentage of plan quota — there's no public API for that.
 Recomputed at turn boundaries with a 5-minute cache so hooks stay fast.
 
-## Answer permissions from the phone (Claude Code, opt-in)
-
-```sh
-npx carmoji gate-config
-```
-
-prints a `PreToolUse` hook snippet with a tool matcher (e.g. `Bash`). With
-it installed, whenever Claude wants to run a matched tool the phone chimes
-(a doorbell sound used by nothing else), shows big pleading eyes, and pops
-an **Allow / Deny** card with the command text — your tap settles the
-permission on the computer via the hook's official decision output. No
-answer within ~55 s falls through to the normal terminal prompt.
-
-Honest limits: this decides *tool permissions* only — hooks expose no way
-to answer AskUserQuestion option pickers — and the Codex integration currently
-treats `PermissionRequest` as display-only.
+## Answer permissions from the phone (Claude Code)
+
+`carmoji install claude` hooks Claude Code's `PermissionRequest` event,
+which fires **only when a permission dialog is about to appear** —
+allowlisted tools and auto-accepted edits never trigger it, so nothing
+ever slows down a call that would have run anyway. When it fires, the
+phone chimes (a doorbell sound used by nothing else), shows big pleading
+eyes, and pops an **Allow / Deny** card with the command text — your tap
+settles the prompt on the computer via the hook's official decision
+output. No answer within ~55 s falls through to the normal terminal
+prompt (`npx carmoji test approval` exercises the whole loop).
+
+Simple **AskUserQuestion** pickers ride the same hook: one single-select
+question with 2–4 labeled options becomes a tappable option card on the
+phone (`npx carmoji test question` demos it), and your pick is fed back
+as the answer. Richer questions — several at once, multi-select, free
+text — still show as a pleading toast and are answered in the terminal.
+
+Honest limits: the Codex integration currently treats `PermissionRequest`
+as display-only (answering from the phone is planned next).
+
+Older Claude Code versions without the `PermissionRequest` hook can use
+`npx carmoji config gate` instead: a legacy `PreToolUse` gate with a tool
+matcher (e.g. `Bash`). Unlike `PermissionRequest`, that variant fires on
+*every* matched call, allowlisted or not, so keep its matcher narrow.
 
 ## How it works
 

package/carmoji.js

@@ -9,15 +9,18 @@
 //                    whose Code Buddy sheet shows <code>
 //                    (pairing is additive — events fan out to every device)
 //   unpair [device]  forget a paired device by name or ip[:port], or `all`
-//   install <tool>   install hooks for a tool (or `all`); see `tools`
-//   uninstall <tool> remove CarMoji hooks from a tool's config
+//   install <tool>|all    install hooks for a tool (or every detected one)
+//   uninstall <tool>|all  remove CarMoji hooks from a tool's config
 //   tools            list supported tools and where their hooks live
 //   hook             hook entry point, all tools (reads hook JSON on stdin;
 //                    --source <tool>, --event <name>, --gate)
 //   codex-notify     legacy Codex notify entry point (event JSON as last arg)
-//   test <name>      send a test event: start|prompt|edit|read|run|heartbeat|done|error|permission|end
-//   claude-config    print the .claude/settings.json hooks snippet
-//   codex-config     print the ~/.codex/config.toml notify line (legacy)
+//   test <name>      send a test event; `test approval` pops the Allow/Deny card
+//   config <what>    print a manual config snippet: claude | codex | gate
+//
+// Every command answers --help; `carmoji hook --help` documents the stdin
+// JSON it accepts. Old command spellings (install-claude, claude-config, …)
+// keep working as hidden aliases because shipped app versions print them.
 
 import {
   readFileSync, writeFileSync, mkdirSync,
@@ -219,16 +222,21 @@ async function send(config, message) {
 }
 
 /**
- * Send an approval_request and hold the connection open until the phone
- * answers (or the timeout passes). Resolves "allow", "deny", or null.
+ * Send a blocking card and hold the connection open until the phone
+ * answers (or the timeout passes). Resolves the phone's reply frame —
+ * `{decision:"allow"|"deny"}` for approval cards, `{answer:"<label>"}`
+ * for question cards — or null. `requireCap` names a capability the
+ * phone's ack must advertise; an ack without it resolves null right
+ * away so older app builds fall back to the display-only path instead
+ * of blocking the agent for nothing.
  */
-async function requestApproval(config, message, timeoutMs = 55_000) {
+async function requestApproval(config, message, timeoutMs = 55_000, requireCap) {
   const { default: WebSocket } = await import('ws');
   return new Promise((resolve) => {
     const ws = new WebSocket(`ws://${config.host}:${config.port}`, {
       handshakeTimeout: SEND_TIMEOUT_MS,
     });
-    const timer = setTimeout(() => finish(null), timeoutMs);
+    let timer = setTimeout(() => finish(null), timeoutMs);
     ws.on('open', () => {
       ws.send(JSON.stringify({ v: 1, code: config.code, ...message }));
     });
@@ -236,8 +244,20 @@ async function requestApproval(config, message, timeoutMs = 55_000) {
       try {
         const reply = JSON.parse(data.toString());
         if (reply.ok === false) return finish(null);
-        if (reply.decision === 'allow' || reply.decision === 'deny') {
-          finish(reply.decision);
+        if (reply.decision === 'allow' || reply.decision === 'deny'
+            || typeof reply.answer === 'string') {
+          return finish(reply);
+        }
+        if (reply.hold === true) {
+          // The human is typing a free-form answer — give them longer
+          // before falling through to the terminal.
+          clearTimeout(timer);
+          timer = setTimeout(() => finish(null), HOLD_WAIT_MS);
+          return;
+        }
+        if (reply.ok === true && requireCap
+            && !(Array.isArray(reply.caps) && reply.caps.includes(requireCap))) {
+          return finish(null);
         }
         // A plain ack means the card is up — keep waiting for the tap.
       } catch { /* ignore unparsable frames */ }
@@ -259,26 +279,58 @@ function sendAll(devices, message) {
 }
 
 /**
- * Show the approval card on every paired phone; the first tap anywhere
- * wins. The other phones' cards drop when this process exits and their
- * sockets close. Resolves null when nobody answers in time.
+ * Show the approval/question card on every paired phone; the first tap
+ * anywhere wins. The other phones' cards drop when this process exits and
+ * their sockets close. Resolves null when nobody answers in time.
  */
-function requestApprovalAll(devices, message, timeoutMs) {
+function requestApprovalAll(devices, message, timeoutMs, requireCap) {
   if (devices.length === 0) return Promise.resolve(null);
   return new Promise((resolve) => {
     let pending = devices.length;
     for (const device of devices) {
-      requestApproval(device, message, timeoutMs).then((decision) => {
+      requestApproval(device, message, timeoutMs, requireCap).then((reply) => {
         pending -= 1;
-        if (decision || pending === 0) resolve(decision);
+        if (reply || pending === 0) resolve(reply);
       });
     }
   });
 }
 
+/**
+ * The one AskUserQuestion shape the phone can answer (MVP): a single
+ * single-select question whose 2–4 options all have labels. Anything
+ * richer — several questions, multiSelect, free-form — returns null and
+ * stays display-only, answered in the terminal.
+ */
+function answerableQuestion(input) {
+  const questions = input?.questions;
+  if (!Array.isArray(questions) || questions.length !== 1) return null;
+  const [entry] = questions;
+  if (!entry || entry.multiSelect === true) return null;
+  if (typeof entry.question !== 'string' || !entry.question.trim()) return null;
+  const raw = Array.isArray(entry.options) ? entry.options : [];
+  if (raw.length < 2 || raw.length > 4) return null;
+  const options = [];
+  for (const option of raw) {
+    const label = typeof option === 'string' ? option : option?.label;
+    if (typeof label !== 'string' || !label.trim()) return null;
+    const description = typeof option?.description === 'string'
+      ? option.description.replace(/\s+/g, ' ').slice(0, 200)
+      : undefined;
+    options.push({ label, description });
+  }
+  return {
+    question: entry.question,
+    header: typeof entry.header === 'string' && entry.header.trim()
+      ? entry.header : undefined,
+    options,
+  };
+}
+
 function summarizeToolInput(payload) {
   const input = payload.tool_input || {};
   const text = input.command || input.file_path || input.description
+    || input.questions?.[0]?.question
     || JSON.stringify(input);
   return String(text).replace(/\s+/g, ' ').slice(0, 140);
 }
@@ -548,7 +600,23 @@ function backupFile(path) {
 }
 
 const CLAUDE_HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse',
-                            'PostToolUse', 'Notification', 'Stop', 'SessionEnd'];
+                            'PermissionRequest', 'PostToolUse', 'Notification',
+                            'Stop', 'SessionEnd'];
+
+// PermissionRequest fires only when a permission dialog is about to appear,
+// and the dialog waits for the hook — so the phone gets a bounded window to
+// answer, then silence falls through to the normal terminal prompt. Tapping
+// "Other…" on a question card sends {hold:true}, stretching that window to
+// HOLD_WAIT_MS so there's time to type. The installed hook timeout leaves
+// headroom over the longest wait.
+const APPROVAL_WAIT_MS = 55_000;
+const HOLD_WAIT_MS = 120_000;
+const PERMISSION_HOOK_TIMEOUT_S = 150;
+
+/** Sources whose PermissionRequest hook accepts a decision back via
+ *  `hookSpecificOutput.decision` (Claude Code's schema). Codex is the next
+ *  candidate once its hooks are verified to honor the reply. */
+const ANSWERABLE_PERMISSION_SOURCES = new Set(['claude']);
 
 // ---------------------------------------------------------------------------
 // Multi-tool hook installers (see EVENT_ALIASES for how their events map).
@@ -676,21 +744,25 @@ function installJsonHooks(key, tool) {
   for (const event of tool.events ?? CLAUDE_HOOK_EVENTS) {
     const entries = Array.isArray(hooks[event]) ? hooks[event] : [];
     const command = tool.eventFlag ? `${base} --event ${event}` : base;
+    // PermissionRequest blocks while the phone shows Allow/Deny; everything
+    // else must stay too quick to ever be felt in the session.
+    const seconds = timeout(event === 'PermissionRequest'
+      ? PERMISSION_HOOK_TIMEOUT_S : 5);
     switch (tool.format) {
       case 'claude':
         entries.push({ matcher: '*',
-                       hooks: [{ type: 'command', command, timeout: timeout(5) }] });
+                       hooks: [{ type: 'command', command, timeout: seconds }] });
         break;
       case 'codex':
       case 'nested':
-        entries.push({ hooks: [{ type: 'command', command, timeout: timeout(5) }] });
+        entries.push({ hooks: [{ type: 'command', command, timeout: seconds }] });
         break;
       case 'flat':
         entries.push({ command });
         break;
       case 'trae':
         entries.push({ matcher: '*', loop_limit: 5,
-                       hooks: [{ type: 'command', command, timeout: timeout(5) }] });
+                       hooks: [{ type: 'command', command, timeout: seconds }] });
         break;
       case 'copilot':
         entries.push({ type: 'command', bash: command, timeoutSec: 5 });
@@ -883,14 +955,20 @@ function installTool(key, { skipMissing = false } = {}) {
   installJsonHooks(key, tool);
 }
 
-function uninstallTool(key) {
+function uninstallTool(key, { skipMissing = false } = {}) {
   const tool = TOOLS[key];
   if (!tool) {
     console.error(`Unknown tool "${key}". Known: ${Object.keys(TOOLS).join(', ')}`);
     process.exit(1);
   }
+  // `uninstall all` sweeps every known tool; stay quiet about the ones that
+  // were never installed instead of printing 14 "nothing installed" lines.
+  const nothing = () => {
+    if (!skipMissing) console.log(`${tool.name}: nothing installed.`);
+  };
   if (tool.format === 'cline') {
     const dir = join(homedir(), tool.config);
+    if (!existsSync(dir)) { nothing(); return; }
     for (const event of tool.events) {
       const path = join(dir, event);
       if (existsSync(path) && readFileSync(path, 'utf8').includes('carmoji')) {
@@ -902,15 +980,20 @@ function uninstallTool(key) {
   }
   if (tool.format === 'kimi') {
     const path = join(homedir(), tool.config);
-    if (existsSync(path)) {
-      writeConfig(path, removeKimiBlocks(readFileSync(path, 'utf8')) + '\n');
+    if (!existsSync(path) || !readFileSync(path, 'utf8').includes('carmoji')) {
+      nothing();
+      return;
     }
+    writeConfig(path, removeKimiBlocks(readFileSync(path, 'utf8')) + '\n');
     console.log(`Removed CarMoji hooks for ${tool.name}.`);
     return;
   }
   const path = key === 'codex' ? join(codexHome(), 'hooks.json')
     : join(homedir(), tool.config);
-  if (!existsSync(path)) { console.log(`${tool.name}: nothing installed.`); return; }
+  if (!existsSync(path) || !readFileSync(path, 'utf8').includes('carmoji')) {
+    nothing();
+    return;
+  }
   const root = readJsonConfig(path);
   if (root.hooks && typeof root.hooks === 'object') {
     for (const [event, value] of Object.entries(root.hooks)) {
@@ -967,11 +1050,10 @@ function installCodexNotify() {
 }
 
 function claudeConfigSnippet() {
-  const entry = [{ hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 5 }] }];
   const hooks = {};
-  for (const name of ['SessionStart', 'UserPromptSubmit', 'PreToolUse',
-                      'PostToolUse', 'Notification', 'Stop', 'SessionEnd']) {
-    hooks[name] = entry;
+  for (const name of CLAUDE_HOOK_EVENTS) {
+    const timeout = name === 'PermissionRequest' ? PERMISSION_HOOK_TIMEOUT_S : 5;
+    hooks[name] = [{ hooks: [{ type: 'command', command: HOOK_COMMAND, timeout }] }];
   }
   return JSON.stringify({ hooks }, null, 2);
 }
@@ -979,6 +1061,17 @@ function claudeConfigSnippet() {
 async function main() {
   const [command, arg, ...rest] = process.argv.slice(2);
 
+  // `carmoji help [command]`, `carmoji --help`, or `--help` anywhere.
+  // Real agent hooks never pass --help, so this can't shadow the hook path.
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp(arg);
+    return;
+  }
+  if (arg === '--help' || rest.includes('--help')) {
+    printHelp(command);
+    return;
+  }
+
   switch (command) {
     case 'pair': {
       if (!/^\d{4}$/.test(arg || '')) {
@@ -1100,7 +1193,11 @@ async function main() {
 
     case 'hook': {
       // Runs inside the coding agent on every hook — must be silent, quick,
-      // and always exit 0 so it can never disturb the session.
+      // and always exit 0 so it can never disturb the session. The two
+      // deliberate exceptions hold the hook open while the phone answers:
+      // PermissionRequest (fires only when a permission dialog was about to
+      // block the session anyway) and the legacy --gate (blocks every
+      // matched PreToolUse).
       // Flags: --source <tool> (default claude), --event <name> for tools
       // whose stdin lacks the event name, --gate for phone approvals.
       try {
@@ -1119,14 +1216,14 @@ async function main() {
         // the phone shows Allow/Deny; the printed JSON settles the
         // permission. Timeout falls through to the normal terminal prompt.
         if (flags.includes('--gate') && payload.hook_event_name === 'PreToolUse') {
-          const decision = await requestApprovalAll(devices, {
+          const decision = (await requestApprovalAll(devices, {
             source,
             session: payload.session_id,
             event: 'approval_request',
             tool: payload.tool_name,
             detail: summarizeToolInput(payload),
             project: payload.cwd ? basename(payload.cwd) : undefined,
-          });
+          }))?.decision;
           if (decision) {
             console.log(JSON.stringify({
               hookSpecificOutput: {
@@ -1141,6 +1238,79 @@ async function main() {
           break;
         }
 
+        // PermissionRequest fires only when a permission dialog is about to
+        // appear (allowlisted tools never trigger it), so blocking here —
+        // unlike the PreToolUse gate — never delays a call that would have
+        // run anyway. A phone tap settles the prompt; silence falls through
+        // to the terminal dialog.
+        const canonicalEvent = EVENT_ALIASES[payload.hook_event_name]
+          ?? payload.hook_event_name;
+        if (canonicalEvent === 'PermissionRequest'
+            && ANSWERABLE_PERMISSION_SOURCES.has(source)) {
+          const common = {
+            source,
+            session: payload.session_id,
+            host: hostname(),
+            project: payload.cwd ? basename(payload.cwd) : undefined,
+          };
+
+          // AskUserQuestion rides the same hook: simple option pickers get
+          // a tappable card; the tapped label is fed back through
+          // updatedInput.answers, keyed by the QUESTION TEXT (Claude Code
+          // looks answers up by it — keying by header yields empty answers)
+          // with the original `questions` kept in place (Claude Code crashes
+          // on its absence). Richer shapes fall through to display-only.
+          if (payload.tool_name === 'AskUserQuestion') {
+            const question = answerableQuestion(payload.tool_input);
+            if (question) {
+              const reply = await requestApprovalAll(devices, {
+                ...common,
+                event: 'question_request',
+                tool: payload.tool_name,
+                detail: question.question.replace(/\s+/g, ' ').slice(0, 140),
+                question,
+              }, APPROVAL_WAIT_MS, 'question');
+              // Either a tapped option label or free text typed behind the
+              // card's "Other…" button — Claude Code takes any string, the
+              // same way its own picker's Other row does.
+              const answer = reply?.answer?.trim();
+              if (answer) {
+                console.log(JSON.stringify({
+                  hookSpecificOutput: {
+                    hookEventName: 'PermissionRequest',
+                    decision: {
+                      behavior: 'allow',
+                      updatedInput: {
+                        ...payload.tool_input,
+                        answers: { [question.question]: answer },
+                      },
+                    },
+                  },
+                }));
+                break;
+              }
+            }
+            // No card, no tap, or an unknown label: fall through to the
+            // pleading face + toast; the picker stays in the terminal.
+          } else {
+            const decision = (await requestApprovalAll(devices, {
+              ...common,
+              event: 'approval_request',
+              tool: payload.tool_name,
+              detail: summarizeToolInput(payload),
+            }, APPROVAL_WAIT_MS))?.decision;
+            if (decision) {
+              console.log(JSON.stringify({
+                hookSpecificOutput: {
+                  hookEventName: 'PermissionRequest',
+                  decision: { behavior: decision },
+                },
+              }));
+            }
+            break;
+          }
+        }
+
         const event = eventFromHook(payload);
         if (!event) break;
         // host lets the phone attribute plan-window usage per machine and
@@ -1197,8 +1367,8 @@ async function main() {
 
     case 'test': {
       const event = TEST_EVENTS[arg];
-      if (!event) {
-        console.error(`Usage: carmoji test <${Object.keys(TEST_EVENTS).join('|')}> [session] [tokens]`);
+      if (!event && arg !== 'approval' && arg !== 'question') {
+        console.error(`Usage: carmoji test <${Object.keys(TEST_EVENTS).join('|')}|approval|question> [session] [tokens] [project] — details: carmoji test --help`);
         process.exit(1);
       }
       const devices = loadDevices();
@@ -1206,6 +1376,47 @@ async function main() {
         console.error('Not paired yet — run: carmoji pair <code>');
         process.exit(1);
       }
+      if (arg === 'approval') {
+        // Exercises the blocking PermissionRequest flow end to end.
+        console.log(`Approval card sent — tap Allow or Deny on the phone (${APPROVAL_WAIT_MS / 1000}s)…`);
+        const decision = (await requestApprovalAll(devices, {
+          source: 'test',
+          session: rest[0],
+          host: hostname(),
+          event: 'approval_request',
+          tool: 'Bash',
+          detail: 'carmoji test approval — tap Allow or Deny',
+        }, APPROVAL_WAIT_MS))?.decision;
+        console.log(decision
+          ? `Decision: ${decision}`
+          : 'No answer — in a real session Claude Code would fall through to the terminal prompt.');
+        process.exit(decision ? 0 : 1);
+      }
+      if (arg === 'question') {
+        // Exercises the blocking AskUserQuestion flow end to end.
+        console.log(`Question card sent — tap an option on the phone (${APPROVAL_WAIT_MS / 1000}s)…`);
+        const answer = (await requestApprovalAll(devices, {
+          source: 'test',
+          session: rest[0],
+          host: hostname(),
+          event: 'question_request',
+          tool: 'AskUserQuestion',
+          detail: 'Which flavor should the demo pick?',
+          question: {
+            question: 'Which flavor should the demo pick?',
+            header: 'Flavor',
+            options: [
+              { label: 'Vanilla', description: 'The safe default' },
+              { label: 'Matcha', description: 'A little adventurous' },
+              { label: 'Durian', description: 'You know what you did' },
+            ],
+          },
+        }, APPROVAL_WAIT_MS, 'question'))?.answer;
+        console.log(answer
+          ? `Answer: ${answer}`
+          : 'No answer — in a real session the picker would stay in the terminal.');
+        process.exit(answer ? 0 : 1);
+      }
       const [session, tokens, project] = rest;
       const message = { source: 'test', session, host: hostname(), ...event };
       if (tokens !== undefined) message.tokens = Number(tokens);
@@ -1248,8 +1459,14 @@ async function main() {
     }
 
     case 'uninstall': {
+      if (arg === 'all') {
+        for (const key of Object.keys(TOOLS)) {
+          uninstallTool(key, { skipMissing: true });
+        }
+        break;
+      }
       if (!arg) {
-        console.log(`Usage: carmoji uninstall <tool>\nTools: ${Object.keys(TOOLS).join(', ')}`);
+        console.log(`Usage: carmoji uninstall <tool>|all\nTools: ${Object.keys(TOOLS).join(', ')}`);
         process.exit(1);
       }
       uninstallTool(arg);
@@ -1266,50 +1483,197 @@ async function main() {
       break;
     }
 
-    case 'install-claude':
-      installClaude();
-      break;
-
-    case 'install-codex':
-      installCodexHooks();
+    case 'config':
+      if (arg === 'claude') printClaudeConfig();
+      else if (arg === 'codex') printCodexConfig();
+      else if (arg === 'gate') printGateConfig();
+      else printHelp('config');
       break;
 
     case 'install-codex-notify':
       installCodexNotify();
       break;
 
+    // Hidden back-compat aliases — the app's setup sheet and old READMEs
+    // print these spellings, so they must keep working.
+    case 'install-claude':
+      installTool('claude');
+      break;
+    case 'install-codex':
+      installTool('codex');
+      break;
     case 'claude-config':
-      console.log('Merge this into the project’s .claude/settings.json (or ~/.claude/settings.json for everywhere):\n');
-      console.log('(Or let `carmoji install-claude` do it for you, with a backup.)\n');
-      console.log(claudeConfigSnippet());
+      printClaudeConfig();
       break;
-
     case 'codex-config':
-      console.log('Modern Codex reads hooks from $CODEX_HOME/hooks.json — prefer:');
-      console.log('  carmoji install codex\n');
-      console.log('For older Codex versions, add this line to ~/.codex/config.toml:\n');
-      console.log(RUNNING_FROM_PACKAGE
-        ? 'notify = ["npx", "-y", "carmoji", "codex-notify"]'
-        : `notify = ["node", "${SCRIPT_PATH}", "codex-notify"]`);
+      printCodexConfig();
       break;
-
     case 'gate-config':
-      console.log('Opt-in: answer Claude Code permission prompts from the phone.');
-      console.log('Merge into .claude/settings.json, adjusting the matcher to the tools you want gated:\n');
-      console.log(JSON.stringify({
-        hooks: {
-          PreToolUse: [{
-            matcher: 'Bash',
-            hooks: [{ type: 'command', command: `${HOOK_COMMAND} --gate`, timeout: 60 }],
-          }],
-        },
-      }, null, 2));
-      console.log('\nNotes: allow/deny from the phone settles the permission;');
-      console.log('no answer within ~55s falls through to the terminal prompt as usual.');
+      printGateConfig();
+      break;
+
+    default:
+      printHelp();
+  }
+}
+
+function printClaudeConfig() {
+  console.log('Merge this into the project’s .claude/settings.json (or ~/.claude/settings.json for everywhere):\n');
+  console.log('(Or let `carmoji install claude` do it for you, with a backup.)\n');
+  console.log(claudeConfigSnippet());
+}
+
+function printCodexConfig() {
+  console.log('Modern Codex reads hooks from $CODEX_HOME/hooks.json — prefer:');
+  console.log('  carmoji install codex\n');
+  console.log('For older Codex versions, add this line to ~/.codex/config.toml:\n');
+  console.log(RUNNING_FROM_PACKAGE
+    ? 'notify = ["npx", "-y", "carmoji", "codex-notify"]'
+    : `notify = ["node", "${SCRIPT_PATH}", "codex-notify"]`);
+}
+
+function printGateConfig() {
+  console.log('Legacy/advanced: `carmoji install claude` now installs a PermissionRequest');
+  console.log('hook that answers real permission prompts from the phone by itself.');
+  console.log('The PreToolUse gate below instead fires on EVERY matched tool call, even');
+  console.log('allowlisted ones — useful only on older Claude Code versions without the');
+  console.log('PermissionRequest hook, or to force-gate specific tools.');
+  console.log('Merge into .claude/settings.json, adjusting the matcher to the tools you want gated:\n');
+  console.log(JSON.stringify({
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: `${HOOK_COMMAND} --gate`, timeout: 60 }],
+      }],
+    },
+  }, null, 2));
+  console.log('\nNotes: allow/deny from the phone settles the permission;');
+  console.log('no answer within ~55s falls through to the terminal prompt as usual.');
+}
+
+const USAGE = `carmoji bridge — talk to the CarMoji app on your phone
+
+  pair <code> [ip[:port]]      pair with a phone (code from its Code Buddy sheet)
+  unpair [<name|ip[:port]>|all]  forget paired devices
+  discover                     list CarMoji devices on this Wi-Fi
+  install <tool>|all           install hooks (tools: ${Object.keys(TOOLS).join(', ')})
+  uninstall <tool>|all         remove CarMoji hooks from a tool's config
+  tools                        show each tool's config path and whether it's present
+  test <event>                 send a fake event; \`test approval\` pops the Allow/Deny card
+  hook                         entry point the agents' hooks invoke (reads JSON on stdin)
+  config <claude|codex|gate>   print a manual config snippet
+  codex-notify                 legacy Codex notify entry point
+
+Run a command with --help for details — \`carmoji hook --help\` documents the
+accepted stdin JSON, \`carmoji test --help\` lists every test event.`;
+
+/** Detailed per-command help; anything without a dedicated page gets USAGE. */
+function printHelp(topic) {
+  switch (topic) {
+    case 'hook':
+      console.log(`carmoji hook [--source <tool>] [--event <name>] [--gate]
+
+Entry point the coding agents' hooks invoke: reads ONE hook event as JSON on
+stdin, forwards it to every paired phone, and exits 0 no matter what so it can
+never disturb a session. Unpaired = immediate no-op.
+
+Flags:
+  --source <tool>  which agent is calling (default: claude) — sets the wire
+                   \`source\` and enables tool-specific payload handling
+  --event <name>   event name for tools whose stdin JSON lacks one
+                   (Gemini, Cursor, Trae, Copilot)
+  --gate           legacy PreToolUse gate — see \`carmoji config gate\`
+
+Accepted stdin JSON — Claude Code's field names, with aliases folded in:
+  hook_event_name  or hookEventName / eventName / event / hookName / --event
+  session_id       or sessionId / conversation_id / conversationId / taskId
+  tool_name        or toolName / (Cline) preToolUse.toolName
+  tool_input       or toolArgs (JSON string) / (Cline) preToolUse.parameters
+  cwd              project folder shown on the phone (default: process cwd)
+  message / prompt human snippet for prompt & permission toasts
+  transcript_path  lets the bridge tail token usage for the tok/s readout
+
+Canonical events: ${CLAUDE_HOOK_EVENTS.join(', ')},
+PostToolUseFailure, SubagentStart/Stop, PreCompact/PostCompact — plus each
+tool's dialect (beforeShellExecution, TaskComplete, permission_request, …);
+see EVENT_ALIASES in carmoji.js for the full mapping. Unknown events are
+silently ignored.
+
+Blocking: a Claude Code PermissionRequest holds the hook open up to ${APPROVAL_WAIT_MS / 1000}s
+while the phone shows a card, then prints the decision for the agent:
+  {"hookSpecificOutput":{"hookEventName":"PermissionRequest",
+                         "decision":{"behavior":"allow"}}}
+AskUserQuestion gets an option-picker card instead when it's one
+single-select question with 2–4 labeled options; the tapped label — or
+free text typed behind the card's "Other…" button, which sends
+{hold:true} to stretch the wait to ${HOLD_WAIT_MS / 1000}s — comes back via
+decision.updatedInput.answers. Multi-question and multiSelect stay
+display-only.
+No tap → no output → the normal terminal prompt appears.
+
+Try it:
+  echo '{"hook_event_name":"PreToolUse","session_id":"s1","tool_name":"Edit"}' \\
+    | carmoji hook`);
+      break;
+
+    case 'test':
+      console.log(`carmoji test <event> [session] [tokens] [project]
+
+Sends a fake event to every paired phone so you can watch the reactions
+without a coding agent.
+
+  start       wakes up, excited            (session_start)
+  prompt      perks up and listens         (prompt)
+  edit        focused typing face          (tool_start Edit)
+  read        pores over a document        (tool_start Read)
+  run         nervous side-eye             (tool_start Bash)
+  heartbeat   no reaction; session liveness + token sample (tool_end)
+  done        celebration with hearts      (turn_done)
+  error       dizzy comic collapse         (error)
+  permission  pleading + floating "?"      (permission)
+  end         contented sigh               (session_end)
+  approval    pops the Allow/Deny card, waits ${APPROVAL_WAIT_MS / 1000}s, prints your tap
+  question    pops an option-picker card, waits ${APPROVAL_WAIT_MS / 1000}s, prints your pick
+
+  [session]   session key — use two different values to simulate several
+              agents at once
+  [tokens]    cumulative output-token count for the tok/s readout
+  [project]   project name shown under the dashboard robot`);
+      break;
+
+    case 'config':
+      console.log(`carmoji config <claude|codex|gate>
+
+  claude  the .claude/settings.json hooks snippet (what \`install claude\`
+          writes, including the ${PERMISSION_HOOK_TIMEOUT_S}s PermissionRequest hook)
+  codex   the legacy ~/.codex/config.toml notify line for Codex versions
+          without hooks.json (modern Codex: \`carmoji install codex\`)
+  gate    the legacy PreToolUse gate snippet — fires on every matched call;
+          superseded by the PermissionRequest hook \`install claude\` sets up`);
+      break;
+
+    case 'install':
+      console.log(`carmoji install <tool>|all
+
+Writes CarMoji's hooks into the tool's own config (a .bak backup is saved
+next to anything modified; reinstalling replaces earlier CarMoji entries).
+\`all\` installs into every tool detected on this machine.
+
+Tools: ${Object.keys(TOOLS).join(', ')}
+\`carmoji tools\` shows each one's config path and whether it's present.`);
+      break;
+
+    case 'uninstall':
+      console.log(`carmoji uninstall <tool>|all
+
+Removes every CarMoji entry from the tool's hook config, leaving other
+hooks untouched. \`all\` sweeps every known tool quietly.
+
+Tools: ${Object.keys(TOOLS).join(', ')}`);
       break;
 
     default:
-      console.log('carmoji bridge — usage: pair <code> [ip[:port]] | unpair [<name|ip[:port]>|all] | discover | install <tool>|all | uninstall <tool> | tools | test <event> | hook [--source <tool>] [--event <name>] [--gate] | codex-notify | claude-config | codex-config | gate-config');
+      console.log(USAGE);
   }
 }
 
@@ -1317,6 +1681,7 @@ export {
   applyTranscriptTokenRecord,
   eventFromHook,
   normalizeDevices,
+  requestApproval,
   stripLegacyCarMojiNotifyLine,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carmoji",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Bring your CarMoji pet to life from Claude Code / Codex — a LAN bridge that streams coding events to the CarMoji iOS app",
   "type": "module",
   "bin": {