[agent]
Agent: Claude Code (claude-sonnet-4-6) — caro-qa-agent
Problem
caro ai --help contains three contradictory signals that confuse users about what the command actually does:
- Subcommand description says "Generate an interactive AI command via conversational session (Atuin-AI-style)" — implying a TTY REPL.
--once flag says "The only mode supported today" — implying the REPL doesn't work.--continue-session flag is documented as a distinct opt-in ("Resume a recent session if available") but the flag is silently discarded in dispatch (continue_session: _ in src/main.rs), making it a no-op.
A new user reading the help output cannot tell whether caro ai "my prompt" will start an interactive session, resume a prior session, or run a single turn. In practice it always runs a single turn with SessionMode::ResumeOrNew (which is correct behavior), but the documentation path to that understanding is broken.
Reproduction
caro ai --help
# Read the description: "interactive AI command via conversational session"
# Read --once: "The only mode supported today"
# Read --continue-session: "Resume a recent session if available (default behavior)"
# ← contradictory: if --once is the only mode, why does --continue-session exist?
# Observe: both of the following are identical in effect
caro ai --once "list files"
caro ai --continue-session "list files"
Expected vs Actual
Expected: The help text accurately describes the current behaviour:
- Single-turn mode is the only interactive mode (no TTY REPL).
- Session data (conversation history) is persisted and resumed across invocations by default.
--new-session forces a fresh session; --continue-session is the default and can be omitted.- The
--once flag is a scripting affordance that is currently always implied.
Actual: The help implies a REPL that does not exist, labels --once as "the only mode" (confusing since session-resume is real), and silently accepts --continue-session without acting on it.
Environment
- caro version:
caro 1.5.0 (be07b22 2026-07-18)
- OS: Linux 6.18.44-fc-v24 x86_64 (remote sandbox)
- Test date: 2026-09-05
- Backend: n/a (documentation-only finding)
Investigation
Code path in src/main.rs (dispatch block):
Some(Commands::Ai {
new_session,
continue_session: _, // ← silently discarded
once: _, // ← silently discarded
ref prompt,
}) => {
let new = new_session;
match run_ai_once(&cli, new, ai_trailing).await { ... }
}Module-level comment in src/ai/runner.rs line 4:
//! The interactive REPL is out of scope for the MVP. `run_once` is the primitive
//! both scripted callers (`caro ai --once "prompt"`) and the future REPL will
The REPL is correctly deferred; the documentation just hasn't caught up.
Suggested fix (documentation-only, no behaviour change):
- Update the subcommand long description to say: "Run one AI turn with optional session history. The TTY REPL mode is planned but not yet available — use
--once explicitly for shell-hook compatibility."
- Drop
--continue-session from the public API surface or document it as a no-op synonym for the default.
- Change
--once description from "The only mode supported today" to "Run one turn and return (default behaviour; flag exists for explicit shell-hook use)."
Severity
P2 — feature works but not as documented; --once/--continue-session flags accepted silently without matching behaviour; subcommand description advertises a REPL that does not exist. release-gap: shipped in v1.5.0 with contradictory help text.
Prompt used to generate this comment
caro QA agent — daily rotation slot C (caro ai --once surface), scheduled remote run 2026-09-05
"
[agent]Agent: Claude Code (
claude-sonnet-4-6) — caro-qa-agentProblem
caro ai --helpcontains three contradictory signals that confuse users about what the command actually does:--onceflag says "The only mode supported today" — implying the REPL doesn't work.--continue-sessionflag is documented as a distinct opt-in ("Resume a recent session if available") but the flag is silently discarded in dispatch (continue_session: _insrc/main.rs), making it a no-op.A new user reading the help output cannot tell whether
caro ai "my prompt"will start an interactive session, resume a prior session, or run a single turn. In practice it always runs a single turn withSessionMode::ResumeOrNew(which is correct behavior), but the documentation path to that understanding is broken.Reproduction
Expected vs Actual
Expected: The help text accurately describes the current behaviour:
--new-sessionforces a fresh session;--continue-sessionis the default and can be omitted.--onceflag is a scripting affordance that is currently always implied.Actual: The help implies a REPL that does not exist, labels
--onceas "the only mode" (confusing since session-resume is real), and silently accepts--continue-sessionwithout acting on it.Environment
caro 1.5.0 (be07b22 2026-07-18)Investigation
Code path in
src/main.rs(dispatch block):Module-level comment in
src/ai/runner.rsline 4:The REPL is correctly deferred; the documentation just hasn't caught up.
Suggested fix (documentation-only, no behaviour change):
--onceexplicitly for shell-hook compatibility."--continue-sessionfrom the public API surface or document it as a no-op synonym for the default.--oncedescription from "The only mode supported today" to "Run one turn and return (default behaviour; flag exists for explicit shell-hook use)."Severity
P2 — feature works but not as documented;
--once/--continue-sessionflags accepted silently without matching behaviour; subcommand description advertises a REPL that does not exist.release-gap: shipped in v1.5.0 with contradictory help text.Prompt used to generate this comment