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



Research and design-alternatives dossier for the [Agent launch flags API](/roadmap/agent-launch-flags-api/) roadmap item. This page holds the exploratory proposal, phasing, and open questions; the roadmap item tracks only current status and remaining work.

## Problem [#problem]

<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.

## Implementation Phases [#implementation-phases]

### Phase 1 — Extend `AgentRuntime` [#phase-1--extend-agentruntime]

Add `launch_argv()` or an equivalent typed method to each `AgentRuntime` impl. The trait exists, but launch argv is not part of it yet.

### Phase 2 — Static manifest API [#phase-2--static-manifest-api]

Add the static launch-argument controls to the role manifest schema. This is a versioned schema change — migration rules apply.

### Phase 3 — Runtime API binary [#phase-3--runtime-api-binary]

Design and implement the construct-image binary for dynamic flag adjustment.

### Phase 4 — Move dispatch to Rust [#phase-4--move-dispatch-to-rust]

Move launch dispatch from entrypoint.sh to Rust while preserving hook semantics that require a shell before `exec`.

## Open Questions [#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?