feat(advise): run by hand, on request, or as a subagent QA check

README.md

@@ -56,18 +56,45 @@ no third-party dependencies.
 
 ## Second opinions
 
-`/codex-headless:advise` puts Codex (in a read-only sandbox) and a Fable 5.1
-subagent to work as advisors in parallel. It runs only when you ask for it,
-either with the command or by asking for "a second opinion" or to "ask codex and
-fable". Claude sends both the same brief and merges their verdicts. When they
-disagree, Claude shows both positions next to its own view and asks you to
-decide.
+`/codex-headless:advise` puts Codex (in a read-only sandbox) and a Claude
+advisor subagent to work as advisors in parallel. Claude sends both the same
+brief and merges their verdicts. When they disagree, Claude shows both
+positions next to its own view and asks you to decide.
 
 There are two checkpoints: before Claude commits to an approach, and before it
 calls the work done. Asking for advisors on the whole task covers both.
 Otherwise your request covers the checkpoint you asked about, and Claude asks
 you before it runs the other one.
 
+It never runs on Claude's own initiative. There are three ways to start it:
+
+- **By hand.** Type `/codex-headless:advise`.
+- **By asking.** Ask for "a second opinion" or to "ask codex and fable", and
+  Claude runs it. Permission rules control this path. To have Claude ask you
+  first every time, add `"ask": ["Skill(codex-headless:advise)"]` to
+  `permissions` in your settings. To allow only the command, use `"deny"`
+  instead; a deny rule does not block the command.
+- **As a QA check at the end of your own subagents.** Preload the skill in
+  the subagent's definition and tell it when to run:
+
+  ```markdown
+  ---
+  name: my-implementer
+  description: ...
+  skills:
+    - codex-headless:advise
+  ---
+
+  ...your instructions...
+
+  Before you report back, run the advise skill's `done` checkpoint on your
+  changes and include its verdict in your report.
+  ```
+
+  A subagent cannot start another subagent or ask you a question, so inside
+  one the skill runs Codex alone as the second model and hands any
+  disagreement back to the main conversation instead of asking you.
+
 ## Data handling
 
 **What goes to OpenAI.** Codex runs under your own Codex login and sends its

skills/advise/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: advise
-description: Get a second opinion from two independent advisors at once, Codex (read-only via `codex exec`) and a Fable 5.1 subagent, then merge their verdicts. Use it only when the user asks for it, for example "get a second opinion", "ask codex and fable", "have codex and fable review this", or "multi-advisor". A run sends the brief and the repository files Codex reads to OpenAI through the user's Codex login, so never start it on your own initiative, however large or risky the task looks.
+description: Get a second opinion from two independent advisors at once, Codex (read-only via `codex exec`) and a Claude advisor subagent, then merge their verdicts. Use it only when the user asks for it, for example "get a second opinion", "ask codex and fable", or "multi-advisor", or when the user's own configuration asks for it, such as a subagent definition that runs it as a QA check before reporting back. A run sends the brief and the repository files Codex reads to OpenAI through the user's Codex login, so never start it on your own initiative, however large or risky the task looks.
 argument-hint: "[plan|done] <what you want reviewed>"
 version: 0.3.1 # x-release-please-version
 allowed-tools:
@@ -15,12 +15,14 @@ allowed-tools:
 # Second opinions from Codex and Fable
 
 You keep doing the work. Two advisors review it independently: Codex in a
-read-only sandbox, and Fable 5.1 as a subagent. Neither one writes code. You
-merge what they say, and when they disagree, the user decides.
+read-only sandbox, and a Claude advisor subagent (Fable). Neither one writes
+code. You merge what they say, and when they disagree, the user decides.
 
 ## When to run it
 
-Only when the user asks. A run sends the brief to OpenAI, and Codex sends the
+Only when the user asks, either in the conversation or through their own
+configuration, such as a subagent definition that tells you to run it before
+you report back. A run sends the brief to OpenAI, and Codex sends the
 repository files it reads too, so the user has to want that. Never start it
 because a task looks large or risky.
 
@@ -37,6 +39,18 @@ If they do not say yes, carry on without it.
 
 Never run it on every edit. Two runs per task is the whole budget.
 
+### Inside a subagent
+
+When you are a subagent that was told to run this as a QA check, run the
+`done` checkpoint once, before you report back. A subagent cannot start
+another subagent or ask the user, so:
+
+- Skip the Fable advisor and run Codex alone. Report the Fable advisor as
+  skipped, not as failed.
+- Do not use `AskUserQuestion`. When Codex disagrees with your work on
+  anything that changes the verdict, put both positions in your report to the
+  parent and let it decide.
+
 ## Step 1: Write one shared brief
 
 Both advisors get exactly the same text. That way, when they disagree, the cause