From d2036e7e282adc870f706d8cdb943e00c79f6ba1 Mon Sep 17 00:00:00 2001 From: bradley inniss Date: Mon, 16 Mar 2026 00:41:47 -0700 Subject: [PATCH 1/2] Update docs for question hooks and answer flow --- ORCA_REFERENCE.md | 1 + app/components/AgentSkillCard.tsx | 2 +- app/lib/pageMarkdown.ts | 1 + app/page.tsx | 5 +---- 4 files changed, 4 insertions(+), 5 deletions(-) diff --git a/ORCA_REFERENCE.md b/ORCA_REFERENCE.md index a953c36..5e9969f 100644 --- a/ORCA_REFERENCE.md +++ b/ORCA_REFERENCE.md @@ -57,6 +57,7 @@ Load order (later overrides earlier): - `--codex-only` - `--codex-effort ` - `--on-milestone ` +- `--on-question ` - `--on-task-complete ` - `--on-task-fail ` - `--on-invalid-plan ` diff --git a/app/components/AgentSkillCard.tsx b/app/components/AgentSkillCard.tsx index 34a17d4..7a35fdd 100644 --- a/app/components/AgentSkillCard.tsx +++ b/app/components/AgentSkillCard.tsx @@ -20,7 +20,7 @@ orca "your task here" ## Key Commands orca Start a new run orca status [--last] Check run status -orca answer Answer a question the agent raised +orca answer 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 diff --git a/app/lib/pageMarkdown.ts b/app/lib/pageMarkdown.ts index 91e8b73..3d0fb2c 100644 --- a/app/lib/pageMarkdown.ts +++ b/app/lib/pageMarkdown.ts @@ -56,6 +56,7 @@ Load order (later overrides earlier): - \`--spec \`, \`--plan \`, \`--config \` - \`--codex-effort \` - \`--on-milestone \` +- \`--on-question \` - \`--on-task-complete \` - \`--on-task-fail \` - \`--on-invalid-plan \` diff --git a/app/page.tsx b/app/page.tsx index 4c67b8f..6f6c2c9 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -1237,10 +1237,7 @@ export default defineOrcaConfig({ orca status --run # 2) Submit the answer -orca answer "yes, use migration A" - -# 3) Continue execution -orca resume --run `} +orca answer "yes, use migration A"`} lang="shell" />

Date: Mon, 16 Mar 2026 12:17:26 -0700 Subject: [PATCH 2/2] Sync docs for question hooks and answer flow --- .gitignore | 1 + ORCA_REFERENCE.md | 10 ++++--- app/components/AgentSkillCard.tsx | 6 ++++- app/lib/pageMarkdown.ts | 11 +++++--- app/page.tsx | 43 ++++++++++++++++++++++++------- 5 files changed, 52 insertions(+), 19 deletions(-) diff --git a/.gitignore b/.gitignore index 5ef6a52..e3a7542 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ yarn-error.log* # typescript *.tsbuildinfo next-env.d.ts +.env*.local diff --git a/ORCA_REFERENCE.md b/ORCA_REFERENCE.md index 5e9969f..fc62f38 100644 --- a/ORCA_REFERENCE.md +++ b/ORCA_REFERENCE.md @@ -24,7 +24,7 @@ orca resume --run --codex-only --codex-effort high orca cancel --last orca cancel --run -orca answer "yes, use migration A" +orca answer "yes, use migration A" # answer and resume a run in waiting_for_answer ``` ## PR Workflow @@ -77,7 +77,7 @@ Load order (later overrides earlier): `orca cancel`: `--run `, `--last`, `--config ` -`orca answer`: `[run-id] [answer]`, `--run ` +`orca answer`: `[run-id] [answer]`; use `--run ` when selecting the run non-positionally `orca list`: `--config ` @@ -98,6 +98,7 @@ Load order (later overrides earlier): Hook names: - `onMilestone` +- `onQuestion` - `onTaskComplete` - `onTaskFail` - `onInvalidPlan` @@ -110,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) @@ -119,7 +121,7 @@ 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` @@ -127,7 +129,7 @@ Top-level: `executor`, `openaiApiKey`, `runsDir`, `sessionLogs`, `skills`, `maxR `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. diff --git a/app/components/AgentSkillCard.tsx b/app/components/AgentSkillCard.tsx index 7a35fdd..4269e15 100644 --- a/app/components/AgentSkillCard.tsx +++ b/app/components/AgentSkillCard.tsx @@ -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: -- -- 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 ( diff --git a/app/lib/pageMarkdown.ts b/app/lib/pageMarkdown.ts index 3d0fb2c..8826e06 100644 --- a/app/lib/pageMarkdown.ts +++ b/app/lib/pageMarkdown.ts @@ -24,7 +24,7 @@ orca resume --run --codex-only --codex-effort high orca cancel --last orca cancel --run -orca answer "yes, use migration A" +orca answer "yes, use migration A" # answer and resume a run in waiting_for_answer \`\`\` ## PR Workflow @@ -54,6 +54,7 @@ Load order (later overrides earlier): \`orca\` / \`orca run\`: - \`[task]\`, \`--task \`, \`-p, --prompt \` - \`--spec \`, \`--plan \`, \`--config \` +- \`--codex-only\` - \`--codex-effort \` - \`--on-milestone \` - \`--on-question \` @@ -75,7 +76,7 @@ Load order (later overrides earlier): \`orca cancel\`: \`--run \`, \`--last\`, \`--config \` -\`orca answer\`: \`[run-id] [answer]\`, \`--run \` +\`orca answer\`: \`[run-id] [answer]\`; use \`--run \` when selecting the run non-positionally \`orca list\`: \`--config \` @@ -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) @@ -117,7 +120,7 @@ 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\` @@ -125,7 +128,7 @@ Hook contract: \`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. diff --git a/app/page.tsx b/app/page.tsx index 6f6c2c9..f87f276 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -474,6 +474,10 @@ orca --plan ./specs/feature.md`} flag="--on-milestone " desc="Shell command to run on each milestone" /> + @@ -1072,7 +1076,7 @@ export default defineOrcaConfig({ /> @@ -1088,14 +1092,14 @@ export default defineOrcaConfig({

Thinking-level controls are explicit: use - - {" codex.thinkingLevel.decision|planning|execution "} - {" "} + + {" codex.thinkingLevel.decision|planning|review|execution "} + {" "} with canonical values + | 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 };