Metadata-Version: 2.4
Name: custodian-codex-guard
Version: 0.1.1
Summary: Custodian Guard for OpenAI Codex — typed action risk classification, fail-closed enforcement, and hash-chained receipts for Codex tool calls.
Author-email: InovinLabs <hello@inovinlabs.com>
License-Expression: MIT
Project-URL: Homepage, https://getcustodian.xyz
Project-URL: Repository, https://github.com/KeyArgo/custodian-codex-guard
Project-URL: Custodian kernel, https://github.com/KeyArgo/custodian-kernel
Keywords: ai,agent,codex,openai,security,guardrails,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: custodian-kernel<0.5,>=0.4.0
Provides-Extra: paladin
Requires-Dist: custodian-kernel[paladin]<0.5,>=0.4.0; extra == "paladin"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Custodian Guard for Codex

*(OpenAI Build Week, July 2026)*

A capability firewall for coding agents. Codex can inspect, test, and edit
inside an approved workspace; credential use, network operations, destructive
commands, production changes, money movement, and governance changes stop at a
human-approval boundary. Every decision produces a value-free HMAC hash-chained
receipt. Classification is deterministic — typed action-kind rules over the
tool name and arguments, not a model call — so a mislabeled or adversarial
proposal can't talk its way past the boundary by re-describing itself.

This is the Build Week contribution specifically: the Codex-facing MCP server,
the policy bridge, the receipts CLI, and the governance skill. It depends on
[`custodian-kernel`](https://github.com/KeyArgo/custodian-kernel) — the
policy engine, adapter pipeline, and approval/filesystem/ledger-access
policies — which is agent-agnostic and predates this Build Week.

This plugin is generic. It does not know about any particular website, IDE,
or operator. A site or IDE is a client of the MCP boundary, never part of the
kernel.

## How Codex and GPT-5.6 were used

Codex (running GPT-5.6) implemented the MCP server and the typed action
bridge, adversarially tested its own classifier against deliberately
mislabeled and disguised commands, found and fixed relative-workspace
resolution edge cases, and built the deterministic judge demo
(`scripts/codex-guard-demo.py`) and regression tests. GPT-5.6 does not run
inside the enforcement path itself — classification is deterministic, typed
rules over the tool name and arguments, checked on every request — so there
is nothing here a model could talk its way around. That is a deliberate
design choice made *with* Codex during development, not a limitation.

## Install for judging

Python 3.11 or later:

```bash
# Linux/macOS
python3 -m venv .venv
. .venv/bin/activate
# Windows PowerShell
python -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install -e .
custodian-codex setup
custodian-codex doctor
```

`pip install -e .` pulls in `custodian-kernel` (pinned to the exact commit
this was built and verified against — see `pyproject.toml`; 0.4.0 isn't on
PyPI yet) automatically, nothing else to install first. Start a new Codex
thread after `setup` so it loads the plugin. The plugin manifest is at
`plugins/custodian-codex-guard/.codex-plugin/plugin.json`; its governance
skill is at `plugins/custodian-codex-guard/skills/govern-codex/SKILL.md`.

If the integration itself is broken, the operator — not the model — can run
`custodian-codex disable`. This removes the Codex plugin while deliberately
preserving receipts and approvals for diagnosis; `custodian-codex setup`
restores it. Start a new Codex thread after either change.

## Sixty-second proof

```bash
python scripts/codex-guard-demo.py
pytest -q tests/
```

The demo performs no network calls and changes no external state. It shows a
safe test and workspace edit passing, `.env` access being denied, deliberately
misclassified delete/deploy commands being independently upgraded to human
escalation, a valid receipt chain, and rejection after receipt tampering.
106 tests cover the full threat model.

## Enforcement contract

`guard_action` returns `autonomous`, `escalation_required`, `approved`, or
`denied`. An escalation is never permission. The model can create a pending
request but cannot approve it; the operator runs the returned
`custodian-codex approve ID --digest DIGEST` outside the model tool boundary.
Approval binds the exact tool, effective risk class, arguments, resolved
workspace, requester, and policy version — any change requires a fresh
request, never a reused approval ID.

No harness — including Codex itself — can read the receipt ledger by
default, not even its own history. Visibility is only ever an explicit
operator grant. The agent being governed is exactly the party a denial log
exists to constrain; letting it read its own denial history would turn the
ledger into an oracle it could probe to learn the enforcement boundary and
route around it.

## What's in this repo vs. the kernel

- **Here:** `custodian/codex_guard/` (MCP server, risk classification,
  receipts, approvals, CLI), `plugins/custodian-codex-guard/` (Codex plugin
  manifest + governance skill), tests, judge demo script.
- **In `custodian-kernel`:** the adapter pipeline (workspace/secret/prompt-
  injection/egress guards), `ApprovalPolicy`, `FilesystemPolicy`,
  `LedgerAccessPolicy` — the policy engine every action is actually checked
  against.

See [`docs/CODEX_GUARD.md`](docs/CODEX_GUARD.md) for the full judge guide.
