Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

24.4 KB
Raw Blame
// Per-agent translation of nodeterm's permission mode into the agent's own approval flag.
//
// claude and grok share one spelling and one vocabulary, which is why they needed no mapping at all
// until now. gemini and codex each have their own, and BOTH are narrower than ours — which is the
// interesting case: our five modes fit neither `default|auto_edit|yolo|plan` nor
// `untrusted|on-request|never`, so a mode the CLI cannot express emits NO flag (its own default)
// rather than a nearest match. A silent substitution would show the user "Plan" while codex ran in
// on-request, or "Auto" while gemini auto-approved every file edit.
//
// Measured: `gemini --help` (0.54.4) and `codex --help` (0.146.0 … 0.154.0). `--sandbox` is
// deliberately not touched: it is a separate axis (read-only | workspace-write |
// danger-full-access), and folding `danger-full-access` into `bypassPermissions` would widen
// filesystem access invisibly — `--ask-for-approval never` on its own still sandboxes.
//
// AND ONE AGENT'S VOCABULARY IS NOT A CONSTANT. codex accepted `untrusted|on-request|never`
// through 0.148.0 and accepts `on-request|never` from 0.149.0 on — measured release by release,
// see `CODEX_APPROVAL_BASELINE`. clap does not ignore a value it does not know, it EXITS, so a
// table pinned to one release is not a stale mapping, it is a dead node. Every value this module
// emits is therefore checked against what the CLI that will actually run the session says it
// takes (`ApprovalCaps`), and a value we have not seen it advertise is never emitted.
import {
  AGENT_CONFIG,
  ALL_PERMISSION_MODES,
  PERMISSION_MODE_CAPABLE,
  PERMISSION_MODE_LABELS,
  hasPermissionMode,
  isPermissionMode,
  permissionModeFlag,
  type AgentId,
  type AgentPermissionMode,
  type BuiltinAgentId
} from './config'
import { argvHasFlag } from '../shell-quote'

/**
 * What we know about the CLI that will actually RUN this session — the facts that decide whether a
 * value in the tables below may be emitted at all.
 *
 * Optional and empty-by-default ON PURPOSE. A caller that passes nothing gets the baseline
 * vocabulary, which is the safe answer everywhere: the launch keeps working, at worst one mode
 * degrades to the CLI's own default (and the derived UI copy says so). A caller that forgets to
 * pass its probe result therefore costs a mode, never a dead pane — which is the only degrade
 * direction this file accepts.
 */
export interface ApprovalCaps {
  /** The values this machine's (or this host's) `codex` advertises for `--ask-for-approval`, read
   *  from its own `--help` — see `core/codex-cli.ts`. `null`/absent = not probed, not probeable
   *  (a remote host, a relay tab), or the probe failed. */
  codexApprovalValues?: readonly string[] | null
  /** Does the `codex` that will RUN this session accept `--no-daemon`? Read by
   *  `withCodexNoDaemon` (`./codex-daemon`), not by anything in this file: the caps bag is simply
   *  what every launch site already threads to the two command assemblers. Anything but a literal
   *  `true` (a remote host, a relay tab, an unprobed or older CLI) emits nothing. */
  codexNoDaemon?: boolean | null
}

/**
 * The `--ask-for-approval` values EVERY codex we have measured accepts, and therefore the answer
 * when we do not know which codex will run.
 *
 * Measured one release at a time on real binaries (`@openai/codex@<v>-linux-x64`, `--help`):
 * 0.146.0 · 0.147.0 · 0.148.0 advertise `untrusted, on-request, never`; 0.149.0 · 0.150.0 ·
 * 0.151.0 · 0.152.0 · 0.153.0 · 0.154.0 advertise `on-request, never`. So `untrusted` was removed
 * in **0.149.0** — five releases before the one issue #785 reported it from — and `on-request` /
 * `never` are common to every one of them.
 *
 * `untrusted` is deliberately NOT in the baseline. An unknown value does not degrade: clap answers
 *
 *   error: invalid value 'untrusted' for '--ask-for-approval <APPROVAL_POLICY>'
 *
 * and exits, so the pane is left at a bare shell with the launch dead (issue #785). A value we
 * have not SEEN this CLI advertise is never emitted; the two we have seen on every measured
 * release are what an unprobed launch falls back to, because that is the command line nodeterm has
 * always sent for those modes.
 */
const CODEX_APPROVAL_BASELINE: readonly string[] = ['on-request', 'never']

/** One agent's approval dialect: the flag it spells, and the values it accepts. ONE fact per agent —
 *  a flag and a table maintained separately is how a third agent added to the table silently emits
 *  the second agent's flag. */
interface ApprovalDialect {
  flag: string
  modes: Partial<Record<AgentPermissionMode, string>>
  /**
   * Optional boolean switch emitted instead of `[flag, value]` for modes that use a standalone flag
   * (antigravity's `--dangerously-skip-permissions` alongside `--mode accept-edits|auto|plan`).
   */
  standaloneFlags?: Partial<Record<AgentPermissionMode, string>>
  /**
   * Does this CLI's OWN default already prompt before every action?
   *
   * This is what decides whether `manual` ("Ask each time") is honoured by emitting NOTHING. For
   * gemini it is true — its `default` mode is documented as "prompt for approval" — so the bare
   * command already keeps the promise. For codex it is false: its built-in default is
   * `on-request`, "the model decides when to ask", so an unflagged codex delivers something else
   * entirely under that label. Kept as a per-agent fact rather than a special case in
   * `modeSupported`, because it is a property of the CLI, not of the mode.
   */
  manualIsDefault: boolean
  /** The values this CLI accepts, when that is version-dependent. `undefined` = every value in
   *  `modes` is stable across the releases we have measured, so the table alone decides (gemini).
   *  Only codex has one — see `CODEX_APPROVAL_BASELINE`. */
  vocabulary?: (caps: ApprovalCaps) => readonly string[]
  /** What this CLI actually does when `manual` turns out to be inexpressible, for the UI note.
   *  Lives beside the table so the sentence cannot drift from it. */
  manualGapNote?: string
  /** argv for a table value. Default `[flag, value]`. Only for a CLI whose modes are DIFFERENT
   *  flags rather than values of one (cursor: `--mode plan` but a bare `--force`). */
  spell?: (value: string) => string[]
}

const GEMINI_MODES: Partial<Record<AgentPermissionMode, string>> = {
  plan: 'plan',
  acceptEdits: 'auto_edit',
  bypassPermissions: 'yolo'
  // `manual` → gemini's own `default`, i.e. NO flag, exactly as it is for claude.
  //
  // `auto` is ABSENT ON PURPOSE, and it is the one absence worth explaining, because `auto` is
  // `DEFAULT_PERMISSION_MODE` — so this decides what an untouched install launches gemini with.
  // gemini's vocabulary is exactly `default|auto_edit|yolo|plan`; none of those means "approve most
  // things but NOT edits", which is what our `auto` promises. The nearest value, `auto_edit`, is
  // documented as "auto-approve edit tools" — the opposite end of the one axis the user cares
  // about. Mapping `auto → auto_edit` would therefore have made every existing gemini node start
  // auto-approving file edits on upgrade, silently: before gemini joined PERMISSION_MODE_CAPABLE it
  // always launched bare (= `default` = prompt for approval), and `modeSupported` would have
  // answered `true`, so the derived copy would not have admitted it either. No flag is the honest
  // answer and reproduces the pre-branch launch exactly. See `unsupportedModesNote`.
}

const ANTIGRAVITY_MODES: Partial<Record<AgentPermissionMode, string>> = {
  plan: 'plan',
  acceptEdits: 'accept-edits',
  auto: 'auto'
  // `manual` → agy's own default (no flag).
  // `bypassPermissions` uses the standalone switch `--dangerously-skip-permissions`
  // (`standaloneFlags` below), measured on `agy --help` (1.2.7).
}

const CODEX_MODES: Partial<Record<AgentPermissionMode, string>> = {
  // codex is the FIRST agent where `manual` emits a flag, and — where the CLI still has the value
  // — it has to. For every other agent `manual` = no flag = a default that already prompts
  // (gemini's own `default` is documented as "prompt for approval"), which is exactly what the
  // label "Ask each time" promises. codex's built-in default is NOT that: measured on 0.146.0 AND
  // re-measured on 0.151.0, `codex doctor` reports `approval policy OnRequest` with no `approval`
  // key in ~/.codex/config.toml — the model decides when to ask. So leaving `manual` unflagged
  // delivers `on-request` under an "ask each time" label, and collapses two dropdown entries onto
  // one behaviour — the same dishonesty this module exists to remove, just expressed as an
  // unflagged claim instead of a substituted flag. `untrusted` is the real equivalent: "only run
  // trusted commands without asking; escalate anything not in the trusted set".
  //
  // THIS ENTRY IS A CANDIDATE, NOT A PROMISE. codex removed `untrusted` in 0.149.0, so on any
  // current CLI it is filtered out by `vocabulary` below and `manual` emits nothing — and
  // `modeSupported` then answers false, so `unsupportedModesNote` admits it instead of the
  // dropdown quietly lying. It stays in the table because a codex <= 0.148.0 is still a codex a
  // user may be running, and on THAT CLI "Ask each time" really is expressible; the probe is what
  // decides, not this file.
  //
  // What was checked before concluding the mode is gone (all on 0.151.0): `-a unless-trusted` —
  // rejected by clap; `-c approval_policy=untrusted` and `-c approval_policy=unless-trusted` —
  // both refused with "config could not be loaded", so the TOML route is not a back door either;
  // `--approve-for-me` — a real flag, but it routes approvals through AUTOMATIC review, which is
  // the opposite of asking the user. 0.149.0+ genuinely cannot express "ask every time".
  manual: 'untrusted',
  auto: 'on-request',
  bypassPermissions: 'never'
  // No `plan` and no edit-specific mode exists in ANY measured codex (0.146.0 … 0.154.0), so
  // `plan` and `acceptEdits` are absent ON PURPOSE — see modeSupported.
}

const CURSOR_MODES: Partial<Record<AgentPermissionMode, string>> = {
  auto: 'auto-review',
  plan: 'plan',
  bypassPermissions: 'force'
  // MEASURED on cursor-agent 2026.09.28-64d2043: the flags reach the session from BEFORE the `agent`
  // subcommand (see AGENT_CONFIG.cursor), and the effect is real, not just a footer label. With
  // `--model composer-2.5 --force agent '<touch a file>'` the shell command ran with no approval
  // prompt and the footer read "Run Everything"; the same command with no mode flag stopped at
  // "Run this command? Not in allowlist: touch"; `--mode plan` answered a "create a file" prompt
  // with a written plan ("Ready to build?") and created nothing.
  //
  // `manual` → cursor's own default, NO flag, and that default really prompts: `approvalMode:
  // "allowlist"` in ~/.cursor/cli-config.json, shell commands off the allowlist stop at a dialog.
  //
  // `auto` → `--auto-review` ("Auto-review (Smart Auto): a server classifier auto-runs safe tool
  // calls and prompts for the rest"). That is the same shape as claude's `--permission-mode auto`
  // (a classifier decides), so it is the honest equivalent, not a nearest match. MEASURED on
  // 2026.10.01-e373342: `--auto-review agent '<touch a file>'` ran `touch` with no prompt and the
  // footer read "Auto-review". `auto` is DEFAULT_PERMISSION_MODE, so this IS what an untouched cursor
  // node launches with. It was first left bare to avoid widening existing nodes at upgrade (the
  // gemini `auto_edit` trap), but cursor ships in this same change, so there are no existing nodes,
  // and the bare allowlist default asked for every command (the user's own report, 2026-10-02).
  // No flag means "auto-approve edits, prompt for shell", so `acceptEdits` has no candidate and
  // `unsupportedModesNote` admits it. `--mode ask` (read-only Q&A) and `--sandbox` (a separate
  // axis, like codex's) are deliberately not touched.
  //
  // `--force` over its alias `--yolo`: same code path ("Run Everything"), and `--force` is the name
  // `--help` gives first.
}

/**
 * The agents that need a translation, flag and vocabulary together.
 *
 * These two used to be separate lookups — a `tableFor` ternary and a `flagFor` ternary whose `else`
 * branch was codex's flag. A third agent added to the table and forgotten in the flag would then
 * have emitted `--ask-for-approval <its own value>`: a wrong flag carrying a right value, i.e. a
 * failed launch, from an edit that looks complete. One record makes that impossible to express.
 *
 * Looked up through `Object.hasOwn`, not `[agentId]`: `AgentId` is OPEN (custom agents carry
 * user-typed ids), so a plain-object index answers `'constructor'` with a Function.
 */
const APPROVAL_DIALECTS: Partial<Record<AgentId, ApprovalDialect>> = {
  gemini: { flag: '--approval-mode', modes: GEMINI_MODES, manualIsDefault: true },
  antigravity: {
    flag: '--mode',
    modes: ANTIGRAVITY_MODES,
    standaloneFlags: { bypassPermissions: '--dangerously-skip-permissions' },
    manualIsDefault: true
  },
  codex: {
    flag: '--ask-for-approval',
    modes: CODEX_MODES,
    manualIsDefault: false,
    vocabulary: (caps) =>
      caps.codexApprovalValues?.length ? caps.codexApprovalValues : CODEX_APPROVAL_BASELINE,
    manualGapNote:
      'That default asks only when the model chooses to: `untrusted`, the policy that meant ' +
      'ask-every-time, was removed in codex-cli 0.149.0 and has no replacement.'
  },
  cursor: {
    flag: '--mode',
    modes: CURSOR_MODES,
    manualIsDefault: true,
    spell: (value) =>
      value === 'force' ? ['--force'] : value === 'auto-review' ? ['--auto-review'] : ['--mode', value]
  }
}

/**
 * The value this dialect may actually EMIT for this mode — the table entry, filtered through what
 * the target CLI says it accepts. `undefined` = emit nothing.
 *
 * `Object.hasOwn`, not `[mode]`, for the same reason `dialectFor` uses it: the callers below
 * validate `mode` with `isPermissionMode` first, and this keeps the lookup honest even so — a
 * plain-object index answers `'constructor'` with a Function, and this value is headed for a shell
 * command line.
 */
function emittableValue(
  dialect: ApprovalDialect,
  mode: AgentPermissionMode,
  caps: ApprovalCaps
): string | undefined {
  const value = Object.hasOwn(dialect.modes, mode) ? dialect.modes[mode] : undefined
  if (!value) return undefined
  if (!dialect.vocabulary) return value
  return dialect.vocabulary(caps).includes(value) ? value : undefined
}

function standaloneFlag(
  dialect: ApprovalDialect,
  mode: AgentPermissionMode
): string | undefined {
  return dialect.standaloneFlags && Object.hasOwn(dialect.standaloneFlags, mode)
    ? dialect.standaloneFlags[mode]
    : undefined
}

const dialectFor = (agentId: AgentId): ApprovalDialect | null =>
  Object.hasOwn(APPROVAL_DIALECTS, agentId) ? APPROVAL_DIALECTS[agentId] ?? null : null

/** Can this agent actually start in this mode? `false` means the launch omits the flag and the
 *  agent uses its own default — surfaced in the UI so the user is not misled. */
export function modeSupported(
  agentId: AgentId,
  mode: AgentPermissionMode,
  caps: ApprovalCaps = {}
): boolean {
  if (!isPermissionMode(mode)) return false
  const dialect = dialectFor(agentId)
  // claude and grok speak our own vocabulary and their defaults prompt: every mode is reachable.
  if (!dialect) return hasPermissionMode(agentId)
  // `manual` — "ask each time" — is reached two different ways, which is why the table alone is
  // not its authority: by emitting NO flag on a CLI whose own default already prompts
  // (`manualIsDefault`: claude, grok, gemini, antigravity), or by emitting a value that means it
  // (codex's `untrusted`). An agent that can do NEITHER cannot keep the promise, and this is where
  // that is admitted — codex >= 0.149.0 is exactly that case, and it is why this early return
  // stopped being an unconditional `true`.
  if (mode === 'manual')
    return dialect.manualIsDefault || emittableValue(dialect, 'manual', caps) !== undefined
  if (standaloneFlag(dialect, mode) !== undefined) return true
  return emittableValue(dialect, mode, caps) !== undefined
}

/**
 * The flags to append for this agent + mode. Empty = the bare command.
 *
 * The mode is re-validated at the top for the same reason `permissionModeFlag` does it: the value
 * comes from hand-editable, git-shared JSON (settings.json / project.json) and is interpolated into
 * a shell command line, so its TYPE proves nothing. Without the guard, a forged `constructor`
 * indexes a plain-object table and hands back a Function — one that would have been stringified
 * onto a tmux `send-keys` line. (`dialectFor` closes the same hole on the agent id.)
 */
export function approvalFlags(
  agentId: AgentId,
  mode: AgentPermissionMode,
  caps: ApprovalCaps = {}
): string[] {
  if (!isPermissionMode(mode)) return []
  const dialect = dialectFor(agentId)
  if (dialect) {
    const sw = standaloneFlag(dialect, mode)
    if (sw) return [sw]
    const value = emittableValue(dialect, mode, caps)
    return value ? (dialect.spell?.(value) ?? [dialect.flag, value]) : []
  }
  // claude + grok keep their exact historical spelling, validated at the interpolation site.
  return hasPermissionMode(agentId) ? permissionModeFlag(mode) : []
}

/**
 * Appends the agent's approval flag to a launch command, if it has one. The single funnel for every
 * CLI launch path (new node, cold-restore resume, branch, handoff, canvas control).
 *
 * WHERE the flag lands is decided one layer up, by `createAgentNode`: with no `argvPromptSeparator`
 * (claude, gemini, codex, antigravity) it goes LAST, keeping those command lines byte-identical;
 * with one (grok's `--`, cursor's `agent`) it must go BEFORE the separator: `--` is end-of-options,
 * and cursor's flags are root options that the `agent` subcommand reads (measured, see CURSOR_MODES).
 *
 * **A flag the command already carries is left alone (issue #601).** `cmd` is not always ours:
 * `settings.agentLaunchCommands` lets the user replace the program part with a wrapper, and a
 * wrapper may spell the approval flag itself. Appending regardless produced
 * `claude --permission-mode bypassPermissions --permission-mode auto` — a duplicate the settings
 * field still displayed as exactly what the user typed, so whichever occurrence the CLI honoured,
 * they had no way to tell which one was in force.
 *
 * The contract this settles is "program only, minus what you spelled yourself", not "the override
 * owns the whole command". The whole-command reading cannot work: the settings copy already
 * promises that `--resume` and friends are appended, and a wrapper has no way to know the session id
 * a cold restore is resuming — so nodeterm has to keep appending. What it must not do is append a
 * SECOND opinion about a flag the user has already stated one about; theirs is the more specific and
 * the more explicit, and it wins.
 *
 * Deliberately not extended to `withAgentModel`: a model switch is a per-node action the user just
 * took, and letting a global launch-command override veto it would silently strand that node on the
 * wrapper's model. Different specificity, opposite answer.
 *
 * A command with no override cannot reach the suppression — nodeterm builds it and never puts the
 * flag in twice — so every existing launch line is byte-identical.
 */
export function withPermissionMode(
  cmd: string,
  id: AgentId,
  mode: AgentPermissionMode,
  caps: ApprovalCaps = {}
): string {
  const flags = approvalFlags(id, mode, caps)
  if (!flags.length) return cmd
  const dialect = dialectFor(id)
  if (dialect) {
    const knownFlags = [flags[0], dialect.flag, ...Object.values(dialect.standaloneFlags ?? {})]
    if (knownFlags.some((f) => f && argvHasFlag(cmd, f))) return cmd
  } else if (argvHasFlag(cmd, flags[0])) {
    return cmd
  }
  return `${cmd} ${flags.join(' ')}`
}

// ---------------------------------------------------------------------------------------------
// UI copy, DERIVED from the mapping above.
//
// The settings description has to name the agents the mode applies to and admit where it does not
// apply, and both facts live in the mapping. Spelling them out in a string literal is how a sentence
// starts telling users that Plan works on an agent that has silently stopped supporting it — a
// sentence that drifts from the mapping is worse than none. So they are computed.
// ---------------------------------------------------------------------------------------------

const agentLabel = (id: AgentId): string =>
  AGENT_CONFIG[id as BuiltinAgentId]?.label ?? id

const joinAnd = (parts: string[]): string =>
  parts.length <= 1
    ? (parts[0] ?? '')
    : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`

/**
 * The agents whose start-up mode we can set, labelled for prose: "Claude Code, Grok, …".
 *
 * `mode` narrows to the agents that can actually express THAT mode (a warning about "Bypass all"
 * must not name an agent the mode never reaches); `exclude` drops one the sentence is already about
 * (claude's version-gate note, whose subject is claude).
 */
export function permissionModeAgentsLabel(opts?: PermissionModeAgentFilter): string {
  return joinAnd(permissionModeAgentIds(opts).map(agentLabel))
}

interface PermissionModeAgentFilter {
  mode?: AgentPermissionMode
  exclude?: readonly AgentId[]
  /** What the target CLIs accept, so a "which agents support this mode?" answer is about the CLIs
   *  the user actually has. Omitted = the baseline, exactly as everywhere else in this file. */
  caps?: ApprovalCaps
}

/**
 * The ids `permissionModeAgentsLabel` will name, under the same filter.
 *
 * Exported so a caller can AGREE with the label grammatically — one agent takes "is", several take
 * "are" — instead of hardcoding a plural that reads as "Grok are unaffected" the day the capable list
 * narrows. Same drift `permissionModeAgentsLabel` exists to prevent, one level down.
 */
export function permissionModeAgentIds(opts?: PermissionModeAgentFilter): AgentId[] {
  return PERMISSION_MODE_CAPABLE.filter(
    (id) =>
      !opts?.exclude?.includes(id) &&
      (opts?.mode === undefined || modeSupported(id, opts.mode, opts.caps ?? {}))
  )
}

/**
 * One sentence per capable agent that cannot express every mode, naming the modes and saying what
 * happens instead. Empty string when there is nothing to admit — so the caller appends it blindly
 * and the sentence disappears by itself the day a CLI grows the missing mode.
 */
export function unsupportedModesNote(caps: ApprovalCaps = {}): string {
  return PERMISSION_MODE_CAPABLE.map((id) => ({
    label: agentLabel(id),
    gaps: ALL_PERMISSION_MODES.filter((m) => !modeSupported(id, m, caps)),
    // Only rendered when `manual` is among the gaps — see below. A generic "starts in its own
    // default" is honest for Plan and Accept edits (nothing was promised about what the default
    // does), but it is NOT enough for "Ask each time": the user picked a promise about every
    // single action, and codex's default keeps none of it. The sentence lives on the dialect so
    // it can only be written where the behaviour it describes is.
    manualGap: dialectFor(id)?.manualGapNote
  }))
    .filter((a) => a.gaps.length > 0)
    .map(({ label, gaps, manualGap }) => {
      const modes = joinAnd(gaps.map((m) => PERMISSION_MODE_LABELS[m]))
      const verb = gaps.length > 1 ? 'have' : 'has'
      const head = `${modes} ${verb} no ${label} equivalent, so ${label} sessions start in ${label}'s own default.`
      return gaps.includes('manual') && manualGap ? `${head} ${manualGap}` : head
    })
    .join(' ')
}

/**
 * Agents where `bypassPermissions` bypasses APPROVALS only, because their sandbox is a separate axis
 * this module deliberately does not touch — codex's `--sandbox`, where `--ask-for-approval never`
 * still sandboxes. Kept beside the mapping that causes it rather than in the component, so the
 * warning copy cannot drift from which agents it is true of.
 */
const SANDBOX_RETAINED: readonly AgentId[] = ['codex']

/** The clause a "Bypass all" warning owes, so "no permission checks" is not read as "no sandbox
 *  either". Empty string when it applies to nobody. */
export function bypassSandboxCaveat(caps: ApprovalCaps = {}): string {
  const ids = permissionModeAgentIds({ mode: 'bypassPermissions', caps }).filter((id) =>
    SANDBOX_RETAINED.includes(id)
  )
  if (!ids.length) return ''
  const label = joinAnd(ids.map(agentLabel))
  return `${label} still ${ids.length > 1 ? 'run' : 'runs'} in its own sandbox — only the approval prompts are skipped.`
}