microsoft / microsoft/agent-governance-toolkit

RFC: Codex Integration

Open
#3,408 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

triage
Dominant language
Python
Stars
6.3k
Forks
1.1k
Avg merge
5d 11h
Merged PRs (30d)
142

Description

### Summary

This RFC proposes adding first-party Codex CLI governance to AGT as a new package, `agent-governance-codex-cli`. It's a thin host adapter over the existing Claude Code governance core. Codex's hook system (SessionStart, UserPromptSubmit, PreToolUse) mirrors Claude Code's contract, so the governance logic is reused unchanged and only host wiring is new, following the same derivation used for the OpenCode integration (#2658). I originally [fork and extended it to govern my own Codex agent](https://github.com/thatjosh/agent-governance-toolkit), so it's already implemented and verified, with policy deny/allow/audit working e2e. I'm happy to contribute it back upstream and help maintain this going forward.

Working fork: https://github.com/thatjosh/agent-governance-toolkit

### Motivation

AGT ships governance integrations for Claude Code, Copilot CLI, OpenCode, and Antigravity, but not for the OpenAI Codex CLI, which is becoming more popular with GPT 5.6.

### Detailed Design

Codex's hook system (SessionStart, UserPromptSubmit, PreToolUse) mirrors Claude Code's contract, so the governance logic is reused unchanged and only host wiring is new, following the same derivation used for the OpenCode integration (https://github.com/microsoft/agent-governance-toolkit/pull/2658).

### Enforcement surface

| Codex event | AGT behavior |
|---|---|
| `SessionStart` | inject governance context |
| `UserPromptSubmit` | prompt inspection, fail-closed block |
| `PreToolUse` | allow / deny / ask via policy |

Decision mapping onto Codex's hook response schema:

```jsonc
// policy deny ->
{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
"permissionDecision": "deny", "permissionDecisionReason": "…AGT policy…" } }
// policy review -> "permissionDecision": "ask"
// policy allow -> no permissionDecision
```

### Alternatives Considered

N/A

### Security Implications

Trust model / cryptographic boundaries are unchanged. This package does not modify the policy engine, trust scoring, cryptographic choices, or the audit format. It reuses the existing Claude Code governance core unchanged and only translates Codex's hook payloads
to and from that core.

### Migration / Backward Compatibility

_No response_

### Scope

Single package

### Target Placement

Integration (integrations/ directory)

### Prior Art

https://github.com/microsoft/agent-governance-toolkit/pull/2658

### Checklist

- [x] I have searched existing issues and RFCs for duplicates
- [x] I have read the ADR index (adr/index.md) for related decisions
- [x] I am willing to implement this RFC or help review an implementation

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the integrations/ directory and the ADR index at adr/index.md, then compare the existing OpenCode integration from pull request #2658 with the working fork linked in this RFC. Verify that the Codex package covers SessionStart, UserPromptSubmit, and PreToolUse with the stated allow, deny, and ask mappings, and that end-to-end policy behavior matches the described scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, security
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.