Update to Codex Advisor

{
  "description": "Consult for ordinary material architecture, interface, data-model, or explicit advisor, generic-advisor, authorization, challenge, second-opinion, or architecture-review choices; or, when targeted evidence still leaves unresolved cross-module or system design, compatibility or concurrency boundaries, competing diagnoses, security, privacy, or trust boundaries, recovery, irreversible-state migration, or data-loss decisions; and the completion consultation that complex multi-phase or multi-file work takes before it is declared complete. Skip factual/status/summarization work, fully determined mechanical edits, formatting/renaming/docs synchronization, settled-plan execution, final review owned elsewhere, explicit no-delegation/root-only requests, and every borderline case.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 312
    },
    {
      "relative_path": "references/operations.md",
      "size_in_bytes": 22558
    }
  ],
  "name": "consultation",
  "skill_md_contents": "---\nname: consultation\ndescription: Consult for ordinary material architecture, interface, data-model, or explicit advisor, generic-advisor, authorization, challenge, second-opinion, or architecture-review choices; or, when targeted evidence still leaves unresolved cross-module or system design, compatibility or concurrency boundaries, competing diagnoses, security, privacy, or trust boundaries, recovery, irreversible-state migration, or data-loss decisions; and the completion consultation that complex multi-phase or multi-file work takes before it is declared complete. Skip factual/status/summarization work, fully determined mechanical edits, formatting/renaming/docs synchronization, settled-plan execution, final review owned elsewhere, explicit no-delegation/root-only requests, and every borderline case.\n---\n\n# Advisor consultation\n\nUse one fresh, read-only, zero-tool advisor only when the task has a concrete material\ndecision. The root owns architecture, implementation routing, verification, and acceptance.\nBefore consultation, the root performs any repository or web research and supplies\nenough relevant evidence and source references in the five-section decision packet for\nthe advisor to recommend a path.\n\nThe root may assign bounded evidence gathering to separate research workers before assembling the decision packet; the consulted advisor still uses zero tools and never delegates.\n\nIf that evidence cannot settle the question, a valid\nadvisor result may instead identify a concrete research-first next step, missing\nevidence, research questions, or bounded brainstorming areas. The advisor does not\ninspect files, call tools, fetch the web, or conduct independent research.\n\n## Declare the route\n\nRead-only discovery may ground the decision. For a consult candidate, inspect the\nparent identity before the first implementation write and before its decision record:\n\n```sh\nsh <absolute-installed-plugin-root>/scripts/inspect-parent-runtime.sh\n```\n\nThe preflight uses only `CODEX_THREAD_ID` and the caller-supplied/default sessions\nroot. It accepts an unambiguous persisted parent with a recognized sandbox policy;\nthe parent itself need not be read-only because the consultation runs in a distinct\nexplicitly read-only Codex process. A missing, ambiguous, malformed, or conflicting\nparent runtime is unavailable. Do not use `CODEX_SESSION_ID` as a fallback. Emit\nexactly one record:\n\n```text\nADVISOR DECISION\nroute: consult | skip | unavailable\nreason: <one task-specific sentence>\nquestion: <bounded decision question, or none>\n```\n\nConsult when at least one positive trigger in the description applies. Skip when all\napplicable work is routine, the user forbids delegation, or eligibility is borderline.\nGeneral quality is not a decision question.\n\nComplex work takes one completion consultation before it is declared complete. This\napplies when the task already took `route: consult`, or when it spans multiple phases,\nfiles, or sessions. Emit a second `ADVISOR DECISION` and consult before reporting the\nwork done. The bounded question is whether the finished work meets its stated contract\nand what evidence would falsify that. It is not a final diff review or release\nverification, which stay outside this plugin and with their existing owner: the root\nstill owns verification and acceptance, and the advisor still uses zero tools and sees\nonly the packet. Routine, single-step, and already-skipped work takes no completion\nconsultation.\n\nAn identified parent uses `route: consult`, including a normal `workspace-write`\nroot. An unavailable parent uses `route: unavailable`, emits no `ADVISOR CALL`,\nstarts no consultation process, and does not block the root's own work. The ordinary\n`route: skip` path is unchanged.\nA non-Codex surface has no supported local transport, so it takes `route: unavailable` and emits no `ADVISOR CALL` or `ADVISOR RESULT`.\n\n## Explicit configuration is separate\n\nThe bundled installed `advisor.toml` is live configuration for normal `--tier`\nconsultations. It contains exactly `[standard]` and `[specialist]`, each with `model`\nand `effort`; edit it in place and the next consultation uses the pair. No catalog,\ndiscovery, canary, saved state, or file copy is a prerequisite. Any syntactically valid\nfuture selector is permitted subject to account/runtime support; `gpt-6-astra` for\nSpecialist opts into higher usage. Plugin updates or reinstalling can replace edits.\nThe helper's `show` and `doctor` report the actual pairs, installed path, and SHA-256\nsource revision. Catalogs, presets, and canaries are isolated advanced tools; `set`\nand `reset` reject as legacy-only, and `restore` states that it cannot affect tiers.\n\n`models test MODEL --effort EFFORT --authorize-usage --parent-thread THREAD_ID`\nuses model capacity. Never infer that authorization from catalog metadata, a saved\nselection, or a configuration request. CLI `0.153.2` app-server currently lacks the\nisolation flags required for safe discovery, so `models refresh` safely returns\nunavailable without changing state; it is not a live model canary.\n\n## Consult exactly\n\n1. Resolve the absolute installed plugin root from this loaded `SKILL.md` path: it is\n   two directories above the directory containing this file. Verify that\n   `run-advisor.sh`, `inspect-parent-runtime.sh`, and `inspect-agent-runtime.sh` are\n   regular, nonsymlinked files beneath that installed root. Use those absolute paths\n   for every consultation command. Never elevate a repository-relative or\n   workspace-resolved `plugins/advisor` script.\n2. Classify the decision risk. Standard consultation uses\n   `--tier standard`. Its live file model and effort default to Terra / `high` with no\n   setup, discovery, or canary. This permits the real consultation attempt, not a\n   compatibility claim; post-run runtime inspection remains required. This is the\n   default for ordinary bounded material architecture, interface, data-model, and\n   explicit generic advisor requests.\n   Specialist consultation uses `--tier specialist`. Its live file model and effort\n   default to GPT-6 Sol / `high` with the same zero-setup launch permission, only when\n   targeted evidence still leaves unresolved a cross-module or system design,\n   compatibility or concurrency boundary, competing diagnosis, an unresolved security or trust boundary, recovery, an irreversible migration or data-loss decision, or a credible unresolved High-severity disagreement. Security adjacency or project importance alone, or an ordinary architecture question alone, does not qualify. A borderline choice uses Standard. The parent model and sandbox are irrelevant to selection.\n3. Resolve the selected tier through the installed helper. Before invoking the\n   consultation transport, emit this visible main-chat receipt using the actual resolved model and effort metadata:\n\n```text\nADVISOR CALL\ntier: Standard | Specialist\nmodel: <resolved model selector>\neffort: <resolved effort>\nreason: <one task-specific sentence>\nquestion: <bounded decision question>\nstatus: running\n```\n\n4. Send only this bounded, non-sensitive packet to the fixed transport on stdin:\n\n```text\nDECISION\n<one question the root must resolve>\n\nCONTEXT\n<goal, relevant root-gathered evidence with source references, and current constraints>\n\nOPTIONS\n<known viable choices, including the tentative choice when one exists>\n\nBOUNDARIES\n<owned files, excluded scope, compatibility, security, and authority limits>\n\nREQUEST\nChallenge the tentative choice. Recommend one path when the packet supports a\ndecision; otherwise identify a concrete research-first next step, specific missing evidence,\nresearch questions, or bounded brainstorming areas. Identify the strongest\ncounterargument, name evidence that would change the recommendation, and give\nspecific acceptance checks. Use zero tools: do not inspect files, call tools, fetch\nthe web, or conduct independent research. Do not perform or delegate the follow-up.\n```\n\nRequire the model to emit exactly one object conforming to the installed\n`advisor-response.schema.json`, with no prose or code fences. This JSON Schema is\nthe sole supported wrapper model-output format. Direct/native role invocation is unsupported and is not schema-validated. The required fields are:\n\n```text\nrecommendation, why, strongest_objection, change_my_mind, risks,\nfollow_up_areas: required nonblank strings\nacceptance_checks: required nonempty array of nonblank strings\n```\n\n5. Run exactly one selected consultation. Invoke the fixed installed-plugin wrapper\n   with the shell tool's `sandbox_permissions: require_escalated` boundary and a\n   narrow justification for launching one read-only Advisor child. Do not first try\n   the wrapper inside the parent sandbox: nested Codex app-server initialization is\n   blocked there. The elevation applies only to the fixed launcher; the consultation\n   process itself is forced to `--sandbox read-only` and must pass runtime inspection.\n   Do not call `codex exec` directly and do not pass a model or effort override;\n   `run-advisor.sh` resolves the selected tier once, uses its exact live-file model and\n   effort, forces `--sandbox read-only`, starts a fresh\n   `codex exec` thread using existing Codex authentication, and never reads or copies\n   authentication files:\n\n```sh\n/bin/sh <absolute-installed-plugin-root>/scripts/run-advisor.sh --tier standard <<'ADVISOR_PACKET'\nDECISION\n<the complete five-section packet continues here>\nADVISOR_PACKET\n# or use: --tier specialist\n```\n\nWhen the shell tool is called through the Codex tool runtime, a deferred result\nmust be drained before it is classified. Use this caller-side pattern for every\ntier and role (the wrapper's model does not change the handoff contract):\n\n```javascript\nlet process = await tools.exec_command({cmd: transportCommand});\nlet combinedOutput = process.output ?? \"\";\nwhile (process.session_id) {\n  process = await tools.write_stdin({\n    session_id: process.session_id,\n    chars: \"\",\n    yield_time_ms: 5000,\n    max_output_tokens: 20000,\n  });\n  combinedOutput += process.output ?? \"\";\n}\nif (process.session_id || process.exit_code == null) {\n  throw new Error(\"Advisor transport did not reach a terminal result\");\n}\nif (process.exit_code !== 0) {\n  throw new Error(\"Advisor transport failed\");\n}\nconst candidates = combinedOutput.split(/\\r?\\n/).flatMap((line) => {\n  try { return [JSON.parse(line)]; } catch { return []; }\n}).filter((value) => value && value.schema_version === 3);\nif (candidates.length !== 1) {\n  throw new Error(\"Advisor transport did not return exactly one schema-v3 envelope\");\n}\nconst verifiedEnvelope = candidates[0];\ntext(JSON.stringify(verifiedEnvelope));\n```\n\nA nonempty `session_id` from `exec_command` is nonterminal: keep polling the\nsame session with `write_stdin` and preserve every returned output chunk in\n`combinedOutput`. The initial yielded result is nonterminal progress, never an\nAdvisor envelope. Likewise, an outer `functions.wait` result or heartbeat is nonterminal progress.\nDo not parse it, emit a receipt, or classify the consultation until the owning\n`functions.exec` call has drained the exact process and validated its terminal\noutput. Parse `combinedOutput` only after the process has no `session_id` and a\nterminal `exit_code`. Because the shell tool may merge stderr progress into\n`output`, extract exactly one parseable `schema_version: 3` JSON object from the\ncomplete accumulator and reject zero or multiple candidates. Only then use\n`text(JSON.stringify(verifiedEnvelope))` to deliver that verified envelope from\nthe enclosing `functions.exec`; nested shell-tool output is not itself a result.\n\n   Use this single-quoted heredoc form, after proving the delimiter is absent from the\n   packet. Never use `< packet.txt`, an unquoted heredoc, `eval`, or shell-interpolated\n   packet text at this elevated boundary. The packet exists only on the wrapper's\n   stdin; do not stage it in a workspace-writable file.\n\n   The wrapper writes progress only to stderr and emits one verified JSON object on\n   stdout. It runtime-inspects every launched child before classifying that child's\n   response. Wrapper-owned semantic validation rejects malformed JSON, duplicate,\n   missing, extra, wrong-type, noncontiguous-array, or blank schema fields, then\n   deterministically renders the accepted object as this exact canonical eight-line\n   receipt:\n\n```text\nADVISOR RESPONSE\nRECOMMENDATION: <recommendation>\nWHY: <why>\nSTRONGEST OBJECTION: <strongest_objection>\nCHANGE MY MIND: <change_my_mind>\nACCEPTANCE CHECKS: <acceptance checks joined by ; >\nRISKS: <risks>\nFOLLOW-UP AREAS: <follow_up_areas>\n```\n\n   Mandatory post-response inspection proves the exact frozen model and effort,\n   read-only isolation, distinct-thread identity, `codex_exec` provenance,\n   and zero tool calls before validation can succeed. When the first child proves the exact frozen model and effort,\n   read-only runtime, distinct thread, allowlisted `codex_exec` or `Codex Desktop`\n   provenance, and zero tool calls but\n   returns a runtime-valid response-validation failure, the wrapper emits only its\n   redacted failure `class` and `field` on stderr and performs exactly one fresh\n   corrective retry using the same frozen model and effort. The retry prompt names only that\n   diagnostic, never rejected content. A consultation launches at most two children.\n   Packet, launcher, event, identity,\n   same-session, runtime, wrong-model, wrong-effort, non-read-only, normalization, provenance, or tool-use failure\n   is terminal and never retries. A second response-validation failure fails closed.\n   Rejected content is never emitted, accepted, merged, or copied into the retry\n   prompt. Every attempt artifact remains only in one private mode-0700 consultation directory beneath the private transport root; an unconditional exit trap removes\n   that directory after every wrapper exit.\n6. Receive the required advisor response from the verified JSON without supplying\n   more context or asking it to research. A valid processed response contains either\n   a recommendation grounded in the packet or a concrete research-first follow-up\n   under `FOLLOW-UP AREAS`.\n7. Treat a response that passed mandatory runtime inspection as evidence and verify\n   its cited source references. For a research-first response, treat the concise\n   research-first plan as the recommendation and its concrete inquiries as\n   `FOLLOW-UP AREAS`. Then record `accept`, `modify`, or `reject` with one reason:\n   `accept` means the root accepts the returned technical recommendation or\n   research-first plan, never a technical choice that the advisor did not make.\n   After runtime evidence and advice processing, always emit this visible\n   main-chat receipt:\n\n```text\nADVISOR RESULT\nstatus: completed | unavailable\ntier: Standard | Specialist\nmodel: <verified resolved model selector>\neffort: <verified resolved effort>\nisolation: read-only\nrecommendation: <concise recommendation, or unavailable>\ndecision: accept | modify | reject | blocked\nreason: <one sentence>\n```\n\n8. After a valid, runtime-inspected completed result, the root may route only the\n   identified research or brainstorming follow-up to an appropriate Luna or Terra\n   subagent outside this consultation, synthesize that work, and optionally start a\n   fresh consultation with a new `ADVISOR CALL` and `ADVISOR RESULT` receipt. Those\n   subagents do not rescue or alter the original consultation result. An unavailable result cannot be rescued by follow-up work.\n9. The advisor may not spawn, route, research, implement, or review final work. Do\n   not independently spawn a replacement or second advisor, implementer, or final\n   reviewer as part of this consultation. The wrapper-owned response retry above is\n   the only permitted second child.\n\n`completed` requires a processed advisor response with either a recommendation or a\nconcrete `FOLLOW-UP AREAS` entry, plus mandatory post-response runtime inspection.\nAny unavailable runtime evidence, non-read-only runtime policy, tool-use evidence, or\nrequired advice produces `status: unavailable`,\n`recommendation: unavailable`, and `decision: blocked` and remains fail-closed.\nThese receipts summarize verified evidence; they are not runtime proof.\nThe distinct Codex consultation thread remains the inspectable detailed record.\n\nIf exact completed transport evidence is unavailable, report `advisor unavailable`\nand block the consult route. Never continue independently, substitute another model\nor effort, or add an implementer or final reviewer after choosing `consult`.\n\nFor `skip` or `unavailable`, emit only the existing `ADVISOR DECISION`; do not emit\n`ADVISOR CALL` or `ADVISOR RESULT`, and do not start the transport. An unavailable parent does not\nblock root-owned work.\n\nSee [operations](references/operations.md) for installation, runtime evidence, and\nevaluation details.\n\nLegacy cached integrations may use `--role advisor-terra` or `--role advisor-sol`.\nThose compatibility routes remain fixed to Terra/high and GPT-6 Sol/high and do not follow\n`advisor.toml`. They cannot be combined with a tier or preset. New calls use the tier\ninterface above; raw model and effort flags are never accepted by the wrapper.\nThe explicit `--role advisor-astra` route is a separate fixed opt-in to gpt-6-astra/high.\nIt is never selected by Standard/Specialist defaults, trigger selection, fallback, or\naudit tier counts, and cannot be combined with a tier or preset.\n"
}