carmoji 0.3.5 → 0.3.7

package/README.md

@@ -153,10 +153,11 @@ 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)
+## Answer permissions from the phone (Claude Code and Codex)
 
-`carmoji install claude` hooks Claude Code's `PermissionRequest` event,
-which fires **only when a permission dialog is about to appear** —
+`carmoji install claude` and `carmoji install codex` hook each agent'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
@@ -165,10 +166,14 @@ 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).
+For Claude Code, 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.
+Codex questions use its App Server `requestUserInput` protocol rather than
+lifecycle hooks, so they remain terminal-only; Codex Allow/Deny permission
+approvals do work from the phone.
 
 Older Claude Code versions without the `PermissionRequest` hook can use
 `npx carmoji config gate` instead: a legacy `PreToolUse` gate with a tool

package/carmoji.js

@@ -222,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 }));
     });
@@ -239,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 */ }
@@ -262,23 +279,54 @@ 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
@@ -557,15 +605,22 @@ const CLAUDE_HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse',
 
 // 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.
+// 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 PERMISSION_HOOK_TIMEOUT_S = 75;
+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']);
+/** Sources whose PermissionRequest hook accepts Allow/Deny through
+ *  `hookSpecificOutput.decision`. */
+const ANSWERABLE_APPROVAL_SOURCES = new Set(['claude', 'codex']);
+
+/** Sources whose question protocol accepts `decision.updatedInput`.
+ *  Codex questions use App Server requestUserInput instead of hooks, so a
+ *  synthetic AskUserQuestion event must remain display-only. */
+const ANSWERABLE_QUESTION_SOURCES = new Set(['claude']);
 
 // ---------------------------------------------------------------------------
 // Multi-tool hook installers (see EVENT_ALIASES for how their events map).
@@ -1165,14 +1220,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: {
@@ -1191,32 +1246,74 @@ async function main() {
         // 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.
+        // to the terminal dialog.
         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, {
+        if (canonicalEvent === 'PermissionRequest') {
+          const common = {
             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 },
-              },
-            }));
+          };
+
+          // 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'
+              && ANSWERABLE_QUESTION_SOURCES.has(source)) {
+            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 if (payload.tool_name !== 'AskUserQuestion'
+                     && ANSWERABLE_APPROVAL_SOURCES.has(source)) {
+            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;
           }
-          break;
         }
 
         const event = eventFromHook(payload);
@@ -1275,8 +1372,8 @@ async function main() {
 
     case 'test': {
       const event = TEST_EVENTS[arg];
-      if (!event && arg !== 'approval') {
-        console.error(`Usage: carmoji test <${Object.keys(TEST_EVENTS).join('|')}|approval> [session] [tokens] [project] — details: carmoji test --help`);
+      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();
@@ -1287,19 +1384,44 @@ async function main() {
       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, {
+        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);
+        }, APPROVAL_WAIT_MS))?.decision;
         console.log(decision
           ? `Decision: ${decision}`
-          : 'No answer — in a real session Claude Code would fall through to the terminal prompt.');
+          : 'No answer — in a real session the coding agent 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);
@@ -1482,11 +1604,16 @@ 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:
+Blocking: a Claude Code or Codex 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"}}}
+For Claude Code, 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; Codex questions use App Server requestUserInput instead.
 No tap → no output → the normal terminal prompt appears.
 
 Try it:
@@ -1511,6 +1638,7 @@ without a coding agent.
   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
@@ -1558,6 +1686,7 @@ export {
   applyTranscriptTokenRecord,
   eventFromHook,
   normalizeDevices,
+  requestApproval,
   stripLegacyCarMojiNotifyLine,
 };
 

package/package.json

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