#19200: fix(cli): validate --session-id is not a session key format
commands
size: S
When users pass a session key format (`agent:...`) to `--session-id`, show a helpful error message directing them to use `--session-key` instead.
## Problem
Users sometimes confuse `--session-id` (for UUIDs) with `--session-key` (for `agent:...` format keys), leading to unexpected behavior where the agent workspace is not resolved correctly.
## Solution
Add validation that detects when a session key format is passed to `--session-id` and throws a clear error:
```
It looks like you passed a session key to --session-id. Please use --session-key instead.
```
This teaches users the correct parameter usage rather than silently accepting both formats.
Closes #13635
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds input validation to the `agentCommand` function in `src/commands/agent.ts` that detects when a session key format (`agent:...`) is mistakenly passed to `--session-id` and throws a descriptive error directing users to use `--session-key` instead.
- The validation check at line 194 uses `.trim().toLowerCase().startsWith("agent:")`, which is consistent with session key detection patterns used elsewhere in the codebase (`src/routing/session-key.ts`, `src/infra/state-migrations.ts`, `src/gateway/session-utils.ts`).
- Placement is correct: after the message-required check but before the session resolution logic that would silently accept the malformed input.
- No tests were added for this validation. While the logic is simple, a unit test covering the error case would strengthen confidence.
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge — it adds a straightforward input validation guard with no side effects on existing behavior.
- The change is minimal (6 lines), isolated to an early validation check, and follows established codebase patterns for detecting session key formats. It only affects the error path for a specific misuse pattern and cannot regress normal operation. Deducting one point for the absence of a test covering the new error condition.
- No files require special attention.
<sub>Last reviewed commit: 78345e8</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#8774: Fix/frontend session key normalization
by zhaodageng · 2026-02-04
81.5%
#21662: fix(gateway): validate session key ownership against agent scope
by AI-Reviewer-QS · 2026-02-20
78.9%
#22098: fix: isolate agent sessions by explicit --session-id
by AIflow-Labs · 2026-02-20
77.5%
#19177: fix: use parseAgentSessionKey instead of fragile split pattern
by El-Patronum · 2026-02-17
76.4%
#16061: fix(sessions): tolerate invalid sessionFile metadata
by haoyifan · 2026-02-14
75.9%
#15744: fix: allow cross-agent session path validation
by scottgl9 · 2026-02-13
75.8%
#20072: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions
by Be1Human · 2026-02-18
75.0%
#15888: fix: store relative session file paths instead of absolute
by devAnon89 · 2026-02-14
74.1%
#15176: fix(sessions): allow channel-routed session IDs and cross-agent paths
by cathrynlavery · 2026-02-13
74.0%
#17132: fix: filter out invalid session entries with empty sessionFile
by Limitless2023 · 2026-02-15
73.9%