Skip to content

agents create: expose spec-backed turn/prompt knobs as first-class flags #7

@longevityboris

Description

@longevityboris

Context

Flagged by Codex audit (docs/reference/spec-audit-pre-v0.3.0.md §4). We documented these as patch-only paths in AGENTS_UPDATE_HELP but they're common enough that PATCHing for every tweak is friction.

Candidates (spec-backed, high-signal)

TurnConfig

  • --initial-wait-time <secs> → conversation_config.turn.initial_wait_time
  • --silence-end-call-timeout <secs> → conversation_config.turn.silence_end_call_timeout (−1 disables)
  • --soft-timeout-secs <secs> + --soft-timeout-message <str> → conversation_config.turn.soft_timeout_config
  • --turn-mode <silence|turn> → conversation_config.turn.mode

PromptAgentAPIModel

  • --reasoning-effort <none|minimal|low|medium|high|xhigh> → prompt.reasoning_effort
  • --max-tokens <n> → prompt.max_tokens
  • --thinking-budget <n> → prompt.thinking_budget
  • --ignore-default-personality → prompt.ignore_default_personality
  • --rag / --rag-max-chunks <n> → prompt.rag.*

AgentConfig

  • --max-duration-message <str> → agent.max_conversation_duration_message (what the agent says when hitting the hard timeout)

Use case

Every one of these was a PATCH in the user's Guidance 40 session. Turning them into flags cuts the work from "PATCH roundtrip + rebuild the body" to one line.

Files

  • src/cli.rs (AgentsAction::Create)
  • src/commands/agents/create.rs
  • src/commands/agents/mod.rs (dispatch)
  • src/help.rs (AGENTS_CREATE_HELP, AGENTS_UPDATE_HELP)
  • src/commands/agent_info.rs

Acceptance

  • Each flag writes to the spec-correct path.
  • Enum-valued flags use clap value_parser! with the spec enum.
  • AGENTS_UPDATE_HELP keeps the patch-path documentation (patching should still work).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions