Master consult

Master Consult

Escalate a hard problem to a stronger local model while keeping the calling agent responsible for implementation and verification.

Resolve the launcher

Treat the directory containing this SKILL.md as SKILL_ROOT. Run the launcher with Python 3:

python3 "$SKILL_ROOT/scripts/master_consult.py" doctor --project "$PWD"

On Windows, use python when python3 is unavailable.

Codex must be able to write its own session store under CODEX_HOME so later turns can resume. If doctor reports that the caller Agent sandbox blocks this write, request scoped approval to run the launcher outside the caller sandbox. This outer approval does not change the inner master's read-only project sandbox.

Escalation decision

Apply this policy before each consultation:

• Consult immediately when the user explicitly asks for a stronger model or independent review.
• Consult after two distinct hypotheses or fixes leave the same failure, or after three failed hypothesis -> verification -> failure cycles.
• Consult after three or more sequential investigations have narrowed the problem but still cannot establish the root cause. Do not consult on this trigger once the root cause is already established; continue local implementation and verification instead.
• Consult when contradictory evidence remains after one safe discriminating check cannot explain it.
• Consult before changing authentication, secrets, cryptography, destructive data operations, migrations, concurrency/recovery behavior, persistent formats, or public compatibility.
• Use an exact follow-up ID when earlier master advice was implemented and new evidence or a new failure appears.
• Ask the user, rather than consulting, when requirements, permission, credentials, reproduction input, or external service state is missing.
• Continue locally after a routine first failure when a specific, inexpensive next check exists.

Count an attempt only when it contains a distinct hypothesis, a discriminating probe or change, a predicted observation, and the actual result. Re-running the same command or making another speculative edit does not count.

Workflow

1. Establish the private scope for the current caller conversation. First run list --json directly. Codex, Claude Code, and other supported hosts automatically use their stable conversation ID when exactly one is available; this survives context compaction while keeping different conversations in different ledgers.

   Only if the launcher reports that no stable host conversation ID or explicit adapter is available, run:

   python3 "$SKILL_ROOT/scripts/master_consult.py" scope new --json
   

   Retain this fallback scope_token only in the current Agent conversation. Set it as MASTER_CONSULT_SCOPE_TOKEN on every later launcher command, never reuse or disclose it, and understand that it cannot be recovered if host context compaction removes it. For durable operation on an unsupported host, configure the explicit MASTER_CONSULT_HOST_AGENT and MASTER_CONSULT_HOST_SESSION_ID adapter pair instead.

2. Inspect prior consultations in the current caller conversation before every escalation:

   python3 "$SKILL_ROOT/scripts/master_consult.py" list --project "$PWD" --json
   

   Use each entry's exact ID, title, initial_question, latest_question, turn count, and can_follow_up value to identify its topic. If summaries are ambiguous, run show --json for the candidate IDs to inspect their full stored, redacted question and answer. Never choose a consultation from model/provider metadata alone.

3. Choose a fresh consultation when the problem is independent, the user requests a new perspective, or no matching resumable session exists. Independent tasks in one caller conversation share only the private ledger; each must receive a new consultation ID.

4. Choose an exact follow-up when the user implemented an earlier answer and still has a problem. Match the current problem against the stored initial and latest question summaries, then use the exact Master Consult ID. Never use latest, last, or a provider shortcut. If several sessions could match, show the current conversation's topic summaries and ask which one to continue.

5. Give the master a compact problem statement containing:

   • the observed behavior and exact error;
   • the desired behavior;
   • relevant attempts in chronological order, the narrowed scope, and why the root cause remains uncertain;
   • hard constraints and the requested form of the answer.

   For a narrowing-investigation consultation, ask the master to identify the root cause from the current clues, or, if that is not yet possible, to provide ranked hypotheses and the next discriminating checks with expected outcomes.

   Do not paste the whole repository. The master must orient itself from the project root and read relevant files independently. Do not include secrets.

6. Start a fresh read-only consultation:

   python3 "$SKILL_ROOT/scripts/master_consult.py" ask \
     --project "$PWD" \
     --isolation read-only \
     -- "Use the investigation history to identify the root cause. If evidence is insufficient, give ranked hypotheses and the next discriminating checks with expected outcomes."
   

7. Continue a prior consultation after implementation results are known:

   python3 "$SKILL_ROOT/scripts/master_consult.py" follow-up \
     --project "$PWD" \
     mc-SESSION-ID \
     -- "I applied the proposal, but this exact failure remains. Re-read the changed files and reassess."
   

8. Apply this waiting contract after ask or follow-up:

   • Run the consultation as a host Agent task/process when the host supports it. Call the host's blocking wait once with two wake-up conditions: this exact task completes, or one observation interval expires. If the host has no waitable-task primitive, keep the launcher invocation in the foreground until it returns; do not simulate the interval with polling. The launcher itself has no provider timeout.
   • Use a 25-minute observation interval by default. For a clearly complex consultation, choose a longer interval before starting the wait. Never choose a shorter automatic interval. This is an observation cadence, never a provider timeout or termination deadline.
   • If task completion wakes the wait first, consume the launcher result immediately; do not run status. If the interval wakes it first, run exactly one status <exact-ID> --json check, then follow the next rule.
   • On active, begin the next host-level blocking wait for the same task using the same or a longer interval. Do not use repeated short waits, a status loop, a countdown, process diagnostics, list, show, another Master Consult command, or progress narration between interval checks. Do not call it stuck, inspect or kill processes. Never terminate an active consultation.
   • On stale, report that the provider outcome is unknown and ask the user before recovery action. On finished, consume the original launcher result or use show for the exact consultation. A direct user request to check now still permits one immediate status observation.
   • The wait is silent. Do not send elapsed-time, still waiting, no response, active, or similar intermediate messages. User-visible output during the wait is limited to the final result, an actual launcher end/error, or a direct user-requested status check.
   • Silence, elapsed time, no output, and a missing provider session ID are not evidence that a consultation is stuck.

   Work only on genuinely unrelated tasks that do not change the consultation's project while its task runs.

9. Relay the master's answer to the user, then independently inspect, implement, and test it. Treat the answer as expert advice, not proof.

Isolation rules

• Keep read-only as the default. It runs Codex against the original project with a read-only sandbox.
• Use snapshot only when the master needs to edit or run experiments. The launcher creates a persistent filtered copy outside the project when possible, runs Codex with write access only inside that copy, and never syncs changes back.
• When a read-only master says an experiment is necessary, start a new snapshot consultation. It must not create a temporary workspace, request higher permissions, or attempt an isolation bypass from a read-only consultation.
• Never use danger-full-access, bypass approval flags, --last, or ephemeral provider sessions.
• Keep the same isolation mode for all turns in one session. Start a new consultation to change modes.
• The master may write its own provider session metadata outside the project; this is required for exact follow-up turns.
• The launcher removes caller scope credentials and host conversation IDs from the master's environment before invoking Codex.
• The external Codex process receives a dedicated skills.config override that disables this caller-facing Skill. Apply it on fresh and follow-up turns; do not ask the master to load or invoke this workflow.
• Every fresh provider thread is claimed in a fixed user-level registry; reuse by another consultation discards that turn's provider content and is quarantined.
• A consultation is pinned to the Codex executable and CODEX_HOME that created it. Do not switch either value on a follow-up.

Commands

# Environment and provider checks
python3 "$SKILL_ROOT/scripts/master_consult.py" doctor --project "$PWD"

# List masters called by this Agent conversation and whether each can be followed up
python3 "$SKILL_ROOT/scripts/master_consult.py" list --project "$PWD"

# Show the stored question and answer for one explicit consultation
python3 "$SKILL_ROOT/scripts/master_consult.py" show --project "$PWD" mc-SESSION-ID

# One-shot local liveness check after the waiting contract permits it
python3 "$SKILL_ROOT/scripts/master_consult.py" status --project "$PWD" mc-SESSION-ID --json

# Read a prompt from stdin to avoid shell quoting problems
python3 "$SKILL_ROOT/scripts/master_consult.py" ask --project "$PWD" -

The launcher defaults to provider codex, model gpt-5.6-sol, reasoning effort max, disabled web search, non-interactive approvals, a child-only configuration that disables this Skill, and redaction of common secret formats. It does not silently downgrade the model or reasoning effort. A consultation has no launcher deadline: it waits until Codex returns, the caller interrupts it, or the operating system/external supervisor stops it.

State and troubleshooting

The launcher maintains a separate ledger for every canonical-project and caller-conversation pair instead of reading private Codex storage formats. Another conversation in the same project gets a different physical ledger and cannot use list, show, or follow-up to inspect this one. Each public list entry includes the redacted initial consultation topic, latest question and answer previews, turn count, status, and a computed can_follow_up flag so the caller can choose the correct exact ID.

status <exact-ID> --json is a one-shot local check governed by the waiting contract above. A direct user request may trigger it immediately. active means the local launcher still holds that consultation's exclusive lock; it is not evidence of a hang and must not trigger diagnostics or termination. finished means no launcher holds it. stale means the ledger says running while no launcher currently holds the lock; this can occur just before lock acquisition or after an interruption, so the provider outcome is unknown. Status never contacts Codex and cannot certify remote-model or network health. It is visible only to the current private caller conversation.

Read references/state-and-security.md when state location, isolation, redaction, or concurrency matters. Read references/codex-provider.md when diagnosing Codex commands, JSONL events, authentication, model availability, or resume failures.