Agent Launch Flags API: Design Options

Research and design-alternatives dossier for the 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

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.

Implementation Phases

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

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

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

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

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?