docs(skill): known gotcha — claude subcommands in -c are rewritten by flag injection

[tarekrached]

What problem does this solve?

An agent (or human) that creates a session with -c "claude remote-control --name X" — or any claude subcommand — gets a silently different program: tool detection splits the command and re-appends the subcommand tokens after agent-deck's injected --session-id/permission flags, so the pane runs plain interactive claude with remote-control as a positional arg. No server starts, and nothing tells you why. Filed with a sandboxed reproduction as #1800; this PR adds the corresponding Known Gotchas entry so skill-driven agents route around it today, on every released version, independent of when/how the code fix lands.

Why this change

Docs-only, one new entry in the Known Gotchas section of skills/agent-deck/SKILL.md, in the same symptom → workaround → issue format as the existing entries (#957, #966, etc.): what the rewrite looks like, the bash -c 'exec …' workaround, its trade-off (opaque to session-id tracking — fine for server-style subcommands with no conversation to resume), and the explicit note that extra flags (-c "claude --model opus") are unaffected so nobody over-applies the workaround.

User impact

Agents loading the skill warn/work around instead of shipping a session that silently runs the wrong program. No behavior change; no code touched.

Evidence

Reproduced in a fully sandboxed environment (fresh HOME, own TMUX_TMPDIR, argv-logging claude shim) on v1.10.10 — full transcript in #1800. Key capture:

# session created with: -c "claude remote-control --name rc-test"
ARGV: --session-id 80c0ebf9-… --dangerously-skip-permissions remote-control --name rc-test

# workaround: -c "bash -c 'exec claude remote-control --name rc-test'"
ARGV: remote-control --name rc-test

Mechanism verified on current main (cmd/agent-deck/cli_utils.go resolveSessionCommand wrapper-suffix path + internal/session/instance.go flag injection) — details in #1800.

Docs-only diff — no test changes; revert-check not applicable.

AI disclosure

• AI-authored (a model wrote most of it)

Model(s), if AI helped: claude-fable-5

Prompt / session log (optional): —

What actually bothered you

My human asked: "I'm surprised how much is being rediscovered every time agent-deck gets invoked by an agent." This gotcha was the sharpest case: an agent burned a debugging cycle discovering the rewrite and inventing the bash -c workaround, and that knowledge lived nowhere but one transcript until #1800.

Checklist

• Targeted diff: one problem, no unrelated changes
• Tests added or updated for new behavior — docs-only change, no behavior to test
• Test suite passes sandboxed: HOME=$(mktemp -d) XDG_CONFIG_HOME= XDG_DATA_HOME= XDG_CACHE_HOME= go test ./... — not run: docs-only diff, no Go changes (self-check: go-checks skipped)
• If this touches a hot path (list, status, session output, startup, tmux layer): before/after timing evidence included
• CHANGELOG.md untouched (entries are added at landing)
• AI-assisted? Disclosed above, with validation evidence, and I can answer questions about the code
• "Allow edits from maintainers" is enabled

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• skills/agent-deck/SKILL.md is excluded by !**/*.md

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d862224-6c3c-433a-8d7f-92409725966d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

👋 Thanks for the contribution — intake looks complete.

Your PR body carries everything the maintainer's validation pipeline reads first: the problem, the reasoning, the human intent behind it, and an AI-disclosure. It will be applied, built, and tested against main, and you'll get a structured result within about a day. Merges are always human.

_{gate marker read: ai=authored model=claude-fable-5 intent=yes}