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.

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.