Skip to content

cuekit-adapter-permission-bypass-design.md

Latest commit

 

History

History
104 lines (68 loc) · 4.13 KB

cuekit-adapter-permission-bypass-design.md

File metadata and controls

104 lines (68 loc) · 4.13 KB
Raw

Design: default permission bypass for claude-code and opencode adapters

Background

claude-code and opencode tasks run inside cuekit-managed tmux panes. Both runtimes can stop at permission prompts, leaving the parent orchestrator with a running task that needs manual intervention.

Both CLIs expose an explicit dangerous bypass flag for the modes cuekit uses for unattended work:

  • Claude Code: --dangerously-skip-permissions
  • OpenCode batch mode: opencode run --dangerously-skip-permissions

OpenCode's top-level TUI help does not advertise --dangerously-skip-permissions, so cuekit applies OpenCode permission bypass only when adapter_options.mode: "batch" selects opencode run.

Goal

Enable permission bypass by default for delegated claude-code and opencode panes so unattended child agents do not stall on runtime permission prompts.

Allow parent callers to opt out per task via TaskSpec.adapter_options.dangerously_skip_permissions: false.

Non-goals

  • Changing pi adapter behavior
  • Broad permission policy modeling
  • Suppressing non-permission interactive prompts

API

Default behavior requires no option:

{
  "agent_kind": "claude-code",
  "objective": "..."
}

Opt out per task:

{
  "agent_kind": "claude-code",
  "objective": "...",
  "adapter_options": {
    "dangerously_skip_permissions": false
  }
}

Only the boolean literal false disables the flag. Missing, true, strings, or other values keep the default enabled behavior.

Adapter behavior

Claude Code

Default:

claude --dangerously-skip-permissions --model 'sonnet' '<prompt>'

Opt-out:

claude --model 'sonnet' '<prompt>'

OpenCode batch mode

Default with adapter_options.mode: "batch":

opencode run --dangerously-skip-permissions --model 'provider/model' -- '<prompt>'

Opt-out:

opencode run --model 'provider/model' -- '<prompt>'

Safety

This default is intentionally optimized for delegated unattended child agents. It should be used in trusted/sandboxed worktrees because it allows the child runtime to auto-approve permissions that would otherwise require review.

Callers that want runtime permission prompts must pass adapter_options.dangerously_skip_permissions: false.

Testing

  • Claude builder includes the flag by default
  • Claude builder includes the flag for explicit true
  • Claude builder omits the flag for explicit false
  • OpenCode builder includes the flag by default
  • OpenCode builder includes the flag for explicit true
  • OpenCode builder omits the flag for explicit false

Inheriting adapters

gemini, antigravity, and codex inherit the same default-on bypass via shouldDangerouslySkipPermissions. The actual emitted flag differs by binary:

  • gemini emits -y (alias for --yolo), and also accepts adapter_options.approval_mode for granular control (default / auto_edit / yolo / plan) — see gemini adapter design.
  • antigravity (agy) emits --dangerously-skip-permissions. It has no granular approval-mode flag, but it does expose --sandbox for terminal-restricted runs. The adapter reads adapter_options.sandbox: true and emits --sandbox instead of the bypass flag (sandbox wins when both would apply, since the restrictive intent should not be silently overridden). See antigravity adapter design.
  • codex (OpenAI Codex CLI) emits --dangerously-bypass-approvals-and-sandbox. Its sandbox takes a VALUE: adapter_options.sandbox accepts one of read-only / workspace-write / danger-full-access and emits -s <mode> instead of the bypass flag (sandbox wins, same precedence as antigravity). Invalid sandbox values are silently ignored and fall back to default-on bypass. See codex adapter design.

The opt-out semantics (adapter_options.dangerously_skip_permissions: false) are uniform across all five adapters: when set, no bypass flag is emitted, and the runtime's default prompt behavior takes over. For antigravity and codex that means no bypass flag AND no sandbox flag — both knobs default off, the runtime drives.