Turns

A turn is one message to the agent and everything it does to answer: text, tool calls, and questions back to you. A turn can stop and wait for a person, to approve a tool call or to answer a question.

Screen

Type in the composer and press enter. While a turn runs:

Key
a	Approve the waiting tool call
d	Deny it
1 to 9	Pick an offered option
tab, space, enter	Move between a question's fields, select, send
t	Stop the turn
ctrl+c	Cancel the running turn

A message sent while a turn runs is queued behind it.

Commands

Command		Flags
prompt <uri> <text>	Send a message and stream the answer	--model M --queue --steer --json
exec <text>	Create a session, run one turn, and dispose of it	--agent P --cwd DIR --trust --model M --json
queue <uri> <text>	Send it after the running turn	--model M
unqueue <uri> <id>	Take a queued message back
cancel <uri>	Stop the running turn
watch <uri>	Block until the session needs a person, print what it needs, exit	--until turn|input|idle --timeout S --json
confirm <uri> <toolCallId>	Approve a tool call	--deny --option ID
answer <uri> <requestId>	Answer a question	--field k=v --reject

prompt on a session with a running turn is refused, unless you say what to do: --queue runs it after that turn, --steer sends it into that turn.

cancel on a session with no running turn says so and exits 1.

queue prints the id of the message it queued, which is what unqueue takes. Each command that sends one action exits with the host's answer: 0 when the host applied it, or 1 with the host's own reason on stderr when it refused.

A script that drives a session without a person:

ahpc prompt "$S" "fix the failing test" &
ahpc watch "$S" --until input --json   # prints the tool call or question
ahpc confirm "$S" <toolCallId>

MCP tools

Always served.

Tool	What it does	Arguments
send_turn core	Say something to a session and block until the agent has finished answering, then return what it said. A turn that stops to ask a person something is not finished: this keeps waiting, and wait_for_attention is how to find out what it wants.	sessionstring, required textstring, required What to say. modelstring A model id from list_agents. The session's own, if omitted. timeoutSecondsnumber How long to wait. 900 by default. busyqueue | steer Where a turn is already running: queue this behind it, or steer it into that turn. A running turn is refused without this.
queue_turn core	Queue a message to be said once the running turn finishes. Returns at once, unlike send_turn.	sessionstring, required textstring, required
cancel_turn core	Interrupt whatever the agent is doing. What it had already said stays in the transcript.	sessionstring, required
wait_for_attention core, read only	Block until the session needs an answer - a tool call to approve, a question to fill in - or until it goes quiet, and say which. This is what makes a session drivable from here: without it a caller has no way to see what send_turn is waiting on.	sessionstring, required untilstring input, the default, waits for something that wants a person; idle waits for the session to go quiet. timeoutSecondsnumber 300 by default.
confirm_tool_call core	Answer a tool call the agent is blocked on. The id comes from wait_for_attention.	sessionstring, required toolCallIdstring, required approvedboolean, required True to allow it, false to refuse. optionIdstring One of the options the request offered, where it offered any.
answer_question core	Fill in a question the agent put to a person. The request id and the fields come from wait_for_attention.	sessionstring, required requestIdstring, required answersobject The answers, keyed by question id. rejectboolean Decline to answer instead.

Host support

Every AHP host runs turns.