Agent Launch Flags API

Status: Open — design proposal

Problem

docker/runtime/entrypoint.sh hardcodes launch commands per agent:

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

Two APIs, ordered:

1. Static API in jackin.role.toml

Expose [agents.<name>] launch_args = ["--..."] and safe_mode = bool in the role manifest. Default behavior stays identical (existing flags become defaults).

Example:

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

[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

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

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

• 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

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

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

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

Phase 4 — Move dispatch to Rust

Move launch dispatch from entrypoint.sh to jackin-capsule.

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

• docker/runtime/entrypoint.sh
• crates/jackin-core/src/agent.rs
• crates/jackin-capsule/src/runtime_setup.rs

Cross-references

• Agent runtime trait extraction — this item is blocked on the trait extraction (not yet a dedicated roadmap page)
• Docker runtime hardening contract — hardened profiles may restrict launch flags