Expose structured permission changes in ACP metadata

[nikita-ashihmin]

Summary

Expose the exact consequence of Codex permission options through a shared, versioned option-level metadata contract:

{
  "_meta": {
    "permission": {
      "version": 1,
      "changes": []
    }
  }
}

Each change includes a producer-supplied human-readable description plus structured operation, target, matcher, lifetime, and access information where Codex provides it.

Why

ACP already standardizes the option decision category through kind (allow_once, allow_always, reject_once, or reject_always), the button text through name, and selection through optionId. It does not currently describe the exact policy change behind an option.

Clients therefore cannot reliably explain whether an always option grants a command prefix, one network host, filesystem writes under a root, or a broader runtime permission. Parsing display labels is lossy and couples clients to one agent.

This metadata deliberately describes only the exact consequence of the option. It does not duplicate ACP button semantics and does not carry the request reason.

Contract

The common _meta.permission object contains:

• version: 1
• ordered, atomic changes
• a non-empty human-readable description on every change
• policy_rule changes with operation and ruleBehavior
• runtime grant changes with explicit lifetime
• structured targets for commands, network, and filesystem resources

Example command policy amendment:

{
  "type": "policy_rule",
  "operation": "add",
  "ruleBehavior": "allow",
  "description": "Allow commands starting with npm install",
  "targets": [
    {
      "type": "command",
      "matcher": {
        "type": "argv_prefix",
        "argv": ["npm", "install"]
      }
    }
  ]
}

Codex coverage

• exec-policy argv-prefix amendments
• allow and deny network-host policy amendments
• session host grants from managed-network approvals
• session write-root grants for file changes
• turn/session permission-profile grants
• whole-network permission profiles
• legacy filesystem read/write paths
• typed filesystem path, glob, special-path, and deny entries

The original _meta.codex decision payload remains alongside the common metadata, so existing clients and response handling are unchanged.

Compatibility

This uses the existing ACP _meta extension point and requires no protocol-version change. Clients that do not recognize the contract ignore it and continue using standard ACP fields. Missing common metadata means the exact structured consequence is unknown; it must not be interpreted as unrestricted access.

Tests

• full suite: 330 passed, 28 skipped
• TypeScript typecheck passed
• production build passed
• approval snapshots cover turn/session network and filesystem grants
• focused assertions cover command, host, and write-root metadata