Feature: --file flag for passing file references to coding agents

[c-h-]

Summary

When launching coding agents, the supervisor (Doink/OpenClaw) currently inlines entire spec files into the -p prompt. This is:

• Token-wasteful — the supervisor spends tokens reproducing file content that already exists on disk
• Lossy — imperfect reproduction of the original file
• Fragile — prompts starting with --- (YAML frontmatter) crash Claude Code's arg parser (Bug: Prompts starting with '---' parsed as CLI options — silent launch failure #91)

Need a --file flag that reads files from disk and includes them in the prompt context.

Proposed Interface

# Single file
agentctl launch claude-code --cwd ~/personal/arc \
  --file specs/dashboard-spec.md \
  -p "Build the dashboard per the attached spec."

# Multiple files
agentctl launch claude-code --cwd ~/personal/arc \
  --file specs/dashboard-spec.md \
  --file sops/implementation.md \
  -p "Build the spec. Follow the SOP."

# --spec as sugar (already exists for OpenCode, extend to all adapters)
agentctl launch claude-code --spec path/to/SPEC.md -p "Build phase 1"

Behavior

• Resolve path relative to --cwd (or absolute)
• Read file content, prepend to prompt with delimiter: --- File: <path> ---\n<content>\n---\n
• Error if file doesn't exist
• Error if file exceeds size limit (50KB default, configurable)
• Never truncate silently — error on too-large is safer than partial content
• Multiple --file flags allowed, included in order
• Works with all adapters (claude-code, opencode, codex, pi)

Why --file not @path inline syntax

• --file is self-documenting and follows standard CLI conventions (gh --body-file)
• @path requires parsing the prompt string for references, messy with spaces/special chars
• --file separates concerns: files are structural input, -p is the instruction

Prior Art

• OpenCode adapter already has --spec (single file). This generalizes it.
• gh issue create --body-file / gh pr create --body-file
• Docker --env-file

[c-h-]

Fixed in #95 (merged 2026-03-05).

The --file flag is now available in v1.5.2:

agentctl launch claude-code --file spec.md --file sops/impl.md -p "Build the spec"

Also generalizes --spec to work with all adapters, not just OpenCode.