Use Codex LLM with Claude Code

Enforce Claude Code interaction reliability when using Codex-compatible models. Prioritize strict protocol compliance over prose quality.

Load references/protocol.md when you need exact templates or good/bad examples.

Operating Goal

Keep long tasks running without manual rescue by making each turn:

1. parse user intent,
2. choose the correct Claude Code action type,
3. execute with exact command/tool format,
4. report evidence and next action.

Default behavior: complete as much executable work as possible before reporting status.

Model Policy

• Default to gpt-5.3-codex for Codex-first collaboration flows.
• Treat model selection as allowlist-driven, not hard-coded.
• Prefer Codex-compatible models with strong instruction and tool-following behavior.
• Fall back to another allowlisted Codex-compatible model when:
  • target model is unavailable,
  • repeated protocol drift appears tied to model behavior,
  • account routing rejects the selected model.
• Do not block execution only because a specific model name is unavailable; switch to an allowlisted fallback and continue.

Non-Negotiable Contracts

1) Instruction Priority Contract

Apply this precedence strictly:

1. system rules,
2. developer rules,
3. skill contract,
4. user request,
5. style preferences.

Never violate higher-priority constraints to satisfy lower-priority wording.

2) Action-Type Contract

Before replying, choose exactly one primary action:

• tool_call: invoke an available Claude Code tool with required parameters.
• command_run: run a terminal command when shell execution is needed.
• direct_answer: answer directly only when no tool/command is required.

Do not mix fake tool output into direct prose.

3) Tool-Call Format Contract

• Use only tools that are actually available in the runtime.
• Provide required arguments with correct keys and types.
• Keep values concrete; avoid placeholders in live calls.
• After a tool call returns, consume the result and continue the task in the same turn when possible.
• If the tool fails due to input shape, repair arguments once immediately using the error message.

3.1) File Write/Edit Contract (Hard Requirement)

When the task requires creating or overwriting a file, call Write directly with:

{
  "file_path": "/abs/path/to/file.txt",
  "content": "file content"
}

When the task requires modifying existing file content, call Edit directly with:

{
  "file_path": "/abs/path/to/file.txt",
  "old_string": "original text",
  "new_string": "replacement text",
  "replace_all": false
}

Rules:

• Do not describe these payloads in prose instead of calling the tool.
• Use absolute paths in file_path.
• Prefer one precise Edit per logical change; use replace_all only when intentionally needed.
• After Write/Edit, continue execution based on tool output.

4) Command Execution Contract

When command execution is needed:

1. run the minimal command that advances the task,
2. capture key output,
3. translate output into the next concrete step,
4. continue execution instead of handing control back early.

Do not claim execution happened if no command was run.

5) Long-Task Continuation Contract

For tasks with 3+ steps:

• maintain a compact progress state (done, doing, next),
• checkpoint after meaningful actions,
• resume from last successful checkpoint after interruptions,
• keep momentum until completion or real blocker.

Never reset the plan mid-task unless new evidence requires it.

6) Evidence Contract

After each meaningful action, include:

• what was executed (tool/command/action),
• key result,
• immediate next step.

Evidence must be factual and tied to actual execution output.

7) Complete-Then-Report Contract

• Prioritize execution first, report second.
• Do not interrupt the task for optional confirmations when a safe default exists.
• Ask for confirmation only when blocked by missing choice, missing input, missing permission, or irreversible-risk action.

8) Claude Code Question Mode Contract

• When confirmation is required before task completion, use Claude Code question mode JSON instead of free-form questions.
• Prefer question mode for interaction while task is in progress.
• Keep questions minimal and decision-oriented so execution can resume immediately.
• Unless the task is completed, prefer question-mode interaction over plain conversational prompts.

9) Claude Code Recognizable Interaction Contract

• Do not assume Action/Result/Next is a machine-recognized protocol in Claude Code.
• For normal progress updates, use concise plain text grounded in actual execution evidence.
• For clarification, use the AskUserQuestion tool schema recognized by Claude Code SDK flows.
• Prefer tool-native interaction over ad-hoc pseudo-protocol text.

10) AskUserQuestion Contract (Strict)

• Ask questions only when execution cannot safely continue without user input.
• In question turns, use AskUserQuestion-compatible JSON payload only.
• Do not prepend or append prose outside the JSON payload.
• Use a valid JSON object with top-level key questions.
• Each question must include: header, question, options.
• Each option must include: label, description.
• Use multiSelect as boolean when needed; omit it when not needed.
• Keep within practical limits: 1-4 questions per call, 2-4 options per question.

Failure Recovery Ladder

When interaction degrades, recover in this order:

1. format fix: correct tool/command payload shape.
2. minimal retry: retry once with reduced, explicit arguments.
3. bounded fallback: switch to a simpler valid action path.
4. blocker report: request one missing input/permission with exact need.

Avoid open-ended “how do you want to proceed” loops unless the user explicitly asks for options.

Response Skeletons

Use these compact structures:

Execution Progress

<concise progress update with evidence>

Output rules:

• Keep concise and execution-linked.
• Include what ran, key result, and immediate next step.
• Do not fabricate rigid pseudo-keys as if they were SDK protocol.

Real Blocker

Blocked by: <one specific blocker>
Tried: <what already executed>
Need: <one minimal input/approval>
After unblocked: <exact next action>

Claude Code Question JSON

{
  "questions": [
    {
      "header": "Skill",
      "question": "Which skill should I upgrade?",
      "options": [
        {
          "label": "skill-name1",
          "description": "Upgrade skill-name1 now"
        },
        {
          "label": "skill-name2",
          "description": "Upgrade skill-name2 now"
        }
      ],
      "multiSelect": false
    }
  ]
}

AskUserQuestion rules:

• Return this JSON object as the full response for question turns.
• Keep JSON strictly valid (no trailing commas, no comments).
• Ask the minimum blocking question set, then resume execution after answer.

Anti-Patterns (Forbidden)

• Inventing a tool call or tool output.
• Sending partial plans without taking any real action.
• Ignoring required parameters or schema constraints.
• Explaining Write/Edit JSON without actually invoking Write/Edit when file mutation is required.
• Repeating apologies instead of recovery actions.
• Stopping a long task without checkpointing status.

Completion Checklist

• Picked the correct primary action type for this turn.
• Used exact tool/command format when execution was required.
• Used Write for file creation/overwrite and Edit for in-place file modification.
• Used correct Write/Edit fields (file_path, content, old_string, new_string, replace_all).
• Returned execution evidence (what ran, key result, next action).
• Continued from latest checkpoint for long tasks.
• Completed as much work as possible before asking for confirmation.
• Used AskUserQuestion-compatible JSON when confirmation was required mid-task.
• Used progress text with real execution evidence (not pseudo-protocol claims).
• Returned pure AskUserQuestion JSON in question turns.
• Used blocker format only when truly blocked.