feat: add --model and --allowed-tools flags for agent passthrough

[JiraiyaETH]

Summary

Add first-class CLI flags to pass model selection and tool restrictions through to ACP agents, eliminating the need for raw claude -p calls in orchestration scripts.

Requested flags

Flag	Maps to	Example
--model <id>	_meta.claudeCode.options.model / ACP session/set_model	acpx --model sonnet claude exec -f prompt.md
--allowed-tools <list>	_meta.claudeCode.options.allowedTools	acpx --allowed-tools "Read,Grep,Glob" claude exec -f prompt.md
--max-turns <n>	_meta.claudeCode.options.maxTurns	acpx --max-turns 30 claude exec -f prompt.md

Motivation

We run an autonomous orchestration system that dispatches ~20 scripts to Claude Code. 10 scripts have been migrated to ACPX (acpx claude exec), but 21 remain on raw claude -p invocations because they require flags ACPX can't currently pass:

# Typical patterns we can't migrate today:
claude -p --model sonnet --tools "" --no-session-persistence < prompt.md
claude -p --model opus --allowedTools "Read,Glob,Grep" --permission-mode bypassPermissions < prompt.md
claude -p --model claude-sonnet-4-6 < prompt.md
claude -p --max-turns 30 < prompt.md

These are "simple dispatch" patterns — a prompt goes in, text comes out. ACPX exec mode is the right abstraction, but the scripts need to control which model runs and which tools the agent can use.

Why --session-meta isn't enough

PR #32 adds --session-meta as a generic JSON escape hatch, which is useful for advanced cases. But for the three most common agent knobs (model, tools, turn limit), requiring users to hand-write JSON like:

acpx --session-meta '{"claudeCode":{"options":{"model":"sonnet","allowedTools":["Read","Grep"]}}}' claude exec -f prompt.md

...defeats the purpose of a CLI. These are high-frequency flags that deserve first-class treatment, the same way --approve-all and --cwd already exist.

The plumbing already exists

• claude-agent-acp reads _meta.claudeCode.options and spreads into Claude Agent SDK Options (including model, allowedTools, maxTurns)
• claude-agent-acp implements session/set_model for runtime model changes
• This is a CLI surface gap, not a protocol gap

Proposed behavior

# Model selection (global flag, before agent subcommand)
acpx --model sonnet claude exec -f prompt.md
acpx --model opus claude exec "analyze this"

# Tool restrictions
acpx --allowed-tools "Read,Grep,Glob" claude exec -f prompt.md
acpx --allowed-tools "" claude exec -f prompt.md  # no tools (pure reasoning)

# Turn limit
acpx --max-turns 30 claude exec -f prompt.md

# Combined
acpx --approve-all --model sonnet --allowed-tools "Read,Grep" --max-turns 10 claude exec -f prompt.md

Flags would populate _meta.claudeCode.options in the session/new request. For agents that don't support these options, they'd be silently ignored (same as other _meta fields).

Impact

This would let us complete a full migration from claude -p to ACPX across our entire orchestration stack — unifying dispatch, session lifecycle, permission handling, and output formatting under one tool.

Related

• PR feat: add --session-meta and --claude-agent CLI options #32 (--session-meta / --claude-agent) — complementary, not competing
• Issue feat: support thought_level config option for codex-acp #11 (thought_level for codex) — same category of "agent config from CLI"

[marcocadei]

+1, it would be a great addition

[aavetis]

consider reasoning efforts too.