feat(codex): first-class Codex CLI skill runtime

[dpol1]

Summary

• Closes feat(adapter/codex): first-class Codex CLI skill runtime #313: makes OpenAI Codex a first-class Magpie skill runtime instead of a delegation target, per RFC-AI-0004 Principle 3 (vendor neutrality). A maintainer with only Codex installed can now discover and run Magpie skills end to end.
• Ships a committed, reviewed Codex posture: .codex/config.toml (workspace-write, network off, on-request approvals) and .codex/rules/magpie.rules (scoped read allows, prompted remote mutations, forbidden credential disclosure). sandbox-lint --codex validates both statically.
• Skips the SKILL.md-to-AGENTS.md conversion the issue suggested: Codex scans the canonical .agents/skills symlinks natively, so SKILL.md stays the single source. The setup and setup-isolated skills route Codex sessions to explicit Codex steps before any Claude-only branch, and new eval fixtures pin that routing.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --all-files passes (all hooks green, including check-placeholders, symlink-lint, workspace ruff/mypy/pytest, skill-and-tool-validate, spec-validate)
• For Python packages touched: uv run pytest (103 passed in tools/sandbox-lint, including the new tests/test_codex.py invariant cases for tampered configs and rules) / ruff check / mypy all clean
• For Groovy bridges touched: not touched
• For skill changes: eval suite passes for the affected skill
  (`PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/e
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (runtime-routing suites for all four setup-isolated-setup-* skills, each with a cg the Codex branch is taken and no .claude` file is treated as a failure)
• Other: end-to-end smoke on a real Codex session (/skills discovery, $magpie-security-issue-triage invocation, approval prompt on a gh mutation)

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation
  (approval_policy = "on-request"; exec-policy rules prompt on gh pr/gh issue mu
• Sandbox — no new unrestricted host access; network reach declared in the adapter
  (workspace-write with network_access = false; networked bridges cross the native
• Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose (the check-placeholders prek hook is the mechanical gate)
• Conversational + correctable — agentic-override path documented if behaviour is
• Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
• Privacy LLM — private content does not reach a non-approved LLM; redactor invoke

Linked issues

Closes #313.

Notes for reviewers (optional)

• The issue proposed mapping SKILL.md onto Codex's AGENTS.md convention. This PR rejects tee would be a second source that drifts from .claude/skills. Codex follows the existing.agents/skills symlinks, so nothing is duplicated. If that call looks wrong, the runtime-contract table in docs/adapters/codex.md is the place to push back.
• sandbox-lint parses magpie.rules by splitting on prefix_rule( after dropping commeeal Starlark parser. Deliberate trade-off: the invariants only need block-level matching,and a parser dependency felt heavier than the problem. Tampering cases are covered in tests/test_codex.py.
• Two known gaps, both documented in the adapter's limitations section: agent-guard denialodex hook yet, and the exec-policy rule format is an evolving Codex interface, so theadapter stays experimental until a minimum Codex version is pinned.
• Project trust stays a human decision. Adoption never edits Codex trust state, and pre-exfiguration survives adopt and upgrade.

[potiuk]

NICE!

[justinmclean]

Solid first-class Codex adapter, and the network-disabled workspace-write sandbox as the hard boundary with the exec-policy layer adding per-action prompts is the right shape. License headers are all present, the parser edge-case tests are good, and the known-limitations section is refreshingly honest. A few observations inline, none blocking.

Smaller observations

• .codex/rules/magpie.rules — gh api is ungoverned. The generic passthrough gh api (and gh api graphql) can perform any mutation: create/merge PRs, delete issues, even read the token via gh api user. It matches none of the prefix_rule patterns, so it falls through to approval_policy = "on-request". The network_access = false sandbox does backstop it (a networked gh api call escalates to approval, so it's not a silent bypass), but it skips the descriptive per-action prompt that every other gh mutation gets. Worth deciding explicitly: add a prefix_rule(pattern = ["gh", "api"], decision = "prompt") (or forbidden) so the operator sees intent, rather than leaning on the sandbox alone.

• sandbox_lint/codex.py — invariant checks substring-match the whole rule block, including the justification string. check_codex_invariants tests things like '"download"' in block against the full prefix_rule(...) text. A future allow rule whose justification happens to contain "download", "push", or "token" would flip a check (false positive on the release-download guard; false negative if a justification string satisfies a "must prompt" check). Matching only the pattern = [...] list rather than the entire block would make the linter robust to justification wording.

• sandbox_lint/codex.py — the linter asserts required rules exist but never rejects an over-broad allow. The checks confirm some prompt/forbidden block covers gh-pr/gh-issue/git-push/auth-token, but nothing fails a profile that adds, say, prefix_rule(pattern = ["gh", "pr", "merge"], decision = "allow"). Codex most-specific-matching mitigates the known-mutation case, and network sandboxing limits blast radius for gh, but for a security linter a positive "no mutation verb appears in any allow block" check would close the gap. Reasonable to defer if "invariants only, first cut" is the intent — flagging so it's a conscious choice.

• nit — gh auth refresh is forbidden in the rules but only gh auth token is asserted by the linter and exercised by test_codex.py. Both credential ops matter; a one-line assertion + test case would lock the refresh half in too.