Sync Orca docs for question hooks and answer flow

.gitignore

@@ -39,3 +39,4 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+.env*.local

ORCA_REFERENCE.md

@@ -24,7 +24,7 @@ orca resume --run <run-id> --codex-only --codex-effort high
 orca cancel --last
 orca cancel --run <run-id>
 
-orca answer <run-id> "yes, use migration A"
+orca answer <run-id> "yes, use migration A"   # answer and resume a run in waiting_for_answer
 ```
 
 ## PR Workflow
@@ -57,6 +57,7 @@ Load order (later overrides earlier):
 - `--codex-only`
 - `--codex-effort <low|medium|high|xhigh>`
 - `--on-milestone <cmd>`
+- `--on-question <cmd>`
 - `--on-task-complete <cmd>`
 - `--on-task-fail <cmd>`
 - `--on-invalid-plan <cmd>`
@@ -76,7 +77,7 @@ Load order (later overrides earlier):
 
 `orca cancel`: `--run <run-id>`, `--last`, `--config <path>`
 
-`orca answer`: `[run-id] [answer]`, `--run <id>`
+`orca answer`: `[run-id] [answer]`; use `--run <id>` when selecting the run non-positionally
 
 `orca list`: `--config <path>`
 
@@ -97,6 +98,7 @@ Load order (later overrides earlier):
 
 Hook names:
 - `onMilestone`
+- `onQuestion`
 - `onTaskComplete`
 - `onTaskFail`
 - `onInvalidPlan`
@@ -109,6 +111,7 @@ Hook contract:
 - `context` is `{ cwd, pid, invokedAt }`.
 - Command hooks (`hookCommands` and CLI `--on-*`) receive JSON via stdin.
 - No `ORCA_*` hook payload env-var framing.
+- `onQuestion` fires when Codex requests user input and includes `requestId`, `threadId`, `turnId`, `itemId`, and `questions`.
 - `onError` fires for run errors and hook-dispatch/command-hook failures.
 
 ## OrcaConfig Reference (complete)
@@ -118,15 +121,15 @@ Top-level: `executor`, `openaiApiKey`, `runsDir`, `sessionLogs`, `skills`, `maxR
 `maxRetries` is an accepted OrcaConfig field; current planner-generated task retry limits are still fixed by task graph contracts.
 
 
-`codex.*`: `enabled`, `model`, `effort`, `thinkingLevel.decision|planning|execution`, `command`, `timeoutMs`, `multiAgent`, `perCwdExtraUserRoots`
+`codex.*`: `enabled`, `model`, `effort`, `thinkingLevel.decision|planning|review|execution`, `command`, `timeoutMs`, `multiAgent`, `perCwdExtraUserRoots`
 
 `pr.*`: `enabled`, `requireConfirmation`
 
 `review.plan.*`: `enabled`, `onInvalid`
 
 `review.execution.*`: `enabled`, `maxCycles`, `onFindings`, `validator.auto`, `validator.commands`, `prompt`
 
-Thinking-level controls use `codex.thinkingLevel.decision|planning|execution` with canonical values `low|medium|high|xhigh`.
+Thinking-level controls use `codex.thinkingLevel.decision|planning|review|execution` with canonical values `low|medium|high|xhigh`.
 
 Codex app-server integration: at session startup Orca calls `skills/list` with `cwds: [cwd]`, `forceReload: true`, and optional `codex.perCwdExtraUserRoots` mappings.
 

app/components/AgentSkillCard.tsx

@@ -20,7 +20,7 @@ orca "your task here"
 ## Key Commands
 orca <task>              Start a new run
 orca status [--last]     Check run status
-orca answer <text>       Answer a question the agent raised
+orca answer <run-id> <text>  Answer a question the agent raised
 orca resume [--last]     Resume a paused run
 orca cancel [--last]     Cancel a run
 orca pr create [--last]  Open a PR for the run's branch
@@ -30,11 +30,15 @@ export default {
   executor: "codex",           // "codex" (default)
   sessionLogs: "./session-logs",
   hooks: {
+    onQuestion: async (event) => {
+      console.log(event.questions[0]?.question);
+    },
     onComplete: async (event, context) => {
       console.log(event.message, context.cwd);
     },
   },
   hookCommands: {
+    onQuestion: "node ./scripts/on-question.mjs",
     onComplete: "node ./scripts/on-complete.mjs",
   },
   codex: { multiAgent: false },
@@ -44,7 +48,7 @@ export default {
 - Codex executor requires ~/.codex/auth.json
 - Must be run inside a git repo
 - Run ID format: <slug>-<unix-ms>-<hex4>
-- Use orca answer to unblock a waiting run`;
+- Use orca answer to respond when status is waiting_for_answer (run resumes automatically)`;
 
 export function AgentSkillCard({ compact = false }: { compact?: boolean }) {
   return (

app/lib/pageMarkdown.ts

@@ -24,7 +24,7 @@ orca resume --run <run-id> --codex-only --codex-effort high
 orca cancel --last
 orca cancel --run <run-id>
 
-orca answer <run-id> "yes, use migration A"
+orca answer <run-id> "yes, use migration A"   # answer and resume a run in waiting_for_answer
 \`\`\`
 
 ## PR Workflow
@@ -54,8 +54,10 @@ Load order (later overrides earlier):
 \`orca\` / \`orca run\`:
 - \`[task]\`, \`--task <text>\`, \`-p, --prompt <text>\`
 - \`--spec <path>\`, \`--plan <path>\`, \`--config <path>\`
+- \`--codex-only\`
 - \`--codex-effort <low|medium|high|xhigh>\`
 - \`--on-milestone <cmd>\`
+- \`--on-question <cmd>\`
 - \`--on-task-complete <cmd>\`
 - \`--on-task-fail <cmd>\`
 - \`--on-invalid-plan <cmd>\`
@@ -74,7 +76,7 @@ Load order (later overrides earlier):
 
 \`orca cancel\`: \`--run <run-id>\`, \`--last\`, \`--config <path>\`
 
-\`orca answer\`: \`[run-id] [answer]\`, \`--run <id>\`
+\`orca answer\`: \`[run-id] [answer]\`; use \`--run <id>\` when selecting the run non-positionally
 
 \`orca list\`: \`--config <path>\`
 
@@ -96,6 +98,7 @@ Load order (later overrides earlier):
 
 Hook names:
 - \`onMilestone\`
+- \`onQuestion\`
 - \`onTaskComplete\`
 - \`onTaskFail\`
 - \`onInvalidPlan\`
@@ -108,6 +111,7 @@ Hook contract:
 - \`context\` is \`{ cwd, pid, invokedAt }\`.
 - Command hooks (\`hookCommands\` and CLI \`--on-*\`) receive JSON via stdin.
 - No \`ORCA_*\` hook payload env-var framing.
+- \`onQuestion\` fires when Codex requests user input and includes \`requestId\`, \`threadId\`, \`turnId\`, \`itemId\`, and \`questions\`.
 - \`onError\` fires for run errors and hook-dispatch/command-hook failures.
 
 ## OrcaConfig Reference (complete)
@@ -116,15 +120,15 @@ Hook contract:
 \`maxRetries\` is an accepted OrcaConfig field; current planner-generated task retry limits are still fixed by task graph contracts.
 
 
-\`codex.*\`: \`enabled\`, \`model\`, \`effort\`, \`thinkingLevel.decision|planning|execution\`, \`command\`, \`timeoutMs\`, \`multiAgent\`, \`perCwdExtraUserRoots\`
+\`codex.*\`: \`enabled\`, \`model\`, \`effort\`, \`thinkingLevel.decision|planning|review|execution\`, \`command\`, \`timeoutMs\`, \`multiAgent\`, \`perCwdExtraUserRoots\`
 
 \`pr.*\`: \`enabled\`, \`requireConfirmation\`
 
 \`review.plan.*\`: \`enabled\`, \`onInvalid\`
 
 \`review.execution.*\`: \`enabled\`, \`maxCycles\`, \`onFindings\`, \`validator.auto\`, \`validator.commands\`, \`prompt\`
 
-Thinking-level controls use \`codex.thinkingLevel.decision|planning|execution\` with canonical values \`low|medium|high|xhigh\`.
+Thinking-level controls use \`codex.thinkingLevel.decision|planning|review|execution\` with canonical values \`low|medium|high|xhigh\`.
 
 Codex app-server integration: at session startup Orca calls \`skills/list\` with \`cwds: [cwd]\`, \`forceReload: true\`, and optional \`codex.perCwdExtraUserRoots\` mappings.
 

app/page.tsx

@@ -474,6 +474,10 @@ orca --plan ./specs/feature.md`}
                   flag="--on-milestone <cmd>"
                   desc="Shell command to run on each milestone"
                 />
+                <Flag
+                  flag="--on-question <cmd>"
+                  desc="Shell command to run when Codex requests user input"
+                />
                 <Flag
                   flag="--on-error <cmd>"
                   desc="Shell command to run on error"
@@ -679,7 +683,7 @@ orca cancel --run feature-auth-1766228123456-1a2b`}
                 <Flag flag="[answer]" desc="Answer text (positional)" />
                 <Flag
                   flag="--run <id>"
-                  desc="Run ID as a named flag (alias for positional)"
+                  desc="Run ID as a named flag (use instead of positional run-id)"
                 />
               </tbody>
             </table>
@@ -1072,7 +1076,7 @@ export default defineOrcaConfig({
                 />
                 <Flag
                   flag="codex.*"
-                  desc="enabled, model, effort, thinkingLevel.decision|planning|execution, command, timeoutMs, multiAgent, perCwdExtraUserRoots"
+                  desc="enabled, model, effort, thinkingLevel.decision|planning|review|execution, command, timeoutMs, multiAgent, perCwdExtraUserRoots"
                 />
                 <Flag flag="pr.*" desc="enabled, requireConfirmation" />
                 <Flag flag="review.plan.*" desc="enabled, onInvalid" />
@@ -1088,14 +1092,14 @@ export default defineOrcaConfig({
             </table>
             <p style={{ ...S.p, fontSize: "13px", marginTop: "12px" }}>
               Thinking-level controls are explicit: use
-              <code
-                style={{
-                  fontFamily: "ui-monospace, monospace",
-                  color: "#22d3ee",
-                }}
-              >
-                {" codex.thinkingLevel.decision|planning|execution "}
-              </code>{" "}
+                <code
+                  style={{
+                    fontFamily: "ui-monospace, monospace",
+                    color: "#22d3ee",
+                  }}
+                >
+                  {" codex.thinkingLevel.decision|planning|review|execution "}
+                </code>{" "}
               with canonical values
               <code
                 style={{
@@ -1181,6 +1185,10 @@ export default defineOrcaConfig({
                   flag="onMilestone"
                   desc="Fired at each milestone checkpoint"
                 />
+                <Flag
+                  flag="onQuestion"
+                  desc="Fired when Codex requests user input for the current turn"
+                />
                 <Flag
                   flag="onTaskComplete"
                   desc="Fired when a single task completes successfully"
@@ -1237,10 +1245,7 @@ export default defineOrcaConfig({
 orca status --run <run-id>
 
 # 2) Submit the answer
-orca answer <run-id> "yes, use migration A"
-
-# 3) Continue execution
-orca resume --run <run-id>`}
+orca answer <run-id> "yes, use migration A"`}
               lang="shell"
             />
             <p
@@ -1414,6 +1419,21 @@ export default {
             <CodeBlock
               code={`type HookEventMap = {
   onMilestone:    BaseHookEvent & { hook: "onMilestone" };
+  onQuestion:     BaseHookEvent & {
+    hook: "onQuestion";
+    requestId: string | number;
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    questions: Array<{
+      header: string;
+      id: string;
+      question: string;
+      isOther: boolean;
+      isSecret: boolean;
+      options?: Array<{ label: string; description: string }> | null;
+    }>;
+  };
   onTaskComplete: BaseHookEvent & { hook: "onTaskComplete"; taskId: string; taskName: string };
   onTaskFail:     BaseHookEvent & { hook: "onTaskFail"; taskId: string; taskName: string; error: string };
   onInvalidPlan:  BaseHookEvent & { hook: "onInvalidPlan"; error: string };