Submit
All skills
Skillintermediate

Codex Delegation Mode for ce:work

Users running ce:work from Claude Code (or other non-Codex agents) may want to delegate the actual code-writing to Codex. Two motivations: (1) Codex may produce better code for certain tasks, and (2) delegating token-heavy implementation work to Codex conserves tokens on the user's current model.

Claude Code Knowledge Pack7/10/2026

Overview

Codex Delegation Mode for ce:work

Problem Frame

Users running ce:work from Claude Code (or other non-Codex agents) may want to delegate the actual code-writing to Codex. Two motivations: (1) Codex may produce better code for certain tasks, and (2) delegating token-heavy implementation work to Codex conserves tokens on the user's current model.

PR #364 attempted this via a separate ce-work-beta skill with prose-based delegation instructions. The agent improvises CLI syntax each run, producing non-deterministic results confirmed as flaky in the PR author's own testing. The root cause: describing Codex CLI invocation in prose lets the agent guess differently every time.

ce-work-beta does have a structured 7-step External Delegate Mode (environment guards, availability checks, prompt file writing, circuit breaker), but the CLI invocation step itself is prose-based, causing the non-determinism. This feature ports the useful structural elements (guards, circuit breaker pattern) while replacing prose invocations with concrete bash templates.

Implementation note (2026-03-31): The final rollout was redirected to ce:work-beta so stable ce:work remains unchanged during beta. ce:work-beta must be invoked manually; ce:plan and workflow handoffs stay on stable ce:work until promotion.

Delegation Flow

/ce:work delegate:codex ~/plan.md
         │
         ▼
┌──────────────────────────┐
│ Parse arguments           │
│ - Extract delegate flag   │
│ - Require plan file       │
│ - Check local.md default  │
│ - Resolution chain:       │
│   flag > local.md > off   │
└────────┬─────────────────┘
         │
         ▼
┌──────────────────────────┐     ┌───────────────────────┐
│ Environment guard         │────>│ Notify if explicit,   │
│ $CODEX_SANDBOX set?       │ yes │ use standard mode     │
│ $CODEX_SESSION_ID set?    │     └───────────────────────┘
└────────┬─────────────────┘
         │ no
         ▼
┌──────────────────────────┐     ┌───────────────────────┐
│ Availability check        │────>│ Fall back to          │
│ command -v codex          │ no  │ standard mode + notify│
└────────┬─────────────────┘     └───────────────────────┘
         │ yes
         ▼
┌──────────────────────────┐     ┌───────────────────────┐
│ Consent + mode selection  │────>│ Ask: disable          │
│ work_delegate_consent set?   │ no  │ delegation?           │
│ Show warning + sandbox    │     │ Set local.md          │
│ mode choice (yolo/full-   │     └───────────────────────┘
│ auto). Recommend yolo.    │
│ (headless: require prior) │
└────────┬─────────────────┘
         │ accepted
         ▼
┌──────────────────────────┐
│ Per-unit execution loop   │
│ (SERIAL, not parallel)    │
│ For each implementation   │
│ unit in the plan:         │
│                           │
│ 1. Check unit eligibility │
│    (out-of-repo? trivial?)│
│    -> local if ineligible │
│ 2. Named stash snapshot   │
│ 3. Write prompt + schema  │
│    to .context/compound-  │
│    engineering/codex-      │
│    delegation/             │
│ 4. codex exec w/ flags    │
│ 5. Classify result:       │
│    CLI fail | task fail | │
│    verify fail | success  │
│ 6. Pass: commit, drop     │
│    stash, clean scratch   │
│    Fail: rollback,        │
│          increment ctr    │
│ 7. If 3 consecutive       │
│    failures: fall back    │
│    to standard mode       │
└──────────────────────────┘

Requirements

Activation and Configuration

  • R1. Codex delegation is an optional mode within ce:work, not a separate skill. ce-work-beta is superseded: its delegation logic is replaced by this feature; its non-delegation features (e.g., Frontend Design Guidance) should be ported to ce:work as a separate concern if valuable. Disposition of ce-work-beta (delete vs. retain without delegation) is a planning decision, not a product decision.
  • R2. Delegation is triggered via a resolution chain: (1) per-invocation argument wins, (2) work_delegate setting in .claude/compound-engineering.local.md is fallback, (3) hard default is false (off).
  • R3. Canonical activation argument is delegate:codex. The skill also recognizes fuzzy variants: codex mode, codex, delegate codex, and similar intent expressions. Agent intent recognition handles the fuzzy matching — the set does not need to be exhaustively enumerated.
  • R4. Canonical deactivation argument is delegate:local. Also recognizes fuzzy variants like no codex, local mode, standard mode.
  • R5. Delegation only applies to structured plan execution. Ad-hoc prompts without a plan file always use standard mode regardless of the delegation setting. When delegation mode is active for a plan, each implementation unit is delegated to Codex by default. The agent may execute a unit locally in standard mode when: (a) the unit explicitly requires modifications outside the repository root, or (b) the unit is trivially small (single-file config change, simple substitution) where delegation overhead exceeds the work. The agent states which mode it's using for each unit before execution.

Environment Safety

  • R6. When running inside a Codex sandbox (detected by $CODEX_SANDBOX or $CODEX_SESSION_ID environment variables), delegation is disabled and ce:work proceeds in standard mode. If the user explicitly requested delegation (via argument), emit a brief notification: "Already inside Codex sandbox — using standard mode." If delegation was only enabled via local.md default, proceed silently.
  • R7. All delegation logic lives in the skill itself. Converters do not modify skill behavior for cross-platform compatibility — the environment guard handles platform detection at runtime.

Availability and Fallback

  • R8. Before delegation, check command -v codex. If the Codex CLI is not on PATH, fall back to standard mode with a brief notification: "Codex CLI not found — using standard mode."
  • R9. No minimum version check for now. If a future CLI change breaks delegation, the invocation fails loudly and the fix is a single bash line update.

Consent and Mode Selection

  • R10. First time delegation activates in a project, show a one-time consent flow that: (1) explains what delegation does and the security implications, (2) presents the sandbox mode choice with a recommendation, and (3) records the user's decisions. The sandbox modes are:
    • yolo (recommended): Maps to --yolo (--dangerously-bypass-approvals-and-sandbox). Full system access including network. Required for verification steps that run tests or install dependencies. Explain why this is recommended.
    • full-auto: Maps to --full-auto. Workspace-write sandbox, no network access. Tests/installs that need network will fail. Suitable for pure code-writing tasks without verification dependencies.
  • R11. On user acceptance, store work_delegate_consent: true and work_delegate_sandbox: yolo (or full-auto) in .claude/compound-engineering.local.md. Do not show the consent flow again for this project.
  • R12. On user decline, ask whether to disable codex delegation entirely. If yes, set work_delegate: false in local.md and proceed in standard mode.
  • R13. In headless mode, delegation proceeds only if work_delegate_consent is already true in local.md. If not set or false, fall back to standard mode silently. Headless runs never prompt for consent and never silently escalate to unsandboxed mode without prior interactive consent.

Execution Mechanism

  • R14. Delegation uses concrete bash commands, not prose instructions. The exact invocation template:

    # Read sandbox mode from settings (default: yolo)
if [ "$CODEX_SANDBOX_MODE" = "full-auto" ]; then
  SANDBOX_FLAG="--full-auto"
else
  SANDBOX_FLAG="--yolo"
fi

codex exec \\
  $SANDBOX_FLAG \\
  --output-schema .context/compound-engineering/codex-delegation/result-schema.json \\
  -o .context/compound-engineering/codex-delegation/result-<unit-id>.json \\
  - < .context/compound-engineering/codex-delegation/prompt-<unit-id>.md

    The agent executes this verbatim — no improvisation of CLI syntax.

  • R15. Sandbox posture defaults to yolo (--yolo, shorthand for --dangerously-bypass-approvals-and-sandbox) but the user may choose full-auto during the consent flow (R10). The choice is stored in work_delegate_sandbox in local.md. yolo is recommended because --full-auto blocks network access, which is required for verification steps (running tests, installing dependencies). If full-auto is chosen and causes repeated verification failures, the circuit breaker (R18) handles fallback.

  • R16. When delegation mode is active, ALL units execute serially — both delegated and locally-executed units. Git stash is a global stack; mixing parallel and serial execution on the same working tree causes stash entanglement. This means delegation mode and swarm mode (Agent Teams) are mutually exclusive. Before each delegated unit, the loop assumes a clean working tree (enforced by ce:work's Phase 1 setup and by mandatory commits after each successful unit). Snapshot the working tree via named stash: git stash push --include-untracked -m "ce-codex-<unit-id>". On failure, rollback via git checkout -- . && git clean -fd && git stash drop "$(git stash list | grep 'ce-codex-<unit-id>' | head -1 | cut -d: -f1)". On success, commit the changes, then drop the named stash.

  • R17. The structured prompt template is written to a file at .context/compound-engineering/codex-delegation/prompt-<unit-id>.md rather than piped via stdin, to avoid ARG_MAX limits for large CURRENT PATTERNS sections. The template includes: TASK (goal from implementation unit), FILES TO MODIFY (file list), CURRENT PATTERNS (relevant code context), APPROACH (from implementation unit), CONSTRAINTS (no git commit, restrict modifications to files within the repository root, scoped changes, line limit, mandatory result reporting), and VERIFY (test/lint commands). Prompt files are cleaned up after each successful unit.

  • R18. A consecutive failure counter tracks delegation failures. After 3 consecutive failures, the skill falls back to standard mode for remaining units with a notification.

  • R19. Failure classification uses a multi-signal approach. codex exec returns exit code 0 even when the task fails — the exit code only reflects CLI infrastructure, not task success.

    CategorySignalAction
    CLI failureExit code != 0Hard failure — fall back to standard mode
    Result absentExit code 0, result JSON missing or malformedCount as task failure
    Task failureExit code 0, result schema status: "failed"Count toward circuit breaker, rollback
    Task partialExit code 0, result schema status: "partial"Keep changes, report gaps to main agent
    Verify failureExit code 0, status: "completed", VERIFY failsCount toward circuit breaker, rollback
    SuccessExit code 0, status: "completed", VERIFY passesCommit, drop stash, continue

  • R20. A result schema file is written alongside the prompt file. Codex is instructed via --output-schema to produce structured JSON conforming to this schema. The -o flag writes the result to result-<unit-id>.json. The schema:

    {
  "type": "object",
  "properties": {
    "status": { "enum": ["completed", "partial", "failed"] },
    "files_modified": { "type": "array", "items": { "type": "string" } },
    "issues": { "type": "array", "items": { "type": "string" } },
    "summary": { "type": "string" }
  },
  "required": ["status", "files_modified", "issues", "summary"],
  "additionalProperties": false
}

    The prompt CONSTRAINTS section includes mandatory result reporting instructions telling Codex it MUST fill in the schema honestly: status: "completed" only if all changes were made, "partial" if incomplete, "failed" if no meaningful progress. Known limitation: --output-schema only works with gpt-5 family models, not gpt-5-codex or codex- prefixed models (Codex CLI bug #4181). If the result JSON is absent or malformed, classify as task failure.

  • R21. The prompt constraint tells Codex to restrict all modifications to files within the repository root. If Codex discovers mid-execution that it needs to modify files outside the repo root, it should complete what it can within the repo and report what it couldn't do via the result schema issues field. The main agent then handles the out-of-repo work in standard mode. Out-of-repo changes cannot be detected or rolled back by git stash — this is an accepted risk mitigated by the prompt constraint and per-unit pre-screening (R5).

Settings in compound-engineering.local.md

  • R22. New YAML frontmatter keys in .claude/compound-engineering.local.md:
    • work_delegate: codex/false (default: false) — delegation target when enabled
    • work_delegate_consent: true/false — whether the user has completed the one-time consent flow
    • work_delegate_sandbox: yolo/full-auto (default: yolo) — sandbox posture for codex exec

Success Criteria

  • Codex successfully implements implementation units from ce:plan output across a variety of task types (new features, bug fixes, refactors)
  • CLI invocations are deterministic — no agent improvisation of shell syntax across runs
  • Delegation activates only when explicitly requested (argument or local.md), only with a plan file, and never when running inside Codex
  • Failed delegation rolls back cleanly via named git stash without corrupting tracked repository files
  • The result schema provides reliable signal for success/failure classification
  • Users who never enable delegation experience zero change in ce:work behavior

Scope Boundaries

  • Not a separate skill. ce-work-beta is superseded. This modifies ce:work directly.
  • No app-server integration. We use bare codex exec, not the codex-companion.mjs app server or the codex plugin's rescue skill. The delegation pattern is fire-prompt -> wait -> inspect-result, which is exactly what codex exec provides.
  • No ad-hoc delegation. Delegation only applies to structured plan execution with a plan file. Bare prompts without plans always use standard mode.
  • No minimum version gating. Added later if a breaking CLI change actually occurs.
  • No periodic re-consent. One acceptance per project. Version-gated or calendar-based re-consent can be added later if needed.
  • No converter changes. The skill handles platform detection internally via environment variable checks.
  • No out-of-repo detection. Git stash cannot protect files outside the repo. Defense is prompt constraint + per-unit pre-screening, not post-execution validation.
  • No timeout for v1. Neither codex exec nor the most mature codex integration (osc-work) implements timeouts. Added later if users report h