cli-setu 0.1.0

package/src/cli-adapters/codex.js

@@ -0,0 +1,261 @@
+// Codex adapter. Verified interactively against codex-cli 0.154.0 by
+// actually spawning it in a real node-pty PTY and driving it through a
+// file-write and a shell-command request (not guessed from --help text or
+// docs) - see the project chat history for the exact probe scripts and
+// their raw captured output.
+//
+// Codex's real per-action approval prompt (confirmed live, after asking
+// it to write a file):
+//
+//   Would you like to make the following edits?
+//
+//   Description: Apply proposed file edits
+//   Destination:
+//   <full path>
+//
+//   › 1. Yes, proceed (y)
+//     2. Yes, and don't ask again for these files (a)
+//     3. No, and tell Codex what to do differently (esc)
+//
+//   Press enter to confirm or esc to cancel
+//
+// This is genuinely different from Claude Code's approval mechanism in
+// two ways that matter for this adapter's shape:
+//   1. No hook system - Claude Code's PermissionRequest hook (see
+//      claude.js) reports an approval as a structured JSON event BEFORE
+//      it's shown, via a file Claude Code itself writes. Codex has no
+//      equivalent for its interactive PTY mode - the ONLY signal is the
+//      rendered prompt text itself, appearing in the same PTY stream as
+//      everything else Codex prints. This adapter's approvals therefore
+//      work by scrolling-buffer text matching (sourceMode: 'pty-scrape'),
+//      not a queue file - supervisor-qr.js branches on this flag.
+//   2. The reject option is "esc" (a bare Escape keystroke), not a
+//      numbered "3" the way Claude Code's Bash prompts work - "3" here is
+//      actually a WORDED alternative phrasing of the same escape action,
+//      not a separate hotkey. getDialogOptions maps this correctly (see
+//      below) rather than assuming Claude Code's "always numbered 1/2/3"
+//      pattern generalizes.
+//
+// Two more numbered-menu screens appear on a brand new working directory
+// (also confirmed live) that are NOT per-action approvals and must NOT be
+// relayed to the phone as if they were - they're one-time local setup
+// gates:
+//   "Do you trust the contents of this directory?" (1. Yes, continue /
+//   2. No, quit) and "Set up the Codex agent sandbox..." (1. Set up
+//   default sandbox [needs Administrator] / 2. Use non-admin sandbox /
+//   3. Quit). autoAnswerOnboarding below detects and answers both
+//   automatically (continue + non-admin sandbox) so pairing a fresh
+//   laptop/folder doesn't stall waiting on a phone tap for a purely local
+//   one-time step - see supervisor-qr.js's onData handler for where this
+//   gets called before real-approval detection even runs.
+const ONBOARDING_TRUST_RE = /do you trust the contents of this directory\?/i;
+const ONBOARDING_SANDBOX_RE = /set up the codex agent sandbox/i;
+
+// autoAnswerOnboarding(scrollbackWindow) -> keystrokes to write, or null
+// if no onboarding gate is present in this window. Checked BEFORE real
+// approval detection on every chunk (see supervisor-qr.js) - deliberately
+// simple string matches, not full menu parsing, since these two screens'
+// wording is fixed and their answers are hardcoded, not user-configurable.
+function autoAnswerOnboarding(scrollbackWindow) {
+  if (ONBOARDING_TRUST_RE.test(scrollbackWindow)) {
+    return { keystrokes: '\r', reason: 'trust-directory' }; // "1. Yes, continue" is the default selection
+  }
+  if (ONBOARDING_SANDBOX_RE.test(scrollbackWindow)) {
+    return { keystrokes: '2\r', reason: 'non-admin-sandbox' }; // avoid requiring Administrator
+  }
+  return null;
+}
+
+// The real per-action approval prompt (see header comment). Loose enough
+// to tolerate ANSI noise between words (confirmed necessary - Codex's TUI
+// interleaves cursor-sync escape codes mid-render far more heavily than
+// Claude Code's), but anchored on "Would you like to make the following
+// edits?" / "Press enter to confirm or esc to cancel" as the real, fixed
+// bracketing text - both confirmed present verbatim in a live capture.
+//
+// Real gap found by testing: Codex has AT LEAST TWO distinct approval
+// prompt templates, not one - a second, differently-worded shape appeared
+// for a shell command (as opposed to a file edit):
+//
+//   Would you like to run the following command?
+//
+//   Environment: local
+//   Reason: Do you want to allow me to create hello.txt in the current workspace?
+//
+//   $ Set-Content -LiteralPath hello.txt -Value 'hello world' -NoNewline
+//
+//   1. Yes, proceed (y)
+//   2. Yes, and don't ask again for commands that start with `Set-Content ...` (p)
+//   3. No, and tell Codex what to do differently (esc)
+//
+// A regex built against only the file-edit shape ("make the following
+// edits?" / "Description:" / "Destination:") silently matched nothing at
+// all for this one - detectApproval below tries BOTH start patterns and
+// extracts shape-appropriate fields, rather than assuming Codex has one
+// canonical prompt template the way the first version of this file did.
+const APPROVAL_START_RE = /would you like to (?:make the following edits|run the following command)\?/i;
+const APPROVAL_END_RE = /press enter to confirm or esc to cancel/i;
+const DESCRIPTION_RE = /description:\s*([^\n]+)/i;
+const DESTINATION_RE = /destination:\s*\n?\s*([^\n]+)/i;
+const REASON_RE = /reason:\s*([^\n]+)/i;
+const COMMAND_RE = /\$\s*([^\n]+)/;
+
+// Real bug found by testing: description/destination text came through
+// with raw ANSI codes embedded IN the value itself (e.g. "\x1b[3mApply
+// proposed file edits\x1b[23m\x1b[K" instead of a clean "Apply proposed
+// file edits") - Codex's TUI wraps individual words/spans in their own
+// italic/clear-to-EOL codes, not just around the whole line the way
+// Claude Code's simpler /cost render does, so [^\n]+ alone wasn't enough
+// to keep them out. Stripping all ANSI/CSI sequences before running the
+// field regexes (rather than trying to make the regexes themselves
+// tolerate embedded codes) is the fix that generalizes to whatever else
+// Codex might wrap the same way.
+const ANSI_RE = /\x1b\[[0-9;?]*[a-zA-Z]/g;
+
+function stripAnsi(text) {
+  return text.replace(ANSI_RE, '');
+}
+
+// Returns a NEW approval event if the window contains a complete,
+// not-yet-seen prompt, else null. `seenAt` lets supervisor-qr.js avoid
+// re-detecting the SAME still-on-screen prompt on every subsequent chunk
+// (the PTY keeps redrawing it while nothing's changed) - it hashes the
+// description/destination text, not the whole noisy raw window.
+function detectApproval(scrollbackWindow) {
+  const startMatch = scrollbackWindow.match(APPROVAL_START_RE);
+  const endMatch = scrollbackWindow.match(APPROVAL_END_RE);
+  if (!startMatch || !endMatch || endMatch.index < startMatch.index) return null;
+
+  const section = stripAnsi(scrollbackWindow.slice(startMatch.index, endMatch.index + endMatch[0].length));
+  const isCommandPrompt = /run the following command/i.test(startMatch[0]);
+
+  // File-edit shape: Description: / Destination:
+  // Shell-command shape: Reason: / a "$ <command>" line - no
+  // Description/Destination fields at all, confirmed absent in the live
+  // capture, so falling back to DESCRIPTION_RE/DESTINATION_RE for this
+  // shape would just silently return null forever.
+  const description = isCommandPrompt
+    ? section.match(REASON_RE)?.[1]?.trim() || null
+    : section.match(DESCRIPTION_RE)?.[1]?.trim() || null;
+  const destination = isCommandPrompt
+    ? section.match(COMMAND_RE)?.[1]?.trim() || null
+    : section.match(DESTINATION_RE)?.[1]?.trim() || null;
+
+  return {
+    // A stable-ish key for THIS prompt's identity, so supervisor-qr.js
+    // can tell "still the same on-screen prompt" apart from "a new one
+    // just appeared" without needing Codex to hand out its own id (it
+    // doesn't, for this UI) - description+destination is what actually
+    // varies between two different edit/command requests.
+    fingerprint: `${description || ''}|${destination || ''}`,
+    isCommandPrompt,
+    description,
+    destination,
+    raw: section,
+  };
+}
+
+// Codex's own wording IS the option labels - "Yes, proceed (y)" etc. -
+// unlike Claude Code, where getDialogOptions has to invent labels for a
+// bare tool_name/tool_input. keystroke '\x1b' for the reject path (option
+// 3's parenthetical says "(esc)", not a hotkey digit - confirmed in the
+// live capture) is the one place this genuinely differs from Claude
+// Code's all-numeric-hotkey menus.
+//
+// Option 2's wording actually differs by prompt shape (confirmed live):
+// file-edit says "...for these files", the shell-command shape says
+// "...for commands that start with `<the actual command>`" - kept
+// generic here ("don't ask again") rather than hardcoding either exact
+// phrasing, since neither is universally correct and the phone doesn't
+// need Codex's exact words to convey what the option does.
+function getDialogOptions(event) {
+  return [
+    { label: 'Yes, proceed', keystroke: '1', style: 'approve' },
+    { label: "Yes, and don't ask again", keystroke: '2', style: 'approve-alt' },
+    { label: 'No, tell Codex what to do differently', keystroke: '\x1b', style: 'reject' },
+  ];
+}
+
+function describePrompt(event) {
+  if (event.isCommandPrompt) {
+    if (event.description && event.destination) return `${event.description}\n$ ${event.destination}`;
+    return event.destination ? `Run: ${event.destination}` : 'Run this command?';
+  }
+  if (event.description && event.destination) return `${event.description}?\n${event.destination}`;
+  return event.description || 'Approve this action?';
+}
+
+module.exports = {
+  id: 'codex',
+  displayName: 'Codex',
+  // See claude.js's icon comment for why this is adapter-declared, not
+  // hardcoded in the UI - and why this is a generic icon, not OpenAI's
+  // actual logo (no official asset bundled/fabricated here).
+  icon: { name: 'terminal', color: '#10A37F' }, // OpenAI's own public brand accent is a teal/green - approximated here, not an official value
+  spawn: {
+    // Real, verified path (see `where codex` / `Get-Command codex` output
+    // in the project chat history) - node-pty on Windows needs a real
+    // resolved executable, the same requirement claude.js's spawn.command
+    // already works around for Claude Code.
+    command:
+      process.platform === 'win32'
+        ? 'C:\\Users\\hp\\AppData\\Roaming\\npm\\codex.cmd'
+        : 'codex',
+    args: () => [],
+  },
+  approvals: {
+    sourceMode: 'pty-scrape', // supervisor-qr.js branches on this vs. claude.js's 'hook-queue'
+    autoAnswerOnboarding,
+    detectApproval,
+    describePrompt,
+    getDialogOptions,
+  },
+  // Real per-turn token usage (`turn.completed`'s `usage` object) is only
+  // reachable via `codex exec --json`'s spawn-per-turn model - a
+  // fundamentally different execution model from the persistent PTY this
+  // adapter drives for approvals (see README.md), not built here.
+  //
+  // What IS available for free: Codex's interactive TUI shows a live "NN%
+  // context left" indicator in its status bar continuously (confirmed
+  // live - no slash command or injection needed, unlike Claude Code's
+  // /cost). triggerKeystrokes: null signals supervisor-qr.js to skip its
+  // periodic-injection timer entirely for this adapter and instead just
+  // watch every chunk - cheap, since parseFromOutput here is one small
+  // regex, not the multi-regex /cost parse Claude Code's adapter needs.
+  // Remote slash-command palette (Section 15 roadmap item #6). Verified
+  // LIVE against codex-cli 0.155.1 by actually typing '/' at a real
+  // prompt (not guessed from --help) - the real menu also lists /ide,
+  // /keymap, /vim, and /experimental, deliberately excluded here since
+  // they only make sense for whoever is physically typing at THIS
+  // terminal (a keybinding remap, a composer mode toggle) - nothing a
+  // phone tap communicates any intent for. /model, /permissions,
+  // /approve, /memories are the ones a REMOTE user plausibly wants to
+  // trigger. No /compact or /cost exist for Codex at all (confirmed
+  // absent from the real menu) - matches this adapter's usage section
+  // above, which already gets Codex's numbers from the passive "% context
+  // left" status bar instead of a slash command.
+  commands: [
+    { id: 'model', label: 'Switch model', keystrokes: '/model\r' },
+    { id: 'permissions', label: 'Change permissions', keystrokes: '/permissions\r' },
+    { id: 'approve', label: 'Approve recent retry', keystrokes: '/approve\r' },
+    { id: 'memories', label: 'Memory settings', keystrokes: '/memories\r' },
+  ],
+  usage: {
+    triggerKeystrokes: null,
+    parseFromOutput(chunk) {
+      const match = chunk.match(/(\d{1,3})%\s*context left/i);
+      if (!match) return null;
+      return {
+        totalTokens: null,
+        inputTokens: null,
+        outputTokens: null,
+        costUsd: null,
+        // Codex reports "% LEFT", Claude Code's adapter reports "% USED" -
+        // inverted here so both adapters feed the same
+        // sessionContextUsedPct field with the same meaning.
+        sessionContextUsedPct: 100 - Number(match[1]),
+        raw: chunk,
+      };
+    },
+  },
+};

package/src/cli-adapters/generic.js

@@ -0,0 +1,32 @@
+// The fallback adapter - what an unrecognized/never-integrated CLI gets.
+// This is what makes "supports any CLI" literally true rather than "the
+// two CLIs someone bothered to write an adapter for": spawn it in a PTY,
+// mirror its raw output to the phone, done. No structured Confirmations
+// card (approvals: null - the human sees the prompt live in the mirrored
+// terminal and has to answer it from the laptop itself, same as running
+// the CLI with no bridge at all), no token/cost tracking (usage: null).
+//
+// command comes from whatever --cli <name> the user actually typed -
+// this adapter doesn't know or care what that binary does, only that
+// it's a real command on PATH the user asked to run.
+module.exports = function genericAdapter(cliCommand) {
+  return {
+    id: cliCommand,
+    displayName: cliCommand,
+    // Generic fallback icon - same neutral glyph for ANY CLI without its
+    // own adapter (see claude.js/codex.js for what a real adapter
+    // declares instead). Muted grey rather than an accent color, since
+    // this represents "unknown CLI," not a specific recognized brand.
+    icon: { name: 'terminal-outline', color: '#7C8B99' },
+    spawn: {
+      command: cliCommand,
+      args: () => [],
+    },
+    approvals: null,
+    usage: null,
+    // No known slash-commands for an unrecognized CLI - the phone shows
+    // no palette at all rather than a guessed/empty one (see
+    // DevicesScreen.js/TerminalScreen.js's null-check).
+    commands: null,
+  };
+};

package/src/cli-adapters/index.js

@@ -0,0 +1,27 @@
+// One place supervisor.js asks "which adapter for this CLI name" -
+// unrecognized names fall through to the generic PTY-only adapter
+// (see generic.js) rather than erroring out, since "not yet integrated"
+// should never mean "can't run this CLI through the bridge at all."
+const claude = require('./claude');
+const codex = require('./codex');
+const shell = require('./shell');
+const makeGeneric = require('./generic');
+
+const KNOWN_ADAPTERS = {
+  claude,
+  codex,
+  shell,
+};
+
+// Real product decision (confirmed directly by the PM): bare `setu` with
+// no --cli flag bridges the user's own plain terminal, not Claude Code
+// specifically - the user decides what to run once it's open. Defaulting
+// to 'claude' here silently assumed every user wanted an AI CLI running
+// the instant they typed `setu`, which isn't actually the product's real
+// intent (a genuine remote terminal, not an AI-agent-only bridge).
+function getAdapter(cliName) {
+  const normalized = (cliName || 'shell').toLowerCase();
+  return KNOWN_ADAPTERS[normalized] || makeGeneric(cliName);
+}
+
+module.exports = { getAdapter, KNOWN_ADAPTERS };

package/src/cli-adapters/shell.js

@@ -0,0 +1,52 @@
+// The default adapter when a user runs plain `setu` with no --cli flag at
+// all - a real gap in the earlier design: `setu` (bare) always launched
+// Claude Code specifically, silently assuming that's what every user
+// wants. The actual product intent (confirmed directly by the PM) is
+// simpler and more honest: `setu` bridges the user's OWN real terminal to
+// their phone - a genuine remote shell, nothing AI-specific - and the
+// user decides what to run inside it once it's open (`claude`, `codex`,
+// `npm install`, `git status`, anything). Running an AI CLI inside this
+// bridged shell still gets real approval detection IF that CLI has its
+// own adapter (this adapter itself has none - see approvals: null below)
+// - detection is about what's actually running inside the PTY moment to
+// moment, not about which adapter spawned the shell around it.
+const os = require('os');
+
+function resolveShellCommand() {
+  if (process.platform === 'win32') {
+    // Real users' machines vary here - PowerShell is the modern Windows
+    // default (present on every Windows 10/11 install), but COMSPEC
+    // (usually cmd.exe) is what Windows itself considers "the" shell for
+    // a process that doesn't ask for anything more specific. Preferring
+    // PowerShell when it's genuinely on PATH, falling back to COMSPEC
+    // (or a bare cmd.exe) otherwise, covers both cases without assuming
+    // one specific install layout the way a hardcoded path would.
+    return 'powershell.exe';
+  }
+  // SHELL is the real, standard POSIX convention for "the user's own
+  // configured shell" (bash, zsh, fish, ...) - respecting it here means
+  // this bridges whatever shell the user already actually uses day to
+  // day, not a hardcoded assumption that might not even be installed.
+  return process.env.SHELL || '/bin/bash';
+}
+
+module.exports = {
+  id: 'shell',
+  displayName: os.platform() === 'win32' ? 'PowerShell' : 'Shell',
+  icon: { name: 'terminal-outline', color: '#7C8B99' },
+  spawn: {
+    command: resolveShellCommand(),
+    args: () => [],
+  },
+  // No structured Confirmations card - a plain shell has no permission-
+  // prompt concept of its own to detect. If the user launches an AI CLI
+  // INSIDE this shell, that CLI's own real adapter (claude.js/codex.js)
+  // still isn't active here, since supervisor.js picks exactly one
+  // adapter per process/session at startup - a real user wanting
+  // structured approvals for a specific CLI should run `setu --cli
+  // claude` (or codex) directly, same as always. This adapter is
+  // specifically for "just give me my terminal, I'll decide what to run."
+  approvals: null,
+  usage: null,
+  commands: null,
+};

package/src/config.js

@@ -0,0 +1,54 @@
+// Real gap in the proof-of-concept this package replaces: supervisor-qr.js
+// required a hand-typed device name and session id on every single run
+// (`node supervisor-qr.js Laptop-1 session-A`) - fine for testing several
+// fake "laptops" side by side on one dev machine, wrong for a real
+// install. A real user's computer already has a name; this reads it
+// automatically instead of asking, and remembers it across runs.
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_DIR = path.join(os.homedir(), '.cli-setu');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function defaultDeviceName() {
+  return os.hostname() || 'My Computer';
+}
+
+// Saved once, on the first `setu pair`, so a later OS-level hostname
+// change (renaming the machine, moving to a new user profile) doesn't
+// silently rename an already-paired device out from under the user - the
+// Devices tab's identity for this machine stays whatever it was when it
+// was actually paired, not whatever the OS reports today.
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+// Called by `setu pair` - creates the config the FIRST time, using the
+// auto-detected hostname as the default device name. A config that
+// already exists (this machine has paired before) is left untouched;
+// re-pairing intentionally reuses the same device identity rather than
+// minting a second, confusing "device" for the same physical laptop.
+function loadOrCreateConfig() {
+  const existing = readConfig();
+  if (existing) return existing;
+  return { deviceName: defaultDeviceName(), deviceToken: null };
+}
+
+module.exports = {
+  CONFIG_DIR,
+  CONFIG_FILE,
+  defaultDeviceName,
+  readConfig,
+  writeConfig,
+  loadOrCreateConfig,
+};

package/src/hooks.js

@@ -0,0 +1,80 @@
+// Real gap in the proof-of-concept this replaces: .claude/settings.json's
+// hook command was a hardcoded absolute path into phase1/, hand-edited
+// once for this one dev machine. A real npm-installed package can't ship
+// that - every user's global install lives at a different path (varies by
+// OS, by nvm/volta version manager, by whether it's a global or local
+// install), and expecting someone to hand-edit JSON before their first
+// `setu` run defeats the entire point of "npm install -g cli-setu" being
+// a real, ready-to-use install. This ensures the CURRENT project's
+// .claude/settings.json has the right hook registered, pointing at
+// wherever THIS running copy of cli-setu actually lives on disk right now
+// - computed fresh each time, never assumed.
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_SCRIPT = path.join(__dirname, 'onPermissionRequest.js');
+
+function hookEntry() {
+  return {
+    matcher: '*',
+    hooks: [{ type: 'command', command: `node "${HOOK_SCRIPT}"` }],
+  };
+}
+
+// True only if every hook entry for this event already points at OUR
+// hook script - a project that has its own unrelated PermissionRequest/
+// PreToolUse hooks configured is left alone rather than silently
+// appending a second, possibly conflicting one under the same event.
+function alreadyRegistered(existingHooksForEvent) {
+  if (!Array.isArray(existingHooksForEvent) || existingHooksForEvent.length === 0) return false;
+  return existingHooksForEvent.every((entry) =>
+    (entry.hooks || []).some((h) => typeof h.command === 'string' && h.command.includes('onPermissionRequest.js'))
+  );
+}
+
+// Ensures the CURRENT working directory's .claude/settings.json has both
+// hooks pointed at this package's real install location. Called once at
+// the start of every `setu` (bare) run - cheap (a few small file reads/
+// writes), and self-healing if the package is ever moved/reinstalled at a
+// different path (a stale command string gets overwritten with today's
+// real path automatically, no manual fix needed).
+function ensureHooksRegistered(projectDir) {
+  const claudeDir = path.join(projectDir, '.claude');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    // No settings.json yet, or it's not valid JSON - start fresh rather
+    // than crash; an unreadable existing file is left untouched below by
+    // simply not being parsed further, but we still want `setu` itself to
+    // keep working for this session's approval detection.
+  }
+
+  settings.hooks = settings.hooks || {};
+
+  let changed = false;
+  // PostToolUse (new) - fires once a tool call actually runs, which can
+  // only happen after its PermissionRequest was answered somehow (locally
+  // at the keyboard or remotely from the phone). This is what lets
+  // supervisor.js detect "answered locally" and stop a phone's card from
+  // being stuck pending forever - see onPermissionRequest.js's own
+  // comment on why this event specifically.
+  for (const event of ['PermissionRequest', 'PreToolUse', 'PostToolUse']) {
+    if (!alreadyRegistered(settings.hooks[event])) {
+      // Merge, don't replace - a project's own unrelated hooks for this
+      // event (if any) are kept; ours is appended alongside them.
+      settings.hooks[event] = [...(settings.hooks[event] || []), hookEntry()];
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    console.log('[setu] Registered the approval-detection hook in .claude/settings.json');
+  }
+}
+
+module.exports = { ensureHooksRegistered };

package/src/onPermissionRequest.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// The PermissionRequest hook handler. Claude Code invokes this script and
+// pipes the event payload to its stdin every time a tool call needs a
+// permission decision - BEFORE the prompt is shown to the user. This
+// script only OBSERVES (logs) - it deliberately never returns a
+// "decision" object, so the real prompt still shows normally.
+// Auto-approving here would defeat the whole point of a remote approval
+// system.
+//
+// Registered into each project's own .claude/settings.json by
+// src/hooks.js, pointing at THIS script's real location inside the
+// globally-installed cli-setu package (not copied per-project).
+const fs = require('fs');
+const path = require('path');
+const { CONFIG_DIR } = require('./config');
+const { queueFileFor } = require('./cli-adapters/claude').approvals;
+
+const LOG_FILE = path.join(CONFIG_DIR, 'hook-events.log');
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function main() {
+  const raw = readStdinSync();
+  const receivedAt = new Date().toISOString();
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch (err) {
+    fs.appendFileSync(LOG_FILE, `[${receivedAt}] PARSE_ERROR: ${err.message} | raw="${raw}"\n`);
+    process.exit(0);
+  }
+
+  const summary = {
+    receivedAt,
+    hook_event_name: event.hook_event_name,
+    tool_name: event.tool_name,
+    tool_input: event.tool_input,
+    session_id: event.session_id,
+    cwd: event.cwd,
+    permission_mode: event.permission_mode,
+  };
+
+  fs.appendFileSync(LOG_FILE, JSON.stringify(summary) + '\n');
+
+  // Signal the supervisor for PermissionRequest (a new prompt to relay)
+  // AND PostToolUse (real gap found by testing: a prompt answered
+  // directly at the laptop's own keyboard - never via the phone at all -
+  // left the phone's card stuck "pending" forever, since nothing ever
+  // told the Backend the tool actually ran. PostToolUse only fires once
+  // the tool call actually executes, which can only happen after ITS
+  // permission prompt was answered somehow, locally or remotely - so
+  // supervisor.js treats a PostToolUse for a tool_name/session_id it's
+  // still holding pending as proof that prompt is resolved, see
+  // resolveIfPending() there). PreToolUse is still observed (logged
+  // above) but not written to the queue - it fires on EVERY tool call,
+  // not just ones that will show a prompt, and would make the supervisor
+  // try to resolve prompts that were never actually pending.
+  // queueFileFor(CONFIG_DIR, event.cwd) must resolve to the exact same
+  // path supervisor.js's own QUEUE_FILE does - both call the SAME
+  // function from cli-adapters/claude.js rather than each computing
+  // their own copy of this path, so they can never drift apart.
+  if (event.hook_event_name === 'PermissionRequest' || event.hook_event_name === 'PostToolUse') {
+    // Real bug found by testing: a broken queueFileFor import here threw
+    // silently - Claude Code invokes this script as a subprocess with no
+    // visible stderr, so the exception vanished with zero indication
+    // anywhere that the queue write never happened. Catching and logging
+    // it explicitly means a future regression here shows up in
+    // hook-events.log instead of silently breaking the whole relay chain.
+    try {
+      fs.appendFileSync(queueFileFor(CONFIG_DIR, event.cwd), JSON.stringify(summary) + '\n');
+    } catch (err) {
+      fs.appendFileSync(LOG_FILE, `[${receivedAt}] QUEUE_WRITE_ERROR: ${err.message}\n`);
+    }
+  }
+
+  // Deliberately exit 0 with NO stdout decision object.
+  // Per current docs, exit code 2 is ignored for PermissionRequest anyway -
+  // only a JSON `decision` on stdout can gate it, and we never emit one.
+  process.exit(0);
+}
+
+main();