# Agent Launch Flags API: Design Options (https://jackin.tailrocks.com/research/agents/runtimes/agent-launch-flags-api-design/)



## Summary [#summary]

Launch behavior should converge on typed `AgentRuntime` options, with versioned static role controls and a bounded dynamic adapter rather than provider flags leaking into callers.

## Research question [#research-question]

<RepoFile path="docker/runtime/entrypoint.sh">docker/runtime/entrypoint.sh</RepoFile> hardcodes final launch argv per agent in a shell `case` statement keyed on `$JACKIN_AGENT` (Claude gets `--dangerously-skip-permissions --verbose`, Codex gets `--enable goals --dangerously-bypass-approvals-and-sandbox`, Amp gets `--dangerously-allow-all`, Kimi gets `--yolo`, OpenCode sets `OPENCODE_CONFIG_CONTENT='{"permission":"allow"}'`, Grok gets `--always-approve`). A security-conscious role author who wants to run Claude without `--dangerously-skip-permissions` (for audit replay, for example) cannot express that in `jackin.role.toml`. The role manifest has per-agent model and provider config, but no launch-argument override or safe-mode field. Launch flags remain a shell policy decision, not a jackin❯ manifest policy decision.

By default jackin❯ always passes the dangerous-mode flags (this is the whole point — autonomous agents). But role authors need the ability to override or extend these args.

## Proposal [#proposal]

Two APIs, ordered:

### 1. Static API in jackin.role.toml [#1-static-api-in-jackinroletoml]

Expose launch-argument controls in the versioned role manifest. The current manifest uses top-level `agents = [...]` plus per-agent tables such as `[claude]`, `[codex]`, `[kimi]`, `[opencode]`, and `[grok]`; the final schema should fit that existing shape unless a schema bump deliberately moves to an agent map. Default behavior stays identical: existing high-autonomy args remain defaults.

Example:

```toml
[claude]
launch_args = ["--dangerously-skip-permissions", "--verbose"]
```

```toml
[claude]
safe_mode = true
```

When `safe_mode = true`, the dangerous-mode flags are omitted for that agent. When `launch_args` is set, it overrides the defaults entirely for that agent. Exact names remain open; the shipped schema does not yet include either field.

### 2. Runtime API via construct image binary [#2-runtime-api-via-construct-image-binary]

Provide a command inside the construct image, likely in `jackin-capsule`, that role hooks can call before agent exec to dynamically adjust agent launch arguments. This allows a role to evaluate runtime conditions and modify flags without editing the image entrypoint.

Example: a role might call the binary to add `--model` overrides or remove `--dangerously-skip-permissions` based on workspace conditions.

### 3. Move launch dispatch to Rust [#3-move-launch-dispatch-to-rust]

Move final launch argv construction out of bash into a Rust surface. Bash remains only the hook-compatible wrapper that can source `source.sh` before `exec`. The `AgentRuntime` trait already exists (<RepoFile path="crates/jackin-core/src/agent/runtime.rs">crates/jackin-core/src/agent/runtime.rs</RepoFile>), so this item can add a launch-argv method to that adapter surface instead of first waiting for trait extraction.

## Non-goals [#non-goals]

* Do not remove the default dangerous-mode behavior. Autonomous agents are the core value proposition.
* Do not allow operators to add arbitrary flags the agent runtime doesn't understand.
* Do not bypass the `AgentRuntime` adapter surface with a second launch-dispatch table.

## Delivery ownership [#delivery-ownership]

Implementation sequencing and current status belong to the [Agent launch flags API roadmap item](/roadmap/agent-launch-flags-api/). This dossier retains the static manifest, runtime API, and Rust dispatch alternatives that constrain that work.

## Limitations and open questions [#limitations-and-open-questions]

1. What is the exact shape of the runtime API binary? What arguments does it accept?
2. Should safe mode be a per-agent field only, or should there also be a role-wide default?
3. How does the runtime API interact with the static manifest settings? (Override? Merge? Prepend/append?)
4. Should static launch args be unrestricted strings, a typed enum of known flags, or a small policy object per agent?