carmoji 0.3.3 → 0.3.5

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,27 @@ 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).
+
+Honest limits: this decides *tool permissions* only — AskUserQuestion
+option pickers show as a pleading toast but must be answered in the
+terminal — and 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

@@ -5,18 +5,22 @@
 // address + pairing code in ~/.config/carmoji/config.json.
 //
 // Commands:
-//   pair <code>      discover the phone on this Wi-Fi and pair with it
+//   pair <code>      discover phones on this Wi-Fi and pair with the one
+//                    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,
@@ -170,8 +174,8 @@ async function askTTY(question) {
 }
 
 /** Let the user pick between several discovered phones. */
-async function chooseDevice(devices) {
-  console.log('Multiple CarMoji devices found:');
+async function chooseDevice(devices, heading = 'Multiple CarMoji devices found:') {
+  console.log(heading);
   devices.forEach((d, i) => console.log(`  ${i + 1}. ${d.name} — ${d.host}:${d.port}`));
   if (!process.stdin.isTTY) {
     console.error('\nRe-run with the address of the one you want: carmoji pair <code> <ip[:port]>');
@@ -278,6 +282,7 @@ function requestApprovalAll(devices, message, timeoutMs) {
 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);
 }
@@ -547,7 +552,20 @@ 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. The
+// installed hook timeout leaves headroom over the bridge's wait.
+const APPROVAL_WAIT_MS = 55_000;
+const PERMISSION_HOOK_TIMEOUT_S = 75;
+
+/** 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).
@@ -675,21 +693,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 });
@@ -882,14 +904,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')) {
@@ -901,15 +929,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)) {
@@ -966,11 +999,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);
 }
@@ -978,6 +1010,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 || '')) {
@@ -987,10 +1030,18 @@ async function main() {
       let target;
       const manual = rest[0];
       if (manual) {
-        // Manual addressing for networks with several phones (the app's
-        // Code Buddy sheet shows the address) or when mDNS is blocked.
+        // Manual addressing (the app's Code Buddy sheet shows the address)
+        // for networks where mDNS is blocked.
         const [host, port] = manual.split(':');
         target = { host, port: Number(port) || 8737, name: host };
+        const result = await send({ ...target, code: arg },
+                                  { source: 'bridge', event: 'turn_done' });
+        if (result !== 'ok') {
+          console.error(result === 'bad-code'
+            ? `"${target.name}" (${target.host}:${target.port}) rejected the pairing code — check that device’s Code Buddy sheet.`
+            : `Found "${target.name}" at ${target.host}:${target.port} but couldn’t talk to it (${result}).`);
+          process.exit(1);
+        }
       } else {
         console.log('Looking for CarMoji on this network…');
         const devices = await discoverAll();
@@ -999,17 +1050,27 @@ async function main() {
           console.error('You can also pair by address: carmoji pair <code> <ip[:port]>');
           process.exit(1);
         }
-        target = devices.length === 1 ? devices[0] : await chooseDevice(devices);
+        // The pairing code identifies the phone: probe every discovered
+        // device with it and pair with whichever accepts — no picking from
+        // a list when several phones share the network.
+        const results = await Promise.all(devices.map((d) =>
+          send({ ...d, code: arg }, { source: 'bridge', event: 'turn_done' })));
+        const accepted = devices.filter((_, i) => results[i] === 'ok');
+        if (accepted.length === 0) {
+          console.error(results.includes('bad-code')
+            ? `No device on this network accepted code ${arg} — check the Code Buddy sheet on the phone you want:`
+            : 'Found CarMoji but couldn’t talk to it:');
+          devices.forEach((d, i) =>
+            console.error(`  ${deviceLabel(d)}: ${results[i]}`));
+          process.exit(1);
+        }
+        // Two phones drew the same 4-digit code — let the user break the
+        // tie instead of guessing.
+        target = accepted.length === 1 ? accepted[0]
+          : await chooseDevice(accepted, 'Several devices accepted this pairing code:');
       }
       const device = { name: target.name, host: target.host,
                        port: target.port, code: arg };
-      const result = await send(device, { source: 'bridge', event: 'turn_done' });
-      if (result !== 'ok') {
-        console.error(result === 'bad-code'
-          ? `"${target.name}" (${target.host}:${target.port}) rejected the pairing code — check that device’s Code Buddy sheet. (Wrong phone? Pass its address: carmoji pair <code> <ip[:port]>)`
-          : `Found "${target.name}" at ${target.host}:${target.port} but couldn’t talk to it (${result}).`);
-        process.exit(1);
-      }
       // Pairing the same device again just refreshes its code; other
       // devices stay paired unless the user says otherwise here.
       const others = loadDevices().filter(
@@ -1081,7 +1142,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 {
@@ -1122,6 +1187,38 @@ 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. AskUserQuestion also arrives as a
+        // PermissionRequest, but the phone has no option picker, so it drops
+        // to the display-only path below.
+        const canonicalEvent = EVENT_ALIASES[payload.hook_event_name]
+          ?? payload.hook_event_name;
+        if (canonicalEvent === 'PermissionRequest'
+            && ANSWERABLE_PERMISSION_SOURCES.has(source)
+            && payload.tool_name !== 'AskUserQuestion') {
+          const decision = await requestApprovalAll(devices, {
+            source,
+            session: payload.session_id,
+            host: hostname(),
+            event: 'approval_request',
+            tool: payload.tool_name,
+            detail: summarizeToolInput(payload),
+            project: payload.cwd ? basename(payload.cwd) : undefined,
+          }, APPROVAL_WAIT_MS);
+          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
@@ -1178,8 +1275,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') {
+        console.error(`Usage: carmoji test <${Object.keys(TEST_EVENTS).join('|')}|approval> [session] [tokens] [project] — details: carmoji test --help`);
         process.exit(1);
       }
       const devices = loadDevices();
@@ -1187,6 +1284,22 @@ 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);
+        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);
+      }
       const [session, tokens, project] = rest;
       const message = { source: 'test', session, host: hostname(), ...event };
       if (tokens !== undefined) message.tokens = Number(tokens);
@@ -1229,8 +1342,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);
@@ -1247,50 +1366,191 @@ 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 (any tool except AskUserQuestion)
+holds the hook open up to ${APPROVAL_WAIT_MS / 1000}s while the phone shows Allow/Deny, then
+prints the decision for the agent:
+  {"hookSpecificOutput":{"hookEventName":"PermissionRequest",
+                         "decision":{"behavior":"allow"}}}
+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
+
+  [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);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carmoji",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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": {