# Agent Launch Flags API (https://jackin.tailrocks.com/reference/roadmap/agent-launch-flags-api/)



**Status**: Open — design proposal

## Problem [#problem]

<RepoFile path="docker/runtime/entrypoint.sh">docker/runtime/entrypoint.sh</RepoFile> hardcodes launch commands per agent:

```bash
case "${JACKIN_AGENT:?}" in
  claude)   LAUNCH=(claude --settings '{"skipDangerousModePermissionPrompt":true}' --dangerously-skip-permissions --verbose) ;;
  codex)    LAUNCH=(codex --enable goals --dangerously-bypass-approvals-and-sandbox) ;;
  amp)      LAUNCH=(amp --dangerously-allow-all) ;;
  ...
```

A security-conscious role author who wants to run Claude without `--dangerously-skip-permissions` (e.g. for audit replay) cannot. The role manifest has no `agent.launch_args` field. The launch flags are a bash policy decision, not a jackin' 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 `[agents.<name>] launch_args = ["--..."]` and `safe_mode = bool` in the role manifest. Default behavior stays identical (existing flags become defaults).

Example:

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

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

When `safe_mode = true`, the dangerous-mode flags are omitted. When `launch_args` is set, it overrides the defaults entirely.

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

Provide a binary inside the construct image (part of the jackin-capsule tooling) that agent roles can call during execution to dynamically adjust agent launch arguments. This allows a role to evaluate conditions at runtime and modify flags.

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 the launch dispatch out of bash into `jackin-capsule runtime-setup` (which already runs). Bash becomes a thin wrapper, not the policy layer. The `AgentRuntime` trait now exists, so this item can add a launch-argv method to that adapter surface instead of first waiting for the 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]

The agent runtime trait has landed. Add `launch_argv()` or an equivalent typed method to each `AgentRuntime` impl, then route launch dispatch through that method.

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

Add `launch_args` and `safe_mode` to the agent 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 jackin-capsule.

## 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 global flag or per-agent?
3. How does the runtime API interact with the static manifest settings? (Override? Merge? Prepend/append?)

## Related Files [#related-files]

* <RepoFile path="docker/runtime/entrypoint.sh">
    docker/runtime/entrypoint.sh
  </RepoFile>
* <RepoFile path="crates/jackin-core/src/agent.rs">
    crates/jackin-core/src/agent.rs
  </RepoFile>
* <RepoFile path="crates/jackin-capsule/src/runtime_setup.rs">
    crates/jackin-capsule/src/runtime_setup.rs
  </RepoFile>

## Cross-references [#cross-references]

* Agent runtime trait extraction — this item is blocked on the trait extraction (not yet a dedicated roadmap page)
* [Docker runtime hardening contract](/reference/roadmap/docker-runtime-hardening-contract/) — hardened profiles may restrict launch flags