Add a copyable CLI supervisor prompt for Agent Mode sessions

[erauner12]

Summary

RepoPrompt CE has useful copy/export flows for sending context elsewhere, but there is not yet a simple way to copy a prompt that lets an external terminal-based agent monitor an existing Agent Mode session through the RPCE CLI.

This proposal adds a small UI action in the Agent Mode session … menu that copies a minimal, self-contained "CLI supervisor" prompt. The user can paste that prompt into a fresh Codex or similar CLI-agent session so the external agent knows how to find the relevant RPCE window/session, report progress, and only when explicitly asked, gently steer the existing session via the existing RPCE CLI.

This is a third copy idiom:

• Export Context: "Here is context; do work on it."
• Session handoff: "Become or continue this session."
• CLI supervisor prompt: "Supervise this live session from the outside."

The prompt should be a remote-operator briefing, not a context migration payload.

User story

As a RepoPrompt CE user with a long-running Agent Mode session, I want to copy one prompt from the session menu, paste it into a fresh Codex or CLI-agent terminal, and have that external agent immediately know how to find my session, report its status, and — only when I ask — nudge it using the existing RPCE CLI.

Proposed behavior

Add a menu item to the Agent Mode session … menu, for example:

Copy CLI Supervisor Prompt

The copied prompt should be intentionally small at first. Instead of trying to encode every possible guardrail up front, the initial implementation should validate the smallest prompt that works in a real external-agent session, then add more text only if testing shows a concrete failure mode.

For normal/customer-facing usage, the rendered prompt should use the normal CE CLI target, expected to be rpce-cli. Development/debug usage should render rpce-cli-debug only when the running app/build/install context indicates the debug target is intended.

Initial minimal prompt shape

This is illustrative, not final copy. Dynamic values are placeholders. The CLI binary should be resolved from the selected/running target, so customer-facing CE usage does not mention the debug CLI, while development/debug testing can render the debug CLI.

<rpce_cli_supervisor>
You are supervising an existing RepoPrompt CE Agent Mode session through the RPCE CLI.
Default to read-only monitoring.

Session hints — verify before acting:
cli_binary: <resolved-cli>
window_id: <window-id>
workspace: <workspace-name>
session_id: <session-id>
session_name: <session-name>

First verify routing:
  <cli> -e 'windows'
  <cli> -w <window-id> -c agent_manage -j '{"op":"list_sessions"}'

If the session is present, report status from:
  <cli> -w <window-id> -c agent_manage -j '{"op":"get_log","session_id":"<session-id>"}'
  <cli> -w <window-id> -c agent_run -j '{"op":"wait","session_id":"<session-id>","timeout":120}'

Do not use agent_run op=start, agent_run op=cancel, agent_manage op=stop_session,
or agent_manage op=cleanup_sessions. Only steer/respond if I explicitly ask.

Begin by verifying the session exists, then give me a one-paragraph status report.
</rpce_cli_supervisor>

The closing directive is intentional: without an explicit first move, pasted prompts often produce "understood, what would you like me to do?" instead of actually checking the session.

CLI target resolution

The prompt should not hard-code the debug CLI for all users.

The composer should render the CLI target from the app/build/install context or a small explicit target choice:

• Normal/customer-facing CE target: rpce-cli
• Development/debug target: rpce-cli-debug

A normal CE prompt should look like:

cli_binary: rpce-cli

rpce-cli -e 'windows'
rpce-cli -w 1 -c agent_manage -j '{"op":"list_sessions"}'

For development/debug testing, the same template can render:

cli_binary: rpce-cli-debug

rpce-cli-debug -e 'windows'
rpce-cli-debug -w 1 -c agent_manage -j '{"op":"list_sessions"}'

The first prototype should test both cases rather than assuming the prompt text is final:

1. Normal CE instance renders and works with rpce-cli.
2. Local RPCE development/debug instance renders and works with rpce-cli-debug.

Explicit API scope

This feature should require zero changes to agent_run, agent_manage, or any MCP tool schema.

It should be only:

• a UI menu item,
• a pure prompt-composer string function,
• a clipboard write with copied-state feedback.

The copied prompt consumes the CLI exactly as it exists today. If live testing shows the current CLI output lacks information needed to disambiguate a session, that should be filed separately instead of expanding this issue.

Deliberately omitted from the copied prompt

The prompt should not inline transcript XML or file-content snapshots.

Reasons:

• It would duplicate existing handoff/export behavior.
• It would make the clipboard payload large and stale.
• The CLI already gives the external agent live ways to inspect current state, such as agent_manage op=get_log.
• Keeping the prompt to a small identity block plus static instructions makes the composer deterministic and easy to test.

Reserved refinements

These may be worth adding later, but should not be part of the initial prompt unless live testing proves they are needed:

• Worktree-specific wording, such as an optional worktree_root field
• Termination-condition wording
• Blocked-session escalation wording
• Wait-timeout semantics
• Shell-quoting guidance
• Other detailed safety rules beyond the minimal prohibition line

The initial goal is to find the smallest prompt that makes the external agent verify the session and report status correctly.

Non-goals

• No new CLI commands, MCP tools, agent_run / agent_manage operations, or runtime machinery
• No MCP schema changes
• No terminal or Codex integration beyond copying text to the clipboard
• No auto-launching external agents
• No embedded transcript or file-content snapshot
• No persistence or settings UI in the initial version, beyond whatever small target choice/resolution is needed to render the intended CLI binary
• Not an autonomous control harness

Suggested implementation shape

Keep the first version small:

• Add one menu item to the existing Agent Mode session … menu
• Add one pure prompt-composer function that accepts identity values and the resolved CLI target, then returns the prompt string
• Write the composed prompt to the clipboard and show copied-state feedback
• Add unit coverage for the composer, especially:
  • selected/resolved CLI binary rendering,
  • verification wording,
  • prohibited operations,
  • omission of transcript/file content,
  • deterministic output size.

Likely affected area:

• Agent Mode UI under Sources/RepoPrompt/Features/AgentMode

No new MCP protocol surface is expected or desired.

Acceptance criteria

• With an Agent Mode session available, the session … menu includes an action to copy a CLI supervisor prompt.
• The copied prompt contains current identity hints for the window/workspace/session when available.
• Normal/customer-facing CE usage renders the normal CLI target, expected to be rpce-cli, and does not hard-code the debug CLI.
• Development/testing usage can render rpce-cli-debug when the debug target is selected or inferred.
• The copied prompt instructs the receiving agent to verify embedded IDs before acting.
• Pasting the prompt into a fresh external CLI-agent session is enough for that agent to enumerate windows, locate the referenced session or report it missing, and summarize recent status using existing CLI commands.
• Steering/responding instructions are gated behind explicit human request.
• Destructive or disruptive operations appear only in a prohibition line.
• The prompt does not instruct agent_run op=start as part of supervising an existing session.
• The prompt does not inline transcript XML or file contents.
• The prompt remains bounded and deterministic: static body plus a small identity block.

Open questions

1. CLI target signal: What exact app/build/install signal should the composer use to choose between normal CE (rpce-cli) and development/debug (rpce-cli-debug) rendering?
2. No live session: Should the menu item be hidden/disabled when there is no active Agent Mode session, or should it copy a discovery-only prompt with window/workspace identity but no session ID?
3. User goal injection: Should v1 be fully canned, or should it allow a short optional instruction such as "watch for failing tests"?

[erauner12]

Implemented independently by @baron in #610, which was merged into main on July 23, 2026.

PR #610 adds a Handoff action to the Agent Mode chat … menu, copies the exact window/workspace/context/session routing identities, selects rpce-cli or rpce-cli-debug for the running build, and directs the receiving agent through bind_context plus agent_manage.extract_handoff.

That delivers the core one-click external-agent handoff proposed here. The merged implementation is framed as extracting and continuing the exact session rather than the original read-only supervisor/monitoring loop, but it addresses the main workflow this issue was intended to unlock.

Thanks @baron for picking this up and shipping it.