Add the following section to ~/.codex/AGENTS.md and save the companion luna_worker.toml as ~/.codex/agents/luna_worker.toml.
- Primary agents: proactively delegate bounded, self-contained jobs to
luna_workerwhen Luna can complete and verify them independently and delegation saves work or supervision. Suitable jobs include authorized releases through established procedures, focused web research, long-running scripts, batch processing, and straightforward implementation. Handle small operations directly by default, unless there are long waits, useful independent parallel work, or an explicit user request to delegate. - Delegate preparation, execution, and verification as one complete job. Build a concise brief from available context and file references; avoid extra parent tool calls solely to prepare the delegation when that information is sufficient. Leave input inspection, artifact preparation, and routine validation to Luna, except where the parent needs them to establish scope or authorization.
- Choose
reasoning_effortexplicitly at each spawn:lowfor known procedures and script supervision,mediumfor focused research and simple changes, andhighormaxfor harder reasoning still suitable for Luna. Useagent_type="luna_worker"; its model is fixed to Luna while effort is chosen per assignment. - Prefer
fork_turns="none"with a sufficient brief: objective, working directory, relevant context/files, authorized actions, owned files if editing, and completion checks. Children must preserve concurrent work and must not delegate further. - For unattended delivery in the Codex app, first confirm
send_message_to_threadis available. Include a uniquejob_id,delivery="callback", andreply_thread_idobtained from the primary task's actual runtimeCODEX_THREAD_ID. Never guess this ID or substitute a child ID. For ordinary collected results, usedelivery="return"and collect the final answer in the active turn. - After dispatching a callback job, continue useful independent work or end the turn with a brief handoff and pending status. Do not poll or stay in a waiting loop. Luna must send one explicit completion, failure, or blocking-decision callback to the supplied task; native child completion alone is insufficient to wake an idle parent.
- On callback, reconcile the result with the original job and current state, verify the supplied evidence as needed, and report the outcome without repeating valid checks. Close finished children with
interrupt_agent. Do not turn completion messages into new delegation loops.