agent-control-plane-core 0.5.2 → 0.6.0

package/src/adapters/gemini.mjs

@@ -40,10 +40,13 @@ import {
   canonicalTool,
   lookup,
   assertAliasTargetsModeled,
+  MODELED_TOOL_INPUT_KEYS,
   makeEvent,
   normalizeVerdict,
   nativeResponse,
-  collectPassthrough,
+  UNRENDERED_ON_UNKNOWN,
+  readonlySet,
+  baseMeta,
   asObject,
   asString,
   asStringOrNull,
@@ -51,8 +54,12 @@ import {
 
 /** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
 /** @typedef {import("../control-plane.mjs").Verdict} Verdict */
-/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 /** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+// Re-exported on this subpath even though no signature below names it:
+// tsc turns each @typedef into an `export type` in the generated .d.mts,
+// so dropping this line breaks `import type { EventMeta } from "…/<agent>"`
+// for every TypeScript consumer.
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
 
 export const AGENT = "gemini";
 export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
@@ -62,8 +69,18 @@ export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
  * builtins on v0.26+ (COVERED). MCP routing through the same matcher is only
  * MEDIUM-confidence and unproven, subagent firing for a loaded agent is
  * undocumented, and resumed-session behavior has no source — all three are
- * UNKNOWN, held at fail-closed until an item-⑤ probe upgrades them. A guessed ✅
- * here would be a silent fail-open.
+ * UNKNOWN. A guessed ✅ here would be a silent fail-open.
+ *
+ * Only the MCP row is fail-closed in practice: `parse` reads it, because
+ * {@link classifyCallClass} detects MCP from the tool name or `mcp_context`.
+ * The SUBAGENT row answers only for a payload carrying a non-empty `agent_type`
+ * ({@link classifyCallClass}); Gemini CLI documents no such field, so a
+ * subagent's call is judged today by the row its TOOL selects — BUILTIN
+ * (COVERED, i.e. vetoable), or the MCP row above when the name or `mcp_context`
+ * says so. The RESUMED row has no signal at all and is DECLARATIVE ONLY. Both
+ * record the matrix verdict for a consumer reading COVERAGE directly; the
+ * subagent one starts biting the moment a payload names an agent, which is what
+ * an item-⑤ probe of [G3] would establish.
  */
 /** @type {import("../control-plane.mjs").CoverageMap} */
 export const COVERAGE = Object.freeze({
@@ -85,6 +102,54 @@ const GATED_EVENTS = Object.freeze(
 );
 assertGatedKinds(GATED_EVENTS, AGENT);
 
+// The kinds whose only content channel is context: the tool has already run
+// (or there is no tool), so neither an input nor an output replacement has
+// anywhere to go.
+const CONTEXT_ONLY = readonlySet(["mutated_input", "mutated_output"]);
+
+/**
+ * Which {@link VERDICT_CONTENT_FIELDS} have no native channel on each event
+ * kind, so `render` drops them. Gemini CLI documents
+ * `hookSpecificOutput.tool_input` on BeforeTool, `systemMessage` on the tool
+ * events and `hookSpecificOutput.additionalContext` on BeforeAgent. It documents
+ * NO AfterTool output-rewrite field, so `mutated_output` is dropped on every
+ * kind. `mutated_input` is dropped everywhere
+ * but BeforeTool: the tool has already run by AfterTool, and BeforeAgent has no
+ * tool input at all, so emitting `tool_input` there names a channel the host
+ * ignores while reading to the caller as a mutation applied.
+ *
+ * ALLOW path only. The enforced-deny branch of `render` returns no stdout at
+ * all, so a deny drops `additional_context` too, on every kind — these rows do
+ * not describe it.
+ *
+ * AfterTool is GATED here, so a redaction verdict does reach this adapter and
+ * cannot be honoured. It renders {@link POST_TOOL_REDACTION_UNSUPPORTED} on
+ * `systemMessage` instead, so the model is told the output above it is
+ * unredacted rather than left to read it as vetted. The raw output still reaches
+ * the model; a guardrail that must actually redact has to deny.
+ * @type {Record<string, ReadonlySet<string>|undefined>}
+ */
+export const UNRENDERED_FIELDS = Object.freeze({
+  ...Object.fromEntries(
+    Object.values(EventKind).map((kind) => [kind, UNRENDERED_ON_UNKNOWN]),
+  ),
+  [EventKind.PRE_TOOL]: readonlySet(["mutated_output"]),
+  [EventKind.POST_TOOL]: CONTEXT_ONLY,
+  [EventKind.PROMPT_SUBMIT]: CONTEXT_ONLY,
+});
+
+/**
+ * What the model is told when a verdict redacts an AfterTool output Gemini has
+ * no channel to replace. Exported so a caller composing its own `systemMessage`
+ * can recognize it; recognize it with `endsWith`, never equality, because a
+ * verdict carrying `additional_context` too puts that context first (see
+ * {@link decisionBody}).
+ */
+export const POST_TOOL_REDACTION_UNSUPPORTED =
+  "The monitor redacted this tool output, but Gemini CLI has no AfterTool " +
+  "channel to replace it. Treat the tool output above as UNREDACTED and " +
+  "unvetted.";
+
 /** Gemini CLI native hook event names (the `hook_event_name` field). */
 export const HookEvent = Object.freeze({
   BEFORE_TOOL: "BeforeTool",
@@ -98,40 +163,30 @@ const NATIVE_TO_KIND = Object.freeze({
   [HookEvent.BEFORE_AGENT]: EventKind.PROMPT_SUBMIT,
 });
 
+/**
+ * The native event a conformance probe should carry for each kind — this
+ * adapter's own answer, so an every-kind probe exercises the branch that kind
+ * really takes. `session_start` and `unknown` have no Gemini event and are
+ * absent.
+ * @type {Record<string, string|undefined>}
+ */
+export const NATIVE_EVENT_FOR = Object.freeze(
+  Object.fromEntries(
+    Object.entries(NATIVE_TO_KIND).map(([native, kind]) => [kind, native]),
+  ),
+);
+
 // Only the fields the adapter maps are consumed; everything else (timestamp,
 // mcp_context, original_request_name, …) survives verbatim in meta.passthrough.
+// The STANDARD_META_FIELDS are consumed by `baseMeta`, not listed here.
 const CONSUMED = new Set([
   "hook_event_name",
-  "session_id",
-  "cwd",
-  "transcript_path",
   "tool_name",
   "tool_input",
   "tool_response",
   "prompt",
 ]);
 
-/**
- * @param {string} nativeEvent
- * @param {Record<string, unknown>} raw
- * @returns {EventMeta}
- */
-function geminiMeta(nativeEvent, raw) {
-  /** @type {EventMeta} */
-  const meta = {
-    agent: AGENT,
-    native_event: nativeEvent,
-    integration_mode: INTEGRATION_MODE,
-    primary_gate_present: true,
-    passthrough: collectPassthrough(raw, CONSUMED),
-  };
-  if (typeof raw.session_id === "string") meta.session_id = raw.session_id;
-  if (typeof raw.cwd === "string") meta.cwd = raw.cwd;
-  if (typeof raw.transcript_path === "string")
-    meta.transcript_path = raw.transcript_path;
-  return meta;
-}
-
 /**
  * Adapter-scoped native-builtin → canonical tool aliases, applied ONLY when a
  * call classifies as BUILTIN. These names are too generic for the global
@@ -141,10 +196,11 @@ function geminiMeta(nativeEvent, raw) {
  * `mcp_{server}_{tool}` name (gemini-cli docs/tools/mcp-server.md), so a bare
  * builtin name in `tool_name` can only be the builtin. Renaming the tool also
  * renames its INPUT to the schema that name advertises, via
- * {@link GEMINI_INPUT_ALIASES} — a consumer told `event.tool` is `Read` reads
- * `input.file_path` and finds it, rather than reading `undefined` off a
- * forwarded `absolute_path` and allowing. Targets are pinned to
- * {@link MODELED_TOOLS} at import, every entry must be witnessed by a gemini
+ * {@link GEMINI_INPUT_ALIASES}, and the rename must actually produce that key or
+ * the call keeps its native name (see {@link geminiCall}) — a consumer told
+ * `event.tool` is `Read` reads `input.file_path` and finds it, rather than
+ * reading `undefined` off a forwarded `absolute_path` and allowing. Targets are
+ * pinned to {@link MODELED_TOOLS} at import, every entry must be witnessed by a gemini
  * conformance fixture (`assertToolAliasesCovered`), and every aliased case must
  * carry the canonical input key (`assertAliasedInputsCanonical`).
  * @type {Readonly<Record<string, string>>}
@@ -172,38 +228,27 @@ const GEMINI_INPUT_ALIASES = Object.freeze({
 
 assertAliasTargetsModeled(GEMINI_TOOL_ALIASES);
 
-/**
- * Canonicalize a Gemini native tool name: adapter-scoped builtin aliases first
- * (BUILTIN calls only — an MCP- or context-flagged call is never reclassified),
- * then the global {@link canonicalTool} map, else verbatim.
- * @param {string|null} nativeTool
- * @param {string} callClass a {@link CallClass} value
- * @returns {string|null}
- */
-function geminiCanonicalTool(nativeTool, callClass) {
-  if (nativeTool !== null && callClass === CallClass.BUILTIN) {
-    const scoped = lookup(GEMINI_TOOL_ALIASES, nativeTool);
-    if (scoped !== undefined) return scoped;
-  }
-  return canonicalTool(nativeTool);
-}
-
 /**
  * @param {string} kind
  * @param {Record<string, unknown>} raw
- * @param {string|null} nativeTool
- * @param {string} callClass a {@link CallClass} value
- * @returns {Record<string, unknown>}
+ * @returns {Record<string, unknown>} the NATIVE tool input, in Gemini's dialect
  */
-function geminiInput(kind, raw, nativeTool, callClass) {
+function geminiInput(kind, raw) {
   if (kind === EventKind.PROMPT_SUBMIT)
     return { prompt: asString(raw.prompt, "") };
   if (kind !== EventKind.PRE_TOOL && kind !== EventKind.POST_TOOL) return {};
-  const input = asObject(raw.tool_input);
-  // Renamed only where the NAME was renamed: the aliases are builtin-scoped, so
-  // an MCP tool that happens to be called `read_file` keeps its own dialect.
-  if (callClass !== CallClass.BUILTIN || nativeTool === null) return input;
-  const renames = lookup(GEMINI_INPUT_ALIASES, nativeTool);
+  return asObject(raw.tool_input);
+}
+
+/**
+ * A copy of `input` with each `renames` key that the payload actually supplies
+ * moved to its canonical name. A native key the payload omits is NOT invented,
+ * so the result carries the canonical key only where a real value backs it.
+ * @param {Record<string, unknown>} input
+ * @param {Record<string, string>|undefined} renames native key → canonical key
+ * @returns {Record<string, unknown>}
+ */
+function renameInputKeys(input, renames) {
   if (renames === undefined) return input;
   const out = { ...input };
   for (const [nativeKey, canonicalKey] of Object.entries(renames)) {
@@ -214,6 +259,46 @@ function geminiInput(kind, raw, nativeTool, callClass) {
   return out;
 }
 
+/**
+ * Decide the canonical tool name and the input TOGETHER — the scoped alias
+ * applies to both or to neither.
+ *
+ * Renaming `read_file` to `Read` ADVERTISES the schema that name carries
+ * ({@link MODELED_TOOL_INPUT_KEYS}: `Read` promises `input.file_path`). So the
+ * alias is applied only when the renamed input really supplies that key. A
+ * builtin payload that does not — a `read_file` with no `absolute_path`, a
+ * `write_file` with no `file_path` — keeps its NATIVE name and its native input,
+ * because a native name promises nothing and reaches a judge as a name it must
+ * handle on purpose. Splitting the two decisions is the bypass this function
+ * exists to make unrepresentable: a judge told "this is a Read" read
+ * `input.file_path`, got `undefined`, and allowed.
+ *
+ * The aliases are builtin-scoped, so an MCP-sourced or context-flagged call is
+ * never reclassified and keeps its own dialect; a name the scoped map does not
+ * hold falls through to the global {@link canonicalTool}.
+ * @param {string|null} nativeTool
+ * @param {string} callClass a {@link CallClass} value
+ * @param {Record<string, unknown>} input the native tool input
+ * @returns {{ tool: string|null, input: Record<string, unknown> }}
+ */
+function geminiCall(nativeTool, callClass, input) {
+  const native = { tool: canonicalTool(nativeTool), input };
+  if (nativeTool === null || callClass !== CallClass.BUILTIN) return native;
+  const scoped = lookup(GEMINI_TOOL_ALIASES, nativeTool);
+  if (scoped === undefined) return native;
+  const renamed = renameInputKeys(
+    input,
+    lookup(GEMINI_INPUT_ALIASES, nativeTool),
+  );
+  const advertised = lookup(
+    /** @type {Record<string, string>} */ (MODELED_TOOL_INPUT_KEYS),
+    scoped,
+  );
+  if (advertised === undefined || !Object.hasOwn(renamed, advertised))
+    return native;
+  return { tool: scoped, input: renamed };
+}
+
 /**
  * Parse a raw Gemini CLI hook payload into a normalized {@link ToolCallEvent}.
  * Never throws on an unmodelled event type or tool-input field. A payload comes
@@ -238,16 +323,24 @@ export function parse(native) {
   const gating = kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL;
   const response = kind === EventKind.POST_TOOL ? raw.tool_response : undefined;
   const nativeTool = gating ? asStringOrNull(raw.tool_name) : null;
-  const meta = geminiMeta(nativeEvent, raw);
+  const meta = baseMeta({
+    agent: AGENT,
+    native_event: nativeEvent,
+    integration_mode: INTEGRATION_MODE,
+    primary_gate_present: true,
+    native: raw,
+    consumed: CONSUMED,
+  });
   if (nativeTool !== null) meta.native_tool = nativeTool;
   // Classify on the NATIVE name (MCP detection keys on the `mcp_…` FQN prefix
   // every Gemini MCP tool carries); the class gates both the veto flag and the
   // builtin-only adapter-scoped aliases.
   const callClass = classifyCallClass(nativeTool, raw);
+  const call = geminiCall(nativeTool, callClass, geminiInput(kind, raw));
   return makeEvent({
     event: kind,
-    tool: geminiCanonicalTool(nativeTool, callClass),
-    input: geminiInput(kind, raw, nativeTool, callClass),
+    tool: call.tool,
+    input: call.input,
     response,
     this_call_vetoable: vetoableFor(kind, GATED_EVENTS, COVERAGE[callClass]),
     meta,
@@ -275,6 +368,10 @@ export function render(verdict, event, { soleGate = false } = {}) {
   // reads its block rationale from stderr, not the ignored stdout body). Carry it
   // on NativeResponse.stderr so `emit` writes it to fd 2 — a genuine block is
   // never surfaced to the user/model with no explanation.
+  // No stdout body at all on this path, so EVERY content field is dropped here,
+  // whatever UNRENDERED_FIELDS says for the kind — that map describes the allow
+  // path. Nothing is lost that a blocked call could still use: the tool never
+  // runs, so only `additional_context` had anywhere to go.
   if (enforced)
     return nativeResponse({
       transport: INTEGRATION_MODE,
@@ -286,7 +383,7 @@ export function render(verdict, event, { soleGate = false } = {}) {
   const body =
     event.event === EventKind.PROMPT_SUBMIT
       ? promptSubmitBody(vd)
-      : decisionBody(vd, soleGate);
+      : decisionBody(vd, event.event, soleGate);
   return nativeResponse({
     transport: INTEGRATION_MODE,
     exit_code: 0,
@@ -295,31 +392,53 @@ export function render(verdict, event, { soleGate = false } = {}) {
   });
 }
 
+/**
+ * Write Gemini's advisory `decision: "deny"` (plus any reason) onto `out` for a
+ * deny or an ask — Gemini has no native ask tier, so both surface the same way.
+ * Shared by both body builders so the two cannot drift apart.
+ * @param {Record<string, unknown>} out
+ * @param {Verdict} vd
+ * @returns {boolean} whether a decision was written
+ */
+function applyAdvisoryDeny(out, vd) {
+  if (vd.decision !== Decision.DENY && vd.decision !== Decision.ASK)
+    return false;
+  out.decision = "deny";
+  if (vd.reason !== undefined) out.reason = vd.reason;
+  return true;
+}
+
 /**
  * Build the exit-0 stdout decision body. `allow` abstains — no `decision` key,
  * so Gemini runs its normal flow — unless `soleGate` opts into the real
  * `decision: "allow"`. `deny`/`ask` both surface an advisory `decision: "deny"`
  * (Gemini has no native ask tier). `mutated_input` rides along as
- * `hookSpecificOutput.tool_input` and `additional_context` as Gemini's native
- * `systemMessage`. Returns undefined when there is nothing to emit (a pure
- * abstaining allow).
+ * `hookSpecificOutput.tool_input` on BeforeTool only, and `additional_context`
+ * as Gemini's native `systemMessage`. A `mutated_output` has no channel at all:
+ * on AfterTool it becomes the {@link POST_TOOL_REDACTION_UNSUPPORTED} warning on
+ * that same `systemMessage`, joined after any context the verdict also carries.
+ * Returns undefined when there is nothing to emit (a pure abstaining allow).
  * @param {Verdict} vd
+ * @param {string} kind the normalized {@link EventKind} being rendered
  * @param {boolean} soleGate
  * @returns {Record<string, unknown>|undefined}
  */
-function decisionBody(vd, soleGate) {
+function decisionBody(vd, kind, soleGate) {
   /** @type {Record<string, unknown>} */
   const out = {};
-  if (vd.decision === Decision.DENY || vd.decision === Decision.ASK) {
-    out.decision = "deny";
-    if (vd.reason !== undefined) out.reason = vd.reason;
-  } else if (soleGate) {
-    out.decision = "allow";
-  }
-  if (vd.mutated_input !== undefined)
+  if (!applyAdvisoryDeny(out, vd) && soleGate) out.decision = "allow";
+  if (kind === EventKind.PRE_TOOL && vd.mutated_input !== undefined)
     out.hookSpecificOutput = { tool_input: vd.mutated_input };
-  if (vd.additional_context !== undefined)
-    out.systemMessage = vd.additional_context;
+  // `systemMessage` is documented on the TOOL events. An UNKNOWN kind is an
+  // event this adapter could not name, so it has no established channel and
+  // carries nothing.
+  const toolEvent = kind === EventKind.PRE_TOOL || kind === EventKind.POST_TOOL;
+  const messages = [];
+  if (toolEvent && vd.additional_context !== undefined)
+    messages.push(vd.additional_context);
+  if (kind === EventKind.POST_TOOL && vd.mutated_output !== undefined)
+    messages.push(POST_TOOL_REDACTION_UNSUPPORTED);
+  if (messages.length > 0) out.systemMessage = messages.join("\n\n");
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
@@ -339,10 +458,7 @@ function decisionBody(vd, soleGate) {
 function promptSubmitBody(vd) {
   /** @type {Record<string, unknown>} */
   const out = {};
-  if (vd.decision === Decision.DENY || vd.decision === Decision.ASK) {
-    out.decision = "deny";
-    if (vd.reason !== undefined) out.reason = vd.reason;
-  }
+  applyAdvisoryDeny(out, vd);
   if (vd.additional_context !== undefined)
     out.hookSpecificOutput = { additionalContext: vd.additional_context };
   return Object.keys(out).length > 0 ? out : undefined;
@@ -353,6 +469,8 @@ export const geminiAdapter = {
   AGENT,
   INTEGRATION_MODE,
   COVERAGE,
+  UNRENDERED_FIELDS,
+  NATIVE_EVENT_FOR,
   parse,
   render,
 };