@longleash/cli 0.1.0-rc.1

package/runtime/daemon/hooks/agent-pid.mjs

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process'
+
+/**
+ * The agent process this hook belongs to, found by walking up the process tree.
+ *
+ * Hooks are spawned through a shell, so the immediate parent is usually `sh` — climb a few
+ * levels and take the first ancestor that is actually the agent. This is what makes Stop on a
+ * phone end a real process instead of being decoration.
+ *
+ * Shared by every agent's hook and matched against the agent's OWN name. The Codex hook
+ * originally reported no pid at all, so `stop()` saw `pid === null` and refused every single
+ * time — the phone's Stop button did nothing, forever, with nothing to explain why.
+ *
+ * @param {RegExp} matcher matches the ancestor's command line, e.g. /\bcodex\b/
+ * @returns {number | null}
+ */
+export function findAgentPid(matcher) {
+  let pid = process.ppid
+  for (let hop = 0; hop < 6 && pid > 1; hop += 1) {
+    let line
+    try {
+      line = execFileSync('ps', ['-o', 'ppid=,command=', '-p', String(pid)], {
+        encoding: 'utf8',
+        timeout: 1500,
+      }).trim()
+    } catch {
+      return null
+    }
+    const match = line.match(/^\s*(\d+)\s+(.*)$/)
+    if (!match) return null
+    if (matcher.test(match[2])) return pid
+    pid = Number(match[1])
+  }
+  return null
+}

package/runtime/daemon/hooks/install-codex-hooks.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Installs the LongLeash hook into Codex CLI's ~/.codex/config.toml.
+ *
+ *   node hooks/install-codex-hooks.mjs            install (or verify already installed)
+ *   node hooks/install-codex-hooks.mjs --remove   uninstall cleanly
+ *
+ * Three things make this different from the Claude installer, and each one is a
+ * decision rather than an accident:
+ *
+ *  1. **It is a surgical text edit, not a parse-and-rewrite.** This is the person's
+ *     real config, with their comments and their formatting. A round-trip through a
+ *     TOML serialiser would silently reformat a file we were only asked to add two
+ *     lines to. Our lines live between markers so removal is exact.
+ *
+ *  2. **It refuses on old Codex versions.** Codex hooks do not fire below the known
+ *     working version — the config parses and then does nothing, with no warning.
+ *     A hook that is "installed" and silently inert is worse than one that was never
+ *     installed, because the person concludes LongLeash is broken.
+ *
+ *  3. **It explains Codex's hook-trust prompt instead of evading it.** Codex will ask
+ *     the person to review the new hook on next start. There is a flag to bypass that;
+ *     we will not use it and will not tell anyone else to.
+ */
+import { execFileSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`
+const HOOK_COMMAND = `${shellQuote(process.execPath)} ${shellQuote(resolve(here, 'longleash-codex-hook.mjs'))}`
+const CONFIG = process.env.CODEX_HOME
+  ? join(process.env.CODEX_HOME, 'config.toml')
+  : join(homedir(), '.codex', 'config.toml')
+
+const BEGIN = '# >>> LongLeash — managed block, edits between these markers are overwritten'
+const END = '# <<< LongLeash'
+
+/**
+ * The oldest Codex known to actually run hooks. 0.147.0 was verified working and
+ * 0.136.0 verified silently inert; the boundary between them has not been bisected,
+ * so this sits at the proven-good end. Refusing a version that might have worked
+ * costs someone one upgrade; accepting one that does not costs them their trust.
+ */
+const MIN_CODEX = [0, 147, 0]
+
+const removing = process.argv.includes('--remove')
+
+function codexVersion() {
+  let out
+  try {
+    out = execFileSync('codex', ['--version'], { encoding: 'utf8', timeout: 10_000 })
+  } catch {
+    return null // not installed, or not on PATH
+  }
+  const m = out.match(/(\d+)\.(\d+)\.(\d+)/)
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+}
+
+const isOlder = (a, b) => a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2]
+const show = (v) => v.join('.')
+
+/** Remove a previously installed block, wherever it sits, leaving the rest untouched. */
+function stripOurBlock(text) {
+  const begin = text.indexOf(BEGIN)
+  if (begin === -1) return text
+  const end = text.indexOf(END, begin)
+  if (end === -1) return text
+  // Codex records hook-review state in a [hooks.state] table. Current Codex may insert
+  // that table before our closing comment. It belongs to Codex/the user, not to us, so
+  // an update or uninstall must never erase it with our managed lines.
+  const inside = text.slice(begin + BEGIN.length, end)
+  const stateAt = inside.search(/^\[hooks\.state\][ \t]*$/m)
+  const state = stateAt === -1 ? '' : inside.slice(stateAt).trim()
+  const after = end + END.length
+  const trailingNewline = text[after] === '\n' ? 1 : 0
+  const stripped = text.slice(0, begin) + text.slice(after + trailingNewline)
+  if (state === '' || /^\[hooks\.state\][ \t]*$/m.test(stripped)) return stripped
+  const base = stripped.replace(/\s*$/, '')
+  return `${base}${base === '' ? '' : '\n\n'}${state}\n`
+}
+
+/**
+ * `withHeader` when we are the ones creating the `[hooks]` table. It has to live
+ * INSIDE the markers, or --remove strips our keys and leaves an orphan header behind —
+ * a file that no longer matches the one we were handed.
+ */
+function ourBlock(withHeader) {
+  return [
+    BEGIN,
+    ...(withHeader ? ['[hooks]'] : []),
+    '# SessionStart tells LongLeash a Codex session exists.',
+    '# PermissionRequest is the decision itself — Codex fires it only when it has',
+    '# already decided it needs a human, so LongLeash never has to guess.',
+    'SessionStart = [{ hooks = [{ type = "command", command = ' + JSON.stringify(HOOK_COMMAND) + ', timeoutSec = 5 }] }]',
+    'SessionEnd = [{ hooks = [{ type = "command", command = ' + JSON.stringify(HOOK_COMMAND) + ', timeoutSec = 5 }] }]',
+    '# PreToolUse only observes activity, so already-running VS Code sessions are visible.',
+    'PreToolUse = [{ hooks = [{ type = "command", command = ' + JSON.stringify(`${HOOK_COMMAND} --observe`) + ', timeoutSec = 5 }] }]',
+    'PermissionRequest = [{ hooks = [{ type = "command", command = ' + JSON.stringify(HOOK_COMMAND) + ', timeoutSec = 180 }] }]',
+    END,
+  ].join('\n')
+}
+
+if (!removing) {
+  const version = codexVersion()
+  if (version === null) {
+    console.error('Codex CLI was not found on PATH. Install it first, then run this again.')
+    console.error('Nothing was changed.')
+    process.exit(1)
+  }
+  if (isOlder(version, MIN_CODEX)) {
+    console.error(`Codex ${show(version)} is installed, but its hooks do not fire.`)
+    console.error(`LongLeash needs Codex ${show(MIN_CODEX)} or newer to see Codex sessions.`)
+    console.error('')
+    console.error('This is not a guess: on older builds the configuration is accepted and then')
+    console.error('silently ignored, which would leave LongLeash looking installed and broken.')
+    console.error('')
+    console.error('  Update with:  codex update')
+    console.error('')
+    console.error('Nothing was changed. Claude Code sessions are unaffected.')
+    process.exit(1)
+  }
+}
+
+let text = ''
+if (existsSync(CONFIG)) {
+  text = readFileSync(CONFIG, 'utf8')
+  const backup = `${CONFIG}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`
+  copyFileSync(CONFIG, backup)
+  console.log(`Backed up ${CONFIG} to ${backup}`)
+} else {
+  mkdirSync(dirname(CONFIG), { recursive: true })
+}
+
+const withoutOurs = stripOurBlock(text)
+
+if (removing) {
+  // Our block was appended after a blank line, so removing it leaves that blank behind.
+  // Normalise to exactly one trailing newline — the shape the file had before we touched
+  // it. "Uninstall" has to mean the file is genuinely as it was found.
+  const restored = withoutOurs.replace(/\s*$/, '')
+  writeFileSync(CONFIG, restored === '' ? '' : `${restored}\n`)
+  console.log('LongLeash hooks removed from Codex. Codex sessions are invisible to the phone again.')
+  process.exit(0)
+}
+
+// TOML forbids declaring the same table twice, so where our keys go depends on whether
+// the person already has a [hooks] table of their own.
+const hasHooksHeader = /^[ \t]*\[hooks\][ \t]*$/m.test(withoutOurs)
+const hasHooksSubtable = [...withoutOurs.matchAll(/^[ \t]*\[hooks\.([^\]]+)\][ \t]*$/gm)]
+  // Codex owns both the parent table and one quoted child table per reviewed hook.
+  // They can be moved out of our managed block during an update, but they are review
+  // receipts rather than competing hook definitions and must not make the update refuse.
+  .some((match) => match[1] !== 'state' && !match[1]?.startsWith('state.'))
+const hasDottedHooks = /^[ \t]*hooks\.[A-Za-z]/m.test(withoutOurs)
+
+if (hasHooksSubtable || hasDottedHooks) {
+  console.error(`${CONFIG} already defines Codex hooks in a form this installer will not edit safely.`)
+  console.error('Rather than risk corrupting your config, add these two lines to your [hooks] table')
+  console.error('by hand:')
+  console.error('')
+  for (const line of ourBlock().split('\n')) {
+    if (!line.startsWith('#')) console.error(`  ${line}`)
+  }
+  console.error('')
+  console.error('Nothing was changed.')
+  process.exit(1)
+}
+
+let next
+if (hasHooksHeader) {
+  // Insert our keys directly beneath their existing [hooks] header, which stays theirs.
+  next = withoutOurs.replace(/^([ \t]*\[hooks\][ \t]*)$/m, `$1\n${ourBlock(false)}`)
+} else {
+  const body = withoutOurs.replace(/\s*$/, '')
+  next = `${body}${body === '' ? '' : '\n\n'}${ourBlock(true)}\n`
+}
+
+writeFileSync(CONFIG, next.endsWith('\n') ? next : `${next}\n`)
+
+console.log('LongLeash hooks installed for Codex lifecycle, discovery, and permissions.')
+console.log('Terminal and VS Code sessions appear on your phone, including already-running sessions.')
+console.log('At a laptop prompt, press L to return immediately to Codex\'s native prompt.')
+console.log('')
+console.log('Two things Codex will ask you, both expected:')
+console.log('  1. "Hooks need review" — say yes, or the hook will not run.')
+console.log('  2. "Do you trust the contents of this directory?" — hooks only load in trusted folders.')
+console.log('')
+console.log('Already-running codex sessions pick this up on their next restart.')

package/runtime/daemon/hooks/install-hooks.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Installs the LongLeash hook into ~/.claude/settings.json — with a backup, idempotently,
+ * and without touching anything else in the file.
+ *
+ *   node hooks/install-hooks.mjs            install (or verify already installed)
+ *   node hooks/install-hooks.mjs --remove   uninstall cleanly
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`
+const HOOK_COMMAND = `${shellQuote(process.execPath)} ${shellQuote(resolve(here, 'longleash-hook.mjs'))}`
+const SETTINGS = join(homedir(), '.claude', 'settings.json')
+const EVENTS = {
+  SessionStart: [{ matcher: '*', command: HOOK_COMMAND, timeout: 5 }],
+  // PermissionRequest means Claude Code itself was about to render a permission dialog.
+  PermissionRequest: [{ matcher: '*', command: HOOK_COMMAND, timeout: 180 }],
+  PreToolUse: [
+    // AskUserQuestion is not a permission, so PermissionRequest never sees it.
+    { matcher: 'AskUserQuestion', command: HOOK_COMMAND, timeout: 180 },
+    // An observer makes already-running/auto-mode VS Code sessions discoverable without
+    // ever returning a decision or holding up the tool call.
+    { matcher: '*', command: `${HOOK_COMMAND} --observe`, timeout: 5, async: true },
+  ],
+  SessionEnd: [{ matcher: '*', command: HOOK_COMMAND, timeout: 5 }],
+}
+
+const removing = process.argv.includes('--remove')
+
+let settings = {}
+if (existsSync(SETTINGS)) {
+  try {
+    settings = JSON.parse(readFileSync(SETTINGS, 'utf8'))
+  } catch {
+    console.error(`Refusing to touch ${SETTINGS}: it is not valid JSON. Fix it first.`)
+    process.exit(1)
+  }
+  const backup = `${SETTINGS}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`
+  copyFileSync(SETTINGS, backup)
+  console.log(`Backed up settings to ${backup}`)
+} else {
+  mkdirSync(dirname(SETTINGS), { recursive: true })
+}
+
+settings.hooks ??= {}
+const ours = (entry) => entry?.hooks?.some((h) => String(h.command ?? '').includes('longleash-hook'))
+
+for (const [name, configs] of Object.entries(EVENTS)) {
+  const list = Array.isArray(settings.hooks[name]) ? settings.hooks[name] : []
+  const kept = list.filter((entry) => !ours(entry))
+  if (!removing) {
+    for (const config of configs) {
+      const { matcher, command, timeout, async } = config
+      kept.push({
+        matcher,
+        hooks: [{ type: 'command', command, timeout, ...(async === true ? { async: true } : {}) }],
+      })
+    }
+  }
+  if (kept.length > 0) settings.hooks[name] = kept
+  else delete settings.hooks[name]
+}
+if (Object.keys(settings.hooks).length === 0) delete settings.hooks
+
+writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n')
+
+if (removing) {
+  console.log('LongLeash hooks removed. Terminal sessions are invisible to the phone again.')
+} else {
+  console.log('LongLeash hooks installed for lifecycle, permissions, and questions.')
+  console.log('Terminal and VS Code sessions appear on your phone, including sessions')
+  console.log('that were already running when LongLeash started.')
+  console.log('At a laptop prompt, press L to return immediately to the native prompt.')
+}

package/runtime/daemon/hooks/local-handoff.mjs

@@ -0,0 +1,47 @@
+import { openSync } from 'node:fs'
+import { ReadStream, WriteStream } from 'node:tty'
+
+/**
+ * Give a person at the terminal an immediate path back to the agent's native prompt.
+ * Raw mode matters: a line-buffered `/dev/tty` competes poorly with the parent TUI and can
+ * swallow the first key. This owns one keystroke, then restores the terminal before returning.
+ */
+export function laptopHandoff(surface) {
+  const never = new Promise(() => {})
+  if (
+    surface !== 'terminal' ||
+    process.env.LONGLEASH_LOCAL_HANDOFF === 'off' ||
+    process.platform === 'win32'
+  ) return { promise: never, close() {} }
+
+  let input
+  let output
+  let settled = false
+  let resolveHandoff
+  const promise = new Promise((resolve) => { resolveHandoff = resolve })
+  const close = () => {
+    if (settled) return
+    settled = true
+    try { input?.setRawMode(false) } catch {}
+    input?.destroy()
+    output?.end()
+  }
+  try {
+    input = new ReadStream(openSync('/dev/tty', 'r'))
+    output = new WriteStream(openSync('/dev/tty', 'w'))
+    input.setRawMode(true)
+    input.resume()
+    input.once('data', () => {
+      if (!settled) resolveHandoff()
+    })
+    input.once('error', close)
+    output.once('error', close)
+    output.write(
+      '\nLongLeash mirrored this request to your phone. Press L to decide on this laptop now.\n',
+    )
+  } catch {
+    close()
+    return { promise: never, close() {} }
+  }
+  return { promise, close }
+}

package/runtime/daemon/hooks/longleash-codex-hook.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/** LongLeash's Codex CLI hook. Every failure exits 0 with no opinion. */
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { detectSurface } from './surface.mjs'
+import { findAgentPid } from './agent-pid.mjs'
+import { laptopHandoff } from './local-handoff.mjs'
+
+function dedupeKey(event) {
+  if (typeof event.tool_use_id === 'string' && event.tool_use_id !== '') return event.tool_use_id
+  const turn = typeof event.turn_id === 'string' ? event.turn_id : ''
+  if (turn === '') return null
+  let input = ''
+  try {
+    input = JSON.stringify(event.tool_input) ?? ''
+  } catch {
+    return null
+  }
+  const fingerprint = createHash('sha256').update(`${event.tool_name ?? ''}\0${input}`).digest('base64url')
+  return `${turn}:${fingerprint.slice(0, 22)}`
+}
+
+async function main() {
+  if (process.env.LONGLEASH_MANAGED === '1') return
+  const raw = await readStdin()
+  let event
+  try {
+    event = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  const observe = process.argv.includes('--observe')
+  const name = event.hook_event_name
+  if (observe && name !== 'PreToolUse') return
+  if (!observe && name !== 'PermissionRequest' && name !== 'SessionStart' && name !== 'SessionEnd') return
+
+  let endpoint
+  try {
+    const dataDir = process.env.LONGLEASH_DATA ?? join(homedir(), '.longleash')
+    endpoint = JSON.parse(readFileSync(join(dataDir, 'hook-endpoint.json'), 'utf8'))
+  } catch {
+    return
+  }
+  if (!endpoint?.url || !endpoint?.secret) return
+
+  const asking = !observe && name === 'PermissionRequest'
+  const surface = detectSurface(process.env)
+  const pid = findAgentPid(/\bcodex\b/)
+  const key = dedupeKey(event)
+  const body = JSON.stringify({
+    ...event,
+    hook_event_name: observe ? 'SessionObserved' : name,
+    ll_agent: 'codex',
+    ll_surface: surface,
+    ...(pid === null ? {} : { ll_pid: pid }),
+    ...(key === null ? {} : { ll_dedupe: key }),
+  })
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), asking ? 150_000 : 3_000)
+  timer.unref?.()
+  const handoff = asking ? laptopHandoff(surface) : { promise: new Promise(() => {}), close() {} }
+  let outcome
+  try {
+    outcome = await Promise.race([
+      fetch(endpoint.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-longleash-hook': endpoint.secret },
+        body,
+        signal: controller.signal,
+      }).then((response) => ({ kind: 'response', response })),
+      handoff.promise.then(() => ({ kind: 'laptop' })),
+    ])
+  } catch {
+    return
+  } finally {
+    clearTimeout(timer)
+    handoff.close()
+  }
+  if (outcome.kind === 'laptop') {
+    controller.abort()
+    return
+  }
+  const response = outcome.response
+  if (!response.ok || !asking) return
+
+  let verdict
+  try {
+    verdict = await response.json()
+  } catch {
+    return
+  }
+  if (verdict.decision !== 'allow' && verdict.decision !== 'deny') return
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PermissionRequest',
+      decision: {
+        behavior: verdict.decision,
+        message: String(verdict.reason ?? 'Decided from your phone'),
+      },
+    },
+  }))
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => { data += chunk })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+  })
+}
+
+main().catch(() => {}).finally(() => process.exit(0))

package/runtime/daemon/hooks/longleash-hook.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * LongLeash's Claude Code hook.
+ *
+ * PermissionRequest is the source of truth for real permission prompts. PreToolUse is
+ * only synchronous for AskUserQuestion (which needs input rather than permission), and
+ * is also installed as an async observer so an already-running VS Code session becomes
+ * visible without stealing control from it.
+ *
+ * The iron rule is graceful degradation: if LongLeash is absent, slow, or unreachable,
+ * this exits 0 without a decision and Claude Code's native prompt takes over.
+ */
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { detectSurface } from './surface.mjs'
+import { findAgentPid } from './agent-pid.mjs'
+import { laptopHandoff } from './local-handoff.mjs'
+
+async function main() {
+  // A Codex/Claude process launched and owned by LongLeash already has a structured
+  // adapter. Letting its user hooks report it again creates a duplicate ghost session.
+  if (process.env.LONGLEASH_MANAGED === '1') return
+
+  const raw = await readStdin()
+  let event
+  try {
+    event = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  const observe = process.argv.includes('--observe')
+  const name = event.hook_event_name
+  if (observe && name !== 'PreToolUse') return
+  const askingQuestion = name === 'PreToolUse' && event.tool_name === 'AskUserQuestion'
+  const askingPermission = name === 'PermissionRequest'
+  if (!observe && !askingQuestion && !askingPermission && name !== 'SessionStart' && name !== 'SessionEnd') {
+    return
+  }
+
+  let endpoint
+  try {
+    const dataDir = process.env.LONGLEASH_DATA ?? join(homedir(), '.longleash')
+    endpoint = JSON.parse(readFileSync(join(dataDir, 'hook-endpoint.json'), 'utf8'))
+  } catch {
+    return
+  }
+  if (!endpoint?.url || !endpoint?.secret) return
+
+  const surface = detectSurface(process.env)
+  const pid = findAgentPid(/\bclaude\b/)
+  const body = JSON.stringify({
+    ...event,
+    hook_event_name: observe ? 'SessionObserved' : name,
+    ll_agent: 'claude',
+    ll_surface: surface,
+    ...(pid === null ? {} : { ll_pid: pid }),
+  })
+  const asking = !observe && (askingPermission || askingQuestion)
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), asking ? 150_000 : 3_000)
+  timer.unref?.()
+  const handoff = asking ? laptopHandoff(surface) : { promise: new Promise(() => {}), close() {} }
+
+  let outcome
+  try {
+    outcome = await Promise.race([
+      fetch(endpoint.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-longleash-hook': endpoint.secret },
+        body,
+        signal: controller.signal,
+      }).then((response) => ({ kind: 'response', response })),
+      handoff.promise.then(() => ({ kind: 'laptop' })),
+    ])
+  } catch {
+    return
+  } finally {
+    clearTimeout(timer)
+    handoff.close()
+  }
+
+  if (outcome.kind === 'laptop') {
+    controller.abort()
+    return // no opinion: Claude Code renders its native prompt immediately
+  }
+  const response = outcome.response
+  if (!response.ok || !asking) return
+
+  let verdict
+  try {
+    verdict = await response.json()
+  } catch {
+    return
+  }
+  if (verdict.decision !== 'allow' && verdict.decision !== 'deny') return
+
+  if (askingPermission) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PermissionRequest',
+          decision: {
+            behavior: verdict.decision,
+            ...(verdict.decision === 'deny'
+              ? { message: String(verdict.reason ?? 'Denied from your phone') }
+              : {}),
+          },
+        },
+      }),
+    )
+    return
+  }
+
+  const answers = verdict.answers
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: verdict.decision,
+        permissionDecisionReason: String(verdict.reason ?? 'Answered from your phone'),
+        ...(verdict.decision === 'allow' && answers && typeof answers === 'object'
+          ? { updatedInput: { ...(event.tool_input ?? {}), answers } }
+          : {}),
+        ...(verdict.decision === 'allow' && typeof verdict.additionalContext === 'string'
+          ? { additionalContext: verdict.additionalContext }
+          : {}),
+      },
+    }),
+  )
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => {
+      data += chunk
+    })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+  })
+}
+
+main()
+  .catch(() => {})
+  .finally(() => process.exit(0))

package/runtime/daemon/hooks/surface.mjs

@@ -0,0 +1,41 @@
+/**
+ * Where a session is being driven from: a plain terminal, or inside VS Code.
+ *
+ * Shared by every agent's hook, and deliberately agent-agnostic. VS Code exports these
+ * variables to ANYTHING it spawns, so this works for Codex, and for whatever CLI we support
+ * next, without needing to learn that agent's private conventions first. An agent-specific
+ * signal is only ever a refinement on top.
+ *
+ * Why it matters: a person running four sessions needs to know which one is the terminal on
+ * their left monitor and which is the editor on their right. Without it, the inbox is four
+ * identical rows and every decision starts with "which one is this?"
+ */
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @returns {'vscode' | 'terminal'}
+ */
+export function detectSurface(env) {
+  // Agent-specific, and the most precise signal available: Claude Code distinguishes its
+  // VS Code extension from a shell that merely happens to be running inside VS Code.
+  const entrypoint = env.CLAUDE_CODE_ENTRYPOINT ?? ''
+  if (/vscode|extension/i.test(entrypoint)) return 'vscode'
+  /**
+   * The editor's own name for itself. This is the signal that catches the VS Code forks:
+   * Cursor ships bundle id `com.todesktop.230313mzl4w4u92`, which contains nothing
+   * recognisable, so matching on the bundle id alone silently classifies it as a terminal.
+   * `TERM_PROGRAM` is what it actually sets.
+   */
+  if (/^(vscode|cursor|windsurf|vscodium|trae|positron)/i.test(env.TERM_PROGRAM ?? '')) return 'vscode'
+
+  // Agent-agnostic. VS Code (and every fork of it) sets these for each child process it
+  // creates, which is why this branch covers CLIs we have never integrated with.
+  if (env.VSCODE_PID || env.VSCODE_IPC_HOOK || env.VSCODE_CWD) return 'vscode'
+
+  const bundle = (env.__CFBundleIdentifier ?? '').toLowerCase()
+  if (bundle.includes('vscode') || bundle.includes('vscodium') || bundle.includes('windsurf')) {
+    return 'vscode'
+  }
+
+  return 'terminal'
+}