commandmate 0.22.2 → 0.24.0

package/dist/server/src/lib/hooks/sources/claude/source.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Claude Code's {@link AgentEventSource} — the first implementation of the
+ * Issue #1759 abstraction, and the one that has to keep behaving exactly as it
+ * did before the abstraction existed.
+ *
+ * Everything here was already in the codebase; what changed is where it lives.
+ * The event-name table and the subtype extraction came out of
+ * `agent-event-types` (S1/S2), the verdict shape out of the permission receiver
+ * (S6), the payload parsers were already their own modules (S7), and the
+ * settings/launch generation stays in `hook-settings-generator` and is reached
+ * through {@link prepareLaunch} (S3/S4/S5). No spelling, no field name and no
+ * emitted byte is different from before — `buildAgentHookSettings` is untouched
+ * and the receiver's decision body is produced by the same code path.
+ *
+ * ## Why the values below are what they are
+ *
+ * - `noDecision: 'proceeds'` — measured, not assumed. #1721 D5 drove a live
+ *   session with a hook that answered `{}` and watched the ordinary TUI
+ *   approval dialog appear, indistinguishable from a machine with no hook at
+ *   all. This is what makes "when in doubt, abstain" a safe rule *for Claude*;
+ *   it is not a safe rule for antigravity or opencode (C3).
+ * - `configScope: 'per-instance'` — `--settings <file>` is per launch, so
+ *   `claude` and `claude-2` in one worktree get different files with different
+ *   correlation keys baked into the URLs. Most tools cannot do this;
+ *   antigravity reads one global file and nothing else (#1757 P8).
+ * - `decisionTimeoutSeconds` — `PERMISSION_REQUEST_TIMEOUT_SECONDS`, the number
+ *   the generator writes into the hook. copilot's equivalent is ≈10s and
+ *   codex's 600s, which is why the number is a capability rather than a
+ *   constant somebody reads once.
+ *
+ * @module lib/hooks/sources/claude/source
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeAgentEventSource = void 0;
+exports.encodeClaudeVerdict = encodeClaudeVerdict;
+const agent_event_types_1 = require("../../../../lib/hooks/agent-event-types");
+const ask_user_question_payload_1 = require("../../../../lib/hooks/ask-user-question-payload");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const permission_request_payload_1 = require("../../../../lib/hooks/permission-request-payload");
+const define_source_1 = require("../define-source");
+const event_mapper_1 = require("../event-mapper");
+const hook_event_vocabulary_1 = require("../hook-event-vocabulary");
+const tool_id_1 = require("./tool-id");
+/**
+ * The no-decision body, byte for byte what the #1721 spike returned for D5.
+ *
+ * Empty is not "an error we swallowed": it is the documented way to say
+ * "CommandMate has no opinion", and Claude responds to it by doing what it
+ * would have done with no hook installed.
+ */
+const NO_DECISION_BODY = {};
+/**
+ * Encode a verdict the way §5.4 of the verification report measured Claude
+ * obeying (S6).
+ *
+ * `hookEventName` is required alongside `decision`; without it the body is
+ * ignored in silence.
+ *
+ * Three of the five verdicts collapse to no-decision, and that is the design
+ * rather than a gap:
+ *
+ *  - `allowAlways` has no Claude spelling. `permission_suggestions` offers
+ *    `addRules` candidates, but writing a persistent rule from a hook is a
+ *    different and much larger promise than approving one call, so this source
+ *    declines instead of approximating.
+ *  - `deny` is never emitted at all. `lib/hooks/permission-decision-service`
+ *    explains why: a denial from Auto-Yes takes the choice away from the human
+ *    in the direction that cannot be undone by waiting, and every case that
+ *    wants one is better served by letting the dialog appear.
+ *  - `answer` belongs to `AskUserQuestion`, whose picker is drawn regardless of
+ *    what a `PermissionRequest` hook says (#1721 §5.6) — answering here would
+ *    be answering a question the human is about to be shown anyway.
+ */
+function encodeClaudeVerdict(verdict) {
+    if (verdict.kind !== 'allowOnce')
+        return NO_DECISION_BODY;
+    return {
+        hookSpecificOutput: {
+            hookEventName: permission_request_payload_1.PERMISSION_REQUEST_EVENT_NAME,
+            decision: { behavior: 'allow' },
+        },
+    };
+}
+/**
+ * Claude Code as an event source.
+ *
+ * Registered in `../registry`. Nothing outside this directory imports it by
+ * name; callers ask the registry for the tool they are holding.
+ */
+exports.claudeAgentEventSource = (0, define_source_1.definePushHookSource)({
+    cliToolId: tool_id_1.CLAUDE_CLI_TOOL_ID,
+    // #1721 D5: an unanswered or empty `PermissionRequest` lands in the ordinary
+    // approval flow. Abstaining is free here — and only here plus codex/copilot.
+    noDecision: { kind: 'proceeds' },
+    capabilities: {
+        // Claude is the one tool that emits all seven (#1757 §8.1). It is still not
+        // a licence to treat `session_end` as "the process exited": `/clear` emits
+        // one too, with `reason: "clear"`, and the pane keeps running.
+        supportedEvents: agent_event_types_1.AGENT_EVENT_TYPES,
+        configScope: 'per-instance',
+        decisionTimeoutSeconds: hook_settings_generator_1.PERMISSION_REQUEST_TIMEOUT_SECONDS,
+    },
+    // S1. A plain name table is enough *for this tool* — one native name, one
+    // word, no predicates — so it is expressed as rules built from the table
+    // rather than as a table, and a source that needs conditions (opencode) adds
+    // them to the same list.
+    mappers: (0, event_mapper_1.fromNameTable)(hook_event_vocabulary_1.CAMEL_CASE_HOOK_EVENT_NAMES),
+    nativeEventNameFields: ['hook_event_name'],
+    conversationIdFields: hook_event_vocabulary_1.SESSION_ID_FIELDS,
+    toolCallIdFields: hook_event_vocabulary_1.TOOL_CALL_ID_FIELDS,
+    // Issue #1783. Claude sends it on `SessionStart` and nowhere else — checked
+    // against every fixture in `tests/fixtures/hooks/claude/`, where only
+    // `session-start.json` carries the key. So the value has to be *remembered*
+    // rather than read off the newest event; `getLastKnownAgentModel` is what
+    // does that. The value arrives with its own suffix (`claude-opus-5[1m]`) and
+    // is not parsed here: a display string the tool chose is the tool's to spell.
+    modelFields: ['model'],
+    // S2.
+    extractDetail: hook_event_vocabulary_1.extractSnakeCaseEventDetail,
+    // S7. Both parsers are strict and answer null for anything they cannot vouch
+    // for; the callers turn null into "no structured data", which degrades to the
+    // behaviour of a machine without hooks rather than into a guess.
+    parsePermissionRequest: (payload) => (0, permission_request_payload_1.parsePermissionRequestPayload)(payload),
+    parseQuestion: (payload) => (0, ask_user_question_payload_1.parseAskUserQuestionPayload)(payload),
+    // S6.
+    encodeVerdict: encodeClaudeVerdict,
+    // S3 / S4 / S5. Delegated rather than reimplemented: `buildClaudeLaunchCommand`
+    // writes the settings file, falls back to the bare path on any failure, and is
+    // covered byte-for-byte by `tests/unit/hooks/hook-settings-generator.test.ts`.
+    prepareLaunch: (target, executablePath) => {
+        const command = (0, hook_settings_generator_1.buildClaudeLaunchCommand)(executablePath, {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId,
+            cliToolId: target.cliToolId,
+        });
+        // The path is reported only when the command actually names it. Injection
+        // can be switched off (`CM_AGENT_HOOKS_INJECT=0`) or fail to write, and both
+        // return the bare executable — claiming a settings file in that case would
+        // be telling the caller about a file that is not there.
+        const settingsPath = (0, hook_settings_generator_1.isHookInjectionEnabled)() && command !== executablePath
+            ? (0, hook_settings_generator_1.getHookSettingsPath)({
+                worktreeId: target.worktreeId,
+                instanceId: target.instanceId,
+                cliToolId: target.cliToolId,
+            })
+            : null;
+        return { command, settingsPath };
+    },
+});

package/dist/server/src/lib/hooks/sources/claude/tool-id.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Claude Code's {@link CLIToolType} id, as a constant.
+ *
+ * A one-line module so that the literal `'claude'` appears in exactly one place
+ * under `src/lib/hooks/`. `hook-settings-generator` defaults its target to this
+ * tool, which is correct — it generates Claude's `--settings` file and nothing
+ * else — but a bare literal there reads as "this layer knows about Claude",
+ * which after Issue #1759 it must not.
+ *
+ * Separate from `./source` because that module imports the settings generator;
+ * importing the constant back out of it would close a cycle.
+ *
+ * @module lib/hooks/sources/claude/tool-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_CLI_TOOL_ID = void 0;
+exports.CLAUDE_CLI_TOOL_ID = 'claude';

package/dist/server/src/lib/hooks/sources/codex/hooks-config.js

@@ -0,0 +1,465 @@
+"use strict";
+/**
+ * codex's `hooks.json`, and the command line that gives one session its
+ * correlation keys (Issue #1760, seams S3/S4/S5 for codex).
+ *
+ * Claude's equivalent is `lib/hooks/hook-settings-generator`, and the two look
+ * nothing alike because codex's hook system differs from Claude's in four ways
+ * that were all measured on codex-cli **0.147.0** rather than read out of a
+ * document. Each one removes an option Claude has:
+ *
+ *  1. **There is no `--settings`.** codex reads `$CODEX_HOME/hooks.json` and
+ *     `<cwd>/.codex/hooks.json` and nothing else — no per-launch file, no
+ *     `--config` pointing at one (#1757 §5.1.2; `hooks.managed_dir` exists as a
+ *     key and fired zero times). So the file cannot carry a worktree id or an
+ *     instance id the way Claude's does: whatever is written is shared by every
+ *     codex session on the machine.
+ *  2. **`type: "http"` destroys the file.** One `http` handler and codex
+ *     discards the whole of `hooks.json` — every `command` hook with it — after
+ *     printing one line to stderr that the TUI never shows (#1757 §5.1.4). The
+ *     only delivery mechanism is `type: "command"`.
+ *  3. **A hook command runs through a shell.** Measured directly for this Issue
+ *     against 0.147.0: `$VAR` expands, `"…"` and `'…'` group, `${VAR:+…}`
+ *     works, `&` inside quotes is literal, and a `#` comment is ignored. The
+ *     hook process also inherits the environment of the shell that started
+ *     codex. **That is what makes point 1 survivable**: the file stays static
+ *     and the per-session keys travel in environment variables set on the
+ *     launch line, so `codex` and `codex-2` in one worktree report as
+ *     themselves. Verified live — a session launched with
+ *     `CM_AGENT_INSTANCE_ID=codex-2` posted `instanceId: "codex-2"`.
+ *  4. **Hooks do not run until a human trusts them.** Trust is recorded in the
+ *     user's own `~/.codex/config.toml` as
+ *     `[hooks.state."<file>:<event>:0:0"] trusted_hash`, and an untrusted hook
+ *     is skipped in complete silence (#1757 P4). CommandMate does not write
+ *     that file — see {@link isCodexHookTrustBypassEnabled} for the whole of
+ *     the reasoning, and `docs/design/agent-event-source-interface.md`.
+ *
+ * ## Why `$CODEX_HOME/hooks.json` and not `<worktree>/.codex/hooks.json`
+ *
+ * Both fire. The worktree-local file was rejected for two reasons: it is inside
+ * a git checkout, so every worktree grows an untracked `.codex/` that shows up
+ * in the Changes view and that an agent running `git add -A` can commit; and
+ * trust is keyed by absolute path, so a per-worktree file means the human
+ * re-answers the review dialog once per worktree, forever. The single file is
+ * byte-identical for every worktree and every instance, which makes trust a
+ * one-time act and makes a rewrite a no-op — {@link writeCodexHookSettings}
+ * leaves the file untouched when the content already matches.
+ *
+ * The cost is that the file is shared with codex sessions CommandMate did not
+ * start. Those post too, with the environment variables unset; the relay omits
+ * the correlation keys it does not have and the receiver falls back to
+ * resolving the worktree from `cwd`, which is exactly the hand-configured
+ * behaviour of Issue #1549. `CM_AGENT_HOOKS_INJECT=0` turns the whole thing off.
+ *
+ * @module lib/hooks/sources/codex/hooks-config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_SUPPORTED_EVENTS = exports.CODEX_PERMISSION_REQUEST_EVENT = exports.CODEX_REGISTERED_EVENTS = exports.CODEX_SESSION_END_TIMEOUT_SECONDS = exports.CODEX_HOOK_TRUST_BYPASS_FLAG = exports.CODEX_HOOK_TRUST_ENV_VAR = exports.CODEX_PERMISSION_URL_ENV_VAR = exports.CODEX_EVENT_URL_ENV_VAR = exports.CODEX_INSTANCE_ID_ENV_VAR = exports.CODEX_WORKTREE_ID_ENV_VAR = exports.CODEX_TOOL_ENV_VAR = exports.CODEX_HOME_ENV_VAR = exports.CODEX_HOOK_MARKER = void 0;
+exports.isCodexHookTrustBypassEnabled = isCodexHookTrustBypassEnabled;
+exports.getCodexHome = getCodexHome;
+exports.getCodexHooksPath = getCodexHooksPath;
+exports.buildCodexEventHookCommand = buildCodexEventHookCommand;
+exports.buildCodexPermissionHookCommand = buildCodexPermissionHookCommand;
+exports.buildCodexHookSettings = buildCodexHookSettings;
+exports.mergeCodexHookSettings = mergeCodexHookSettings;
+exports.writeCodexHookSettings = writeCodexHookSettings;
+exports.buildCodexLaunchCommand = buildCodexLaunchCommand;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const safe_directory_1 = require("../../../../config/safe-directory");
+const types_1 = require("../../../../lib/cli-tools/types");
+const env_1 = require("../../../../lib/env");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const logger_1 = require("../../../../lib/logger");
+const path_validator_1 = require("../../../../lib/security/path-validator");
+const event_mapper_1 = require("../event-mapper");
+const tool_id_1 = require("./tool-id");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/codex/hooks-config');
+/** Loopback: the agent runs on the machine the server runs on. */
+const CODEX_HOOK_HOST = '127.0.0.1';
+/**
+ * Marks a handler as this server's, so a rewrite replaces CommandMate's entries
+ * and leaves the operator's alone.
+ *
+ * Spelled as a trailing shell comment rather than as an extra JSON field
+ * because codex's config parser rejects what it does not know — an unknown
+ * `type` takes the entire file down (#1757 §5.1.4), and an unknown key is not
+ * worth finding out about the same way. Measured: a hook whose command ends
+ * `… # commandmate:agent-hooks` runs and receives its arguments unchanged.
+ */
+exports.CODEX_HOOK_MARKER = 'commandmate:agent-hooks';
+/** `$CODEX_HOME` — codex's own override, honoured so a sandboxed codex stays sandboxed. */
+exports.CODEX_HOME_ENV_VAR = 'CODEX_HOME';
+/** Relay defaults to this tool when the hook does not pass `--tool`. */
+exports.CODEX_TOOL_ENV_VAR = 'CM_AGENT_TOOL';
+/** Correlation key: which worktree this codex process belongs to. */
+exports.CODEX_WORKTREE_ID_ENV_VAR = 'CM_AGENT_WORKTREE_ID';
+/**
+ * Correlation key: which instance.
+ *
+ * The whole of the answer to "`codex` and `codex-2` run in the same directory".
+ * `cwd` cannot tell them apart and neither can `session_id`; the environment of
+ * the process can, because CommandMate is the one that starts it.
+ */
+exports.CODEX_INSTANCE_ID_ENV_VAR = 'CM_AGENT_INSTANCE_ID';
+/** Event receiver URL. Already the relay script's own environment override. */
+exports.CODEX_EVENT_URL_ENV_VAR = 'CM_HOOK_URL';
+/** Auto-Yes v2 receiver URL, with the correlation keys already in its query. */
+exports.CODEX_PERMISSION_URL_ENV_VAR = 'CM_PERMISSION_HOOK_URL';
+/** Opt-in switch for {@link CODEX_HOOK_TRUST_BYPASS_FLAG}; `bypass` is the only value that acts. */
+exports.CODEX_HOOK_TRUST_ENV_VAR = 'CM_CODEX_HOOK_TRUST';
+/** codex's own flag for running unreviewed hooks, for one invocation. */
+exports.CODEX_HOOK_TRUST_BYPASS_FLAG = '--dangerously-bypass-hook-trust';
+/**
+ * `SessionEnd`'s budget, in seconds.
+ *
+ * Not a preference: codex clamps this hook to 3 s and says so in the TUI
+ * (`⚠ clamping SessionEnd hook timeout to 3s in …/hooks.json`), measured on
+ * 0.147.0. Writing {@link HOOK_TIMEOUT_SECONDS} here would put a warning banner
+ * above every session for a value codex was going to ignore.
+ */
+exports.CODEX_SESSION_END_TIMEOUT_SECONDS = 3;
+/**
+ * The events CommandMate registers, and the word each maps to.
+ *
+ * Four of codex's eleven. What is deliberately absent matters more than what is
+ * here:
+ *
+ *  - **`Notification` does not exist on codex** (#1757 §5.1.1: the review screen
+ *    enumerates eleven events and it is not among them). Writing one is
+ *    discarded in silence.
+ *  - **`PreToolUse` / `PostToolUse` are not registered**, though they do fire.
+ *    Claude registers them for the single matcher `AskUserQuestion` (#1726)
+ *    because that tool's arguments *are* the question a human has to answer.
+ *    codex has no such tool, so the only thing registering them would buy is
+ *    two POSTs per tool call — on a session that greps in a loop, two requests
+ *    per `Read`, each of which the agent waits for. `capabilities.supportedEvents`
+ *    says so, so nothing above waits for a word that cannot arrive.
+ *  - **`PermissionRequest` is not here** because it is not an observation: its
+ *    response body is a decision codex obeys, so it goes to its own receiver
+ *    through {@link buildCodexPermissionHookCommand}.
+ */
+exports.CODEX_REGISTERED_EVENTS = {
+    SessionStart: 'session_start',
+    UserPromptSubmit: 'user_prompt_submit',
+    Stop: 'stop',
+    SessionEnd: 'session_end',
+};
+/** codex's spelling of the event whose reply is a verdict (#1757 §5.1.6). */
+exports.CODEX_PERMISSION_REQUEST_EVENT = 'PermissionRequest';
+/** The four words a codex session can actually produce, given the config above. */
+exports.CODEX_SUPPORTED_EVENTS = Object.values(exports.CODEX_REGISTERED_EVENTS);
+/**
+ * Whether to launch codex with {@link CODEX_HOOK_TRUST_BYPASS_FLAG}.
+ *
+ * **Off by default, and the default is the security decision.** The flag
+ * disables review for *every* hook the invocation can see, which includes
+ * `<cwd>/.codex/hooks.json` — a file that lives inside the repository being
+ * worked on. Turning it on by default would mean that cloning a hostile
+ * repository and opening it in CommandMate runs whatever that repository put in
+ * `.codex/hooks.json`, with no dialog, defeating the exact mechanism codex
+ * built to prevent it. A structured `Stop` event is not worth that.
+ *
+ * So the default posture is: CommandMate writes the config and never grants the
+ * trust. The human grants it once, through codex's own review screen, which is
+ * also the only thing that may write `~/.codex/config.toml` — a file this
+ * server never touches (it holds, among other things, the `notify` entry a
+ * user's Computer Use integration depends on). Until then the hooks are inert,
+ * the screen scraper keeps doing what it did before this Issue, and
+ * `cli-tools/codex` dismisses the review dialog so a session still starts.
+ *
+ * `CM_CODEX_HOOK_TRUST=bypass` exists for headless and CI operators who have
+ * weighed that trade for themselves.
+ */
+function isCodexHookTrustBypassEnabled() {
+    return process.env[exports.CODEX_HOOK_TRUST_ENV_VAR] === 'bypass';
+}
+/**
+ * `$CODEX_HOME`, or `~/.codex`.
+ *
+ * Issue #1774: `writeCodexHookSettings` creates this directory with a recursive
+ * mkdir, which does not fail but *hangs* for a path inside `/proc`, `/sys` or
+ * `/dev`. Such a value is refused here and `~/.codex` is used instead.
+ */
+function getCodexHome(options = {}) {
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.codex');
+    if (options.codexHome) {
+        return (0, safe_directory_1.resolveSafeDirectory)(options.codexHome, fallback, 'CodexHookOptions.codexHome');
+    }
+    return (0, safe_directory_1.resolveSafeDirectory)(process.env[exports.CODEX_HOME_ENV_VAR], fallback, exports.CODEX_HOME_ENV_VAR);
+}
+/** Absolute path of the hooks file codex reads. */
+function getCodexHooksPath(options = {}) {
+    return (0, path_1.join)(getCodexHome(options), 'hooks.json');
+}
+/**
+ * Receiver URL for a manually launched codex, as a shell expansion.
+ *
+ * Every session CommandMate starts has the variable set, so this default is
+ * only reached by a codex the operator ran themselves. It mirrors the relay
+ * script's own default (`CM_PORT`, else 3000) rather than baking in the port of
+ * whichever server happened to write the file — the file is machine-wide and
+ * this repository is routinely run as several servers at once.
+ */
+function fallbackUrlExpression(path, query) {
+    return `http://${CODEX_HOOK_HOST}:\${CM_PORT:-3000}${path}${query}`;
+}
+/**
+ * The command for one lifecycle event.
+ *
+ * Prefers the shipped relay, which already reads codex's payload from stdin,
+ * omits correlation keys it was handed empty, and exits 0 when the POST fails.
+ * The inline fallback posts codex's payload verbatim to the same receiver —
+ * which reads it, because the source's mappers know `hook_event_name`.
+ */
+function buildCodexEventHookCommand(event, options = {}) {
+    const marker = ` # ${exports.CODEX_HOOK_MARKER}`;
+    const relay = options.relayScriptPath === undefined ? (0, hook_settings_generator_1.resolveRelayScriptPath)() : options.relayScriptPath;
+    if (relay) {
+        return ([
+            (0, hook_settings_generator_1.shellQuote)(relay),
+            '--tool',
+            tool_id_1.CODEX_CLI_TOOL_ID,
+            '--event',
+            event,
+            // Quoted so an unset variable is one empty argument rather than none;
+            // the relay drops an empty correlation key and falls back to `cwd`.
+            '--worktree-id',
+            `"$${exports.CODEX_WORKTREE_ID_ENV_VAR}"`,
+            '--instance-id',
+            `"$${exports.CODEX_INSTANCE_ID_ENV_VAR}"`,
+            '--stdin-json',
+        ].join(' ') + marker);
+    }
+    const withAuthHeader = options.withAuthHeader ?? (0, hook_settings_generator_1.isAuthTokenExpected)();
+    const auth = withAuthHeader ? ` -H "Authorization: Bearer $${hook_settings_generator_1.AUTH_TOKEN_ENV_VAR}"` : '';
+    // `${VAR:+&k=$VAR}` so a manually launched codex posts no empty correlation
+    // key at all, rather than one the receiver has to reject.
+    const url = `"\${${exports.CODEX_EVENT_URL_ENV_VAR}:-${fallbackUrlExpression(hook_settings_generator_1.AGENT_EVENT_PATH, '')}}` +
+        `?tool=${tool_id_1.CODEX_CLI_TOOL_ID}` +
+        `\${${exports.CODEX_WORKTREE_ID_ENV_VAR}:+&worktreeId=$${exports.CODEX_WORKTREE_ID_ENV_VAR}}` +
+        `\${${exports.CODEX_INSTANCE_ID_ENV_VAR}:+&instanceId=$${exports.CODEX_INSTANCE_ID_ENV_VAR}}"`;
+    return (`curl -sS -f -m ${hook_settings_generator_1.HOOK_TIMEOUT_SECONDS} -X POST -H 'Content-Type: application/json'${auth} ` +
+        `--data-binary @- ${url} >/dev/null 2>&1 || true${marker}`);
+}
+/**
+ * The command for `PermissionRequest`, whose stdout **is** the verdict.
+ *
+ * Never the relay: that script discards the response body, and the body is the
+ * entire point here. `curl` writes what the receiver answers straight to
+ * stdout, which is where codex reads a command hook's decision from — measured
+ * live for this Issue: an `{"hookSpecificOutput":{…"behavior":"allow"}}` reply
+ * ran the command with no dialog, `{}` produced the ordinary approval dialog,
+ * and a receiver that was not running produced the same dialog a second later.
+ *
+ * `-f` so an HTTP error prints nothing, `2>/dev/null` so a connection failure
+ * prints nothing, `|| true` so the hook exits 0. All three land on the same
+ * behaviour: no output, and codex asks the human — which is what it does with
+ * no hook installed at all.
+ */
+function buildCodexPermissionHookCommand(options = {}) {
+    const withAuthHeader = options.withAuthHeader ?? (0, hook_settings_generator_1.isAuthTokenExpected)();
+    const auth = withAuthHeader ? ` -H "Authorization: Bearer $${hook_settings_generator_1.AUTH_TOKEN_ENV_VAR}"` : '';
+    const url = `"\${${exports.CODEX_PERMISSION_URL_ENV_VAR}:-` +
+        `${fallbackUrlExpression(hook_settings_generator_1.PERMISSION_REQUEST_PATH, `?tool=${tool_id_1.CODEX_CLI_TOOL_ID}`)}}"`;
+    return (`curl -sS -f -m ${hook_settings_generator_1.PERMISSION_REQUEST_TIMEOUT_SECONDS} -X POST ` +
+        `-H 'Content-Type: application/json'${auth} --data-binary @- ${url} ` +
+        `2>/dev/null || true # ${exports.CODEX_HOOK_MARKER}`);
+}
+/**
+ * The hooks CommandMate contributes.
+ *
+ * Deterministic and free of per-session values: the same bytes on every
+ * worktree, every instance and every server on the machine. That is what makes
+ * the human's one-time trust survive a restart — codex keys trust by the hash
+ * of the handler, so a file that changed would have to be reviewed again.
+ */
+function buildCodexHookSettings(options = {}) {
+    const handler = (event, timeout) => ({
+        hooks: [{ type: 'command', command: buildCodexEventHookCommand(event, options), timeout }],
+    });
+    const hooks = {};
+    for (const [nativeName, event] of Object.entries(exports.CODEX_REGISTERED_EVENTS)) {
+        const timeout = nativeName === 'SessionEnd' ? exports.CODEX_SESSION_END_TIMEOUT_SECONDS : hook_settings_generator_1.HOOK_TIMEOUT_SECONDS;
+        hooks[nativeName] = [handler(event, timeout)];
+    }
+    hooks[exports.CODEX_PERMISSION_REQUEST_EVENT] = [
+        {
+            hooks: [
+                {
+                    type: 'command',
+                    command: buildCodexPermissionHookCommand(options),
+                    timeout: hook_settings_generator_1.PERMISSION_REQUEST_TIMEOUT_SECONDS,
+                },
+            ],
+        },
+    ];
+    return { hooks };
+}
+/** Whether a handler was written by this server. */
+function isCommandMateHandler(handler) {
+    if (!(0, event_mapper_1.isPlainObject)(handler))
+        return false;
+    return typeof handler.command === 'string' && handler.command.includes(exports.CODEX_HOOK_MARKER);
+}
+/**
+ * Drop this server's previous handlers from one event's groups, keeping
+ * everything else — including groups that end up empty, which are the
+ * operator's to remove.
+ */
+function withoutCommandMateHandlers(groups) {
+    return groups
+        .map((group) => {
+        if (!(0, event_mapper_1.isPlainObject)(group) || !Array.isArray(group.hooks))
+            return group;
+        const kept = group.hooks.filter((handler) => !isCommandMateHandler(handler));
+        if (kept.length === group.hooks.length)
+            return group;
+        return { ...group, hooks: kept };
+    })
+        .filter((group) => {
+        // A group that held nothing but our handler is ours to remove; one the
+        // operator wrote empty is left exactly as found.
+        if (!(0, event_mapper_1.isPlainObject)(group) || !Array.isArray(group.hooks))
+            return true;
+        return group.hooks.length > 0;
+    });
+}
+/**
+ * Fold the generated hooks into whatever is already in the file.
+ *
+ * The file is the operator's, and on most machines it is the *only* place their
+ * own codex hooks can live — there is no second file to put them in. So this
+ * appends rather than replaces: unrelated events keep their handlers, unrelated
+ * top-level keys are carried through untouched, and a handler this server wrote
+ * earlier is replaced rather than duplicated.
+ *
+ * An event whose existing value is not an array is left exactly as it is and
+ * gets no handler from us. Overwriting a shape this function does not
+ * understand would cost the operator a config it presumably tested.
+ *
+ * @param existing - The parsed file, or null when there was none
+ * @param generated - {@link buildCodexHookSettings}
+ * @returns The object to serialise
+ */
+function mergeCodexHookSettings(existing, generated) {
+    const base = (0, event_mapper_1.isPlainObject)(existing) ? { ...existing } : {};
+    const existingHooks = (0, event_mapper_1.isPlainObject)(base.hooks) ? base.hooks : {};
+    const merged = {};
+    for (const [event, groups] of Object.entries(existingHooks)) {
+        merged[event] = Array.isArray(groups) ? withoutCommandMateHandlers(groups) : groups;
+    }
+    for (const [event, groups] of Object.entries(generated.hooks)) {
+        const current = merged[event];
+        if (current !== undefined && !Array.isArray(current))
+            continue;
+        merged[event] = [...(current ?? []), ...groups];
+    }
+    base.hooks = merged;
+    return base;
+}
+/**
+ * Write the hooks file, and answer where it is.
+ *
+ * Idempotent to the byte: when the merged content already matches, the file is
+ * not opened for writing at all, so a machine whose hooks are trusted keeps its
+ * mtime and its trust and sees no review dialog on the next launch.
+ *
+ * @returns The path, or null when the file could not be prepared — which the
+ *   caller turns into "start codex without hooks", never into a failed launch
+ */
+function writeCodexHookSettings(options = {}) {
+    const settingsPath = getCodexHooksPath(options);
+    let existing = null;
+    let previous = null;
+    if ((0, fs_1.existsSync)(settingsPath)) {
+        try {
+            previous = (0, fs_1.readFileSync)(settingsPath, 'utf8');
+            existing = JSON.parse(previous);
+        }
+        catch (error) {
+            // Someone's file that this server cannot read is someone's file this
+            // server must not overwrite. Injection is skipped; the session starts.
+            logger.warn('codex-hooks-config-unreadable', {
+                settingsPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    const content = `${JSON.stringify(mergeCodexHookSettings(existing, buildCodexHookSettings(options)), null, 2)}\n`;
+    if (previous === content)
+        return settingsPath;
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(settingsPath), { recursive: true, mode: 0o700 });
+    (0, fs_1.writeFileSync)(settingsPath, content, { mode: 0o600 });
+    return settingsPath;
+}
+/**
+ * The command that starts codex for one instance.
+ *
+ * Never throws: hooks are an enhancement to a session that has to start anyway,
+ * so anything that goes wrong here returns the bare executable — which is
+ * byte-for-byte the pre-#1760 launch.
+ *
+ * The environment assignments are the per-session half of the design. The
+ * hooks file cannot hold them (there is one file for the machine), the payload
+ * cannot supply them (`cwd` is identical for `codex` and `codex-2`, and
+ * `session_id` changes under the instance), and codex injects nothing of its
+ * own (#1757 §5.1.7 found no `CLAUDE_PROJECT_DIR` equivalent). What is left is
+ * the environment of the process CommandMate starts, which a hook inherits.
+ *
+ * @param executablePath - Resolved codex CLI path or bare command name
+ * @param target - The instance being started
+ * @returns `<assignments> <codex>`, or `executablePath` unchanged when
+ *   injection is off, the ids are unusable, or the file could not be written
+ */
+function buildCodexLaunchCommand(executablePath, target, options = {}) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return executablePath;
+    const instanceId = target.instanceId ?? tool_id_1.CODEX_CLI_TOOL_ID;
+    if (!(0, path_validator_1.isValidWorktreeId)(target.worktreeId) || !(0, types_1.isValidInstanceId)(instanceId)) {
+        // Both become URL parameters the receiver re-validates; a value that would
+        // be rejected there is not worth injecting.
+        logger.warn('codex-hooks-invalid-correlation-key', { worktreeId: target.worktreeId });
+        return executablePath;
+    }
+    try {
+        const settingsPath = writeCodexHookSettings(options);
+        if (!settingsPath)
+            return executablePath;
+        const port = options.port ?? (0, env_1.getServerPort)();
+        const query = new URLSearchParams({
+            tool: tool_id_1.CODEX_CLI_TOOL_ID,
+            worktreeId: target.worktreeId,
+            instanceId,
+        });
+        const assignments = [
+            // Pin the home the file was just written to, rather than trusting the
+            // agent to resolve the same one. Measured on 2026-08-13: a tmux session
+            // inherits the environment of the *tmux server*, which was started long
+            // before CommandMate and knows nothing about its environment — so a
+            // server run with `CODEX_HOME=…` wrote its hooks into that directory
+            // while the codex it launched read `~/.codex` and found none. No error,
+            // no missing file, simply zero events. Naming it here makes "the file we
+            // wrote" and "the file codex reads" the same file by construction; in the
+            // ordinary case where nothing sets it, this is the default codex would
+            // have picked anyway.
+            `${exports.CODEX_HOME_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(getCodexHome(options))}`,
+            `${exports.CODEX_TOOL_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(tool_id_1.CODEX_CLI_TOOL_ID)}`,
+            `${exports.CODEX_WORKTREE_ID_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(target.worktreeId)}`,
+            `${exports.CODEX_INSTANCE_ID_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(instanceId)}`,
+            `${exports.CODEX_EVENT_URL_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(`http://${CODEX_HOOK_HOST}:${port}${hook_settings_generator_1.AGENT_EVENT_PATH}`)}`,
+            `${exports.CODEX_PERMISSION_URL_ENV_VAR}=${(0, hook_settings_generator_1.shellQuote)(`http://${CODEX_HOOK_HOST}:${port}${hook_settings_generator_1.PERMISSION_REQUEST_PATH}?${query.toString()}`)}`,
+        ];
+        const trust = isCodexHookTrustBypassEnabled() ? ` ${exports.CODEX_HOOK_TRUST_BYPASS_FLAG}` : '';
+        return `${assignments.join(' ')} ${(0, hook_settings_generator_1.shellQuote)(executablePath)}${trust}`;
+    }
+    catch (error) {
+        logger.warn('codex-hooks-config-write-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return executablePath;
+    }
+}