feat: custom agent names and per-agent system prompts

[Solar2004]

Summary

Add --agent-name flag to launch for custom agent names, and support for per-agent system prompts via ~/.hcom/agents/<name>.md files.

Changes

• src/agent_prompts.rs — load per-agent prompts from ~/.hcom/agents/
• --agent-name flag in commands/launch.rs
• Prompt injection on bootstrap and session compaction
• Docs in bootstrap output about the agent prompt system

[aannoo]

duplicates existing functionality.

AI review:

PR #46 - --agent-name And Per-Agent Prompts

Branch: feat/agent-prompts

Approximate size: +87/-3, 6 files

Verdict

Delete the route-name feature. Do not add the prompt layer as implemented.

This PR bundles two independent ideas plus an unrelated behavior change to the live OpenCode plugin. The route-name idea violates a core hcom invariant. The prompt-file idea overlaps existing instruction layers and creates durable name-keyed state in a system whose CVCV names intentionally recycle. The OpenCode plugin change is not mentioned in the description.

What The PR Adds

• --agent-name <name> at launch.
• Per-agent prompt files under agents/<name>.md.
• Bootstrap append for those files at src/bootstrap.rs:450-454.
• A new read-and-inject step in the live OpenCode plugin (src/opencode_plugin/hcom.ts) on session compaction.

Blockers: --agent-name

1. Breaks the CVCV route-id invariant.

   instances.name is not just display text. It is the route id, mention target, relay identity, transcript binding, and pool-managed collision-avoidance token. User-supplied names bypass the CVCV pool, similarity scoring, and cross-device partitioning.

2. Allows names outside the routing grammar.

   The launcher's explicit-name guard only rejects count > 1 and "instance already exists." It does not validate the supplied string. Names containing : collide with remote-name syntax (name:DEVICE); names containing - confuse tag parsing in src/instances.rs::resolve_display_name; whitespace, control chars, leading @, or -- prefix break shell quoting and address parsing.

3. Can shadow system identity.

   SENDER in src/shared/constants.rs is the string "bigboss" and is inserted into mention resolution alongside instance names. --agent-name bigboss creates an instance whose name shadows the system sender; @bigboss no longer routes to a normal instance.

4. Remote launch still drops the name.

   src/commands/launch.rs:88 serializes "name": hcom_flags.name into the remote-launch JSON. But RemoteLaunchRequest at src/relay/control.rs:631 has no name field; from_params never reads it; handle_remote_launch constructs LaunchParams { ..., name: None, ... }. The flag is sent on the wire and the remote silently discards it.

5. Duplicates existing display ergonomics.

   --tag api with count 1 already produces a memorable display like api-luna while preserving a safe CVCV route id.

Blockers: Per-Agent Prompt Files

1. Adds a fourth instruction layer.

   hcom already has bootstrap/system text, ## NOTES from HCOM_NOTES/hcom config notes, hints from HCOM_HINTS/per-instance config, and launch prompts via --hcom-prompt/--hcom-system-prompt. Tool-native systems also exist (Claude .claude/agents/<name>.md, Codex developer instructions, Gemini system prompts, OpenCode transforms). Another bootstrap layer makes the product harder to reason about.

2. Name-keyed durable state conflicts with recycled CVCV names.

   CVCV names are allocated from a pool with reuse. hcom reset clears the DB but does not touch ~/.hcom/agents/. agents/luna.md written for one instance can affect a future unrelated luna after reset or pool reuse. An agent (or a peer instructing an agent via hcom send) can write agents/<name>.md for a name later recycled to a different role; the next luna reads the prior luna's prompt. Persistent injection surface, not a per-session UX layer.

3. Bootstrap instructions hardcode ~/.hcom.

   The Rust loader (src/agent_prompts.rs) and the OpenCode plugin read from ${HCOM_DIR}/agents/, but the bootstrap text the agent reads (src/bootstrap.rs:190) hardcodes ~/.hcom/agents/<name>.md and echo "role" > ~/.hcom/agents/<name>.md. Under non-default HCOM_DIR (e.g. per-project sandbox HCOM_DIR=$PWD/.hcom), an agent following the instruction writes to the wrong place.

4. Two readers must stay in sync.

   Rust bootstrap (src/bootstrap.rs:450-454) and the OpenCode plugin (src/opencode_plugin/hcom.ts, post-PR) both read the same prompt file shape. File-format changes require keeping the two paths aligned.

Blocker: Unrelated OpenCode plugin change

The PR also modifies src/opencode_plugin/hcom.ts to read ${HCOM_DIR}/agents/${instanceName}.md on session compaction and inject it into output.context. This is a behavior change to the live OpenCode plugin that has nothing to do with --agent-name and is not mentioned in the PR description. It should be either separated into its own commit or explicitly listed.

What To Keep

• The underlying desire for human-readable roles/personas is valid.
• hcom can document a convention such as ~/.hcom/personas/<role>.md.
• Existing launch flags can already inject a role file without new name-keyed persistence.

Required Shape

1. Delete --agent-name. Or, if kept, gate behind a strict validator (allowed character set, reject SENDER/bigboss and other reserved names, refuse :/-/whitespace/control chars), and either error on --device X --agent-name Y or forward the field through RemoteLaunchRequest.
2. Document --tag <label> as the display/grouping mechanism.
3. Enforce instances.name with a strict generated-CVCV invariant on every write path.
4. If persona files are desired, make them a documentation convention consumed by existing --hcom-prompt or notes, not a new bootstrap code path keyed by recyclable route names. Align any retained loader path with HCOM_DIR in both the loader and the bootstrap text shown to the agent.
5. Separate the OpenCode plugin change into its own commit (or its own PR) with explicit justification.

Merge Recommendation

Do not merge. Split the PR only if there is still appetite for a persona convention, but the custom route-name part should be rejected on principle.