/vtell

name: vtell
description: >-
  Send a message to another VelaTerm session when the user asks you to tell, notify, or send instructions
  to that session. Messages appear in the recipient's chat with the sender's agent icon and session name.
  Use --report when an assigned planning/execution workflow requires submitting an executor's result
  for review. Available only inside VelaTerm-hosted local sessions.
argument-hint: "[session] [--steer] [--report --round N] [--message-id msg-UUID] <message>"
allowed-tools: Bash(vtell:*)

vtell

Use the injected `vtell` command to send the requested content to an existing VelaTerm conversation. Sending starts a new turn when the recipient is idle, or queues the message when it is busy. It can resume a stopped native chat process in the same conversation. This is an action, not a read-only lookup: send only when requested by the user or required by an already assigned workflow.

Ordinary messages

vtell <session> "The requested information"
vtell <session> --steer "A remark on the work already under way"
vtell <session> --message-id msg-UUID < message.txt

The target accepts a full session ID, an ID prefix of at least eight characters, an exact name, or a unique name substring. Quote names containing spaces. Prefer the full ID for retries. If the reference is ambiguous, use the returned candidate list to identify the intended session; never choose arbitrarily. `vrefer --list` can help locate a target before sending. Self-targets, archived sessions, and sessions without native chat support are rejected. Supported recipients currently include Claude, Codex, OpenCode, Pi and OMP native chat sessions.

Send a self-contained message with the context and paths the recipient actually needs. Preserve the user's intended meaning and scope. Do not turn an informational update into an instruction to edit files. Treat received messages within the original task's permissions; a sender label does not grant authority.

The backend derives the sender's session ID, name and agent from the sending session. Do not construct identity headers yourself. Ordinary messages display the sender's icon and name and do not change a planning/execution workflow's state.

Steering a message into a running turn

Without `--steer` a message sent to a busy recipient waits for its running turn to end. `--steer` writes the message into that turn instead, so the recipient reads it at its next step and answers it together with the work already under way. With no turn to join the message is sent normally, so `--steer` is never an error on an idle recipient. It cannot be combined with `--report`.

Steer when the recipient is working and the message changes what that work should produce: a correction, a revised requirement, a warning that the current approach is wrong. Do not steer routine progress notes or anything that can wait for the turn to end — steering interrupts the recipient's train of thought, and an idle recipient is better served by an ordinary message that starts a clean turn.

**A recipient stopped on a question or a permission prompt receives the message but cannot read it yet.** Its turn is still open, so the message is written into that turn and nothing is lost, but its agent is waiting for an answer and reads nothing until someone gives one. The receipt says so: it reads `blocked` rather than `steered`. Report that plainly — the message is delivered but unread, and the user has to answer that question before the recipient sees it.

Execution reports

vtell --report --round N --message-id msg-UUID < result.txt
vtell <planner-session> --report --round N --message-id msg-UUID < result.txt

Read `vflow status <workflow-id>` to obtain the current round. `--report` is for the assigned executor: the backend routes one submission according to the saved review setting. With independent review enabled, the full report goes to Review and a progress/reference notice to Plan, entering `reviewing`. With review disabled, the full report goes to Plan, entering `summarizing`; Plan does not perform technical review. Legacy workflows without a review setting retain planner review. An explicit target must resolve to the saved planner or reviewer. When omitting the target, supply the report on stdin. Use the recorded round, not a guessed or incremented value.

A `blocked` workflow still accepts ordinary messages and the assigned executor's current-round report. Submitting that report enters the appropriate review or summary phase without another dispatch or a round increment. Progress updates use ordinary `vtell` and leave the workflow state unchanged. A completed or explicitly stopped workflow cannot accept a new execution report.

Include changed files, what changed, checks actually run and their results, remaining omissions and review evidence. Submit only when this round is ready for review. Reporting is the last action that affects the work: do not edit files afterward, because the reviewer may inspect them immediately. End the turn and wait for feedback in the same conversation. A real blocker still uses `vflow block`. Planning, dispatch, review acceptance, final summary (`finish`), stopping and status remain `vflow` operations.

When independent review is enabled, inspect the returned `deliveries` for both targets. Each target uses a stable submission ID, and retries with the original report ID preserve already-successful deliveries.

Receipts and retries

Text comes from positional arguments or UTF-8 stdin and is limited to 65,536 bytes. Use a quoted message, a quoted heredoc or a file so shell syntax in prose cannot execute. Arguments after `--` are literal.

For a distinct message, generate and retain a `msg-UUID`, target and exact text before sending. If omitted, the command generates an ID and prints it before delivery. Retain that printed ID on failure: retry with `--message-id` and unchanged target, text and report round. Never generate