agent-control-plane-core 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane-core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex, Amp, Gemini CLI) and a conformance suite.",
   "type": "module",
   "repository": {

package/src/adapters/codex.mjs

@@ -414,7 +414,7 @@ export function render(verdict, event, { soleGate = false } = {}) {
     unblocked_exit_code: 0,
     enforced,
     reason: vd.reason,
-    stdout: nativeBody(hookEventName, vd, event, enforced, soleGate),
+    stdout: nativeBody(hookEventName, vd, event, soleGate),
   });
 }
 
@@ -423,15 +423,14 @@ export function render(verdict, event, { soleGate = false } = {}) {
  * @param {string} hookEventName
  * @param {Verdict} vd a normalized verdict
  * @param {ToolCallEvent} event
- * @param {boolean} enforced
  * @param {boolean} soleGate
  * @returns {Record<string, unknown>}
  */
-function nativeBody(hookEventName, vd, event, enforced, soleGate) {
+function nativeBody(hookEventName, vd, event, soleGate) {
   if (event.event === EventKind.POST_TOOL)
     return postToolBody(hookEventName, vd);
   if (hookEventName === HookEvent.PERMISSION_REQUEST)
-    return permissionRequestBody(hookEventName, vd, enforced, soleGate);
+    return permissionRequestBody(hookEventName, vd, soleGate);
   return preToolBody(hookEventName, vd, event);
 }
 
@@ -475,18 +474,18 @@ function preToolBody(hookEventName, vd, event) {
  * `updatedInput` voids the body and there is no context key.
  * @param {string} hookEventName
  * @param {Verdict} vd a normalized verdict
- * @param {boolean} enforced
  * @param {boolean} soleGate
  * @returns {Record<string, unknown>}
  */
-function permissionRequestBody(hookEventName, vd, enforced, soleGate) {
+function permissionRequestBody(hookEventName, vd, soleGate) {
   /** @type {Record<string, unknown>} */
   const hookSpecificOutput = { hookEventName };
+  // Codex substitutes its own text for an empty message
+  // (`permission_request_decision`, [X8]); ours says who denied it.
   if (vd.decision !== Decision.ALLOW) {
-    const message = enforced ? blockReason(vd.reason) : vd.reason;
     hookSpecificOutput.decision = {
       behavior: Decision.DENY,
-      ...(message === undefined ? {} : { message }),
+      message: blockReason(vd.reason),
     };
   } else if (soleGate) {
     hookSpecificOutput.decision = { behavior: Decision.ALLOW };

package/src/agent-manifest.mjs

@@ -62,7 +62,13 @@ function manifestRow(id) {
       ]),
     ),
     pre_tool_filing: adapter.PRE_TOOL_FILING,
-    pre_tool_response: adapter.PRE_TOOL_RESPONSE,
+    pre_tool_response: {
+      ...adapter.PRE_TOOL_RESPONSE,
+      hook_specific_output_keys: [
+        ...adapter.PRE_TOOL_RESPONSE.hook_specific_output_keys,
+      ].sort(),
+      top_level_keys: [...adapter.PRE_TOOL_RESPONSE.top_level_keys].sort(),
+    },
   };
 }
 

package/src/conformance.mjs

@@ -11,9 +11,9 @@ import {
   isCoverageStatus,
   lookup,
   VERDICT_CONTENT_FIELDS,
-  WHOLE_ARGUMENTS,
   FILING_RULE_GRAMMAR,
   isFilingRule,
+  isPlainObject,
 } from "./control-plane.mjs";
 
 /**
@@ -808,22 +808,12 @@ function assertPreToolKeysRead(adapter, event, rendered, label, assert) {
   return true;
 }
 
-/**
- * Whether `value` is an object that is neither `null` nor an array.
- * @param {unknown} value
- * @returns {value is Record<string, unknown>}
- */
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Assert an adapter declares a well-formed `PRE_TOOL_FILING` and
- * `PRE_TOOL_RESPONSE`: both frozen, every filing rule `null` or a frozen
- * `{tool_name, input}` in the mini-language {@link fileModelCall} reads, and
- * each of the response's key lists sorted and duplicate-free beside its
- * boolean-or-null fail-open bit. `agents.json` publishes both verbatim, so a shape a
- * Python consumer cannot apply is refused here, not discovered there.
+ * `PRE_TOOL_RESPONSE`: every filing rule `null` or in the mini-language
+ * {@link fileModelCall} reads, and each response key list an array of strings
+ * beside a boolean-or-null fail-open bit. `agents.json` publishes both, so a
+ * shape a Python consumer cannot apply is refused here, not discovered there.
  * @param {import("./control-plane.mjs").Adapter} adapter
  * @param {any} assert
  */
@@ -831,37 +821,24 @@ function assertPreToolDeclarationsWellFormed(adapter, assert) {
   const agent = adapter.AGENT;
   const filing = adapter.PRE_TOOL_FILING;
   assert.ok(
-    typeof filing === "object" && filing !== null && Object.isFrozen(filing),
-    `${agent}: adapter declares no frozen PRE_TOOL_FILING — every adapter needs one: Object.freeze({}) when its host files every model call as asked`,
+    isPlainObject(filing),
+    `${agent}: adapter declares no PRE_TOOL_FILING — every adapter needs one: {} when its host files every model call as asked`,
   );
-  for (const [name, rule] of Object.entries(filing)) {
-    if (rule === null) continue;
-    const where = `${agent}: PRE_TOOL_FILING[${JSON.stringify(name)}]`;
-    assert.ok(Object.isFrozen(rule), `${where} is not frozen`);
+  for (const [name, rule] of Object.entries(filing))
     assert.ok(
-      isFilingRule(rule),
-      `${where} is ${JSON.stringify(rule)}, not ${FILING_RULE_GRAMMAR}`,
+      rule === null || isFilingRule(rule),
+      `${agent}: PRE_TOOL_FILING[${JSON.stringify(name)}] is ${JSON.stringify(rule)}, not null or ${FILING_RULE_GRAMMAR}`,
     );
-    if (rule.input !== WHOLE_ARGUMENTS)
-      assert.ok(Object.isFrozen(rule.input), `${where}.input is not frozen`);
-  }
   const response = adapter.PRE_TOOL_RESPONSE;
   assert.ok(
-    typeof response === "object" &&
-      response !== null &&
-      Object.isFrozen(response),
-    `${agent}: adapter declares no frozen PRE_TOOL_RESPONSE — every adapter needs one naming the top-level and hookSpecificOutput keys its host reads on the pre-tool event (empty lists when it reads no body)`,
+    isPlainObject(response),
+    `${agent}: adapter declares no PRE_TOOL_RESPONSE — every adapter needs one naming the top-level and hookSpecificOutput keys its host reads on the pre-tool event (empty lists when it reads no body)`,
   );
   for (const level of PRE_TOOL_RESPONSE_LEVELS) {
-    const keys = /** @type {any} */ (lookup(response, level.keys));
+    const keys = lookup(response, level.keys);
     assert.ok(
-      Array.isArray(keys) && Object.isFrozen(keys),
-      `${agent}: PRE_TOOL_RESPONSE.${level.keys} is not a frozen array`,
-    );
-    assert.deepEqual(
-      [...keys],
-      [...new Set(keys)].sort(),
-      `${agent}: PRE_TOOL_RESPONSE.${level.keys} must be sorted and duplicate-free`,
+      Array.isArray(keys) && keys.every((key) => typeof key === "string"),
+      `${agent}: PRE_TOOL_RESPONSE.${level.keys} is not an array of strings`,
     );
     assert.ok(
       [true, false, null].includes(

package/src/control-plane.mjs

@@ -496,9 +496,6 @@ export const UNRENDERED_ON_UNKNOWN = readonlySet(VERDICT_CONTENT_FIELDS);
 /** The {@link PreToolFiling} input reference to a call's whole arguments value. */
 export const WHOLE_ARGUMENTS = "$";
 
-/** The prefix of a {@link PreToolFiling} input reference to one top-level argument. */
-export const ARGUMENT_KEY_PREFIX = "$.";
-
 /**
  * How a host's pre-tool hook files a model's tool call, keyed by MODEL tool
  * name, the {@link flatToolName} of the call's `namespace` and `name`. Each
@@ -545,7 +542,7 @@ export function flatToolName(namespace, name) {
 
 /**
  * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
- * `BeforeTool`), as two sorted key lists, each empty when the host reads no
+ * `BeforeTool`), as two key lists, each empty when the host reads no
  * body: `hook_specific_output_keys` inside `hookSpecificOutput`, and
  * `top_level_keys` at the body's top level. Each list has a fail-open bit,
  * `unread_key_fails_open` and `unread_top_level_key_fails_open`: `true` ⇒ any
@@ -555,79 +552,41 @@ export function flatToolName(namespace, name) {
  */
 
 /**
- * Whether `ref` is a {@link PreToolFiling} input reference: `"$"`, or `"$."`
- * followed by one non-empty key with no `.`.
- * @param {unknown} ref
- * @returns {boolean}
+ * Whether `value` is a plain object: not null, not an array.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
  */
-function isFilingRef(ref) {
-  if (ref === WHOLE_ARGUMENTS) return true;
-  if (typeof ref !== "string" || !ref.startsWith(ARGUMENT_KEY_PREFIX))
-    return false;
-  const key = ref.slice(ARGUMENT_KEY_PREFIX.length);
-  return key !== "" && !key.includes(".");
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/**
- * Whether `input` is a {@link PreToolFiling} rule's input: `"$"`, or a plain
- * object (not an array) whose every value is `"$"` or `"$.<key>"`.
- * @param {unknown} input
- * @returns {boolean}
- */
-function isFilingInput(input) {
-  if (input === WHOLE_ARGUMENTS) return true;
-  return (
-    typeof input === "object" &&
-    input !== null &&
-    !Array.isArray(input) &&
-    Object.values(input).every(isFilingRef)
-  );
-}
+/** A {@link PreToolFiling} reference to one top-level argument; group 1 is the key. */
+const ARGUMENT_REF = /^\$\.([^.]+)$/u;
 
 /** What a {@link PreToolFiling} rule must be, for error messages. */
-export const FILING_RULE_GRAMMAR = `{tool_name: <non-empty string>, input: "${WHOLE_ARGUMENTS}" or an object of "${WHOLE_ARGUMENTS}"/"${ARGUMENT_KEY_PREFIX}<key>" references (<key>: non-empty, no ".")}`;
+export const FILING_RULE_GRAMMAR = `{tool_name: <non-empty string>, input: "${WHOLE_ARGUMENTS}" or an object of "${WHOLE_ARGUMENTS}"/"$.<key>" references (<key>: non-empty, no ".")}`;
 
 /**
- * Whether `rule` is a non-null {@link PreToolFiling} rule: a plain object with
- * exactly a non-empty string `tool_name` and a well-formed `input`. The one
- * grammar both {@link fileModelCall} and the conformance harness hold a rule to.
+ * Whether `rule` is a non-null {@link PreToolFiling} rule: exactly a non-empty
+ * string `tool_name` and an `input` that is `"$"` or an object of `"$"` /
+ * `"$.<key>"` references. The one grammar both {@link fileModelCall} and the
+ * conformance harness hold a rule to.
  * @param {unknown} rule
  * @returns {boolean}
  */
 export function isFilingRule(rule) {
-  if (typeof rule !== "object" || rule === null || Array.isArray(rule))
-    return false;
-  const keys = Object.keys(rule).sort();
-  const { tool_name, input } = /** @type {Record<string, unknown>} */ (rule);
+  if (!isPlainObject(rule)) return false;
+  const { tool_name, input, ...extra } = rule;
+  const isRef = (/** @type {unknown} */ ref) =>
+    ref === WHOLE_ARGUMENTS ||
+    (typeof ref === "string" && ARGUMENT_REF.test(ref));
   return (
-    keys.length === 2 &&
-    keys[0] === "input" &&
-    keys[1] === "tool_name" &&
+    Object.keys(extra).length === 0 &&
     typeof tool_name === "string" &&
     tool_name !== "" &&
-    isFilingInput(input)
-  );
-}
-
-/** The kinds of model tool call a {@link PreToolFiling} distinguishes. */
-export const MODEL_CALL_KINDS = readonlySet(["function", "freeform"]);
-
-/**
- * Resolve one valid {@link PreToolFiling} input reference against `args`;
- * `undefined` when it does not resolve (see {@link PreToolFiling}).
- * @param {string} ref
- * @param {unknown} args
- * @returns {unknown}
- */
-function resolveArgument(ref, args) {
-  if (ref === WHOLE_ARGUMENTS) return args;
-  if (typeof args !== "object" || args === null || Array.isArray(args))
-    return undefined;
-  const value = lookup(
-    /** @type {Record<string, unknown>} */ (args),
-    ref.slice(ARGUMENT_KEY_PREFIX.length),
+    (input === WHOLE_ARGUMENTS ||
+      (isPlainObject(input) && Object.values(input).every(isRef)))
   );
-  return value === null ? undefined : value;
 }
 
 /**
@@ -635,7 +594,7 @@ function resolveArgument(ref, args) {
  * with arguments value `args`, per that host's {@link PreToolFiling}; `null`
  * when the hook files none. The reference reading of the mini-language
  * `agents.json` publishes as `pre_tool_filing`. Throws on a rule outside that
- * grammar or a kind outside {@link MODEL_CALL_KINDS}.
+ * grammar or a kind other than `"function"` or `"freeform"`.
  * @param {PreToolFiling} filing
  * @param {"function" | "freeform"} kind whether the model made a function call or a freeform (custom) call
  * @param {string} name the model tool name, a {@link flatToolName}
@@ -643,7 +602,7 @@ function resolveArgument(ref, args) {
  * @returns {{ tool_name: string, tool_input: unknown } | null}
  */
 export function fileModelCall(filing, kind, name, args) {
-  if (!MODEL_CALL_KINDS.has(kind))
+  if (kind !== "function" && kind !== "freeform")
     throw new Error(
       `control-plane: model call kind ${JSON.stringify(kind)} is neither "function" nor "freeform"`,
     );
@@ -657,10 +616,13 @@ export function fileModelCall(filing, kind, name, args) {
     );
   if (rule.input === WHOLE_ARGUMENTS)
     return { tool_name: rule.tool_name, tool_input: args };
-  const entries = Object.entries(rule.input).map(([key, ref]) => [
-    key,
-    resolveArgument(ref, args),
-  ]);
+  const entries = Object.entries(rule.input).map(([key, ref]) => {
+    const argument = ARGUMENT_REF.exec(ref)?.[1];
+    if (argument === undefined) return [key, args];
+    // A missing key, a null value, or non-object arguments all fail to resolve.
+    const value = isPlainObject(args) ? lookup(args, argument) : undefined;
+    return [key, value === null ? undefined : value];
+  });
   if (entries.some(([, value]) => value === undefined)) return null;
   // fromEntries defines own properties, so an input key `__proto__` stays a
   // key, as it is in a Python consumer's dict, instead of hitting the setter.

package/types/control-plane.d.mts

@@ -135,9 +135,26 @@ export function readonlySet(values: Iterable<string>): ReadonlySet<string>;
  */
 export function flatToolName(namespace: string | null | undefined, name: string): string;
 /**
- * Whether `rule` is a non-null {@link PreToolFiling} rule: a plain object with
- * exactly a non-empty string `tool_name` and a well-formed `input`. The one
- * grammar both {@link fileModelCall} and the conformance harness hold a rule to.
+ * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
+ * `BeforeTool`), as two key lists, each empty when the host reads no
+ * body: `hook_specific_output_keys` inside `hookSpecificOutput`, and
+ * `top_level_keys` at the body's top level. Each list has a fail-open bit,
+ * `unread_key_fails_open` and `unread_top_level_key_fails_open`: `true` ⇒ any
+ * other key there voids the whole body and the call RUNS; `false` ⇒ other keys
+ * are ignored; `null` ⇒ not established from the host's source.
+ * @typedef {Readonly<{ hook_specific_output_keys: readonly string[], unread_key_fails_open: boolean | null, top_level_keys: readonly string[], unread_top_level_key_fails_open: boolean | null }>} PreToolResponse
+ */
+/**
+ * Whether `value` is a plain object: not null, not an array.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether `rule` is a non-null {@link PreToolFiling} rule: exactly a non-empty
+ * string `tool_name` and an `input` that is `"$"` or an object of `"$"` /
+ * `"$.<key>"` references. The one grammar both {@link fileModelCall} and the
+ * conformance harness hold a rule to.
  * @param {unknown} rule
  * @returns {boolean}
  */
@@ -147,7 +164,7 @@ export function isFilingRule(rule: unknown): boolean;
  * with arguments value `args`, per that host's {@link PreToolFiling}; `null`
  * when the hook files none. The reference reading of the mini-language
  * `agents.json` publishes as `pre_tool_filing`. Throws on a rule outside that
- * grammar or a kind outside {@link MODEL_CALL_KINDS}.
+ * grammar or a kind other than `"function"` or `"freeform"`.
  * @param {PreToolFiling} filing
  * @param {"function" | "freeform"} kind whether the model made a function call or a freeform (custom) call
  * @param {string} name the model tool name, a {@link flatToolName}
@@ -582,12 +599,8 @@ export const VERDICT_CONTENT_FIELDS: readonly string[];
 export const UNRENDERED_ON_UNKNOWN: ReadonlySet<string>;
 /** The {@link PreToolFiling} input reference to a call's whole arguments value. */
 export const WHOLE_ARGUMENTS: "$";
-/** The prefix of a {@link PreToolFiling} input reference to one top-level argument. */
-export const ARGUMENT_KEY_PREFIX: "$.";
 /** What a {@link PreToolFiling} rule must be, for error messages. */
 export const FILING_RULE_GRAMMAR: "{tool_name: <non-empty string>, input: \"$\" or an object of \"$\"/\"$.<key>\" references (<key>: non-empty, no \".\")}";
-/** The kinds of model tool call a {@link PreToolFiling} distinguishes. */
-export const MODEL_CALL_KINDS: ReadonlySet<string>;
 /**
  * PROBLEM CLASS — an event marked vetoable on a path where the host can never
  * veto it, so a deny reads downstream as a block that never happened.
@@ -648,7 +661,7 @@ export const BLOCK_TRANSPORT: Readonly<Record<string, Readonly<{
 }>>>;
 /**
  * What a host reads from an exit-0 answer to its pre-tool event (`PreToolUse`,
- * `BeforeTool`), as two sorted key lists, each empty when the host reads no
+ * `BeforeTool`), as two key lists, each empty when the host reads no
  * body: `hook_specific_output_keys` inside `hookSpecificOutput`, and
  * `top_level_keys` at the body's top level. Each list has a fail-open bit,
  * `unread_key_fails_open` and `unread_top_level_key_fails_open`: `true` ⇒ any