Skip to content

[Feature]: worker-start --agent should accept custom/vendor CLI binaries (codex-fugu, claude-fugu, agy, opencode) with the same requested/effective verification #14952

Closed as not planned

Description

@minmuk

Problem or use case

orchestration worker-start --agent <id> only recognizes a fixed set of agents (Claude / Codex / Cursor). Any other installed CLI agent — including community/vendor CLIs that live on PATH just like codex/claude do — is rejected with agent_unconfigured, even though the underlying --model/--effort machinery (and the launch.requested vs launch.effective verification) is exactly what those agents need most.

Concretely, on 2026-08-16/17 I tested four agents that are all real, installed CLI binaries:

  • codex-fugu — a codex-cli fork targeting Sakana AI's Fugu / Fugu Ultra models
  • claude-fugu — a companion wrapper that reuses the claude binary and ~/.claude/ config but swaps the backend to Sakana AI Fugu (via ~/.claude/.fugu-env)
  • agy — Antigravity/Gemini CLI
  • opencode — already tracked in [Feature]: Agent selection and model selection with OpenCode #1122 for its own agent/model picker

None of these can be passed to --agent:

$ orca orchestration worker-start --task <task_id> --agent codex-fugu --worktree current --json
{"error":{"code":"agent_unconfigured","message":"A configured --agent is required when worker-start creates a terminal."}}

$ orca orchestration worker-start --task <task_id> --agent claude-fugu --worktree current --json
{"error":{"code":"agent_unconfigured","message":"A configured --agent is required when worker-start creates a terminal."}}

$ orca orchestration worker-start --task <task_id> --agent agy --worktree current --json
{"error":{"code":"agent_unconfigured","message":"A configured --agent is required when worker-start creates a terminal."}}

The only working path is the generic two-step workaround:

$ orca terminal create --worktree active --command "agy -p '...' --output-format stream-json" --json
$ orca orchestration worker-start --task <task_id> --terminal <handle> --json

This works for supervision (Task/Dispatch tracking, worker-list/-show/-stop/-release all function normally), but it silently drops the one thing --agent+--model+--effort gives for free: launch.requested vs launch.effective verification. For --terminal, both fields come back null, so there is no machine-checkable proof that the command actually launched with the intended model/vendor — you have to trust that your --command string was correct and grep the terminal output yourself.

This matters most for exactly the agents that are not first-class: they're the ones without an existing track record (e.g. Sakana Fugu via codex-fugu/claude-fugu), so being unable to verify "requested == effective" per dispatch makes it harder to build confidence in using them for unattended/scheduled work.

Proposed solution

Either:

  1. Let --agent accept an arbitrary PATH-resolvable command name (not just the built-in enum), and apply the same --model/--effort → launch.requested/launch.effective verification to it when the underlying CLI supports -m/--model-style flags, or
  2. Add a documented extension point (e.g. a local orca.yaml/config entry) for registering additional agent IDs with their launch command template and how the CLI reports its selected model, so --agent <custom-id> resolves and verifies the same way built-ins do.

Alternatives or additional context

Related: #1122 (OpenCode's own agent/model selection is a similar "not first-class" gap) and #13854 (Antigravity/agy has a separate worker-start reliability bug), which together suggest agent coverage beyond Claude/Codex/Cursor is a recurring pain point, not a one-off request.

Activity

  1. jeffhuen commented on Sep 4, 2026

    @jeffhuen

    Confirmed on Orca 1.4.196 with Agy 1.1.26.

    Agy has queued prompts during login since 1.1.23, so #13854 may now be fixed and needs a retest.

    One gap remains: worker-start --agent antigravity cannot set or verify gemini-3.8-flash-high. Orca limits --model to Claude, Codex, and Cursor. A custom terminal works, but launch.effective cannot verify its model or effort.

    Please add model and effort support for antigravity. antigravity is the Orca agent ID; agy is the executable.

  2. added theissue type on Sep 19, 2026
  3. nwparker commented on Sep 19, 2026

    @nwparker
    Contributor

    Verified the remaining worker-start --agent agy name mismatch and opened draft #21664 with a narrow fix.

    ELI5: the executable is called agy, but Orca stores this agent as antigravity. The CLI now translates that alias before asking the local or remote runtime to start the worker.

    On macOS with installed agy 1.2.7 and an isolated folder workspace, the installed CLI returned agent_unconfigured. The rebuilt CLI against the same runtime returned ready / input_accepted; requested and effective agent both read antigravity. The real terminal contained the task marker, then failed generation with 401 ACCESS_TOKEN_TYPE_UNSUPPORTED. The test worker was stopped and released. This does not prove successful generation, hooks or accepted worker_done.

    Sanitized before/after CLI receipt report

    34 focused tests, CLI compilation/typecheck, and changed-code quality checks pass. Local/remote alias mapping is covered by tests; Windows, Linux, WSL, SSH and paired-host execution were not live-tested.

    Scope remains partial: custom vendor registration and verified Antigravity model/effort selection are still open. Current dispatch --inject uses --to <terminal> and does not take --agent; its canonical Antigravity recognition was checked separately. Neither issue should close on this alias fix alone.

  4. nwparker commented on Sep 19, 2026

    @nwparker
    Contributor

    Follow-up to the agy alias fix in #21664: I tested model/effort selection directly with installed agy 1.2.7 on macOS before extending worker-start.

    ELI5: an Antigravity model ID may already include its effort. Combining it with a different effort is an error, and different model families offer different effort levels.

    --model --effort Actual agy result
    gemini-3.7-flash-low high Rejected: conflicting effort
    gemini-3.7-flash-low low Selection accepted; generation then failed 401
    gemini-3.7-flash high Resolved to gemini-3.7-flash-high; generation then failed 401
    gemini-3.1-pro medium Rejected: only low/high available
    Gemini 3.7 Flash (Low) high Rejected: effort not supported with that selector

    The rejected cases reported invalid model selection and started no generation. The accepted cases hit ACCESS_TOKEN_TYPE_UNSUPPORTED, so they do not prove successful generation or worker lifecycle completion. Global authentication and hook settings were unchanged.

    This rules out simply giving every Antigravity model the same low/medium/high option list. The implementation needs model-specific options, must preserve discovered IDs and legacy selector behavior, and must keep conflicting selections out of an effective launch receipt. Early startup logs are insufficient proof: an invalid selection can still log the configured default before the final selection error.

    Current worker-start still refuses Antigravity --model/--effort; #21664 only addresses the executable alias. The existing shared model parser and launch-option catalog are the reuse points for the remaining work. Custom/vendor registration remains separate and open.

  5. nwparker commented on Sep 19, 2026

    @nwparker
    Contributor

    Implemented the Antigravity model/effort portion in draft #21672, stacked on the migration work.

    ELI5: workers can now request an Antigravity model and effort. Orca refuses combinations that conflict instead of starting a worker with a misleading selection. It reuses the existing launch catalog and argument-precedence code; no separate launcher was added.

    Live macOS verification with installed agy 1.2.7:

    • Before, Antigravity worker model selection returned invalid_argument.
    • After, --agent agy --model gemini-3.7-flash --effort high returned ready / input_accepted; requested/effective launch selections matched, and agy's actual rendered footer showed High.
    • A Low-model/High-effort worker request was rejected with invalid_argument.
    • The worker received the task marker, then generation failed with 401 ACCESS_TOKEN_TYPE_UNSUPPORTED. It was stopped and released; no successful generation or accepted worker_done is claimed.

    Actual agy model footer, cropped from hidden Orca renderer

    77 focused tests, full typecheck, Electron/Vite build and changed-code quality passed; the final compatibility correction also passed its 18 relevant tests. CI is starting. Windows/Linux/WSL/SSH and paired-host execution remain unverified for model selection. A receipt records launch arguments, not a completed provider request or account entitlement.

    Custom/vendor registration remains open, so this is not a full fix for this issue. Unknown model selectors are passed through as model-only values; effort support is deliberately limited to the verified selector forms/families.

  6. nwparker commented on Nov 6, 2026

    @nwparker
    Contributor

    The agy alias (#21664) and Antigravity model/effort (#21672) are merged. Arbitrary custom/vendor CLIs as --agent would need launch, readiness, hooks, capability and recovery contracts per binary, which we aren't planning now. Closing as not planned.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions