commandmate 0.22.1 → 0.23.0

package/dist/server/src/lib/hooks/sources/gemini/settings-generator.js

@@ -0,0 +1,315 @@
+"use strict";
+/**
+ * The hooks CommandMate writes into `<worktree>/.gemini/settings.json`, and the
+ * command that launches gemini against them (Issue #1762).
+ *
+ * gemini is the one tool of the five whose hook config is naturally scoped to a
+ * worktree: `settings.setValue("Workspace", "hooks", …)` — which is what
+ * `gemini hooks migrate` calls — writes the workspace file, and the user's
+ * `~/.gemini/settings.json` is never opened (#1757 §5.3.2). So this generator
+ * touches nothing global, and the *shared* `~/.gemini` tree that antigravity
+ * lives in (`./shared-config-tree`) is out of reach by construction.
+ *
+ * What it does touch is a file inside the user's repository. Three consequences
+ * shaped the code:
+ *
+ *  - **It merges, never replaces.** A checked-in `.gemini/settings.json` with
+ *    the team's model, tool allowlist and their own hooks keeps every key; only
+ *    CommandMate's own handlers are rewritten. `mergeGeminiHookSettings` is
+ *    pure, so this is testable without a filesystem.
+ *  - **The written command is deterministic.** gemini persists the exact command
+ *    strings it has been trusted with in `trusted_hooks.json` and re-shows the
+ *    disclosure banner when they change (#1757 §5.3.3), so a command that
+ *    varied per launch would nag on every start. It also makes the merge
+ *    idempotent: relaunching rewrites byte-identical entries.
+ *  - **It does not carry the instance id.** One file serves `gemini` and
+ *    `gemini-2` in the same worktree, so an instance baked into it would label
+ *    both sessions with whichever started last. The instance rides in
+ *    `CM_HOOK_URL` instead — see {@link buildGeminiLaunchCommand}.
+ *
+ * ## Which events are registered, and which are not
+ *
+ * `SessionStart` / `BeforeAgent` / `AfterAgent` / `Notification` / `SessionEnd`.
+ * That is every gemini event with a consumer:
+ * `user_prompt_submit` → `running`, `stop` → `ready`,
+ * `notification(permission_prompt)` → `waiting`, `session_start` → generation
+ * fence, `session_end` → recorded.
+ *
+ * `BeforeTool` / `AfterTool` are deliberately absent. gemini runs hooks
+ * synchronously, so registering them buys two blocking round trips per tool call
+ * — on a hot `read_file` loop that is the agent waiting on CommandMate, all day
+ * — and buys nothing back: `pre_tool_use`/`post_tool_use` answer `running`,
+ * which `user_prompt_submit` has already established and only `stop` clears, and
+ * the one payload they are otherwise read for is `AskUserQuestion`, a tool
+ * gemini does not have. The source still *maps* both spellings, because a user
+ * may register them by hand in the same file.
+ *
+ * @module lib/hooks/sources/gemini/settings-generator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_REGISTERED_HOOKS = exports.GEMINI_SETTINGS_FILENAME = exports.GEMINI_HOOK_TIMEOUT_MS = exports.GEMINI_CONFIG_DIRNAME = void 0;
+exports.getGeminiSettingsPath = getGeminiSettingsPath;
+exports.buildGeminiHookCommand = buildGeminiHookCommand;
+exports.isCommandMateHookCommand = isCommandMateHookCommand;
+exports.buildGeminiHookGroups = buildGeminiHookGroups;
+exports.mergeGeminiHookSettings = mergeGeminiHookSettings;
+exports.writeGeminiHookSettings = writeGeminiHookSettings;
+exports.buildGeminiLaunchCommand = buildGeminiLaunchCommand;
+const path_1 = require("path");
+const types_1 = require("../../../../lib/cli-tools/types");
+const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-generator");
+const logger_1 = require("../../../../lib/logger");
+const event_mapper_1 = require("../event-mapper");
+const shared_config_tree_1 = require("./shared-config-tree");
+const tool_id_1 = require("./tool-id");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/gemini/settings-generator');
+/** Directory gemini reads workspace configuration from, relative to the worktree. */
+exports.GEMINI_CONFIG_DIRNAME = '.gemini';
+/**
+ * Handler timeout, **in milliseconds** — gemini is the one tool that does not
+ * count this in seconds.
+ *
+ * Measured, and measured the hard way. `timeout: 5` — the seconds figure every
+ * other tool takes, and what #1757 §8.2 R13 recorded as "the unit is seconds
+ * everywhere" — produced this on a live v0.55.1 session:
+ *
+ * ```
+ * Hook execution error: Hook timed out after 5ms
+ * Hook execution for SessionStart: 0 succeeded, 1 failed …, total duration: 8ms
+ * ```
+ *
+ * The hook was registered, was disclosed in the banner, and ran — and was killed
+ * before `curl` could open a socket, so **every event was lost while everything
+ * looked correctly configured**. The bundle confirms it:
+ * `DEFAULT_HOOK_TIMEOUT = 6e4` and the message is `Hook timed out after
+ * ${timeout}ms`. gemini's default is therefore 60s where Claude's is 600s and
+ * copilot's is ~10s.
+ *
+ * The value is {@link HOOK_TIMEOUT_SECONDS} converted, so the budget stays the
+ * one number the rest of the codebase reasons about.
+ */
+exports.GEMINI_HOOK_TIMEOUT_MS = hook_settings_generator_1.HOOK_TIMEOUT_SECONDS * 1000;
+/** Workspace settings file, relative to {@link GEMINI_CONFIG_DIRNAME}. */
+exports.GEMINI_SETTINGS_FILENAME = 'settings.json';
+/**
+ * The gemini events CommandMate registers, and the word each relay call reports.
+ *
+ * Ordered as the file is written, so a diff of two generated files reads in one
+ * direction. See the module comment for why `BeforeTool` / `AfterTool` are not
+ * here.
+ */
+exports.GEMINI_REGISTERED_HOOKS = [
+    ['SessionStart', 'session_start'],
+    ['BeforeAgent', 'user_prompt_submit'],
+    ['AfterAgent', 'stop'],
+    ['Notification', 'notification'],
+    ['SessionEnd', 'session_end'],
+];
+/** Absolute path of the workspace settings file for one worktree. */
+function getGeminiSettingsPath(worktreePath) {
+    return (0, path_1.join)(worktreePath, exports.GEMINI_CONFIG_DIRNAME, exports.GEMINI_SETTINGS_FILENAME);
+}
+/**
+ * The relay invocation for one event.
+ *
+ * `type: "http"` is not an option here, or anywhere outside Claude: #1757 R7
+ * measured all four new tools rejecting it, so `scripts/hooks/cmate-agent-event.sh`
+ * is the only delivery mechanism gemini has.
+ *
+ * No `--url`. The endpoint comes from `CM_HOOK_URL`, which
+ * {@link buildGeminiLaunchCommand} puts in the session's environment with the
+ * instance baked in; passing `--url` here would override it from a file that
+ * cannot know which instance it is serving. `--worktree-id` *is* baked in,
+ * because the file already is per-worktree and a body that names the worktree
+ * keeps working when the environment does not reach the hook.
+ *
+ * @param relayPath - Absolute path to the relay script
+ * @param event - The word to report
+ * @param worktreeId - CommandMate's worktree id
+ */
+function buildGeminiHookCommand(relayPath, event, worktreeId) {
+    return [
+        (0, hook_settings_generator_1.shellQuote)(relayPath),
+        '--tool',
+        tool_id_1.GEMINI_CLI_TOOL_ID,
+        '--event',
+        event,
+        '--worktree-id',
+        (0, hook_settings_generator_1.shellQuote)(worktreeId),
+        '--stdin-json',
+    ].join(' ');
+}
+/**
+ * Whether a command string is one CommandMate wrote for this worktree.
+ *
+ * Used to replace our own entries on rewrite instead of appending a duplicate
+ * set at every launch. Three tokens have to be present together — the relay's
+ * name, this tool, and this worktree id — so a hook the operator wrote for a
+ * *different* worktree, or for another tool, or with their own script, is left
+ * alone.
+ *
+ * A hand-configured hook from the #1549 guide that happens to match all three is
+ * replaced, and that is the right outcome: it posts the same event for the same
+ * instance to the same receiver, so the only thing lost is the duplicate.
+ */
+function isCommandMateHookCommand(command, worktreeId) {
+    return (command.includes('cmate-agent-event.sh') &&
+        command.includes(`--tool ${tool_id_1.GEMINI_CLI_TOOL_ID}`) &&
+        command.includes(`--worktree-id ${(0, hook_settings_generator_1.shellQuote)(worktreeId)}`));
+}
+/** Whether one entry of a `hooks[<Event>]` array is CommandMate's. */
+function isCommandMateGroup(group, worktreeId) {
+    if (!(0, event_mapper_1.isPlainObject)(group))
+        return false;
+    // The grouped shape gemini documents.
+    const handlers = group.hooks;
+    if (Array.isArray(handlers)) {
+        return (handlers.length > 0 &&
+            handlers.every((handler) => (0, event_mapper_1.isPlainObject)(handler) &&
+                typeof handler.command === 'string' &&
+                isCommandMateHookCommand(handler.command, worktreeId)));
+    }
+    // A flat handler. Not what this generator emits, but cheap to recognise so an
+    // older or hand-flattened entry of ours is replaced rather than duplicated.
+    return typeof group.command === 'string' && isCommandMateHookCommand(group.command, worktreeId);
+}
+/**
+ * The `hooks` entries CommandMate contributes, keyed by gemini's event name.
+ *
+ * @param relayPath - Absolute path to the relay script
+ * @param target - The instance being started; only its worktree reaches the file
+ * @returns One matcher group per registered event
+ */
+function buildGeminiHookGroups(relayPath, target) {
+    const groups = {};
+    for (const [nativeName, event] of exports.GEMINI_REGISTERED_HOOKS) {
+        groups[nativeName] = [
+            {
+                hooks: [
+                    {
+                        type: 'command',
+                        command: buildGeminiHookCommand(relayPath, event, target.worktreeId),
+                        // Milliseconds. See GEMINI_HOOK_TIMEOUT_MS — this is the one field
+                        // whose unit differs from every other tool's, and getting it wrong
+                        // loses every event without an error anywhere the operator looks.
+                        timeout: exports.GEMINI_HOOK_TIMEOUT_MS,
+                    },
+                ],
+            },
+        ];
+    }
+    return groups;
+}
+/**
+ * Put CommandMate's hooks into an existing settings object without disturbing
+ * anything else in it.
+ *
+ * Pure, so the guarantee this module exists for is checked without a
+ * filesystem. The rules:
+ *
+ *  - every top-level key other than `hooks` is passed through by identity, in
+ *    its original position;
+ *  - inside `hooks`, an event CommandMate does not register is passed through
+ *    **by identity** — including values that are not arrays, which a
+ *    hand-edited file can contain;
+ *  - inside an event CommandMate does register, the user's groups are kept and
+ *    ours are replaced.
+ *
+ * @param existing - The parsed settings file, or null when there is none
+ * @param groups - What {@link buildGeminiHookGroups} produced
+ * @param worktreeId - Identifies our own previous entries
+ * @returns The object to serialise
+ */
+function mergeGeminiHookSettings(existing, groups, worktreeId) {
+    const existingHooks = (0, event_mapper_1.isPlainObject)(existing?.hooks) ? existing.hooks : {};
+    const merged = {};
+    for (const [nativeName, value] of Object.entries(existingHooks)) {
+        if (!Array.isArray(value)) {
+            merged[nativeName] = value;
+            continue;
+        }
+        const kept = value.filter((group) => !isCommandMateGroup(group, worktreeId));
+        // Identity when nothing of ours was in there, so an untouched event is
+        // untouched down to the array instance.
+        merged[nativeName] = kept.length === value.length ? value : kept;
+    }
+    for (const [nativeName, ours] of Object.entries(groups)) {
+        const kept = merged[nativeName];
+        merged[nativeName] = Array.isArray(kept) ? [...kept, ...ours] : [...ours];
+    }
+    return { ...existing, hooks: merged };
+}
+/**
+ * Write `<worktree>/.gemini/settings.json`.
+ *
+ * @param worktreePath - Absolute path of the worktree gemini will run in
+ * @param target - The instance being started
+ * @returns The path written, or null when injection is off or not possible
+ */
+function writeGeminiHookSettings(worktreePath, target) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return null;
+    const relayPath = (0, hook_settings_generator_1.resolveRelayScriptPath)();
+    if (!relayPath) {
+        // No inline-curl fallback, unlike Claude's `SessionStart`: that fallback
+        // posts the agent's payload verbatim and relies on the URL to say which
+        // tool sent it, and the URL here lives in an environment variable a
+        // settings file cannot read. A gemini session with no hooks is the
+        // pre-#1762 status quo; a gemini session posting events nothing can
+        // attribute is worse.
+        logger.warn('gemini-hook-relay-missing', { worktreeId: target.worktreeId });
+        return null;
+    }
+    const settingsPath = getGeminiSettingsPath(worktreePath);
+    try {
+        const existing = (0, shared_config_tree_1.readJsonObjectFile)(settingsPath);
+        const groups = buildGeminiHookGroups(relayPath, target);
+        (0, shared_config_tree_1.writeJsonObjectFile)(settingsPath, mergeGeminiHookSettings(existing, groups, target.worktreeId));
+        return settingsPath;
+    }
+    catch (error) {
+        // Fail-open, like every other part of this path: the events are an
+        // enhancement to a session that has to start regardless.
+        logger.warn('gemini-hook-settings-write-failed', {
+            worktreeId: target.worktreeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * The command that launches gemini for one instance.
+ *
+ * `CM_HOOK_URL` is the whole of the instance correlation, and it is an
+ * environment variable rather than a flag in the settings file for a reason the
+ * file cannot get around: `.gemini/settings.json` is per *worktree*, and
+ * `gemini` and `gemini-2` share it. The relay reads `CM_HOOK_URL` itself — no
+ * shell expansion inside the hook command is involved — and the receiver reads
+ * `tool`, `worktreeId` and `instanceId` out of the query string, which is
+ * exactly how Claude's injected `--settings` correlates.
+ *
+ * When the variable does not reach the hook, the relay falls back to its default
+ * endpoint and the body's `--worktree-id` still resolves the worktree; the event
+ * lands on the primary instance. That is a degradation, not a
+ * misattribution.
+ *
+ * Never throws, and returns the executable unchanged when injection is off, so
+ * `CM_AGENT_HOOKS_INJECT=0` produces the byte-identical command line this tool
+ * used before #1762.
+ *
+ * @param executablePath - `gemini`, or a resolved path to it
+ * @param target - The instance being started
+ * @returns The command line to type into the pane
+ */
+function buildGeminiLaunchCommand(executablePath, target, options = {}) {
+    if (!(0, hook_settings_generator_1.isHookInjectionEnabled)())
+        return executablePath;
+    if (!(0, types_1.isValidInstanceId)((0, hook_settings_generator_1.resolveTargetInstanceId)(target))) {
+        // About to become a URL parameter the receiver re-validates; a value that
+        // would be rejected there is not worth injecting.
+        logger.warn('gemini-hook-invalid-instance-id', { worktreeId: target.worktreeId });
+        return executablePath;
+    }
+    const url = (0, hook_settings_generator_1.buildAgentEventUrl)({ ...target, cliToolId: tool_id_1.GEMINI_CLI_TOOL_ID }, options);
+    return `CM_HOOK_URL=${(0, hook_settings_generator_1.shellQuote)(url)} ${(0, hook_settings_generator_1.shellQuote)(executablePath)}`;
+}

package/dist/server/src/lib/hooks/sources/gemini/shared-config-tree.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Non-destructive JSON config writing for the `~/.gemini` tree that gemini and
+ * antigravity share (Issue #1762).
+ *
+ * ## Why this is one module rather than two
+ *
+ * `~/.gemini/` is gemini's directory, and antigravity squats in it. On a machine
+ * with both installed it holds, at once:
+ *
+ * ```
+ * ~/.gemini/settings.json          gemini, user scope
+ * ~/.gemini/oauth_creds.json       gemini, the credentials a session needs
+ * ~/.gemini/config/hooks.json      antigravity, the ONLY file it reads (#1757 P8)
+ * ~/.gemini/antigravity/           antigravity 2.0 state
+ * ~/.gemini/antigravity-cli/       agy state, incl. its own settings.json
+ * ```
+ *
+ * So "write the config file" is a sentence with a blast radius here that it does
+ * not have for Claude or codex: a generator that rewrites a file wholesale takes
+ * out the *other* tool's configuration, and a generator that redirects the tree
+ * (a `HOME` or `GEMINI_CLI_HOME` swap) takes out gemini's OAuth credentials and
+ * leaves the user staring at a login screen. Both failures are silent at the
+ * moment they happen.
+ *
+ * Everything in this module therefore does exactly one thing: **read what is
+ * there, put CommandMate's own key back, and write the rest through untouched.**
+ * A file CommandMate has never seen keeps every byte it had except the one key
+ * that is ours. Both directions are pinned by
+ * `tests/unit/hooks/sources/shared-config-tree-1762.test.ts`.
+ *
+ * It lives under `gemini/` because the tree is gemini's; `antigravity/` imports
+ * it rather than growing a second copy, which is the point — one merge
+ * implementation means "we do not clobber" is one thing to get right and one
+ * thing to test, instead of two that can drift.
+ *
+ * @module lib/hooks/sources/gemini/shared-config-tree
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonObjectFile = readJsonObjectFile;
+exports.writeJsonObjectFile = writeJsonObjectFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const system_directories_1 = require("../../../../config/system-directories");
+const event_mapper_1 = require("../event-mapper");
+/**
+ * Read a JSON object from disk, or null when there is nothing usable there.
+ *
+ * Null covers three different situations on purpose — absent, unreadable, and
+ * "parsed fine but is not an object" — because the caller's response to all
+ * three is the same: treat the file as empty and write a config that has only
+ * CommandMate's key in it.
+ *
+ * It deliberately does **not** cover "parsed fine and is an object we do not
+ * recognise". That case returns the object, and the merge preserves it. A user's
+ * `settings.json` is full of keys this codebase has never heard of.
+ *
+ * @param path - Absolute path to the file
+ * @returns The parsed object, or null
+ */
+function readJsonObjectFile(path) {
+    if (!(0, fs_1.existsSync)(path))
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        return (0, event_mapper_1.isPlainObject)(parsed) ? parsed : null;
+    }
+    catch {
+        // A hand-edited file with a trailing comma is not something to fail a
+        // session over. Injection is an enhancement; the session starts either way.
+        return null;
+    }
+}
+/**
+ * Write a JSON object, creating the directory when it is missing.
+ *
+ * The mode arguments apply only when the entry is *created*: an existing file
+ * keeps the permissions the user gave it, which matters because these files are
+ * theirs and not CommandMate's. A new one is 0600 and a new directory 0700 — the
+ * same posture `hook-settings-generator` takes, and for the same reason (the
+ * contents name every worktree and instance on the machine).
+ *
+ * Issue #1774: unlike its siblings this takes the path as an argument rather
+ * than resolving an environment variable, so there is no default to fall back
+ * to — the caller asked for one specific file. It therefore *refuses* rather
+ * than redirects. Throwing is the fail-open signal both callers already handle
+ * (`writeGeminiHookSettings` and `writeAntigravityHooksConfig` catch, warn and
+ * return null), and it has to happen before the mkdir: a recursive mkdir under
+ * `/proc` does not throw, it spins the event loop until the process is killed.
+ *
+ * @param path - Absolute path to the file
+ * @param value - The object to serialise
+ * @throws If the path is inside a virtual filesystem. Callers treat a throw as
+ *   "launch without hooks"
+ */
+function writeJsonObjectFile(path, value) {
+    if ((0, system_directories_1.isVirtualFilesystemPath)(path)) {
+        throw new Error(`Refusing to write inside a virtual filesystem: ${path} ` +
+            `(a recursive mkdir under /proc, /sys or /dev never returns on Linux; Issue #1774)`);
+    }
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, fs_1.writeFileSync)(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}

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

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Gemini CLI's {@link AgentEventSource} (Issue #1762, Phase 4-4 of Epic #1720).
+ *
+ * ## Why the values below are what they are
+ *
+ * - **`noDecision: 'proceeds'`.** #1757 could not measure this: the account
+ *   available to the spike was refused by the server with `IneligibleTierError`
+ *   before any tool call happened, so §5.3.6 lists items 6 and 7 as unmeasured.
+ *   It is not guessed either. gemini v0.55.1's shipped bundle decides whether a
+ *   hook blocked a tool in `DefaultHookOutput`:
+ *
+ *   ```js
+ *   isBlockingDecision() { return this.decision === "block" || this.decision === "deny"; }
+ *   isAskDecision()      { return this.decision === "ask"; }
+ *   shouldStopExecution(){ return this.continue === false; }
+ *   ```
+ *
+ *   All three read fields that an empty or absent reply does not have, so
+ *   silence cannot block, cannot escalate and cannot stop. Fail-open is a
+ *   property of the parser rather than of a measurement — which is the stronger
+ *   statement of the two, and the opposite of antigravity, where the same
+ *   question has the opposite answer (`../antigravity/source`).
+ *
+ * - **`encodeVerdict` returns `{}` for every verdict, and this source
+ *   adjudicates nothing.** Not a gap — gemini's hook protocol has no way to
+ *   approve anything. Reading the scheduler in the same bundle:
+ *
+ *   ```js
+ *   const hookResult = await evaluateBeforeToolHook(…);   // 1. the hook runs
+ *   …
+ *   const { decision: policyDecision } = await checkPolicy(…);  // 2. the Policy Engine
+ *   let decision = policyDecision;
+ *   if (hookDecision === "ask") decision = ASK_USER;             // 3. hook may only escalate
+ *   ```
+ *
+ *   A hook can *deny* (step 1 returns an error outright), it can *escalate* an
+ *   allow into a dialog (step 3), and it can do nothing. There is no branch in
+ *   which a hook turns a `checkPolicy` verdict into an approval. So **on gemini,
+ *   approval is the Policy Engine's job and only the Policy Engine's job**
+ *   (`--approval-mode` / `--policy` / `-y, --yolo`), and Auto-Yes keeps exactly
+ *   the one meaning it has today for this tool: the TUI path — detect the
+ *   dialog, answer it. There is no second, hook-shaped approval channel for it
+ *   to compete with, which is what Issue #1720 asked to be established before
+ *   this Issue shipped. CommandMate passes none of those flags, so injecting
+ *   hooks does not widen what a gemini session may do.
+ *
+ * - **`configScope: 'per-worktree'`.** `<worktree>/.gemini/settings.json`
+ *   (#1757 §5.3.2). The user's `~/.gemini/settings.json` is never opened, which
+ *   also keeps this source out of the tree antigravity occupies.
+ *
+ * - **`decisionTimeoutSeconds: 0`.** Not `null`. `null` means "waits forever",
+ *   which is opencode's situation and would be a lie here: no gemini event ever
+ *   waits on a CommandMate verdict, because none is ever asked for.
+ *
+ * @module lib/hooks/sources/gemini/source
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geminiAgentEventSource = void 0;
+exports.injectGeminiHookSettings = injectGeminiHookSettings;
+const types_1 = require("../../../../lib/cli-tools/types");
+const define_source_1 = require("../define-source");
+const event_mapper_1 = require("../event-mapper");
+const hook_event_vocabulary_1 = require("../hook-event-vocabulary");
+const event_vocabulary_1 = require("./event-vocabulary");
+const settings_generator_1 = require("./settings-generator");
+const tool_id_1 = require("./tool-id");
+/**
+ * Write this worktree's `.gemini/settings.json`, on the session-creation path.
+ *
+ * **This is the one thing about gemini that {@link AgentEventSource} cannot
+ * express.** `prepareLaunch` receives an {@link AgentInstanceRef}, which is
+ * `(worktreeId, cliToolId, instanceId)` and carries no filesystem path — the
+ * right shape for the four tools whose config is global or per-instance, and one
+ * field short for the only tool whose config is per-*worktree*. Rather than
+ * widen the interface for one tool, or resolve the path by pulling the database
+ * into the module every receiver imports, the caller that already holds the path
+ * passes it here and `prepareLaunch` builds the command line.
+ *
+ * Reported rather than worked around: see the Issue #1762 entry in `CHANGELOG.md`.
+ *
+ * @param worktreePath - Absolute path of the worktree the session runs in
+ * @param target - The instance being created
+ * @returns The settings file written, or null when nothing was written
+ */
+function injectGeminiHookSettings(worktreePath, target) {
+    const settingsTarget = {
+        worktreeId: target.worktreeId,
+        instanceId: target.instanceId,
+        cliToolId: tool_id_1.GEMINI_CLI_TOOL_ID,
+    };
+    if (!(0, types_1.isValidInstanceId)(target.instanceId ?? tool_id_1.GEMINI_CLI_TOOL_ID))
+        return null;
+    return (0, settings_generator_1.writeGeminiHookSettings)(worktreePath, settingsTarget);
+}
+/**
+ * Gemini CLI 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.geminiAgentEventSource = (0, define_source_1.definePushHookSource)({
+    cliToolId: tool_id_1.GEMINI_CLI_TOOL_ID,
+    // Silence cannot block: `decision` and `continue` are both absent from an
+    // empty reply, and both parsers test for a present value. See the module
+    // comment for the three lines of gemini's own code this rests on.
+    noDecision: { kind: 'proceeds' },
+    capabilities: {
+        // What CommandMate's injected config makes gemini emit. `pre_tool_use` and
+        // `post_tool_use` are absent on purpose — the spellings are mapped, but the
+        // hooks are not registered (see `./settings-generator`), so a caller waiting
+        // for one from a CommandMate-started gemini session would wait for good.
+        supportedEvents: ['session_start', 'user_prompt_submit', 'stop', 'notification', 'session_end'],
+        configScope: 'per-worktree',
+        // No gemini event waits on a verdict from CommandMate. See the module comment.
+        decisionTimeoutSeconds: 0,
+    },
+    // gemini's own table, kept in gemini's own module: four of the seven are
+    // spelled differently, and merging them into the shared CamelCase table would
+    // teach Claude, codex and copilot to accept spellings none of them sends
+    // (`docs/design/agent-event-source-interface.md` §5).
+    mappers: (0, event_mapper_1.fromNameTable)(event_vocabulary_1.GEMINI_HOOK_EVENT_NAMES),
+    nativeEventNameFields: ['hook_event_name'],
+    conversationIdFields: hook_event_vocabulary_1.SESSION_ID_FIELDS,
+    // gemini publishes no per-tool-call correlation id: its `BeforeTool` payload
+    // carries `tool_name` and `tool_input` and nothing resembling `tool_use_id`.
+    toolCallIdFields: [],
+    extractDetail: event_vocabulary_1.extractGeminiEventDetail,
+    // gemini has no `PermissionRequest` event and no `AskUserQuestion` tool
+    // (#1757 §8.1), so there is no payload of either kind to read. Null is the
+    // honest answer and degrades to the behaviour of a machine without hooks.
+    parsePermissionRequest: () => null,
+    parseQuestion: () => null,
+    // gemini hooks cannot approve — only deny, escalate to a dialog, or stop the
+    // agent outright. CommandMate emits none of those: a denial from Auto-Yes
+    // takes the choice away in the direction waiting cannot undo, and an
+    // escalation would add dialogs the Policy Engine had already settled. So every
+    // verdict encodes to the empty body, which the bundle reads as no opinion.
+    encodeVerdict: () => ({}),
+    // The settings file is written by `injectGeminiHookSettings`, which the
+    // session module calls with the worktree path this interface cannot carry.
+    // `settingsPath` is therefore null here rather than wrong.
+    prepareLaunch: (target, executablePath) => ({
+        command: (0, settings_generator_1.buildGeminiLaunchCommand)(executablePath, {
+            worktreeId: target.worktreeId,
+            instanceId: target.instanceId,
+            cliToolId: tool_id_1.GEMINI_CLI_TOOL_ID,
+        }),
+        settingsPath: null,
+    }),
+});

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

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Gemini CLI's {@link CLIToolType} id, as a constant.
+ *
+ * The same one-line module Claude has, for the same reason: the literal
+ * `'gemini'` appears once under `src/lib/hooks/`, and the modules that write
+ * gemini's config import the constant rather than restating it.
+ *
+ * Separate from `./source` because the settings generator needs the id and the
+ * source imports the generator; importing it back out of `./source` would close
+ * a cycle.
+ *
+ * @module lib/hooks/sources/gemini/tool-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_CLI_TOOL_ID = void 0;
+exports.GEMINI_CLI_TOOL_ID = 'gemini';