Table of Contents generated with DocToc
Capability: capability:platform
Harness: OpenAI Codex CLI, IDE, and desktop local runtime
This adapter makes Codex a native Apache Magpie skill runtime. It is not the Claude Code codex delegation plugin: a maintainer with Codex and no Claude Code can discover, invoke, and run Magpie skills end to end.
The implementation follows RFC-AI-0004: shared skill sources, a native sandbox, and per-action human confirmation through Codex's own approval and exec-policy layers.
| Magpie requirement | Codex implementation |
|---|---|
| Skill discovery | Codex reads the existing canonical .agents/skills/magpie-*/SKILL.md symlinks directly. No SKILL.md-to-AGENTS.md translation or duplicate source tree is needed. |
| Repository instructions | Codex reads the repository AGENTS.md hierarchy natively. |
| Tool bridges | Skills invoke the same language-neutral tools/ CLI adapters. Network is disabled inside workspace-write; approved network actions cross the sandbox through Codex rules and approval policy. |
| Filesystem sandbox | Project .codex/config.toml selects workspace-write. |
| Human in the loop | approval_policy = "on-request" and .codex/rules/magpie.rules allow scoped reads, prompt mutations, and forbid credential disclosure. |
| Deterministic guard | The shared tools/agent-guard dispatch core is reachable through its harness-neutral --check / --exec modes (see Deterministic guard rules). |
| Credential isolation | tools/agent-isolation/agent-iso.sh launches agent-iso codex through the shared clean-environment wrapper. |
The committed profile lives in:
.codex/ |-- config.toml `-- rules/ `-- magpie.rules
Both files are policy and are reviewed in Git.
Codex scans .agents/skills from the current directory to the repository root, follows symlinked skill directories, and reads SKILL.md when a skill is chosen. After magpie-setup has adopted the repository:
agent-iso codex./skills to confirm that magpie-* skills are visible.$, for example $magpie-security-issue-triage, or describe a task that matches its frontmatter description.tools/* commands and project placeholders in exactly the same way as every other runtime.An end-to-end triage therefore starts with:
$magpie-security-issue-triage
There is no generated AGENTS.md per skill. AGENTS.md carries persistent repository instructions; SKILL.md remains the workflow source.
Run $magpie-setup from Codex and select adopt or upgrade. The setup lifecycle:
.agents/skills links and harness relay links..codex/ without deleting unrelated project settings. Conflicting sandbox or approval values are surfaced to the maintainer; they are never silently weakened.sandbox-lint --codex .codex on the merged result.When .codex/ already exists, setup preserves unrelated keys. magpie.rules is Magpie-owned; hand edits are shown before replacement.
For the clean-environment layer on Linux or macOS:
source <framework>/tools/agent-isolation/agent-iso.sh agent-iso codex
On Windows, run the POSIX isolation layer through WSL when that layer is required. Codex's native Windows sandbox and the project policy still apply to a native Windows session.
The profile requires:
sandbox_mode = "workspace-write" approval_policy = "on-request" [sandbox_workspace_write] network_access = false
Networked bridges such as gh, jira, Gmail, PonyMail, and CVE tooling therefore cannot silently use network access from the workspace sandbox. The exec-policy file allows narrowly scoped read-only commands, prompts known mutations, and forbids gh auth token and credential refresh operations. Commands not matched by an allow rule still follow the native on-request approval path.
Per-action confirmation belongs to Codex's native rules and approval system: .codex/rules/magpie.rules classifies known commands as allow, prompt, or forbidden before they cross the sandbox boundary, and approval_policy = "on-request" routes everything else to the operator. This is the Codex mapping of RFC-AI-0004 Principle 1 (human-in-the-loop).
Claude Code and OpenCode additionally wire the deterministic tools/agent-guard denials (AI Co-Authored-By trailers, premature --ready-for-review, unsafe public security wording, empty force-pushes) as in-process pre-tool hooks. Codex has no equivalent wired hook adapter in this profile; the same dispatch() core remains available through the harness-neutral --check / --exec modes documented in the agent-guard README. Until a native Codex adapter exists, those framework invariants rely on the exec-policy prompts plus the operator's review of each confirmed action.
Project .codex configuration and rules load only for a trusted project. The operator reviews that trust decision. The framework does not modify user trust state.
Policy changes remain normal reviewed repository changes: an approved elevated action can still modify .codex/, so the profile complements — never replaces — code review.
Run the static validator from the framework or snapshot:
uv run --directory tools/sandbox-lint --group dev sandbox-lint --codex .codex
Then test native rule classification:
codex execpolicy check --pretty \ --rules .codex/rules/magpie.rules \ -- gh pr view 313 codex execpolicy check --pretty \ --rules .codex/rules/magpie.rules \ -- gh pr create --title test --body test codex execpolicy check --pretty \ --rules .codex/rules/magpie.rules \ -- gh auth token
The expected strictest decisions are allow, prompt, and forbidden, respectively.
Also verify:
/skills lists magpie-setup and a representative workflow skill.tools/* bridge used by the selected skill is present and authenticated; tool-specific preflight remains owned by that skill.The four setup-isolated skills route Codex to this adapter:
setup-isolated-setup-install installs or merges the project profile and explains agent-iso codex.setup-isolated-setup-verify runs the static validator, rule-classification probes, /skills checks, and tool preflights.setup-isolated-setup-update compares the installed profile with the current framework snapshot. It reports drift and never weakens policy automatically.setup-isolated-setup-doctor runs the shared live environment probes inside the active Codex sandbox and reports native approval or network failures separately.The Claude-specific setup remains available for Claude Code. Runtime routing must happen before a setup-isolated skill follows Claude-only settings paths.