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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// Generates the managed hook script installed into an agent's own config.
// It sources the endpoint file for the LIVE port/token (restart handoff), no-ops
// outside nodeterm-spawned sessions (gating via NODETERM_NODE_ID), and posts the
// raw hook payload to the loopback server. Fails open at every step.
//
// Endpoint failover: a session's env points at ONE
// endpoint file ($NODETERM_HOOK_ENDPOINT). A Mac-spawned remote session points at the
// reverse-tunnel endpoint the Mac's RemoteHooks wrote; when the Mac is offline that pipe
// is dead and the POST fails silently, so the session goes dark — even when the SAME host
// runs an always-on headless Server Edition whose endpoint file is alive right next to it.
// So the request POST captures curl's exit status and, on failure, walks the OTHER known endpoint
// files (the SSH reverse-tunnel endpoints `~/.nodeterm/hook-endpoint-*.env` + the server-edition
// dataDir + the desktop userData dirs), sourcing each one's sock/port/token, until one POST
// succeeds. The happy path (primary alive) is unchanged — curl succeeds, no candidate scan, no
// re-POST. A host with no candidate files behaves exactly as before (nothing posts).
//
// FALLBACK ORDERING AND BOUND — both were wrong, and the failure was total.
// v1 picked ONE candidate, the freshest by mtime, and retried exactly once. Measured on a live
// host with the Mac closed and 8 agents running:
// hook-endpoint-project-mrkigsjp-4.env 13:25 the primary — excluded as already tried
// hook-endpoint-project-msq9marh-4.env 12:52 another project's tunnel to the SAME Mac, dead
// .nodeterm-server/hook-endpoint.env 00:26 the host's own Server Edition — ALIVE
// The single retry landed on the dead sibling and gave up; the live local endpoint was never
// tried, and that host's mirror held 0 nodes and 0 events while 8 sessions worked. Two fixes:
// 1. ORDER BY FAILURE DOMAIN, NOT BY MTIME. Every `hook-endpoint-*.env` tunnel on a host
// terminates at the SAME desktop, so they share one fate — mtime ranks a dead sibling above a
// listening local server, and the more projects a host has, the deeper the live endpoint is
// buried. A LOCAL endpoint (the host's own Server Edition, then a desktop installed on this
// host) is written by a process running HERE and fails independently, so locals go first;
// tunnels follow, freshest-first among themselves (the live project's endpoint is rewritten
// and VERIFIED on every connect, so mtime is a good tie-break WITHIN that group). The cost of
// being wrong is asymmetric: preferring a local when a sibling tunnel was in fact alive still
// delivers the event (the local instance pushes it) and only loses the desktop's own badge;
// preferring tunnels when they are all dead loses the event entirely.
// 2. TRY SEVERAL, BUT BOUND IT (`nt_fallback_max`, 3). One retry cannot get past even a single
// stale sibling. The bound is what keeps the cure from being its own outage: a dead
// reverse-tunnel socket is not cheap to fail — sshd ACCEPTS the connection and then never
// answers, so each attempt can burn the full `--max-time 1.5`. 3 is chosen against the
// candidate list, not picked round: at most 3 local slots exist and the two desktop userData
// paths are per-OS (mutually exclusive), so a real host has at most 2 locals — 3 attempts
// therefore always reaches a live local endpoint AND still leaves at least one tunnel slot,
// while capping the added latency at ~4.5s on a path that has already failed.
// A single-desktop host — one project, one tunnel, no Server Edition — is untouched: the only
// candidate is the tried one, the list comes back empty, and nothing else runs.
//
// Stale-project self-heal (the glob candidate): a remote session's `NODETERM_HOOK_ENDPOINT` is
// baked into its tmux session at CREATION (`new-session -A -e …`, which tmux ignores when the
// session already exists), and the path carries the PROJECT id:
// `~/.nodeterm/hook-endpoint-<projectId>.env`. Node ids (= tmux session names) deliberately
// survive a project-id change — a re-added folder, a cross-lineage `.nodeterm/project.json`
// adoption — but the endpoint file of the OLD project id is then never rewritten again, so those
// long-lived sessions post into a file pointing at a dead tunnel forever while freshly created
// nodes work. Without the glob the candidate list held only host-LOCAL nodeterm installs, so a
// pure SSH host (no nodeterm of its own) had no self-heal at all: permanent "active but idle".
// The glob makes the live project's endpoint — rewritten and VERIFIED on every connect, hence the
// freshest — a valid fallback. Sending one project's node over another project's socket is
// correct: both tunnels terminate at the SAME hook server, and the node id in the body is what
// identifies the session.
//
// Empty-endpoint self-heal: a session spawned when NO endpoint file existed yet (a phone injects
// NODETERM_NODE_ID + NODETERM_HOOK_ENDPOINT="$NT_EP" where $NT_EP resolved empty on a bare host)
// carries a node id but no token. The gate below keys on the NODE ID, not the token, so such a
// session still reaches nt_send_request — whose failover sources a live sibling endpoint (a Server
// Edition installed later, right next to it) and posts under it. Gating on the token instead would
// exit before that failover ran, leaving the session dark until it was recreated.
//
// Deterministic hook-reply approvals (docs/hook-reply-approvals.md): when
// NODETERM_PERM_WAIT_SECS is set (> 0) in the session env AND the incoming hook is a
// PermissionRequest, the script generates a pendingId, drops the request JSON under
// ~/.nodeterm/pending/, tags the POST body with nodeterm_pending_id (so the mirror/inbox
// learns it), then polls for ~/.nodeterm/pending/<pendingId>.answer for up to that many
// seconds. An answer ('allow' | 'deny') is echoed back as the hook's decision JSON; a
// timeout prints nothing and Claude falls through to its normal interactive prompt. On a valid
// answer it ALSO fires a second, backgrounded "answered" POST (nodeterm_answered=<decision>) so the
// NEEDS YOU badge flips to working immediately rather than lingering until the agent's next hook. The
// whole branch is a NO-OP when the env var is absent (a user's own terminals, older
// nodeterm, non-claude agents), so behavior is bit-for-bit legacy there.
/**
* `identityRoot` is where the Codex thread → node records live (`codexThreadIdentityRoot()`).
* It is a PARAMETER because this builder is also called from tests that never boot a platform,
* and because the prelude has to bake the path in — the shell it runs in has no idea where the
* app's data dir is. Undefined (no platform yet) ⇒ no prelude, i.e. today's script exactly.
*
* The prelude is prepended for EVERY agent, not just codex. It is inert without `CODEX_THREAD_ID`,
* which no other agent's tool shell sets, and one builder beats a codex-only fork of it.
*/
import { codexThreadIdentityResolverSh } from '../../codex-thread-identity-sh'
import { codexThreadIdentityRoot } from '../../codex-identity-proxy'
import { HOOK_CURL_HEADERS_SH } from '../hook-curl-config-sh'
import { NODE_TOKEN_READ_SH } from '../node-token-sh'
import { HOOK_ENDPOINT_FALLBACK_SH } from '../hook-endpoint-failover-sh'
import { ANTIGRAVITY_EVENT_ENV, antigravityDecisionCaseSh } from './antigravity-decision'
import {
PERMISSION_DECISION_MAX_BYTES,
PERMISSION_DECISION_PREFIX,
PERM_WAIT_SECS_INTERACTIVE
} from '../permission-decision'
import {
ASK_USER_QUESTION_TOOL,
EXIT_PLAN_MODE_TOOL,
INTERACTIVE_HOLD_TOOLS
} from '../../../shared/agents/permission-answer'
/**
* Bumped by hand whenever this script's CONTRACT with the server changes. Not a git sha and not a
* date: the server COMPARES it (`>= MIN_TOKEN_AWARE_REVISION`), and a sha does not order.
*
* WHY THIS EXISTS AT ALL. Before it, an old script and a current script whose token file happened to
* be missing were byte-identical on the wire: both POST `version=2` (that field is sourced from the
* ENDPOINT FILE, so it reports the server's protocol version, never the client's) and neither sends
* an X-Nodeterm-Node-Token header. The server therefore could not distinguish "this session cannot
* read a token" from "there is no token to read" — and those need OPPOSITE advice. Messaging's gate
* 2 would have told an SSH-only host's session to retry after its next turn, forever.
*
* Two stale windows this makes visible, and they are ONE mechanism:
* - LOCAL: none in practice. install-helper.ts rewrites the script unconditionally at every boot
* of both shells, so a host running nodeterm is current as of its last start.
* - REMOTE: real. remote-hooks.ts writes it only inside RemoteHooks.setup(), which runs on
* CONNECT. An already-connected project keeps the script it was given, so its remote nodes —
* and any session the PHONE spawns on that host, which runs the host's installed script — stay
* `legacy` until the project reconnects.
*/
export const MANAGED_SCRIPT_REVISION = 5
/** The first revision that reads NODETERM_NODE_TOKEN_DIR and sends the node token (PR #195). */
export const MIN_TOKEN_AWARE_REVISION = 3
/* rev 4 (issue #384): the token read moved to the shared resolver in `node-token-sh.ts`, which
* falls back to the standard token dirs when the endpoint file advertises none. The floor stays 3
* on purpose — rev 3 CAN read a token, which is the only question `MIN_TOKEN_AWARE_REVISION`
* answers; calling it stale would tell a working session to reconnect for nothing.
* rev 5: the answer file may carry a core-built JSON decision (plans/questions), a plain allow on
* ExitPlanMode maps to `updatedInput:{}`, and those two tools hold 540 s. The server gates
* structured answers on it (`MIN_STRUCTURED_ANSWER_REVISION`, permission-decision.ts) — an older
* script would silently ignore them while the write reported success. */
/**
* Which tool the held PermissionRequest is about, and how long to hold it (claude only; spliced
* into the arm branch). Structured answers are docs/hook-reply-approvals.md § "Plans and questions".
*
* `nt_tool` is read with parameter expansion (no subprocess, nothing on an argv) from the FIRST
* `"tool_name":` in the payload. A JSON string cannot contain an unescaped `"tool_name":"` — its
* quotes would be `\"` — so the only way to match an earlier one is a NESTED KEY inside an object
* value, i.e. inside `tool_input`. Claude Code writes `tool_name` before `tool_input` (hook input
* builder, research §1), so the first match is the top-level one; and if that order ever flips, the
* `"tool_input"`-in-the-head check leaves `nt_tool` EMPTY rather than trusting a nested key. Empty is
* the safe direction: the default hold and today's bare allow. The value is then held to a plain
* identifier and only ever compared against two literals.
*
* `nt_wait`: ExitPlanMode / AskUserQuestion are read by a person for minutes, so they hold
* PERM_WAIT_SECS_INTERACTIVE (< the 600 s command-hook timeout our installers
* write with an explicit `timeout: 600`, see CLAUDE_HOOK_EVENTS). EXCEPT for a subagent's request
* (payload names an `agent_id`): Claude awaits a subagent's automated checks BEFORE painting its
* dialog (research §1), so a long hold there would hide the prompt for minutes. Evidence that the
* key is the right signal (claude 2.1.283 bundle, verified by the review): the hook base input is
* `session_id…,permission_mode:r,agent_id:s?.agentId,agent_type:g,…` — `agentId` is undefined on
* the main thread, so JSON.stringify drops the key there and it appears only for a subagent. A
* nested `"agent_id":` inside tool_input merely shortens the hold — the safe direction.
*/
const HELD_TOOL_SH: readonly string[] = [
' nt_tool=""',
' nt_head=${payload%%\'"tool_name":\'*}',
' if [ "$nt_head" != "$payload" ]; then',
' case "$nt_head" in',
' *\'"tool_input"\'*) ;;',
' *)',
' nt_rest=${payload#*\'"tool_name":\'}',
' nt_rest=${nt_rest# }',
' case "$nt_rest" in \'"\'*) nt_rest=${nt_rest#\'"\'}; nt_tool=${nt_rest%%\'"\'*} ;; esac',
' ;;',
' esac',
' fi',
' case "$nt_tool" in \'\'|*[!A-Za-z0-9_.:-]*) nt_tool="" ;; esac',
' nt_wait="$NODETERM_PERM_WAIT_SECS"',
' case "$nt_tool" in',
` ${INTERACTIVE_HOLD_TOOLS.join('|')})`,
' case "$payload" in',
' *\'"agent_id":\'*) ;;',
` *) nt_wait=${PERM_WAIT_SECS_INTERACTIVE} ;;`,
' esac',
' ;;',
' esac'
]
/**
* Decode one answer file into `nt_verb` (allow | deny | hold | empty) and `nt_out` (the exact line
* to print, or empty). The script prints ONLY:
* - a fixed decision for the legacy words `allow` / `deny` (a plain `allow` on ExitPlanMode maps
* to `updatedInput:{}` — Claude DROPS a bare allow on that tool, so the phone's and the header
* button's Approve were silent no-ops; `{}` restores the pre-plan mode, like the dialog's own
* default); or
* - a JSON decision core built (core/agents/permission-decision.ts), printed verbatim only after
* the same bound `isBoundedAnswerContent` applies: the exact prefix + a "allow"/"deny" behavior,
* a closing brace, <= PERMISSION_DECISION_MAX_BYTES, no control bytes (so exactly one line).
* A plain `allow` on AskUserQuestion is `hold`: Claude would drop it (a question needs answers),
* so printing it would close the hook for nothing — the loop consumes the file and KEEPS HOLDING,
* leaving the chat-view answer path open while the TUI dialog works as always. Anything else
* (garbage, a hostile file, an over-long or multi-line JSON) prints nothing and falls through to
* the TUI, exactly as every build before this one did for an unknown answer.
*
* An OLD script (an SSH host keeps the script it got at connect) reads a JSON answer as neither
* `allow` nor `deny`, so it prints nothing and exits — the TUI still answers. Safe degrade.
*/
const ANSWER_DECODE_SH: readonly string[] = [
' nt_verb=""',
' nt_out=""',
' case "$nt_decision" in',
' allow)',
' case "$nt_tool" in',
` ${ASK_USER_QUESTION_TOOL}) nt_verb=hold ;;`,
` ${EXIT_PLAN_MODE_TOOL}) nt_verb=allow; nt_out='${PERMISSION_DECISION_PREFIX}"allow","updatedInput":{}}}}' ;;`,
` *) nt_verb=allow; nt_out='${PERMISSION_DECISION_PREFIX}"allow"}}}' ;;`,
' esac',
' ;;',
` deny) nt_verb=deny; nt_out='${PERMISSION_DECISION_PREFIX}"deny","message":"Denied from nodeterm."}}}' ;;`,
` '${PERMISSION_DECISION_PREFIX}"allow"'*) nt_verb=allow; nt_out="$nt_decision" ;;`,
` '${PERMISSION_DECISION_PREFIX}"deny"'*) nt_verb=deny; nt_out="$nt_decision" ;;`,
' esac',
' # Shape-check a core-built JSON answer before it can reach Claude\'s stdout. The size is the',
' # FILE\'s byte count (wc -c), not ${#…}: that counts characters under bash, bytes under dash.',
' if [ -n "$nt_out" ] && [ "$nt_out" = "$nt_decision" ]; then',
' case "$nt_out" in *\'}\') ;; *) nt_out="" ;; esac',
' # Fail CLOSED: an empty/odd size (wc failed) makes the test error, which also clears nt_out.',
` if ! [ "$nt_size" -le ${PERMISSION_DECISION_MAX_BYTES} ] 2>/dev/null; then nt_out=""; fi`,
" if [ -n \"$nt_out\" ] && [ \"$(printf '%s' \"$nt_out\" | tr -d '\\000-\\037')\" != \"$nt_out\" ]; then nt_out=\"\"; fi",
' [ -n "$nt_out" ] || nt_verb=""',
' fi'
]
/**
* CLAUDE ONLY: which claude process ran this hook, and is it the foreground of its terminal
* (issues #1112, #1153 — the rule and the measurement are in core/agents/claude-pane-origin.ts).
*
* Read HERE, synchronously, before the POST is backgrounded: claude waits on its hook, so
* `$CLAUDE_PID` is alive for this one `ps` even on `SessionEnd`; a read in the server could land
* after the process exited. `$CLAUDE_PID` is exported to hooks by Claude Code itself (measured on
* 2.1.301; present in the binary from at least 2.1.220). One `ps`, BSD- and procps-compatible:
* `stat`'s `+` means "in the foreground process group of its controlling terminal" on both, and
* one `-o` per keyword for the reason PS_FOREGROUND_FLAGS gives. Every way this can fail — no
* `$CLAUDE_PID` (an older claude), a `ps` without `-o`/`-p` (Git Bash, BusyBox), a process already
* gone — leaves all three EMPTY, which the server reads as "unknown" and delivers as before. Git
* Bash is skipped outright: its `ps` cannot answer and a fork there is expensive.
*/
const CLAUDE_ORIGIN_SH: readonly string[] = [
'nt_claude_pid=""',
'nt_claude_fg=""',
'nt_claude_tty=""',
'if [ -z "$nt_msys" ]; then',
' case "$CLAUDE_PID" in',
" ''|*[!0-9]*) ;;",
' *)',
' nt_ps=$(ps -o stat= -o tty= -p "$CLAUDE_PID" 2>/dev/null) || nt_ps=""',
' set -f',
' set -- $nt_ps',
' set +f',
' if [ "$#" -ge 1 ]; then',
' nt_claude_pid="$CLAUDE_PID"',
` case "$1" in *+*) nt_claude_fg=1 ;; *) nt_claude_fg=0 ;; esac`,
` case "$2" in ''|'?'|'??'|-|*[!A-Za-z0-9/._-]*) ;; *) nt_claude_tty="$2" ;; esac`,
' fi',
' ;;',
' esac',
'fi'
]
function safeIdentityRoot(): string | null {
try {
return codexThreadIdentityRoot()
} catch {
return null
}
}
/**
* ANTIGRAVITY ONLY, emitted at BUILD time (every other agent's script is byte-identical without
* it). `agy` reads a hook's stdout as a DECISION and our hook sits in front of every tool call of
* every `agy` on the machine, so the answer is the FIRST thing the script does — before the codex
* prelude, before the NODETERM_NODE_ID gate (a user's own terminal gets the same answer), before
* stdin is read, before the endpoint file is sourced. The table is `antigravity-decision.ts`.
*
* Then stdout AND stderr go to /dev/null for the rest of the run. That is a stronger guarantee than
* auditing every line below: a stray byte (a curl message, a sourced file's echo, a shell warning)
* would become "non-JSON → DENY", and on `PreInvocation` it could be injected into the user's
* conversation (`injectSteps`). `command exec` rather than a bare `exec`: a redirection failure on
* a SPECIAL builtin exits a POSIX shell non-zero, and a non-zero exit is DENY; through `command` it
* is an ordinary failure, and `|| :` absorbs it.
*/
function antigravityAnswerFirst(): string[] {
return [
'# ANSWER FIRST (antigravity): agy reads this stdout as a decision — see antigravity-decision.ts.',
antigravityDecisionCaseSh(),
'# Nothing after the answer may reach stdout or stderr (a stray byte is a DENY, or a message',
'# injected into the conversation).',
'command exec >/dev/null 2>&1 || :'
]
}
export function buildManagedScript(
agentId: string,
identityRoot: string | null = safeIdentityRoot()
): string {
const antigravity = agentId === 'antigravity'
// The codex hook reads its payload BEFORE the identity prelude: the payload's session_id is the
// only thread id a hook under the shared app-server has (#1150/#1175, codex-thread-identity-sh.ts).
const codexPayloadFirst = agentId === 'codex' && !!identityRoot
// The event name rides the POST for antigravity only — its payload never carries one.
// Which claude ran this hook (claude-pane-origin.ts) — claude only, like the event field above.
const originFields =
agentId === 'claude'
? [
' --data-urlencode "nodeterm_claude_pid=${nt_claude_pid}" \\',
' --data-urlencode "nodeterm_claude_fg=${nt_claude_fg}" \\',
' --data-urlencode "nodeterm_claude_tty=${nt_claude_tty}" \\'
]
: []
const eventField = antigravity
? [` --data-urlencode "nodeterm_hook_event=\${${ANTIGRAVITY_EVENT_ENV}}" \\`]
: []
return [
'#!/bin/sh',
...(antigravity ? antigravityAnswerFirst() : []),
...(codexPayloadFirst
? [
'# Payload first (codex only): its leading session_id is this event\'s thread. Parsed with',
'# builtins, anchored at the first byte, so a nested "session_id" in tool input never matches.',
'nt_pre_payload=$(cat)',
'nt_hook_thread=\'\'',
'case "$nt_pre_payload" in',
' \'{"session_id":"\'*)',
' nt_hook_thread=${nt_pre_payload#\'{"session_id":"\'}',
' nt_hook_thread=${nt_hook_thread%%\'"\'*}',
' ;;',
'esac'
]
: []),
...(identityRoot
? [codexThreadIdentityResolverSh(identityRoot, { hookPayloadThread: codexPayloadFirst })]
: []),
'# GATE FIRST, and drain stdin before bailing (issues #186/#187). Order is load-bearing twice:',
'# - The codex thread-identity prelude above may DERIVE the node id (and endpoint) from its',
'# thread id, so the gate cannot move above it — but nothing below needs to run for a',
'# non-nodeterm session, and',
'# sourcing the endpoint file before the gate executed foreign-env file contents in sessions',
'# this script promises a "bit-for-bit legacy no-op" for (#186).',
'# - The drain: claude writes the hook payload into our stdin, and PreToolUse/PostToolUse bodies',
'# exceed one 64KB pipe buffer on any large Read or diff. A bail that exits without reading',
'# EPIPEs the writer mid-payload (#187) — silent, because we still exit 0. The installed',
'# missing-script fallback in settings.json already drains (`else cat >/dev/null`); this makes',
'# the script\'s own bail path keep the same promise.',
'# Gate on the NODE ID only — it is what marks a nodeterm-spawned session (a user\'s own',
'# terminal has neither var and exits here, bit-for-bit legacy no-op). The token is NOT',
'# required at this point: a phone-spawned session whose endpoint was empty/dead at spawn',
'# (NODETERM_HOOK_ENDPOINT="" because no host process existed yet) carries a node id but no',
'# token, and nt_send_request below sources a live sibling endpoint (e.g. a headless Server',
'# Edition that came up AFTER the session) to heal it. Gating on the token here instead would',
'# exit before that failover ever ran, leaving such a session dark until it was recreated.',
'if [ -z "$NODETERM_NODE_ID" ]; then',
' cat >/dev/null 2>&1 || :',
' exit 0',
'fi',
'# Sourced with stdout swallowed, not only stderr: SessionStart and UserPromptSubmit are two of',
'# the events where Claude ADDS hook stdout to the agent\'s context (#186). The endpoint files',
'# nodeterm writes print nothing today — this guards the day one of the four candidate paths',
'# grows a stray echo or an unsilenced warning, which would otherwise be injected into every',
'# prompt silently.',
'if [ -n "$NODETERM_HOOK_ENDPOINT" ] && [ -r "$NODETERM_HOOK_ENDPOINT" ]; then',
' . "$NODETERM_HOOK_ENDPOINT" >/dev/null 2>&1 || :',
'fi',
'# THIS SCRIPT\'s revision, stamped on every POST (X-Nodeterm-Hook-Client) so the server can tell',
'# a session running a pre-identity script from one whose token file is merely missing — they',
'# used to be byte-identical on the wire, because the `version` field below comes from the',
'# ENDPOINT FILE and therefore reports the SERVER\'s protocol version, never the client\'s.',
'# Deliberately set HERE, outside nt_pick_fallback\'s clearing block: sock/port/token-dir belong',
'# to whichever endpoint we adopt, but the revision is a property of this file on this disk.',
'# (The failover SOURCES the endpoint file it adopts, so a file carrying an nt_client_rev line',
'# would overwrite this. Not defended against and not worth defending: every candidate is a',
'# 0600 file under our own $HOME, so writing one already means being us — at which point the',
'# script itself is editable. Noted so the next reader does not have to re-derive it.)',
`nt_client_rev=${MANAGED_SCRIPT_REVISION}`,
'# The PER-NODE capability. The endpoint file (v2) advertises the directory; the token itself is',
'# one file in it named for THIS node id — a lookup by name, never a scan, so a session can only',
'# ever present its own. Absent (pre-v2 endpoint, pre-upgrade session, remote write that failed)',
'# leaves it EMPTY, and an empty header is exactly what the server reads as `legacy`: the POST',
'# still happens and nothing about it fails. Kept in a function because the failover below has to',
'# RE-read it against the dir of the endpoint it adopted — which is why the resolver takes that',
'# endpoint as an argument (see node-token-sh.ts, and issue #384 for the population its',
'# fallbacks exist for: an endpoint file that is still LIVE but advertises no dir at all).',
NODE_TOKEN_READ_SH,
'nt_read_node_token',
HOOK_CURL_HEADERS_SH,
// Report the effective Claude process env, including env from --settings. Always send
// an empty value too: removing an override must invalidate a prior observation.
...(agentId === 'claude'
? [
'nt_context_window="$CLAUDE_CODE_MAX_CONTEXT_TOKENS"',
'case "$nt_context_window" in *[!0-9]*) nt_context_window="" ;; esac',
'[ "${#nt_context_window}" -le 16 ] || nt_context_window=""'
]
: ['nt_context_window=""']),
codexPayloadFirst ? 'payload=$nt_pre_payload' : 'payload=$(cat)',
'if [ -z "$payload" ]; then',
...(antigravity
? [
// agy can fire a hook with NO stdin. The answer is already out; still report the event —
// a Stop with no body is still the end of the turn (the normalizer reads a missing
// fullyIdle as finished), and dropping it would leave the badge on RUNNING.
" payload='{}'"
]
: [' exit 0']),
'fi',
'# Keep the payload OFF curl\'s argv. `--data-urlencode "payload=$payload"` puts the full hook',
'# body (Edit/Write tool_input, the submitted prompt, the last assistant message) into',
'# /proc/<pid>/cmdline — world-readable by every co-tenant for the life of each curl, the exact',
'# leak the headers already avoid via --config. It also caps the event at the kernel argv limit',
'# (~128KB on Linux): a large PreToolUse/PostToolUse body makes curl\'s execve fail E2BIG and the',
'# event is dropped SILENTLY (a lost Stop leaves the node stuck RUNNING). A 0600 temp file read',
'# back with `payload@file` fixes both; it is deleted by whichever POST last reads it (below).',
'nt_payload_file="$HOME/.nodeterm/pending/payload-$$.tmp"',
'# `mkdir -p` on a directory that exists changes nothing — not even its mode — so the test is',
'# the same outcome without the subshell and the mkdir: two processes on every event after the',
'# first one this host ever ran.',
'[ -d "$HOME/.nodeterm/pending" ] || (umask 077; mkdir -p "$HOME/.nodeterm/pending") 2>/dev/null || :',
'(umask 077; printf %s "$payload" > "$nt_payload_file") 2>/dev/null || :',
'# ...but hand curl a path IT can open. Under Git Bash / MSYS this script runs in a POSIX shell',
'# while `curl` is a NATIVE Windows binary (System32, or the one shipped with git), so `$HOME`',
'# expands to `/c/Users/<user>` and curl answers `Failed to open /c/...`. MSYS argument',
'# translation does not save it: the value is embedded after `payload@`, which its heuristic',
'# does not rewrite. Every hook POST failed that way on Windows — silently, since a hook must',
'# never break the agent — so no node ever reported and every session showed Unknown.',
'#',
'# Gated on what the SHELL reports it is, not merely on cygpath being present. `command -v',
'# cygpath` alone is a name check: a WSL or Linux box with anything called cygpath on PATH would',
'# convert a path its own POSIX curl could already open, breaking a case that works today.',
'# `uname -s` answers MINGW*/MSYS* under Git Bash and MSYS2 — the one environment where the',
'# shell is POSIX and curl is not — and Linux/Darwin everywhere else. It is read from the',
'# environment itself rather than inherited, so it still holds when a caller replaces the env',
'# (which is exactly what the hook tests in this repo do). CYGWIN* is deliberately outside the',
'# gate: Cygwin ships its own curl, and that one takes POSIX paths.',
...(agentId === 'claude' ? ['nt_msys=""'] : []),
'nt_payload_arg="$nt_payload_file"',
'case "$(uname -s 2>/dev/null)" in',
' MINGW*|MSYS*)',
...(agentId === 'claude' ? [' nt_msys=1'] : []),
' if command -v cygpath >/dev/null 2>&1; then',
' nt_payload_arg=$(cygpath -w "$nt_payload_file" 2>/dev/null) || nt_payload_arg="$nt_payload_file"',
' [ -n "$nt_payload_arg" ] || nt_payload_arg="$nt_payload_file"',
' fi',
' ;;',
'esac',
...(agentId === 'claude' ? CLAUDE_ORIGIN_SH : []),
'# Deterministic-approval request: only for a PermissionRequest hook while the wait is armed.',
'# `nt_pending` stays empty otherwise, so the POST tag and the poll loop below are both inert.',
'nt_pending=""',
'nt_pending_file=""',
// CLAUDE-ONLY, at BUILD time — not env-gated (issue #409). The old assumption was "non-claude
// agents never see NODETERM_PERM_WAIT_SECS", but the var rides the CLAUDE node's session env
// (default-on hookReplyApprovals) and env is INHERITED: a codex launched from inside a claude
// node's shell — or any nested process — carries it. Codex renders its approval dialog only
// AFTER the PermissionRequest hook exits (measured, codex-cli 0.149.1), so the inherited wait
// held every codex approval for the full 45s, posted the ask under the WRONG (claude) node id,
// and on an answer printed claude's decision JSON into codex's own decision contract — which
// docs/hook-reply-approvals.md explicitly says is unverified. Emitting the arm only into
// claude's script kills all three for every other agent, whatever the inherited env says;
// claude's script stays byte-identical. tmux sessions outlive the app with their spawn-time
// env, which is why "hookReplyApprovals: false" did not stop the field report — the fix must
// not depend on the env at all.
...(agentId === 'claude'
? [
'# Never arm for a claude that is not the foreground of a terminal (claude-pane-origin.ts):',
'# its events are not delivered as this node\'s, so nobody could ever answer the hold.',
'if [ "$nt_claude_fg" != 0 ] && [ -n "$NODETERM_PERM_WAIT_SECS" ] && [ "$NODETERM_PERM_WAIT_SECS" -gt 0 ] 2>/dev/null; then',
' case "$payload" in',
' *\'"hook_event_name":"PermissionRequest"\'*|*\'"hook_event_name": "PermissionRequest"\'*)',
' nt_node=$(printf %s "$NODETERM_NODE_ID" | tr -c \'A-Za-z0-9_-\' \'_\')',
' nt_ms=$(date +%s%3N 2>/dev/null)',
' case "$nt_ms" in \'\'|*[!0-9]*) nt_ms=$(date +%s) ;; esac',
' nt_pending="${nt_node}-${nt_ms}-$$"',
' nt_dir="$HOME/.nodeterm/pending"',
' (umask 077; mkdir -p "$nt_dir") 2>/dev/null || :',
' nt_pending_file="$nt_dir/$nt_pending.json"',
' (umask 077; printf %s "$payload" > "$nt_pending_file") 2>/dev/null || :',
...HELD_TOOL_SH,
' ;;',
' esac',
'fi'
]
: [
'# Hook-reply approvals are claude-only; this script never arms the wait, even when the',
'# session env inherited NODETERM_PERM_WAIT_SECS from a claude node (issue #409).'
]),
// The candidate walk + adopt helpers are SHARED with the canvas-control and context-link
// shims (hook-endpoint-failover-sh.ts) — issue #445: the shims never learned this walk, so
// the same stale endpoint a hook event healed itself around stopped every canvas-control
// verb cold. One definition, three clients; the "Fallback ordering and bound" reasoning in
// the header comment above still governs it.
HOOK_ENDPOINT_FALLBACK_SH,
'# One request POST against the CURRENT endpoint vars. Returns curl\'s exit status so the',
'# caller can fail over; returns 1 when there is no transport at all (unset/unreadable',
'# endpoint) so that case also tries a fallback.',
'nt_request_post() {',
' if [ -n "$NODETERM_HOOK_SOCK" ]; then',
// The pipeline\'s exit status IS curl\'s (POSIX: the status of a pipeline is its last command),
// which is what nt_send_request below reads to decide whether to fail over.
' nt_code=$(nt_hook_headers |',
` curl -sS -o /dev/null -w '%{http_code}' -X POST --unix-socket "$NODETERM_HOOK_SOCK" "http://localhost/hook/${agentId}" \\`,
' --connect-timeout 0.5 --max-time 1.5 --config - \\',
' -H "Content-Type: application/x-www-form-urlencoded" \\',
' --data-urlencode "nodeId=${NODETERM_NODE_ID}" \\',
' --data-urlencode "version=${NODETERM_HOOK_VERSION}" \\',
' --data-urlencode "nodeterm_context_window=${nt_context_window}" \\',
' --data-urlencode "nodeterm_pending_id=${nt_pending}" \\',
...eventField,
...originFields,
' --data-urlencode "payload@${nt_payload_arg}" 2>/dev/null) || return 1',
' elif [ -n "$NODETERM_HOOK_PORT" ]; then',
' nt_code=$(nt_hook_headers |',
` curl -sS -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:\${NODETERM_HOOK_PORT}/hook/${agentId}" \\`,
' --connect-timeout 0.5 --max-time 1.5 --config - \\',
' -H "Content-Type: application/x-www-form-urlencoded" \\',
' --data-urlencode "nodeId=${NODETERM_NODE_ID}" \\',
' --data-urlencode "version=${NODETERM_HOOK_VERSION}" \\',
' --data-urlencode "nodeterm_context_window=${nt_context_window}" \\',
' --data-urlencode "nodeterm_pending_id=${nt_pending}" \\',
...eventField,
...originFields,
' --data-urlencode "payload@${nt_payload_arg}" 2>/dev/null) || return 1',
' else',
' return 1',
' fi',
' [ "$nt_code" != "421" ]',
'}',
'# Request POST with a BOUNDED fallback walk. On a failed primary POST, try the OTHER endpoint',
'# files in most-likely-alive order (nt_candidates) — at most $nt_fallback_max of them — and stop',
'# at the first POST that succeeds. So a session whose primary endpoint is dead (offline Mac',
'# reverse-tunnel) still reaches an alive server (e.g. the headless Server Edition) sitting right',
'# next to it, EVEN when several equally-dead sibling tunnels are listed ahead of it by mtime —',
'# which is what a single freshest-only retry could never get past. In the perm-wait branch this',
'# also carries nodeterm_pending_id to whichever endpoint answers, so the phone/canvas still',
'# learns the ask.',
'# The happy path is untouched: `&& return 0` means a successful primary POST runs no glob, no',
'# subshell and no second curl, exactly as before.',
'nt_send_request() {',
' nt_request_post && return 0',
' nt_list=$(nt_candidates "$NODETERM_HOOK_ENDPOINT")',
' [ -n "$nt_list" ] || return 1',
' # Split the list on NEWLINES only, so a candidate path containing spaces survives (the macOS',
' # "Application Support" entry already has one). `set -f` for the same span, so a path with a',
' # glob character in it is not re-expanded by the unquoted $nt_list.',
' nt_ifs="$IFS"',
' set -f',
' IFS="\n"',
' set -- $nt_list',
' set +f',
' IFS="$nt_ifs"',
' nt_n=0',
' for nt_ep in "$@"; do',
' nt_n=$((nt_n + 1))',
' [ "$nt_n" -le "$nt_fallback_max" ] || break',
' nt_adopt "$nt_ep" || continue',
' # The token is re-read HERE, per candidate, not once at the top: it must come from the dir',
' # the endpoint we just adopted advertises. Reusing the primary\'s (or the previous',
' # candidate\'s) would send our kid to a server that cannot judge it — harmless, but also',
' # pointless, and it would hide a real identity behind a legacy. The adopted path is passed',
' # in for the same reason: when that endpoint advertises no dir, the fallback must derive',
' # from ITS directory, never from the one we are walking away from.',
' nt_read_node_token "$nt_ep"',
' nt_request_post && return 0',
' done',
' return 1',
'}',
'# Advertise status (+ pendingId in the perm-wait branch). In the perm-wait branch this runs in',
'# the FOREGROUND so the ask reaches the (primary or fallback) server before the answer-file poll',
'# begins — and any fallback it sources persists for the "answered" POST below, which then targets',
'# the same live endpoint. Otherwise it is backgrounded so a live session\'s hot path never blocks',
'# on the network (fire-and-forget, exactly as before).',
'if [ -n "$nt_pending" ]; then',
' nt_send_request',
'else',
' # Background the POST (a live session\'s hot path never blocks) and delete the payload temp',
' # file only AFTER it — and its one fallback retry — have finished reading it, so the file',
' # never outlives its reader. The perm-wait branch keeps the file for its "answered" POST.',
' { nt_send_request; rm -f "$nt_payload_file" 2>/dev/null || :; } &',
'fi',
// The poll/decision section below is claude-only at BUILD time, like the arm above: with
// nt_pending permanently empty it was already unreachable in other agents' scripts, but
// keeping claude's decision JSON inside codex.sh is exactly the kind of latent cross-dialect
// output issue #409 was about — strip it so nothing in a non-claude script can ever print a
// decision.
...(agentId === 'claude'
? [
'# Hold the hook open for a phone/canvas answer file, polling every 0.5s up to the armed seconds.',
'if [ -n "$nt_pending" ]; then',
' nt_answer="$HOME/.nodeterm/pending/$nt_pending.answer"',
' nt_max=$((nt_wait * 2))',
' nt_i=0',
' while [ "$nt_i" -lt "$nt_max" ]; do',
' if [ -f "$nt_answer" ]; then',
// Take the file's BYTE size, then read at most one byte past the cap: a hostile multi-megabyte
// file is never slurped into the shell, and the size check below rejects anything over it.
' nt_size=$(wc -c < "$nt_answer" 2>/dev/null)',
` nt_decision=$(head -c ${PERMISSION_DECISION_MAX_BYTES + 1} "$nt_answer" 2>/dev/null)`,
...ANSWER_DECODE_SH,
' if [ "$nt_verb" = hold ]; then',
' # A plain allow on a question: consume it and KEEP HOLDING (see ANSWER_DECODE_SH).',
' rm -f "$nt_answer" 2>/dev/null || :',
' else',
' rm -f "$nt_answer" "$nt_pending_file" 2>/dev/null || :',
' # Fire-and-forget "answered" signal so the canvas/phone NEEDS YOU badge flips to working the',
' # instant we read a valid answer, instead of sticking until the agent\'s next hook (which,',
' # for a text-only reply, is not until the turn\'s Stop). Backgrounded (&) + short --max-time so',
' # the decision JSON below is NEVER delayed. Same POST mechanism as above, tagged',
' # nodeterm_answered=<verb> — the VERB decoded above, never the answer file itself: a JSON',
' # answer carries the user\'s typed text, and nothing from that file may reach an argv.',
' # Only for a valid allow/deny (no POST on a bad/timed-out answer).',
' # The payload temp file is still needed here (the foreground nt_send_request above read',
' # it, and this backgrounded "answered" POST reads it again). Whichever backgrounded POST',
' # is launched self-deletes it after curl returns; if none is (no transport, or a decision',
' # that is neither allow nor deny), it is deleted inline just below.',
' nt_payload_owned=0',
' if [ "$nt_verb" = "allow" ] || [ "$nt_verb" = "deny" ]; then',
' if [ -n "$NODETERM_HOOK_SOCK" ]; then',
' { nt_hook_headers |',
` curl -sS -X POST --unix-socket "$NODETERM_HOOK_SOCK" "http://localhost/hook/${agentId}" \\`,
' --connect-timeout 0.5 --max-time 1 --config - \\',
' -H "Content-Type: application/x-www-form-urlencoded" \\',
' --data-urlencode "nodeId=${NODETERM_NODE_ID}" \\',
' --data-urlencode "version=${NODETERM_HOOK_VERSION}" \\',
' --data-urlencode "nodeterm_context_window=${nt_context_window}" \\',
' --data-urlencode "nodeterm_pending_id=${nt_pending}" \\',
' --data-urlencode "nodeterm_answered=${nt_verb}" \\',
' --data-urlencode "nodeterm_claude_pid=${nt_claude_pid}" \\',
' --data-urlencode "nodeterm_claude_fg=${nt_claude_fg}" \\',
' --data-urlencode "nodeterm_claude_tty=${nt_claude_tty}" \\',
' --data-urlencode "payload@${nt_payload_arg}" >/dev/null 2>&1; rm -f "$nt_payload_file" 2>/dev/null || :; } &',
' nt_payload_owned=1',
' elif [ -n "$NODETERM_HOOK_PORT" ]; then',
' { nt_hook_headers |',
` curl -sS -X POST "http://127.0.0.1:\${NODETERM_HOOK_PORT}/hook/${agentId}" \\`,
' --connect-timeout 0.5 --max-time 1 --config - \\',
' -H "Content-Type: application/x-www-form-urlencoded" \\',
' --data-urlencode "nodeId=${NODETERM_NODE_ID}" \\',
' --data-urlencode "version=${NODETERM_HOOK_VERSION}" \\',
' --data-urlencode "nodeterm_context_window=${nt_context_window}" \\',
' --data-urlencode "nodeterm_pending_id=${nt_pending}" \\',
' --data-urlencode "nodeterm_answered=${nt_verb}" \\',
' --data-urlencode "nodeterm_claude_pid=${nt_claude_pid}" \\',
' --data-urlencode "nodeterm_claude_fg=${nt_claude_fg}" \\',
' --data-urlencode "nodeterm_claude_tty=${nt_claude_tty}" \\',
' --data-urlencode "payload@${nt_payload_arg}" >/dev/null 2>&1; rm -f "$nt_payload_file" 2>/dev/null || :; } &',
' nt_payload_owned=1',
' fi',
' fi',
' if [ "$nt_payload_owned" != 1 ]; then rm -f "$nt_payload_file" 2>/dev/null || :; fi',
' # printf is a shell builtin (dash, bash, busybox): the decision never becomes an argv.',
' if [ -n "$nt_out" ]; then printf \'%s\\n\' "$nt_out"; fi',
' exit 0',
' fi',
' fi',
// nt_max counts HALF-seconds. Where fractional sleep is unsupported the fallback sleeps a full
// second, so it must count 2 — else the 540 s hold would run ~1080 s, past the hook timeout.
' if sleep 0.5 2>/dev/null; then nt_i=$((nt_i + 1)); else sleep 1; nt_i=$((nt_i + 2)); fi',
' done',
' # Timed out: clean up the request + payload files and print nothing → Claude shows its normal prompt.',
' rm -f "$nt_pending_file" "$nt_payload_file" 2>/dev/null || :',
'fi'
]
: []),
'exit 0',
''
].join('\n')
}