Agent Launch Flags API: Design Options

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

docker/runtime/entrypoint.sh 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

Two APIs, ordered:

1. Static API in jackin.role.toml

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:

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

[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

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

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 (crates/jackin-core/src/agent/runtime.rs), so this item can add a launch-argv method to that adapter surface instead of first waiting for trait extraction.

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

Implementation sequencing and current status belong to the Agent launch flags API roadmap item. This dossier retains the static manifest, runtime API, and Rust dispatch alternatives that constrain that work.

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?