Problem
--max-turns sounds like it limits user conversation turns, but it actually counts step-start events (agent steps including tool calls). A single user prompt can trigger 10+ steps.
Location
packages/opencode/src/cli/cmd/run.ts — --max-turns option
Current Description
"maximum number of assistant turns before aborting the session"
Suggested Fix
Either:
- Rename to
--max-steps for clarity
- Or update the description: "maximum number of agent steps (including tool calls) before aborting"
- Add documentation in CI guide explaining the relationship between turns and steps
Impact
Low — the feature works correctly, the naming is just slightly misleading for users who expect "turns" to mean "back-and-forth exchanges".
Found During
PR #350 deep analysis.