Skip to content

[Feature]: orchestration worker-start needs a per-dispatch agent permission surface #12360

Open

Description

@pablontiv

Problem or use case

Summary: orchestration worker-start has no per-dispatch surface for the launched agent's permission flags. Argument resolution goes through one global, GUI-only, per-agent setting (agentDefaultArgs). When that setting resolves to empty for an agent, every supervised worker for that agent launches interactive, and the first tool call parks the worker on a TUI approval prompt that no human is watching. There is no way to start one non-interactive worker while leaving the operator's own panes in manual mode, and no way to set any of this headlessly.

What happened

Orca 1.4.164 on macOS. A coordinator dispatched a batch of supervised workers with orchestration worker-start --agent claude. Three dispatches ended in state=abandoned and two tasks stalled. Inspecting one of the worker terminals showed it parked on an interactive approval prompt for its first file write:

Do you want to create verify.py?
> 1. Yes

The dispatch's own health signals were consistent with a healthy worker: the terminal existed, the agent was recognized, the preamble had been accepted. The worker was simply blocked on a question nobody could answer, because the whole point of a supervised worker is that no human is attached to it.

Recovery took five manual steps: abandon the dispatches, reset the tasks to ready, delete and recreate the worktrees, open replacement terminals with an explicit claude --permission-mode acceptEdits, then re-attach each one with worker-start --terminal.

What the code actually does

I want to correct the obvious first reading of this report, because it is wrong and it matters for scoping. There is an argument-forwarding mechanism, and worker-start does use it. The default even bypasses permissions. The gap is narrower than "worker-start cannot pass flags", and it is a real gap.

Verified at tag v1.4.167:

1. Both worker-start launch branches resolve agent args from the same global setting.

  • Existing worktree: createExistingWorktreeWorkerTerminal calls createTerminal with the bare agent id as the command (src/main/runtime/rpc/methods/orchestration-worker-topology.ts:54-77, call at :61-67). createTerminal routes through resolveAgentTerminalCreateOptions (src/main/runtime/orca-runtime.ts:24340), which builds the startup plan with agentArgs: resolveTuiAgentLaunchArgs(agent, settings.agentDefaultArgs) (src/main/runtime/orca-runtime.ts:23910, function at :23869-23935).
  • New worktree: createWorkerWorktree passes startupAgent to createManagedWorktree (orchestration-worker-topology.ts:100-144, at :137), which calls buildStartupForAgent (orca-runtime.ts:20779), which resolves the same way at orca-runtime.ts:20312.

Both paths read one process-global record: settings.agentDefaultArgs.

2. The shipped default does not prompt. DEFAULT_TUI_AGENT_ARGS = YOLO_TUI_AGENT_ARGS (src/shared/tui-agent-launch-defaults.ts:10), and claude maps to --dangerously-skip-permissions (src/shared/tui-agent-permissions.ts:6-7). Out of the box, worker-start --agent claude launches a worker that does not stop for permission.

3. The freeze is what happens when that setting is empty. resolveAgentPermissionMode classifies empty args as manual (tui-agent-permissions.ts:58-63), and applyAgentPermissionMode writes an empty string for every affected agent when the operator selects Manual (tui-agent-permissions.ts:136-166, write at :152). resolveTuiAgentLaunchArgs returns that empty string verbatim once the key exists (tui-agent-launch-defaults.ts:82-94, at :86-92). The agent then launches bare and prompts on first write. Corroborating field evidence: a stuck worker terminal buffer in the same app showed the literal line manual mode on.

So the observed failure is not a missing mechanism. It is a global mechanism with no per-dispatch scope, driven to a value that is correct for a human at a keyboard and fatal for an unattended worker.

4. The Manual state is reachable without the operator knowing. Besides the Settings toggle, the yolo-defaults migration writes an empty string for any agent that already had a legacy command override: if (agent in commandOverrides) { migratedArgs[agent] = '' } (src/main/persistence.ts:709-753, at :728-731). An operator who once customized the claude launch command is silently migrated into permanent manual mode for that agent, including for every future supervised worker.

The gap, stated precisely

Three sub-claims, all verified at v1.4.167:

  • It is global per agent. One settings.agentDefaultArgs record feeds every launch path in the app: the launcher palette, worktree startup agents, and orchestration workers alike. There is no per-dispatch, per-worktree, or per-run scope.
  • It has no CLI surface at all. git grep agentDefaultArgs over src/cli at v1.4.167 returns zero hits. There is no orca settings command spec (src/cli/specs/ contains no settings module). The only writer is Settings > Agents in the renderer (src/renderer/src/components/settings/AgentsPane.tsx:729-786, control rendered at :874). A headless coordinator, a CI runner, or orca serve cannot set it.
  • worker-start has no per-invocation override. WorkerStartParams accepts no argv, command, or permission field (src/main/runtime/rpc/methods/orchestration-worker-start-schema.ts:4-21). The CLI spec's allowedFlags lists 16 flags, none of them argv-related (src/cli/specs/orchestration-worker-specs.ts:9-27).

The consequence is the one that actually hurts: an operator who keeps Manual mode for their own interactive panes, which is exactly the security posture #5385 asked for and #5440 shipped, cannot dispatch a single non-interactive worker without first loosening the global default for their entire session.

Why the documented workaround does not close it

The recovery path is orca terminal create --command "claude --permission-mode acceptEdits" followed by worker-start --terminal <handle>. That works because resolveBareAgentLaunchCommand matches the launch command by exact string equality (orca-runtime.ts:1363-1395, comparison at :1388), so a command carrying flags is treated as user-authored shell and skips the defaults entirely. It is currently the only CLI-reachable way to control a worker's argv.

I checked whether the re-attach path diverges from the create path in dispatch binding or lifecycle. It does not. Once both branches reach orchestration-workers.ts:206, the code is identical: the same setup stage, the same tui-idle readiness wait (:224-227), the same authority and capability minting (:239-247), the same preamble and sendTerminalAgentPrompt (:250-260), the same markWorkerDispatchReady (:267). The divergence is entirely upstream, and it is the reason the workaround has a real cost:

  • --terminal is rejected outright when combined with new-child or new-top-level creation (orchestration-workers.ts:66-71), and rejected when combined with --agent (:60-65).
  • The terminal must already belong to the resolved worktree and must already be running a recognized agent (:109-123).

Because --terminal can only ever target an existing worktree, and setup is not_applicable for existing worktrees (:75-80, receipt at :158-165), the two-step path can never carry a wait-for-setup startup policy. That policy is only produced by createWorkerWorktree on the creation path (orchestration-worker-topology.ts:158-165). So the statement that the two-step path cannot enforce a repository wait-for-setup startup policy is accurate, and the reason is structural rather than incidental: choosing controllable argv today means giving up worktree creation and setup sequencing in the same call.

Proposed solution

Requirement: the recommended launch path, worker-start --agent <agent> with worktree creation and setup sequencing intact, must be able to produce a worker that can write inside its own worktree without stopping at an interactive prompt, and must be able to do so without changing the global default that governs the operator's own interactive panes.

Concretely, that means three properties:

  1. Per-dispatch scope. The permission posture of a supervised worker is decided at dispatch time, not inherited from a sticky global that exists to protect a human at a keyboard.
  2. Headless reachability. Whatever expresses it must be settable from the CLI, so a coordinator running under orca serve or in CI can use it without a renderer window.
  3. Composable with creation. It must work on the same call as --worktree new-child/new-top-level, --name, and --setup, so choosing it does not force the two-step --terminal fallback and the loss of wait-for-setup.

I am deliberately not designing the flag. Some shapes that would satisfy the requirement, for discussion rather than as a proposal:

  • A --agent-args passthrough on worker-start, mirroring the surface PR Feature/automation agent args 11043 #11873 adds for automations (orca automations create/edit --agent-args "--yolo"). Lowest-novelty option: the model, the override precedence, and the "unset falls back to the global default" semantics would already exist.
  • A semantic --permission-mode <yolo|manual> on worker-start that maps to the agent's own flag via YOLO_TUI_AGENT_ARGS, keeping coordinators out of per-agent flag trivia. Narrower and safer than raw argv, but does not express intermediate modes such as Claude's acceptEdits.
  • A dispatch-scoped override in WorkerStartParams with no CLI surface. Rejected: it fails the headless-reachability property, which is half the problem.

Whatever the shape, two behaviors matter more than the spelling:

  • Unset must keep today's behavior. No change for anyone whose global default already works.
  • The choice must be visible in the dispatch receipt. worker-start already returns structured effects and a setup receipt. A worker launched with a non-default permission posture should say so there, so an operator auditing a run can tell which workers ran unattended and with what.

Alternatives or additional context

Workarounds available today

Workaround Cost
Flip Settings > Agents to Yolo before dispatching Global and sticky. Loosens the operator's own interactive panes for the whole session, which is the posture #5385 explicitly argued against. GUI-only, so unavailable headless.
Per-agent args box in Settings > Agents (AgentsPane.tsx:763-764) Can express --permission-mode acceptEdits precisely, but still global per agent and still GUI-only.
orca terminal create --command "claude --permission-mode acceptEdits" then worker-start --terminal Works, and is CLI-reachable. Costs worktree creation and wait-for-setup sequencing (orchestration-workers.ts:66-71), requires the coordinator to know each agent's flag spelling, and turns one call into several.

Related work

Ref State Disposition
#5385 "Default Agent Arguments Should Not Be --dangerously-skip-permissions/--yolo default" Closed, completed Direct ancestor. Asked for a restrictive default; fixed by #5440. Not a duplicate: it argued about the default value, this issue is about scope. Following its recommendation is what puts an operator into the failing state.
#5440 "Add agent permission mode controls" Merged Shipped the Manual/Yolo/Mixed control. Its own summary states Manual "clears Orca-owned yolo args/env", which is the exact mechanism traced above. Working as designed; the design has no orchestration-worker scope.
#11043 "[Feature] automation cannot set params on agents" Open Same shape, different surface. "I want my automation to run as yolo, but i strictly DONT want this as default for this agent or project." Not a duplicate, but establishes the principle for automations.
PR #11873 "Feature/automation agent args 11043" Open Implements per-automation agentArgs with GUI and CLI (--agent-args), preserving the global default when unset. Closest existing precedent and the natural model to follow. Does not touch orchestration worker-start.
#9977 "[Feature]: Launch an agent in yolo mode directly from the agent launcher" Open Same shape again, for the GUI launcher palette. Sibling, not duplicate: palette-and-keyboard scope, no CLI or orchestration surface.
#5700 "[Feature]: Agent Control Surface Parity" Closed, completed Read in full. Umbrella tracker, split into #5702-stablyai/orca#5709. Its orchestration workstream is #5707. The checklist covers discoverability, stable selectors, structured errors, and machine-readable verification. It does not cover per-dispatch agent launch parameters, and none of its "permission needed" items address the launched agent's own permission mode. Adjacent, not covering.
#10886 "[Bug]: Orca restart restores Codex sessions with stale YOLO args" Open Different direction of the same coupling: a session-level permission choice lost to the global default on restore. Independent; neither blocks the other.
#12177 "fix(orchestration): resolve bare agent ids when launch binary differs" Open PR Touches the same bare-agent resolution path (resolveBareAgentLaunchCommand) that the --terminal workaround depends on. Worth a look for interaction, but orthogonal.
#9951 "[Feature]: Headless dispatch (--headless) — spawn CLI agents as subprocesses instead of creating terminals" Open The closest thing to an alternative solution. A one-shot agent -p "<preamble>" subprocess would sidestep the interactive prompt entirely, because there is no TUI to prompt in. Different scope: it targets orchestration run, replaces the terminal-and-paste model rather than parameterizing it, and would not help any dispatch that still wants a real supervised terminal. Complementary, not a substitute.
#9942 "[Feature]: orchestration run --agent — coordinator should create agent terminals, not bare shells" Open Adjacent coordinator-side gap: orchestration run creates bare shells and pastes preambles into them. Same family of "the launched process is not what the dispatch assumed", different cause. Independent.
#12253 "[Bug]: Orchestration works with omp but stalls when worker is Codex" Open Unversioned and without a captured terminal buffer, so it cannot be confirmed as the same failure. If that stall turns out to be Codex sitting on an approval prompt under Manual mode, it is the same root cause with a different agent. Worth checking against this issue before triaging separately.

Searched issues and pull requests, open and closed, with: worker-start, agentDefaultArgs, permission mode, skip-permissions, acceptEdits, agent args, yolo mode, permission-mode worker, dangerously-skip-permissions orchestration, per-worker agent arguments, orchestration worker agent, worker abandoned dispatch, approval prompt blocks, worker-start terminal reattach, manual mode agent launcher, plus an open-issues-only sweep on worker-start, agent args, and title-matched orchestration. No duplicate found for the orchestration-worker case.

Unproven, recorded for completeness

The same session also had a coordinator-side shell tool call sit blocked for 2h31m (14:40:18Z to 17:11:11Z). It is plausibly the same class of unattended interactive approval, but that was never established. It could equally have been a hung command. Recording it as an observation, not as evidence for this request, and not as a claim that it shares a cause.

Environment

  • Reported from Orca 1.4.164, macOS.
  • All source references verified against tag v1.4.167.

Activity

  1. spengrah commented on Sep 29, 2026

    @spengrah

    Another use case for a per-dispatch --agent-args on worker-start, outside permissions.

    I run a coordinator that launches Codex and Claude workers unattended through worker-start. One Codex setting changes per dispatch: -c service_tier=priority, which I pass only for runs I am watching, because it costs more. worker-start --agent codex carries only --model and --effort, and WorkerStartParams is strict, so there is no channel for it.

    My workaround is the one this issue describes: terminal create --command "codex <my argv>", then terminal wait --for tui-idle, then worker-start --terminal <handle>. It keeps my argv, but it gives up what --agent codex adds, which I confirmed with three live launches on 1.4.216 and Codex 0.155.0:

    • Orca owns the terminal, so worker-stop and worker-release close the whole process tree, MCP children included. With --terminal the terminal is external and I close and scan it myself.
    • Orca's Codex handling applies: trust preflight, the composer-ready signal and the submit retry. With --terminal I keep my own copy of Codex TUI handling, and that copy is what breaks when the Codex TUI changes.

    The first shape in this issue covers me: --agent-args on worker-start, with the semantics PR #11873 gives automations. Unset keeps today's behavior. Set, its arguments follow the global agentDefaultArgs, so a later flag wins, and it is refused when it carries model or effort flags, as a command override is today. The receipt records the effective argv.

  2. emily-bezerra commented on Oct 15, 2026

    @emily-bezerra

    Adding a restrictive, supervised-worker use case to this existing per-dispatch permissions request rather than opening a duplicate. The requirements below include lifecycle integration with an external worktree lease, in addition to per-launch arguments.

    Supported per-dispatch execution policy and external supervisor for orchestration workers

    We need a supported way to launch a single supervised worker with a task-specific execution policy, without changing host-wide agent defaults or using private RPC calls. Is an existing supported integration point available for this?

    Observed installation: Orca 1.4.221, macOS arm64, build metadata commit e65bbc9.

    Read-only source inspection:

    • src/shared/rpc-contract/agent-launch-params.ts accepts agentArgs and cwd for agent.launch.
    • src/shared/rpc-contract/orchestration-worker-start-params.ts exposes model and effort, but no per-dispatch execution-policy or external-supervisor binding.
    • src/main/runtime/rpc/methods/orchestration/worker/worker-start-agent-placement.ts routes to structured or terminal workers using launch preferences.
    • The version-matched low-level topology guide says dispatch --inject does not acquire supervised ownership of the operator-created process.
    • Existing-terminal adoption cannot combine model/effort overrides. We cannot assume it attests the complete external launch contract.

    Required behavior:

    1. Bind a versioned, locally validated execution configuration to one Dispatch; do not change defaults for other launches.
    2. Start the authorized supervisor before the provider. Keep supervised ownership and process-lifetime coordination, including surviving children and uncertain exits.
    3. Configure role instructions and effective tool/filesystem restrictions for that invocation. We are not asking for role names alone to become security controls.
    4. Preserve native Task/Dispatch identity, launch receipts, output, settlement, fencing and recovery. Refuse an incompatible structured/terminal launch before spawning rather than silently dropping restrictions.
    5. Allow external per-worktree writer ownership to remain held until verified process exit/reconciliation, rather than only while the caller invokes worker-start.

    We want to reuse Orca Runs, Tasks, Dispatches, messages and gates; we are not proposing a second scheduler or a patch to the installed application. A documented equivalent that satisfies these requirements is preferable to adding a new API.

    Acceptance would be demonstrated in an isolated fixture: read-only worker denies writes and destructive commands, a second writer is rejected, interrupted supervisor/child processes retain an explicit blocked recovery state, and result/release receipts remain inspectable in Orca. No live worker test has been attempted for this proposed integration.

  3. zach94-fullstack commented on Oct 31, 2026

    @zach94-fullstack

    Another use case for per-dispatch agent args on worker-start: prompt-cache and context cost for Claude workers.

    A coordinator I run dispatches many short supervised Claude workers. Each one only needs the repository instructions and its spec file. Today every worker also starts with everything the operator's interactive sessions load, because agentDefaultArgs is the only argument channel and it is shared with hand-opened tabs.

    Measured with claude -p "/context" (Claude Code 2.1.310, answered locally, no model turn) in the same repository:

    Launch Startup context
    default 63.3k tokens
    --strict-mcp-config --setting-sources project,local + CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 41.7k tokens

    The difference is user MCP tools (~14k), the custom-agent listing (~4.8k), user skills (~3.9k) and auto-memory (~2-6k). A worker does not use any of these. Over one week of transcripts, roughly 34k tokens of each Claude worker's first request were cache writes unique to that worker, and every later request re-reads the whole startup context. So the overhead is paid once as a write and then again on every turn.

    The operator's own sessions do need these tools, so changing agentDefaultArgs globally is not an option. Either of these would cover it:

    An environment channel (--agent-env KEY=VALUE) would also help, since some Claude Code switches are environment variables rather than flags.

  4. Tauri-EPO commented on Nov 3, 2026

    @Tauri-EPO
    Contributor

    Another use case for this issue: read-only reviewer workers for multi-vendor review.

    Skill packs that run review panels across vendors spawn read-only subagents. In pstack, which I am adapting for Orca, the how explorers and the arena cross-judge run with readonly: true, and the judge must come from a different model family than the coordinator. worker-start already covers the family part: on 1.4.247, --model takes Claude, Codex, Cursor, Antigravity, Grok and Muse model ids.

    The read-only part is missing. worker-start --help on 1.4.247 says: "How the worker runs follows the user's own setting for new agent tabs; there is no flag for it". So a judge worker gets the same write access as my interactive tabs and can edit the candidates it grades. Claude (--permission-mode plan) and Codex (--sandbox read-only) each have a native read-only mode. Either a per-dispatch read-only flag or the per-dispatch agent args this issue asks for would cover it.

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions