Codex Agent Contracts

简体中文 | English

Bounded reader and worker subagents for safe, reviewable Codex delegation.

Codex Agent Contracts is a community-maintained configuration kit for local Codex subagents. It separates evidence gathering from implementation, gives each role a least-privilege sandbox default, and defines explicit scope, retry, stopping, validation, and handoff contracts.

This is an independent community project. It is not affiliated with or endorsed by OpenAI.

What is included

Component	Purpose	Default sandbox
luna_reader	Focused codebase exploration and evidence gathering	read-only
luna_worker	Small, explicitly authorized implementation tasks	workspace-write
AGENTS.md example	Parent-agent planning, approval, delegation, and isolation policy	Project policy
Installer	Project-scoped or personal installation, with dry-run and overwrite protection	N/A
Verifier	TOML schema, invariant, locale parity, and shell syntax checks	Read-only

The bundled agents use gpt-5.6-luna with medium reasoning because the official subagents guide recommends Luna for fast, narrow, clear, repeatable, or high-volume work. Change the model when your account, task, or quality requirements call for a different choice.

Design goals

• Separate investigation from mutation.
• Treat every delegation prompt as a scope contract.
• Make retries finite and evidence-driven.
• Stop when authorization, context, or validation is insufficient.
• Return a stable report that the parent agent can inspect.
• Keep global AGENTS.md policy small; place detailed behavior in agent files and project documentation.
• Prefer parallel read work; isolate parallel writes with Git worktrees and non-overlapping ownership.

Quick start

Clone the repository, inspect the dry run, and install the agents for your user account:

git clone https://github.com/Jasper-J04-oss/codex-agent-contracts.git
cd codex-agent-contracts
./scripts/install.sh --scope global --locale en --dry-run
./scripts/install.sh --scope global --locale en
./scripts/verify.sh

For a single project:

./scripts/install.sh \
  --scope project \
  --target /path/to/project \
  --locale en \
  --dry-run

./scripts/install.sh \
  --scope project \
  --target /path/to/project \
  --locale en

The installer refuses to overwrite existing agent files unless --force is explicitly supplied. It never installs or edits AGENTS.md; merge the appropriate example manually after review:

• English policy example
• 简体中文策略示例

Restart Codex or open a new task after changing custom-agent files so the active client reloads them.

Example delegation

Reader:

Use luna_reader to trace how authentication errors reach the API response.
Working directory: /repo
Authorized read scope: src/auth, src/api, tests/auth
Questions: identify the call path and current error mapping.
Expected evidence: file paths, symbols, and relevant test names.
Acceptance criteria: no writes; every conclusion has repository evidence.

Worker:

Use luna_worker to add the missing 401 mapping.
Working directory: /repo-worktrees/auth-401
Authorized write scope: src/api/errors.ts, tests/auth/errors.test.ts
Required behavior: map InvalidSession to HTTP 401.
Validation: npm test -- tests/auth/errors.test.ts
Acceptance criteria: targeted tests pass; no other files change.

The parent agent remains responsible for planning, authorization, architectural decisions, integrating results, and independently checking the diff and validation evidence.

Important sandbox limitation

The sandbox_mode in each custom-agent file is a least-privilege default. According to the official subagents documentation, subagents inherit the parent turn's sandbox and approval policy, and live runtime overrides can take precedence over a custom agent's defaults. Confirm the parent permission mode before delegation. Prompt rules complement the runtime sandbox; they do not replace it.

Repository layout

.codex/agents/             English installable agent files
profiles/zh-CN/agents/     Simplified Chinese installable agent files
examples/                  Small AGENTS.md policy examples
docs/                      Architecture, configuration, and contracts
scripts/                   Safe installer and verifier
.github/workflows/         Continuous validation

Documentation

• Architecture and trust boundaries
• Configuration and installation
• Delegation and report contracts
• Official OpenAI references

Project status

This repository packages configuration and operating conventions; it does not implement a separate orchestrator or bypass Codex permissions. Custom-agent authoring is evolving, so review the official documentation and run ./scripts/verify.sh after upgrades.

License and contributing

Released under the MIT License. See CONTRIBUTING.md and SECURITY.md.