commandmate 0.22.2 → 0.23.0

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

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * GitHub Copilot CLI's {@link AgentEventSource} (Issue #1761, Epic #1720 Phase
+ * 4-3).
+ *
+ * Issue #1761 was filed as conditional — "copilot 1.0.77 may have no hooks at
+ * all; if it does not, withdraw this Issue" — on the evidence that
+ * `copilot --help` never says the word. The #1757 spike then found the feature
+ * documented in `copilot help config`, drove six events out of a live session,
+ * and captured them into `tests/fixtures/hooks/copilot/`. The premise is
+ * inverted: of the four tools Phase 4 adds, **copilot's payloads are the
+ * closest to Claude Code's**, and this file is correspondingly short.
+ *
+ * What it does *not* share with Claude is where the config goes, how a verdict
+ * gets back, and how long there is to send one. All three live in
+ * `./hook-settings`; the module comment there is the one to read before
+ * changing anything about delivery.
+ *
+ * ## The four values that are not Claude's
+ *
+ *  - **`configScope: 'global-singleton'`.** There is no `--settings`. One file,
+ *    `~/.copilot/settings.json`, for every session on the machine — so the
+ *    correlation keys cannot be baked into it and ride in the environment
+ *    instead.
+ *  - **`decisionTimeoutSeconds: 10`**, against Claude's 600 (#1757 §5.2.3). A
+ *    decision path budgeted for Claude misses copilot's window entirely and the
+ *    tool call proceeds unadjudicated.
+ *  - **`supportedEvents` omits `notification` and `pre_tool_use`.** See below;
+ *    both omissions are deliberate and neither is a gap in the mapping.
+ *  - **`encodeVerdict` speaks `permissionDecision`**, not Claude's
+ *    `decision.behavior`, and copilot can express a denial that Claude cannot.
+ *
+ * ## Why `pre_tool_use` is not in `supportedEvents`
+ *
+ * Copilot has no `PermissionRequest`. `PreToolUse` *is* its approval gate: the
+ * hook's stdout decides whether the call runs (#1757 §5.2.4, re-measured for
+ * this Issue against 1.0.79 — `deny` prints `Denied by preToolUse hook: …` and
+ * the command does not execute). CommandMate therefore points that one event at
+ * `/api/hooks/permission-request`, which adjudicates and does not record.
+ *
+ * So `pre_tool_use` never reaches `agent-event-state` for copilot, and
+ * `supportedEvents` is a promise about what does: listing it would leave a
+ * caller waiting for an event that is being answered somewhere else. The mapper
+ * still recognises the spelling — a hand-configured hook from #1549 pointed at
+ * the event route keeps working — which is why the omission is in
+ * `capabilities` and not in `mappers`.
+ *
+ * `notification` is omitted for the opposite reason: it was configured during
+ * the spike and **never fired once**, so there is no captured payload and no
+ * evidence about what `notification_type` would even contain. Prompt detection
+ * for copilot stays with the screen scraper (#1723), which is where it already
+ * is.
+ *
+ * ## Why `session_start` is not a "the agent is up" signal
+ *
+ * Copilot fires `UserPromptSubmit` **before** `SessionStart` — 20.813Z against
+ * 20.915Z, measured. Anything ordering-sensitive built on these two words is
+ * wrong for this tool specifically, which is why the fence in
+ * `beginAgentSession` is a timestamp rather than a state machine.
+ *
+ * @module lib/hooks/sources/copilot/source
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copilotAgentEventSource = void 0;
+exports.parseCopilotPermissionRequest = parseCopilotPermissionRequest;
+exports.encodeCopilotVerdict = encodeCopilotVerdict;
+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 hook_settings_1 = require("./hook-settings");
+const tool_id_1 = require("./tool-id");
+/**
+ * No opinion, byte-for-byte the reply the spike measured copilot treating as
+ * "carry on" (#1757 §5.2.4).
+ *
+ * The same object Claude reads the same way — which is a coincidence worth
+ * naming, because it is emphatically not true of antigravity, where `{}` is a
+ * denial (#1757 P10).
+ */
+const NO_DECISION_BODY = {};
+/**
+ * Read copilot's `PreToolUse` payload as a permission request (S7).
+ *
+ * Deliberately not `parsePermissionRequestPayload`: that one insists on
+ * `hook_event_name === 'PermissionRequest'`, an event copilot does not have, so
+ * reusing it would answer null for every request copilot ever makes and
+ * Auto-Yes would abstain on all of them — silently, and looking exactly like a
+ * working feature with nothing to approve.
+ *
+ * Strict in the same way and for the same reason: anything unvouchable becomes
+ * null, the caller turns null into no-decision, and the fallback is a dialog
+ * rather than an execution.
+ *
+ * `promptId` is always null — copilot sends no correlation id on this payload
+ * (nor on `PreToolUse`/`PostToolUse`; #1757 R5) — so the permission route mints
+ * its own id for the in-flight request.
+ *
+ * @param body - Whatever was posted to `/api/hooks/permission-request`
+ */
+function parseCopilotPermissionRequest(body) {
+    if (!(0, event_mapper_1.isPlainObject)(body))
+        return null;
+    if (body.hook_event_name !== hook_settings_1.COPILOT_PERMISSION_HOOK_EVENT)
+        return null;
+    const toolName = (0, event_mapper_1.readStringField)(body, 'tool_name');
+    if (!toolName || toolName.length > permission_request_payload_1.MAX_TOOL_NAME_LENGTH)
+        return null;
+    // No `tool_input` means nothing for the deny patterns to be judged against,
+    // which makes the request unadjudicatable rather than harmless.
+    if (!(0, event_mapper_1.isPlainObject)(body.tool_input))
+        return null;
+    return {
+        toolName,
+        toolInput: body.tool_input,
+        promptId: null,
+        sessionId: (0, event_mapper_1.readStringField)(body, 'session_id'),
+        permissionMode: null,
+        permissionSuggestions: null,
+    };
+}
+/**
+ * Encode a verdict in copilot's wire form (S6).
+ *
+ * `hookSpecificOutput.permissionDecision`, verified end to end against copilot
+ * 1.0.79: `allow` ran a shell command that would otherwise have prompted,
+ * `deny` refused it and printed the reason, and `{}` fell through to the
+ * ordinary flow.
+ *
+ * `deny` is encoded rather than collapsed — this is the one place copilot is
+ * *more* expressive than Claude, whose source has no spelling for it. Nothing
+ * produces one today (`permission-decision-service` answers allow or
+ * no-decision and never denies, on purpose), so this branch is a capability
+ * being stated honestly, not a behaviour being switched on.
+ *
+ * `allowAlways` and `answer` collapse to no-decision: copilot's
+ * `permissionDecision` has no persistent form, and approving one call is not
+ * the same promise as writing a standing rule.
+ */
+function encodeCopilotVerdict(verdict) {
+    if (verdict.kind === 'allowOnce') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: hook_settings_1.COPILOT_PERMISSION_HOOK_EVENT,
+                permissionDecision: 'allow',
+            },
+        };
+    }
+    if (verdict.kind === 'deny') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: hook_settings_1.COPILOT_PERMISSION_HOOK_EVENT,
+                permissionDecision: 'deny',
+                permissionDecisionReason: verdict.message ?? 'denied by CommandMate',
+            },
+        };
+    }
+    return NO_DECISION_BODY;
+}
+/**
+ * GitHub Copilot 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.copilotAgentEventSource = (0, define_source_1.definePushHookSource)({
+    cliToolId: tool_id_1.COPILOT_CLI_TOOL_ID,
+    // #1757 §5.2.4, re-confirmed here: an empty reply, an unreachable server and
+    // a late reply all land in copilot's ordinary approval flow. Abstaining costs
+    // a dialog and nothing else — true for Claude, codex and copilot, false for
+    // antigravity and opencode (C3).
+    noDecision: { kind: 'proceeds' },
+    capabilities: {
+        // Five of the seven. `pre_tool_use` is answered by the permission receiver
+        // rather than recorded, and `notification` has never been observed to fire.
+        // Both are explained at the top of this file; neither is an oversight.
+        supportedEvents: [
+            'stop',
+            'session_start',
+            'session_end',
+            'user_prompt_submit',
+            'post_tool_use',
+        ],
+        // One file for the whole machine. See `./hook-settings`.
+        configScope: 'global-singleton',
+        decisionTimeoutSeconds: hook_settings_1.COPILOT_HOOK_TIMEOUT_SECONDS,
+    },
+    // The same CamelCase dialect as Claude and codex — measured against six
+    // captured payloads (#1757 §8.1), not assumed from the resemblance. Shared
+    // rather than copied: `hook-event-vocabulary` exists to be the dialect these
+    // three tools agree on, and a private copy here would be a second place for
+    // the same spelling to drift.
+    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,
+    // No captured copilot payload carries one, so this answers null in practice;
+    // it is wired anyway so that a future release which adds `tool_use_id` is
+    // correlated rather than ignored.
+    toolCallIdFields: hook_event_vocabulary_1.TOOL_CALL_ID_FIELDS,
+    // snake_case throughout, exactly as Claude spells it: `source` on
+    // `SessionStart`, `reason` on `SessionEnd`, `tool_name` on the tool events.
+    extractDetail: hook_event_vocabulary_1.extractSnakeCaseEventDetail,
+    parsePermissionRequest: parseCopilotPermissionRequest,
+    // Copilot has no `AskUserQuestion` tool and no captured payload resembling
+    // one. Null is "no structured data", which degrades to the behaviour of a
+    // machine without hooks rather than to a guess.
+    parseQuestion: () => null,
+    encodeVerdict: encodeCopilotVerdict,
+    prepareLaunch: (target, executablePath) => (0, hook_settings_1.buildCopilotLaunchCommand)(executablePath, target),
+});

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

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * GitHub Copilot CLI's {@link CLIToolType}, on its own so that anything needing
+ * only the id does not pull in the source (Issue #1761).
+ *
+ * The same split Claude has, and for the same reason: `hook-settings-generator`
+ * imports `CLAUDE_CLI_TOOL_ID` while `claude/source.ts` imports
+ * `hook-settings-generator`, so a single module would be a cycle.
+ *
+ * @module lib/hooks/sources/copilot/tool-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COPILOT_CLI_TOOL_ID = void 0;
+/** `copilot`, as `CLI_TOOL_IDS` spells it. */
+exports.COPILOT_CLI_TOOL_ID = 'copilot';

package/dist/server/src/lib/hooks/sources/define-source.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Factories that turn a tool's *differences* into an {@link AgentEventSource}
+ * (Issue #1759).
+ *
+ * The interface is wide because the six tools genuinely differ in eleven
+ * places. Making every implementer restate all eleven would guarantee that
+ * Phase 4-2…4-5 is four copies of Claude's file with four things changed —
+ * which is the failure mode Epic #1720 was opened about. So the parts that are
+ * the *same for every push transport* live here exactly once:
+ *
+ *  - `subscribe` resolves immediately; the receiver route is already listening
+ *    and there is nothing per-instance to hold open (C1).
+ *  - `decide` writes into the slot the receiver opened, so the verdict leaves
+ *    through the response body (C2).
+ *  - `listPending` answers with the requests in flight, because a hook that was
+ *    dropped is gone and there is nothing to re-read (C7).
+ *  - `probeActivity` answers null: an event cannot be asked again (C7).
+ *  - `liveness` answers `unknown`: a quiet hook and a dead agent look identical
+ *    (C6).
+ *
+ * What a push tool then has to supply is the list in
+ * {@link PushHookSourceSpec} — spellings, field names, verdict shape, launch
+ * command. `docs/design/agent-event-source-interface.md` walks through adding
+ * one.
+ *
+ * {@link definePullEventSource} exists for the same reason in reverse: opencode
+ * has real subscription, liveness and re-sync behaviour and no launch config at
+ * all, so its defaults are the opposite ones.
+ *
+ * @module lib/hooks/sources/define-source
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePushHookSource = definePushHookSource;
+exports.definePullEventSource = definePullEventSource;
+const agent_event_types_1 = require("../../../lib/hooks/agent-event-types");
+const event_mapper_1 = require("./event-mapper");
+const pending_decisions_1 = require("./pending-decisions");
+/** A subscription that was never really opened. Closing it is legal and inert. */
+const INERT_SUBSCRIPTION = {
+    close: async () => { },
+    liveness: { state: 'unknown' },
+};
+/**
+ * Build a push (hook) source from its differences.
+ *
+ * @returns A source whose transport is `push` and whose lifecycle methods are
+ *   the inert-but-callable ones every hook tool shares
+ */
+function definePushHookSource(spec) {
+    const nativeEventNameFields = spec.nativeEventNameFields ?? ['hook_event_name'];
+    return {
+        cliToolId: spec.cliToolId,
+        transport: 'push',
+        noDecision: spec.noDecision,
+        capabilities: spec.capabilities,
+        normalizeEvent(raw) {
+            const receivedAt = raw.receivedAt ?? Date.now();
+            const nativeEventName = nativeEventNameFields.length > 0
+                ? (0, event_mapper_1.readFirstStringField)(raw.payload, nativeEventNameFields)
+                : null;
+            // An event word the caller already resolved wins over the payload. This
+            // is the only channel antigravity has, and it is also how the relay
+            // script's `--event` reaches here for every other tool.
+            if (raw.event != null && (0, agent_event_types_1.isAgentEventType)(raw.event)) {
+                return (0, event_mapper_1.buildNormalizedEvent)({ event: raw.event }, raw.payload, receivedAt, {
+                    detail: spec.extractDetail,
+                    conversationId: spec.conversationIdFields,
+                    toolCallId: spec.toolCallIdFields,
+                });
+            }
+            const mapping = (0, event_mapper_1.runEventMappers)(spec.mappers, nativeEventName, raw.payload);
+            if (!mapping) {
+                // C8. Not an error: a tool emits more events than CommandMate has words
+                // for, and it grows more of them between releases.
+                (0, event_mapper_1.recordUnknownEvent)(spec.cliToolId, nativeEventName);
+                return null;
+            }
+            return (0, event_mapper_1.buildNormalizedEvent)(mapping, raw.payload, receivedAt, {
+                detail: spec.extractDetail,
+                conversationId: spec.conversationIdFields,
+                toolCallId: spec.toolCallIdFields,
+            });
+        },
+        parsePermissionRequest: spec.parsePermissionRequest,
+        parseQuestion: spec.parseQuestion,
+        encodeVerdict(verdict) {
+            return { kind: 'responseBody', body: spec.encodeVerdict(verdict) };
+        },
+        prepareLaunch: spec.prepareLaunch,
+        async subscribe() {
+            // C1: push sources are subscribed to by existing, not by connecting. The
+            // method is here so a caller can treat both transports the same way.
+            return INERT_SUBSCRIPTION;
+        },
+        async decide(target, decision, verdict) {
+            // C2: the verdict leaves through the body of the request the agent is
+            // blocked on, which the receiver is holding open in a slot.
+            (0, pending_decisions_1.fillDecisionSlot)(target, decision.id, spec.encodeVerdict(verdict));
+        },
+        async listPending(target) {
+            return (0, pending_decisions_1.listOpenDecisions)(target);
+        },
+        async probeActivity() {
+            // C7: there is no endpoint to ask. Callers fall back to the scraper.
+            return null;
+        },
+        liveness() {
+            // C6: a hook that has not fired and an agent that has died look the same.
+            return { state: 'unknown' };
+        },
+    };
+}
+/**
+ * Build a pull (subscription) source from its differences.
+ *
+ * The mirror image of {@link definePushHookSource}: the lifecycle is real and
+ * the verdict never rides on a response body, so {@link
+ * AgentEventSource.encodeVerdict} always answers `outOfBand` and callers are
+ * pushed towards `decide()`.
+ */
+function definePullEventSource(spec) {
+    const nativeEventNameFields = spec.nativeEventNameFields ?? ['type'];
+    return {
+        cliToolId: spec.cliToolId,
+        transport: 'pull',
+        noDecision: spec.noDecision,
+        capabilities: spec.capabilities,
+        normalizeEvent(raw) {
+            const receivedAt = raw.receivedAt ?? Date.now();
+            const nativeEventName = nativeEventNameFields.length > 0
+                ? (0, event_mapper_1.readFirstStringField)(raw.payload, nativeEventNameFields)
+                : null;
+            if (raw.event != null && (0, agent_event_types_1.isAgentEventType)(raw.event)) {
+                return (0, event_mapper_1.buildNormalizedEvent)({ event: raw.event }, raw.payload, receivedAt, {
+                    detail: spec.extractDetail,
+                    conversationId: spec.conversationIdFields,
+                    toolCallId: spec.toolCallIdFields,
+                });
+            }
+            const mapping = (0, event_mapper_1.runEventMappers)(spec.mappers, nativeEventName, raw.payload);
+            if (!mapping) {
+                (0, event_mapper_1.recordUnknownEvent)(spec.cliToolId, nativeEventName);
+                return null;
+            }
+            return (0, event_mapper_1.buildNormalizedEvent)(mapping, raw.payload, receivedAt, {
+                detail: spec.extractDetail,
+                conversationId: spec.conversationIdFields,
+                toolCallId: spec.toolCallIdFields,
+            });
+        },
+        parsePermissionRequest: spec.parsePermissionRequest,
+        parseQuestion: spec.parseQuestion,
+        encodeVerdict() {
+            // C2. There is no request to answer: the event arrived on a stream that
+            // has been open for hours and carries no reply channel.
+            return { kind: 'outOfBand' };
+        },
+        prepareLaunch: spec.prepareLaunch ?? ((_target, executablePath) => ({
+            command: executablePath,
+            settingsPath: null,
+        })),
+        subscribe: spec.subscribe,
+        decide: spec.decide,
+        listPending: spec.listPending,
+        probeActivity: spec.probeActivity,
+        liveness: spec.liveness,
+    };
+}

package/dist/server/src/lib/hooks/sources/event-mapper.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Predicate-based mapping from a source's own events onto the seven words
+ * (Issue #1759, constraint C4).
+ *
+ * The Claude-only implementation this replaces was a
+ * `Record<string, AgentEventType>`: one native spelling in, one word out. That
+ * shape is not general, and #1758 §5.2.3 is the proof:
+ *
+ *  - `message.part.updated` is `pre_tool_use` when `part.state.status` is
+ *    `running` and `post_tool_use` when it is `completed` or `error` — **the
+ *    same event name, two different words, chosen by a field.**
+ *  - `user_prompt_submit` has no event of its own; it is `message.updated` with
+ *    `info.role === "user"`.
+ *  - `notification` is three unrelated events (`permission.asked`,
+ *    `question.asked`, `session.error`) that differ only in `detail`.
+ *
+ * So a mapper is a function, and a source carries an ordered list of them:
+ * the first that returns a value wins, and a list that returns nothing means
+ * "this event is not one of the seven", which is a normal outcome, not an
+ * error (C8).
+ *
+ * @module lib/hooks/sources/event-mapper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UNKNOWN_EVENT_NAMES = void 0;
+exports.whenNamed = whenNamed;
+exports.fromNameTable = fromNameTable;
+exports.runEventMappers = runEventMappers;
+exports.recordUnknownEvent = recordUnknownEvent;
+exports.getUnknownEventTally = getUnknownEventTally;
+exports.resetUnknownEventTallies = resetUnknownEventTallies;
+exports.readStringField = readStringField;
+exports.readFirstStringField = readFirstStringField;
+exports.boundDetail = boundDetail;
+exports.isPlainObject = isPlainObject;
+exports.readNestedString = readNestedString;
+exports.buildNormalizedEvent = buildNormalizedEvent;
+const agent_event_types_1 = require("../../../lib/hooks/agent-event-types");
+/**
+ * The commonest rule: this native name is always that word.
+ *
+ * @param nativeName - e.g. `Stop`, `session.idle`
+ * @param event - The word it maps to
+ * @param detail - A fixed subtype, for sources that fold several events into
+ *   `notification` and need `detail` to tell them apart
+ */
+function whenNamed(nativeName, event, detail) {
+    return (nativeEventName) => nativeEventName === nativeName ? { event, detail: detail ?? null } : null;
+}
+/** Every entry of a name table, as rules. Order within the table is preserved. */
+function fromNameTable(table) {
+    return Object.entries(table).map(([nativeName, event]) => whenNamed(nativeName, event));
+}
+/**
+ * Run an ordered rule list.
+ *
+ * @returns The first mapping produced, or null when no rule matched
+ */
+function runEventMappers(mappers, nativeEventName, payload) {
+    for (const mapper of mappers) {
+        const mapped = mapper(nativeEventName, payload);
+        if (mapped)
+            return mapped;
+    }
+    return null;
+}
+/** Cap on remembered distinct names, so an unbounded vocabulary cannot grow this. */
+exports.MAX_UNKNOWN_EVENT_NAMES = 32;
+const unknownEvents = (globalThis.__agentSourceUnknownEvents ??= new Map());
+/**
+ * Record an event that mapped to nothing.
+ *
+ * Counted rather than thrown, because "I do not recognise this" is the steady
+ * state, not a fault: opencode publishes 89 event types against seven words,
+ * and `server.heartbeat` — which arrives every ten seconds — is not even in the
+ * server's own OpenAPI document (#1758 D3/D5). A receiver that threw would fail
+ * ten times a minute on a healthy connection.
+ */
+function recordUnknownEvent(cliToolId, nativeEventName) {
+    const tally = unknownEvents.get(cliToolId) ?? { count: 0, names: [] };
+    tally.count += 1;
+    const name = nativeEventName ?? '(unnamed)';
+    if (!tally.names.includes(name) && tally.names.length < exports.MAX_UNKNOWN_EVENT_NAMES) {
+        tally.names.push(name);
+    }
+    unknownEvents.set(cliToolId, tally);
+}
+/** @returns What this tool has sent that no rule claimed. */
+function getUnknownEventTally(cliToolId) {
+    const tally = unknownEvents.get(cliToolId);
+    return { count: tally?.count ?? 0, names: [...(tally?.names ?? [])] };
+}
+/** Forget the tallies. For tests; nothing in production resets them. */
+function resetUnknownEventTallies() {
+    unknownEvents.clear();
+}
+// =============================================================================
+// Payload field helpers
+// =============================================================================
+/** A non-empty string field, or null. */
+function readStringField(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+/** The first of `keys` present as a non-empty string, or null. */
+function readFirstStringField(payload, keys) {
+    for (const key of keys) {
+        const value = readStringField(payload, key);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
+/** Trim a subtype to the length the store accepts. */
+function boundDetail(value) {
+    if (value === null || value === '')
+        return null;
+    return value.slice(0, agent_event_types_1.MAX_EVENT_DETAIL_LENGTH);
+}
+/** Type guard for a JSON object (not an array, not null). */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Read a nested path, e.g. `['part', 'state', 'status']`. */
+function readNestedString(payload, path) {
+    let current = payload;
+    for (const key of path) {
+        if (!isPlainObject(current))
+            return null;
+        current = current[key];
+    }
+    return typeof current === 'string' && current !== '' ? current : null;
+}
+/**
+ * Assemble a {@link NormalizedAgentEvent} from a mapping and the payload.
+ *
+ * @param mapping - What the rules decided
+ * @param payload - The event, verbatim
+ * @param receivedAt - Epoch ms
+ * @param fallbacks - Where to look for the fields the rule left unset
+ */
+function buildNormalizedEvent(mapping, payload, receivedAt, fallbacks = {}) {
+    const detail = mapping.detail !== undefined && mapping.detail !== null
+        ? boundDetail(mapping.detail)
+        : boundDetail(fallbacks.detail?.(mapping.event, payload) ?? null);
+    return {
+        event: mapping.event,
+        detail,
+        conversationId: mapping.conversationId ??
+            (fallbacks.conversationId ? readFirstStringField(payload, fallbacks.conversationId) : null),
+        toolCallId: mapping.toolCallId ??
+            (fallbacks.toolCallId ? readFirstStringField(payload, fallbacks.toolCallId) : null),
+        raw: payload,
+        receivedAt,
+    };
+}

package/dist/server/src/lib/hooks/sources/gemini/event-vocabulary.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Gemini CLI's hook vocabulary — its event spellings and its subtype values
+ * (Issue #1762).
+ *
+ * Kept here rather than added to `../hook-event-vocabulary`, which is
+ * deliberate and is spelled out in `docs/design/agent-event-source-interface.md`
+ * §5: that table is *the CamelCase dialect Claude, codex and copilot share*, and
+ * putting `BeforeTool` in it would make every one of those tools accept a
+ * spelling none of them ever sends. The fact that no gemini session has ever
+ * emitted `Stop` is information, and merging the tables destroys it.
+ *
+ * ## Where the table comes from
+ *
+ * The CLI's own migration command. `gemini hooks migrate --from-claude` exists
+ * to port a Claude `settings.json` across, so the map it carries is gemini's
+ * authoritative statement of "this Claude event is that gemini event" (#1757
+ * §5.3.1). Confirmed against the shipped bundle's `HookEventName` enum in
+ * v0.55.1, which lists eleven events:
+ *
+ * ```
+ * BeforeTool  AfterTool  BeforeAgent  Notification  AfterAgent  SessionStart
+ * SessionEnd  PreCompress  BeforeModel  AfterModel  BeforeToolSelection
+ * ```
+ *
+ * Four of them have no word in `AGENT_EVENT_TYPES` and are deliberately absent
+ * below: `PreCompress`, `BeforeModel`, `AfterModel` and `BeforeToolSelection`
+ * are real gemini events (`PreCompress` and `BeforeModel` were captured live in
+ * #1757) that mean nothing CommandMate models. They map to null, get counted by
+ * `recordUnknownEvent`, and are not filed under something adjacent.
+ *
+ * @module lib/hooks/sources/gemini/event-vocabulary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_NOTIFICATION_SUBTYPES = exports.GEMINI_HOOK_EVENT_NAMES = void 0;
+exports.extractGeminiEventDetail = extractGeminiEventDetail;
+const event_mapper_1 = require("../event-mapper");
+const hook_event_vocabulary_1 = require("../hook-event-vocabulary");
+/**
+ * `hook_event_name` values gemini sends, mapped onto the seven words.
+ *
+ * Four of the seven are spelled differently from Claude's — `BeforeAgent`,
+ * `AfterAgent`, `BeforeTool`, `AfterTool` — which is the whole reason a source
+ * carries its own mappers. `SubagentStop` has no gemini counterpart (the CLI
+ * has no subagents; `migrate` folds it onto `AfterAgent`), so it is absent.
+ */
+exports.GEMINI_HOOK_EVENT_NAMES = {
+    SessionStart: 'session_start',
+    SessionEnd: 'session_end',
+    BeforeAgent: 'user_prompt_submit',
+    AfterAgent: 'stop',
+    BeforeTool: 'pre_tool_use',
+    AfterTool: 'post_tool_use',
+    Notification: 'notification',
+};
+/**
+ * gemini's only notification subtype, and the word CommandMate spells it with.
+ *
+ * The value is read out of the shipped bundle: `NotificationType` has exactly
+ * one member, `ToolPermission`, and `fireNotificationEvent` puts it on the wire
+ * verbatim as `notification_type` (v0.55.1). It means precisely what Claude's
+ * `permission_prompt` means — a tool is asking for approval and a dialog is on
+ * screen.
+ *
+ * **The translation is not cosmetic.** `status-mapping.ts` and
+ * `agent-event-state.ts` compare `detail` against the literal string
+ * `permission_prompt`; #1759 abstracted the event *names* but left the subtype
+ * vocabulary shared and Claude-shaped. Publishing `ToolPermission` would
+ * therefore be publishing a subtype nothing downstream recognises, and gemini
+ * would never report `waiting` — silently, with the event arriving and being
+ * recorded correctly the whole time. Translating here is the one place that can
+ * fix it without either editing a tool-agnostic consumer to know a tool's
+ * dialect, or teaching the shared table a gemini spelling.
+ */
+exports.GEMINI_NOTIFICATION_SUBTYPES = {
+    ToolPermission: 'permission_prompt',
+};
+/**
+ * The subtype for a gemini payload, in CommandMate's vocabulary.
+ *
+ * gemini's payload is Claude-shaped snake_case — verified field by field
+ * against the bundle's per-event input builders (`source` on `SessionStart`,
+ * `reason` on `SessionEnd`, `tool_name` on `BeforeTool`/`AfterTool`,
+ * `notification_type` on `Notification`) — so the shared extractor does the
+ * reading. Only `notification` needs translating afterwards.
+ *
+ * An unrecognised notification type is passed through rather than dropped: a
+ * type gemini adds later is worth recording under its own name, and nothing
+ * downstream branches on a value it does not know.
+ *
+ * @param event - The word this payload mapped to
+ * @param payload - The event, verbatim
+ * @returns The subtype, or null when the event has none
+ */
+function extractGeminiEventDetail(event, payload) {
+    if (event !== 'notification')
+        return (0, hook_event_vocabulary_1.extractSnakeCaseEventDetail)(event, payload);
+    const native = (0, event_mapper_1.readStringField)(payload, 'notification_type');
+    if (native === null)
+        return null;
+    return (0, event_mapper_1.boundDetail)(exports.GEMINI_NOTIFICATION_SUBTYPES[native] ?? native);
+}