commandmate 0.22.1 → 0.23.0

package/dist/server/src/lib/hooks/sources/opencode/ingest.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * What a normalised opencode event does to CommandMate's state (Issue #1763).
+ *
+ * The consuming half of the pipeline was already tool-agnostic before this
+ * Issue: `agent-event-state`, `permission-decision-service`,
+ * `current-output-builder`, `status-mapping` and `prompt-waiting-composition`
+ * all key off (worktree, tool, instance) and branch on nothing else. So this
+ * module is deliberately thin — it is the same sequence
+ * `POST /api/hooks/agent-event` and `POST /api/hooks/permission-request`
+ * perform, called in-process because there is no request to perform it on.
+ *
+ * The one place the two paths differ is *where the verdict goes*. A hook is
+ * answered in the body of the request it arrived on; an opencode approval is
+ * answered by a POST to the agent's own server, minutes later if need be. Both
+ * are spelled `answerPendingDecision(source, …)`, which is the seam #1759 built
+ * for exactly this.
+ *
+ * ## Why the database imports are dynamic
+ *
+ * `../registry` statically imports `./source`, so anything `./source`'s module
+ * graph reaches becomes part of every import of `@/lib/hooks/sources` —
+ * including `better-sqlite3` if this module were pulled in eagerly. The state
+ * effects are needed only when an event actually arrives, so they are imported
+ * then. (`./source` does not import this module at all; the runtime wires the
+ * two together.)
+ *
+ * Nothing here throws. An event is a fact about a session that is still
+ * running, and a failure to record it must cost the record, never the session.
+ *
+ * @module lib/hooks/sources/opencode/ingest
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingestOpencodeEvent = ingestOpencodeEvent;
+const logger_1 = require("../../../../lib/logger");
+const agent_event_types_1 = require("../../../../lib/hooks/agent-event-types");
+const agent_event_state_1 = require("../../../../lib/session/agent-event-state");
+const structured_prompt_1 = require("../../../../lib/session/structured-prompt");
+const abstain_1 = require("../abstain");
+const event_mapper_1 = require("../event-mapper");
+const pending_decisions_1 = require("../pending-decisions");
+const registry_1 = require("../registry");
+const mappers_1 = require("./mappers");
+const payloads_1 = require("./payloads");
+const tool_id_1 = require("./tool-id");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/opencode/ingest');
+/** The one-line human-facing summary for a notification, or null. */
+function describeNotification(event) {
+    const properties = (0, event_mapper_1.isPlainObject)(event.raw.properties) ? event.raw.properties : {};
+    if (event.detail === mappers_1.OPENCODE_PERMISSION_DETAIL) {
+        // `metadata.command` exists for `bash` approvals and is what the human is
+        // being asked about; the approval kind is the fallback for the rest.
+        return ((0, event_mapper_1.readNestedString)(properties, ['metadata', 'command']) ??
+            (0, event_mapper_1.readStringField)(properties, 'permission'));
+    }
+    if (event.detail === mappers_1.OPENCODE_QUESTION_DETAIL) {
+        const questions = properties.questions;
+        if (Array.isArray(questions) && (0, event_mapper_1.isPlainObject)(questions[0])) {
+            return (0, event_mapper_1.readStringField)(questions[0], 'question');
+        }
+        return null;
+    }
+    if (event.detail === mappers_1.OPENCODE_ERROR_DETAIL) {
+        return ((0, event_mapper_1.readNestedString)(properties, ['error', 'data', 'message']) ??
+            (0, event_mapper_1.readNestedString)(properties, ['error', 'name']));
+    }
+    return null;
+}
+/**
+ * Adjudicate one approval and answer it over REST (Auto-Yes v2).
+ *
+ * The adjudication itself is `resolvePermissionRequest`, unchanged and shared
+ * with every hook-based tool. What is opencode-specific is what silence means:
+ * on Claude an abstention costs a dialog, here it costs the session, because
+ * the agent waits with no timeout at all (#1758 §5.5.3). `describeAbstain` is
+ * how that gets said out loud — nothing else will say it, since a blocked
+ * opencode session looks exactly like one that is thinking.
+ */
+async function adjudicatePermission(target, event, instanceId) {
+    const source = (0, registry_1.getAgentEventSource)(tool_id_1.OPENCODE_CLI_TOOL_ID);
+    const pending = (0, payloads_1.toOpencodePendingPermission)(event.raw, event.receivedAt);
+    if (!pending) {
+        logger.info('opencode-permission-unparsed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+        });
+        return;
+    }
+    const { resolvePermissionRequest } = await Promise.resolve().then(() => __importStar(require('../../../../lib/hooks/permission-decision-service')));
+    const payload = source.parsePermissionRequest(event.raw);
+    const decision = resolvePermissionRequest({ worktreeId: target.worktreeId, cliToolId: tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId }, payload);
+    const verdict = decision.behavior === 'allow' ? { kind: 'allowOnce' } : { kind: 'abstain' };
+    if (verdict.kind === 'abstain') {
+        const abstain = (0, abstain_1.describeAbstain)(source);
+        if (!abstain.safe) {
+            logger.warn('permission-request-abstain-blocks-agent', {
+                worktreeId: target.worktreeId,
+                cliToolId: tool_id_1.OPENCODE_CLI_TOOL_ID,
+                instanceId,
+                toolName: payload?.toolName ?? null,
+                decisionId: pending.id,
+                reason: decision.reason,
+                consequence: abstain.summary,
+                blocksForMs: abstain.blocksForMs,
+            });
+        }
+    }
+    // C2: for this source the verdict leaves over its own connection, and the
+    // `{}` that comes back is an acknowledgement rather than a reply body.
+    await (0, pending_decisions_1.answerPendingDecision)(source, { worktreeId: target.worktreeId, cliToolId: tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId }, pending, verdict);
+    logger.info('opencode-permission-decided', {
+        worktreeId: target.worktreeId,
+        instanceId,
+        decisionId: pending.id,
+        toolName: payload?.toolName ?? null,
+        behavior: decision.behavior,
+        reason: decision.reason,
+        suppressedBy: decision.suppressedBy,
+    });
+}
+/**
+ * Record a question so `capture --prompts` and the picker can show its options.
+ *
+ * The structured content Claude never had: its `AskUserQuestion` picker has to
+ * be read off the screen (#1708), while opencode publishes the questions and
+ * their choices as data (#1758 §5.2.4).
+ *
+ * `reportPermissionRequestPending` is called alongside because that is the only
+ * exported way to tell the detection layer a human is blocked, and a question
+ * blocks exactly as an approval does — the session reads `busy` and no
+ * `session.idle` arrives until it is answered (§5.3.1). It is recorded as
+ * provisional, so it expires unless the scraper corroborates it, which is the
+ * same treatment Claude's pre-dialog prediction gets.
+ */
+function recordQuestion(target, event, instanceId) {
+    const source = (0, registry_1.getAgentEventSource)(tool_id_1.OPENCODE_CLI_TOOL_ID);
+    const spec = source.parseQuestion(event.raw);
+    if (!spec)
+        return;
+    (0, agent_event_state_1.recordAskUserQuestion)(target.worktreeId, tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId, spec, event.receivedAt);
+    (0, agent_event_state_1.reportPermissionRequestPending)(target.worktreeId, tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId, 'question', event.receivedAt);
+    logger.info('opencode-question-recorded', {
+        worktreeId: target.worktreeId,
+        instanceId,
+        questionCount: spec.questions.length,
+        optionCounts: spec.questions.map((question) => question.choices.length),
+    });
+}
+/** Apply a completed turn to whatever the worktree is doing. */
+async function applyStop(target, instanceId) {
+    const [{ getDbInstance }, { getWorktreeById }, { applyAgentStopEvent }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require('../../../../lib/db/db-instance'))),
+        Promise.resolve().then(() => __importStar(require('../../../../lib/db'))),
+        Promise.resolve().then(() => __importStar(require('../../../../lib/hooks/agent-event-service'))),
+    ]);
+    const db = getDbInstance();
+    const worktree = getWorktreeById(db, target.worktreeId) ?? null;
+    if (!worktree) {
+        // The worktree was removed while its pane was still running. Ordinary, not
+        // an error — the same outcome the hook receiver reports as 202-and-drop.
+        logger.info('opencode-stop-unresolved-target', { worktreeId: target.worktreeId });
+        return;
+    }
+    const outcome = await applyAgentStopEvent(db, worktree, tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId);
+    logger.info('opencode-stop-applied', {
+        worktreeId: target.worktreeId,
+        instanceId,
+        taskId: outcome.taskId,
+        taskEventApplied: outcome.taskEventApplied,
+        verificationRunId: outcome.verificationRunId,
+    });
+}
+/**
+ * Apply one event from the stream.
+ *
+ * @param target - The instance the subscription belongs to
+ * @param event - Already normalised and already through the turn gate
+ */
+async function ingestOpencodeEvent(target, event) {
+    const instanceId = target.instanceId ?? tool_id_1.OPENCODE_CLI_TOOL_ID;
+    try {
+        // The same guard the hook receiver applies. It cannot catch the abort
+        // double-idle on its own — see `./turn-gate`, which is what does — but it
+        // does cover a frame delivered twice by a re-sync racing the live stream.
+        if ((0, agent_event_state_1.isDuplicateAgentEvent)(target.worktreeId, tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId, event.event, event.conversationId, event.receivedAt, event.detail)) {
+            logger.info('opencode-event-duplicate-dropped', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                event: event.event,
+                detail: event.detail,
+            });
+            return;
+        }
+        (0, agent_event_state_1.recordAgentEvent)(target.worktreeId, tool_id_1.OPENCODE_CLI_TOOL_ID, instanceId, {
+            event: event.event,
+            at: event.receivedAt,
+            detail: event.detail?.slice(0, agent_event_types_1.MAX_EVENT_DETAIL_LENGTH) ?? null,
+            sessionId: event.conversationId,
+            message: describeNotification(event)?.slice(0, structured_prompt_1.MAX_STRUCTURED_PROMPT_MESSAGE_LENGTH) ?? null,
+        });
+        if (event.event === 'notification' && event.detail === mappers_1.OPENCODE_PERMISSION_DETAIL) {
+            await adjudicatePermission(target, event, instanceId);
+            return;
+        }
+        if (event.event === 'notification' && event.detail === mappers_1.OPENCODE_QUESTION_DETAIL) {
+            recordQuestion(target, event, instanceId);
+            return;
+        }
+        if (event.event === 'stop') {
+            await applyStop(target, instanceId);
+            return;
+        }
+        logger.info('opencode-event-received', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            event: event.event,
+            detail: event.detail,
+        });
+    }
+    catch (error) {
+        logger.error('opencode-event-ingest-failed', {
+            worktreeId: target.worktreeId,
+            instanceId,
+            event: event.event,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

package/dist/server/src/lib/hooks/sources/opencode/mappers.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * opencode's SSE frames, mapped onto the seven words (Issue #1763, constraint
+ * C4).
+ *
+ * Every rule below is lifted from a frame that was actually captured from
+ * `opencode` 1.18.3 — the files in `tests/fixtures/hooks/opencode/` — and not
+ * from the server's OpenAPI document. The document is wrong in at least one
+ * place that matters (`server.heartbeat` is not in its `Event` union yet
+ * arrives every ten seconds, #1758 D5), so the fixtures are the specification
+ * and the tests read them directly.
+ *
+ * Three of the rules cannot be written as a name table, which is the whole
+ * reason {@link EventMapper} is a function (#1758 §5.2.3):
+ *
+ *  - `message.part.updated` is `pre_tool_use` or `post_tool_use` depending on
+ *    `part.state.status` — one event name, two words.
+ *  - `user_prompt_submit` has no event of its own; it is `message.updated` with
+ *    `info.role === "user"`.
+ *  - `notification` is three unrelated events told apart only by `detail`.
+ *
+ * ## The envelope
+ *
+ * ```json
+ * { "id": "evt_…", "type": "session.idle", "properties": { "sessionID": "ses_…" } }
+ * ```
+ *
+ * The event's name is in `type` and everything else is nested under
+ * `properties`, so `conversationIdFields` — which reads flat keys — cannot
+ * reach `sessionID`. {@link withConversationId} fills it in from the nested
+ * path instead, which is the C5 escape hatch the interface documents.
+ *
+ * @module lib/hooks/sources/opencode/mappers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENCODE_MAPPERS = exports.OPENCODE_ERROR_DETAIL = exports.OPENCODE_QUESTION_DETAIL = exports.OPENCODE_PERMISSION_DETAIL = void 0;
+exports.frameProperties = frameProperties;
+exports.frameSessionId = frameSessionId;
+exports.partToolName = partToolName;
+exports.partCallId = partCallId;
+exports.withConversationId = withConversationId;
+const event_mapper_1 = require("../event-mapper");
+/**
+ * Detail for `permission.asked`.
+ *
+ * Deliberately Claude's spelling. `wait --on-prompt` has to mean the same thing
+ * on both tools, and `agent-event-state` opens its prompt-waiting record on
+ * exactly this string — renaming it for opencode would leave the state machine
+ * silently unable to see an opencode approval dialog (#1758 §9.3).
+ */
+exports.OPENCODE_PERMISSION_DETAIL = 'permission_prompt';
+/**
+ * Detail for `question.asked`.
+ *
+ * A new value rather than a reuse: opencode's `question` tool is answered with
+ * structured choices over its own endpoint, and nothing above this layer should
+ * be able to confuse it with an approval it could allow. There is no
+ * `idle_prompt` equivalent on opencode at all — no event reports "the agent is
+ * sitting at the composer" — so that spelling never appears here.
+ */
+exports.OPENCODE_QUESTION_DETAIL = 'question_prompt';
+/** Detail for `session.error`. */
+exports.OPENCODE_ERROR_DETAIL = 'error';
+/** The `properties` object of a frame, or an empty object. */
+function frameProperties(payload) {
+    return (0, event_mapper_1.isPlainObject)(payload.properties) ? payload.properties : {};
+}
+/** `properties.sessionID`, the id every frame that belongs to a turn carries. */
+function frameSessionId(payload) {
+    return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['sessionID']);
+}
+/** `properties.part.state.status` — `pending` / `running` / `completed` / `error`. */
+function partStatus(payload) {
+    return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['part', 'state', 'status']);
+}
+/** Whether this `message.part.updated` describes a tool call rather than text. */
+function partIsToolCall(payload) {
+    return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['part', 'type']) === 'tool';
+}
+/** `properties.part.tool` — `bash`, `read`, … (lower case, unlike Claude's). */
+function partToolName(payload) {
+    return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['part', 'tool']);
+}
+/** `properties.part.callID` — the correlation key for one tool call. */
+function partCallId(payload) {
+    return (0, event_mapper_1.readNestedString)(frameProperties(payload), ['part', 'callID']);
+}
+/** Statuses that mean the tool call is over, either way (#1758 §5.2.3). */
+const FINISHED_PART_STATUSES = ['completed', 'error'];
+/**
+ * The ordered rules, first match wins.
+ *
+ * `session.status`, `server.connected`, `server.heartbeat`, `permission.replied`
+ * and `question.replied` are deliberately absent. They are real frames that
+ * arrive on every healthy connection and they map to none of the seven words,
+ * so they fall through, return null and are counted (C8) — which is what the
+ * interface asks for and what stops a ten-second keepalive from throwing.
+ *
+ * `session.status(idle)` in particular must NOT be mapped: it is emitted in the
+ * same millisecond as `session.idle` and mapping both would report every turn's
+ * completion twice (#1758 §5.3.2 rule 4).
+ */
+const OPENCODE_BASE_MAPPERS = [
+    // 1:1. `session.deleted` only fires for an explicit `DELETE /session/:id` —
+    // the TUI's `/exit` emits nothing at all — so it is expressible but is not
+    // the signal that the agent is gone. That stays tmux's job (#1758 §5.6.4).
+    (0, event_mapper_1.whenNamed)('session.idle', 'stop'),
+    (0, event_mapper_1.whenNamed)('session.created', 'session_start'),
+    (0, event_mapper_1.whenNamed)('session.deleted', 'session_end'),
+    // Composite: no dedicated event, so the role decides.
+    (type, payload) => type === 'message.updated' &&
+        (0, event_mapper_1.readNestedString)(frameProperties(payload), ['info', 'role']) === 'user'
+        ? { event: 'user_prompt_submit' }
+        : null,
+    // Partial match: one event name, two words, chosen by a nested status.
+    // `pending` — the frame just before `running` — maps to nothing on purpose;
+    // mapping it as well would report every tool call twice.
+    (type, payload) => type === 'message.part.updated' && partIsToolCall(payload) && partStatus(payload) === 'running'
+        ? {
+            event: 'pre_tool_use',
+            detail: (0, event_mapper_1.boundDetail)(partToolName(payload)),
+            toolCallId: partCallId(payload),
+        }
+        : null,
+    (type, payload) => type === 'message.part.updated' &&
+        partIsToolCall(payload) &&
+        FINISHED_PART_STATUSES.includes(partStatus(payload) ?? '')
+        ? {
+            event: 'post_tool_use',
+            detail: (0, event_mapper_1.boundDetail)(partToolName(payload)),
+            toolCallId: partCallId(payload),
+        }
+        : null,
+    // Bundle: three unrelated events collapse into `notification`.
+    (0, event_mapper_1.whenNamed)('permission.asked', 'notification', exports.OPENCODE_PERMISSION_DETAIL),
+    (0, event_mapper_1.whenNamed)('question.asked', 'notification', exports.OPENCODE_QUESTION_DETAIL),
+    (0, event_mapper_1.whenNamed)('session.error', 'notification', exports.OPENCODE_ERROR_DETAIL),
+];
+/**
+ * Fill `conversationId` from the nested envelope.
+ *
+ * @param mapper - A rule that may or may not have set the field itself
+ * @returns The same rule, with `properties.sessionID` as the fallback
+ */
+function withConversationId(mapper) {
+    return (type, payload) => {
+        const mapped = mapper(type, payload);
+        if (!mapped)
+            return null;
+        return { ...mapped, conversationId: mapped.conversationId ?? frameSessionId(payload) };
+    };
+}
+/** The rules an opencode source carries. */
+exports.OPENCODE_MAPPERS = OPENCODE_BASE_MAPPERS.map(withConversationId);

package/dist/server/src/lib/hooks/sources/opencode/payloads.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Reading opencode's approval and question payloads (Issue #1763, seam S7).
+ *
+ * Both shapes are taken from captured frames — `permission-asked.json` and
+ * `question-asked.json` in `tests/fixtures/hooks/opencode/` — and both are
+ * parsed into the vocabulary the tool-independent adjudicator already speaks,
+ * so `permission-decision-service` and `agent-event-state` need no opencode
+ * branch.
+ *
+ * ## The tool name is not in the approval payload
+ *
+ * `permission.asked` carries `permission` (the *kind* of approval:
+ * `external_directory`, …), `patterns`, `metadata` and `tool.callID` — but no
+ * tool name (#1758 §5.4). Auto-Yes matches deny patterns against what is being
+ * asked for, so the name has to come from somewhere: the `message.part.updated`
+ * frame for the same `callID` carries `part.tool` (`bash`), and it arrives
+ * first, so the subscription records the correlation as it goes and this module
+ * looks it up. When the correlation is missing the approval kind is used
+ * instead — an unknown tool name makes `collectToolInputMatchTexts` fall back
+ * to the serialised input, which contains the command, so the matching surface
+ * never silently empties.
+ *
+ * ## What the deny patterns see
+ *
+ * `metadata` verbatim (it holds `command` for `bash` approvals), plus the
+ * approval kind and its patterns. Nothing from the pane and nothing from an
+ * earlier request can reach it — the property #1699 was opened about.
+ *
+ * @module lib/hooks/sources/opencode/payloads
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TRACKED_TOOL_CALLS = void 0;
+exports.rememberOpencodeToolCall = rememberOpencodeToolCall;
+exports.lookupOpencodeToolName = lookupOpencodeToolName;
+exports.resetOpencodeToolCalls = resetOpencodeToolCalls;
+exports.parseOpencodePermissionRequest = parseOpencodePermissionRequest;
+exports.parseOpencodeQuestion = parseOpencodeQuestion;
+exports.toOpencodePendingPermission = toOpencodePendingPermission;
+exports.toOpencodePendingQuestion = toOpencodePendingQuestion;
+const ask_user_question_payload_1 = require("../../../../lib/hooks/ask-user-question-payload");
+const event_mapper_1 = require("../event-mapper");
+/**
+ * Cap on remembered `callID -> tool name` pairs.
+ *
+ * One per tool call, and a long session makes thousands, so the map is bounded
+ * and the oldest is dropped. Forgetting costs a less specific tool name on an
+ * approval, never a wrong one.
+ */
+exports.MAX_TRACKED_TOOL_CALLS = 256;
+const toolCallNames = (globalThis.__opencodeToolCallNames ??= new Map());
+/** Record that a tool call has a name, seen on a `message.part.updated` frame. */
+function rememberOpencodeToolCall(callId, toolName) {
+    toolCallNames.delete(callId);
+    toolCallNames.set(callId, toolName);
+    while (toolCallNames.size > exports.MAX_TRACKED_TOOL_CALLS) {
+        const oldest = toolCallNames.keys().next();
+        if (oldest.done)
+            break;
+        toolCallNames.delete(oldest.value);
+    }
+}
+/** The tool behind a `callID`, or null when it has not been seen. */
+function lookupOpencodeToolName(callId) {
+    if (!callId)
+        return null;
+    return toolCallNames.get(callId) ?? null;
+}
+/** Forget every correlation. Test seam. */
+function resetOpencodeToolCalls() {
+    toolCallNames.clear();
+}
+/**
+ * The object an approval or question lives in.
+ *
+ * Two callers hand this module two different shapes and both are legitimate:
+ * the SSE frame `{ id, type, properties }`, and the bare object
+ * `GET /permission` returns when a missed event is being recovered. Unwrapping
+ * here is what lets the reconnect path reuse the live path's parsing.
+ */
+function unwrap(payload) {
+    if (typeof payload.type === 'string' && (0, event_mapper_1.isPlainObject)(payload.properties)) {
+        return payload.properties;
+    }
+    return payload;
+}
+/** `tool.callID`, present on both approvals and questions. */
+function toolCallId(properties) {
+    return (0, event_mapper_1.readNestedString)(properties, ['tool', 'callID']);
+}
+/**
+ * Read a `permission.asked` frame, or a pending entry from `GET /permission`.
+ *
+ * @param payload - The frame or the bare permission object
+ * @returns The payload the adjudicator judges, or null when this is not an
+ *   approval this server can read — which every caller must treat as "no
+ *   decision", i.e. leave it for the human
+ */
+function parseOpencodePermissionRequest(payload) {
+    const properties = unwrap(payload);
+    const permissionId = (0, event_mapper_1.readStringField)(properties, 'id');
+    const sessionId = (0, event_mapper_1.readStringField)(properties, 'sessionID');
+    // Both are required: the id is what a verdict is addressed to, and without a
+    // session there is nothing to attribute the request to.
+    if (!permissionId || !sessionId)
+        return null;
+    // `question.asked` shares the envelope; it is answered with choices, never
+    // adjudicated as an approval.
+    if (Array.isArray(properties.questions))
+        return null;
+    const kind = (0, event_mapper_1.readStringField)(properties, 'permission');
+    const metadata = (0, event_mapper_1.isPlainObject)(properties.metadata) ? properties.metadata : {};
+    return {
+        toolName: lookupOpencodeToolName(toolCallId(properties)) ?? kind ?? 'permission',
+        toolInput: {
+            permission: kind,
+            patterns: Array.isArray(properties.patterns) ? properties.patterns : [],
+            ...metadata,
+        },
+        // `per_…` is what the reply URL takes, and it is stable for the life of the
+        // request — the correlation key Claude spells `prompt_id`.
+        promptId: permissionId,
+        sessionId,
+        // opencode has no equivalent of Claude's permission mode: the dialog is
+        // drawn unconditionally (§5.5.3), so there is no "do not ask me" state that
+        // would make a no-decision non-blocking.
+        permissionMode: null,
+        // `always` is the rule that would be saved by answering `always`. Recorded
+        // for the audit trail, never a decision input — it is opencode's suggestion,
+        // which is the thing being judged.
+        permissionSuggestions: Array.isArray(properties.always) ? properties.always : null,
+    };
+}
+/**
+ * Read a `question.asked` frame (#1758 §5.2.4).
+ *
+ * The one place opencode is *better* structured than Claude: the choices arrive
+ * as data, where Claude's `AskUserQuestion` picker had to be read off the
+ * screen. The inner shape — `{ question, header, options: [{ label,
+ * description }] }` — is identical to Claude's `tool_input.questions`, so the
+ * existing strict parser is reused rather than re-derived.
+ *
+ * @returns The spec, or null when this is not a readable question
+ */
+function parseOpencodeQuestion(payload) {
+    const properties = unwrap(payload);
+    const questionId = (0, event_mapper_1.readStringField)(properties, 'id');
+    if (!questionId)
+        return null;
+    const questions = (0, ask_user_question_payload_1.parseAskUserQuestionToolInput)({ questions: properties.questions });
+    if (questions === null)
+        return null;
+    return { questions, promptId: questionId };
+}
+/**
+ * Turn an approval into the transport-independent {@link PendingDecision}.
+ *
+ * @param payload - A `permission.asked` frame or a `GET /permission` entry
+ * @param askedAt - Epoch ms
+ */
+function toOpencodePendingPermission(payload, askedAt) {
+    const parsed = parseOpencodePermissionRequest(payload);
+    if (!parsed || !parsed.promptId)
+        return null;
+    return {
+        kind: 'permission',
+        id: parsed.promptId,
+        conversationId: parsed.sessionId,
+        subject: { kind: 'permission', toolName: parsed.toolName, toolInput: parsed.toolInput },
+        raw: payload,
+        askedAt,
+    };
+}
+/** Turn a question into a {@link PendingDecision}. */
+function toOpencodePendingQuestion(payload, askedAt) {
+    const properties = unwrap(payload);
+    const questionId = (0, event_mapper_1.readStringField)(properties, 'id');
+    const spec = parseOpencodeQuestion(payload);
+    if (!questionId || !spec)
+        return null;
+    return {
+        kind: 'question',
+        id: questionId,
+        conversationId: (0, event_mapper_1.readStringField)(properties, 'sessionID'),
+        subject: { kind: 'question', spec },
+        raw: payload,
+        askedAt,
+    };
+}