Cette page n’est pas encore traduite.

Conversations: how the runner relays them

This page is for developers who run agents with instruction agents run, or build their own runner. It describes how an agent's questions and permission requests reach the people who answer for it, how their answers and messages get back, and the tools and limits underneath.

A conversation belongs to one deployment. It holds the agent's lines (what it said and did), its cards (a question with choices, or a permission to use a tool), and what people wrote to it (messages and the controls interrupt and restart). People see it on Settings ▸ Deployments under Conversation, and in the Agents app.

A card from the agent to a person and back, through the runner.

Two paths

How a conversation reaches the agent depends on what the runner runs.

The agent Its cards People's messages
Claude Code given its task as claude -p "…" The runner is Claude Code's host: every permission request and every AskUserQuestion becomes a card, and the answer goes back to Claude Code. Handed to it as a new user message as soon as the runner reads them: when the server announces a change, and every 10 seconds besides. Interrupt and restart act the same way.
Any other command (Codex, agentd, a script), or Claude Code with --no-converse The agent asks itself, with deployments_asks_create, if it is built to. Otherwise its app decides as it would without instruction.md. Handed over by its hooks at its next prompt or tool use.
Claude Code with --remote-control Answered in the Claude app, not on instruction.md (Remote Control). Handed over by its hooks at its next prompt.
Shell
# Claude Code, with the runner as its host: its questions and permission requests come to people on instruction.md
instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- claude -p "Work through today's support queue."

# the plain process instead: Claude Code decides on its own; messages still reach it through its hooks
instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --no-converse -- claude -p "Work through today's support queue."

Claude Code with the runner as its host

When the command after -- is claude -p "<task>", and it sets neither --input-format nor --output-format, the runner takes the task out and runs Claude Code with streams both ways:

What the runner runs
claude -p --input-format stream-json --output-format stream-json --verbose --permission-prompt-tool stdio --permission-mode default

Your other flags stay, and the folder's --settings and --mcp-config are added (Servers, skills and accounts).

--permission-mode default is added unless the command names a mode or --dangerously-skip-permissions. The task is the first message. The folder's follow.json says "converse": true, so the hooks leave messages to the runner.

What the runner does with each thing Claude Code sends:

Claude Code sends The runner
A permission request for a tool (can_use_tool) Makes a permission card: the tool's name, its input with secrets masked, what it would do, and Claude Code's own suggested rules.
AskUserQuestion Makes a question card: up to 4 questions, each with up to 6 choices.
Text Reports a line of type said.
A tool use Reports a line of type ran: its command, file, pattern or address.
The end of a task Reports done or error.
A subagent (the Task or Agent tool) Reports it as a subagent of the agent, and marks its own lines as its.

Lines are sent within 2 seconds, 20 to a report. The runner reads what waits for its agents whenever the server announces a change, and every 10 seconds besides.

The answer Claude Code gets

The card What Claude Code is told
Permission: Allow (allow) Allowed, with its input as it was.
Permission: Allow for this run (allow_run) Allowed, and Claude Code's suggested rules are applied, so it doesn't ask again for the same kind of thing until it restarts.
Permission: Deny (deny) <name> said no through instruction.md., then Their note: <note> when there is one.
Question answered Each question's answer: a choice's label, several for a question that allows it, or the person's own words.
Nobody answered in time, a permission Nobody answered within N minutes, so this was not allowed. Go on without it, or stop and say what you need.
Nobody answered in time, a question Nobody answered within N minutes: choose the safest option yourself, and say which you chose.
Withdrawn Not allowed, or for a question: go on as it thinks best and say what it chose.

A note given with Allow, Allow for this run or a question's answer follows as a message of its own: <name> added: <note>. A denial carries its note in the denial itself. When the card couldn't be made at all (the server can't be reached), the request is denied.

When Claude Code cancels a request, or its process ends, the runner withdraws the card with deployments_asks_withdraw.

Messages, interrupt and restart

  • A message reaches Claude Code as <name> wrote to you through instruction.md: followed by the text. It goes on with everything it knew.
  • Interrupt sends Claude Code its own interrupt: it stops what it is doing and waits.
  • Restart stops the agent and starts it again from its task.

Other agents: through the hooks

An agent the runner doesn't host gets people's messages from its hooks, when its next session starts or at its next prompt or tool use. The hook reads them with deployments_messages_list take: true and adds them to the agent's context:

What the agent reads
<messages from="instruction.md">
Dana Ito wrote to you through instruction.md:
Skip the tickets tagged legal; a person handles those.
</messages>

An interrupt reaches it as a request to stop, say where it is and wait. A restart isn't acted on there: only a hosted agent restarts on request.

Such an agent, or your own runner, asks people with the tools below. The server takes a card only from whoever reports the deployment (deployments_report), or from a person who answers for the agent.

Who answers

The people who answer for an agent are whoever made its rule, whoever deployed it, the person whose runner reports it, and the organization's owners and admins. Only they may answer its cards, write to it, interrupt or restart it, and read its conversation.

Each card is notified to the first three. When none of them is a person (a runner signed in with an agent credential, say), the owners and admins are notified instead. The first answer counts: a second one is refused, naming who answered.

How long a card waits

A card waits for the rule's answerWithin, from 1 to 1,440 minutes, 30 by default. A deployment made one at a time, with no rule, waits 30 minutes. Set it over MCP:

deployments_rules_update
{
  "ruleId": "dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
  "controls": { "answerWithin": 60 }
}

Then the server closes the card as expired, with the default answer: a permission denied, a question left to the agent.

An expired card
{ "state": "expired", "answer": { "decision": "deny", "default": true } }

What is masked

Before a card or a line leaves the machine, the runner replaces what looks like a secret with •••:

  • API keys and tokens by their shape: sk-…, rk-…, pk-… (with ant-, proj-, live-, test-), GitHub (ghp_…, github_pat_…), Slack (xox…-), AWS (AKIA…), Google (AIza…), GitLab (glpat-…), npm (npm_…).
  • The value after Bearer , and after password, passwd, secret, token or api_key followed by = or :.
  • Private keys (-----BEGIN … PRIVATE KEY-----).
  • Any run of 32 or more letters and digits that mixes upper case, lower case and digits.
  • In a tool's input, any field whose name says secret, token, password, api key or authorization.

A tool's input is also cut: each string to 1,500 characters, each list and object to 40 entries, 6 levels deep, the whole to 3,500 bytes. A question card's questions and choices are cut to their limits but sent as Claude Code wrote them, without masking. Masking works on shapes, so a secret in an unusual form can pass. Never put one in a card you make yourself.

The tools

Every part of a conversation is an MCP tool on instruction.md's server. The table is generated from the registry:

ToolTitleClassA limited AI app needsRequiredWho calls it
deployments_asks_createAsk a person, for an agentreadfollowdeploymentId, kindThe runner, for its agent: whoever reports the deployment, or a person who answers for it.
deployments_asks_getRead an agent's questionreadreadaskIdThe runner, to read the answer. Closes a card past its time.
deployments_asks_withdrawWithdraw an agent's questionreadfollowaskIdThe runner, for a card its agent no longer waits on (it ended, restarted, or went on without it).
deployments_asks_listSee what agents ask youreadreadorgIdA person: the open cards of the agents they answer for, oldest first, or all of them newest first.
deployments_asks_answerAnswer an agentadminadminaskIdA person who answers for the agent. Once only: a second answer is a conflict.
deployments_messages_sendWrite to an agentadminadmindeploymentIdA person who answers for the agent: words, or interrupt or restart.
deployments_messages_listRead an agent's conversationreadreaddeploymentIdA person who answers for the agent reads the conversation. The runner, with take: true, takes what waits for its agent, each item once.

deployments_report carries the lines (activity), the subagents and the Remote Control address. It is on the runner's page and the tools reference.

Class admin means the domain checks the caller's role on each call: only the people who answer for the agent may answer, write or control. These tools don't need the org:admin scope, which applies only to the organization, billing and insights tools. A person who limited an AI app at sign-in gets the admin ones only by choosing Everything you can do, and the follow ones only with Follow changes live. Agent credentials never answer cards: only people do.

Examples

A permission card, as a runner makes it:

deployments_asks_create
{
  "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C",
  "kind": "permission",
  "tool": {
    "name": "Bash",
    "input": { "command": "git push origin fix/refund-rounding" },
    "description": "Push the fix"
  },
  "context": "The tests pass; I want to open a pull request.",
  "idempotencyKey": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C:run-41:req-7"
}

A question card:

deployments_asks_create
{
  "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C",
  "kind": "question",
  "questions": [
    {
      "question": "Which branch should the fix go to?",
      "header": "Branch",
      "multiSelect": false,
      "options": [
        { "label": "main", "description": "Released with the next deploy" },
        { "label": "release/4.2", "description": "A patch for the current release" }
      ]
    }
  ]
}

Its state, read until it isn't open (open, answered, expired or withdrawn):

deployments_asks_get (part of the answer)
{
  "ask": {
    "id": "age_01JXA2C4E6G8J0K2M4P6R8T0V2",
    "kind": "permission",
    "state": "answered",
    "answer": { "decision": "deny", "note": "Open a pull request instead." },
    "answeredBy": { "name": "Dana Ito" },
    "expiresAt": "2026-11-22T10:42:00Z"
  }
}

Withdrawing a card the agent no longer waits on:

deployments_asks_withdraw
{ "askId": "age_01JXA2C4E6G8J0K2M4P6R8T0V2", "reason": "the agent no longer waits for it" }

Answering, as a person:

deployments_asks_answer
{ "askId": "age_01JXA2C4E6G8J0K2M4P6R8T0V2", "decision": "allow_run", "note": "Fine for this run." }
deployments_asks_answer
{ "askId": "age_01JXA2C4E6G8J0K2M4P6R8T0V2", "answers": { "Which branch should the fix go to?": "release/4.2" } }

Writing to an agent, and interrupting it:

deployments_messages_send
{ "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C", "text": "Skip the tickets tagged legal; a person handles those." }
deployments_messages_send
{ "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C", "control": "interrupt" }

Taking what waits, as its runner:

deployments_messages_list
{ "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C", "take": true }

Limits

What Limit
Questions on a card 1 to 4
Choices on a question 2 to 6, each label different
A question 500 characters
A choice's label 80 characters
A tool's input 4 KB, after masking
A tool's description 500 characters
What the agent was doing (context) 1,000 characters
A note with an answer 2,000 characters
A message 4,000 characters
A line 500 characters; 20 lines a report
Waiting for an answer answerWithin, 1 to 1,440 minutes; 30 by default
A conversation Its last 500 lines, for 30 days. An open card stays whatever its age.

A retired deployment takes no new cards or messages: the server answers conflict.

The assistant

Under each card, a person can press Explain. The assistant says what the agent asks in plain words, how risky it is and why (Low risk, Some risk or High risk), quotes the instruction's lines that decide it, and suggests an answer and a note. It only suggests: nothing happens until a person presses a button. The agent's words are data to it, never orders to follow.

Kind What it gives
explain, for a card The reading above. It is kept on the card, so the next person reads the same one at no cost.
summary, for an agent (Summarize) A few sentences on what it did, what it waits on, and what went wrong.
ask, for an agent An answer to a person's own question, from the conversation and the instruction only (the Agents app).

These are not MCP tools. The editor and the Agents app call the site's POST /api/assistant/agents, for a person who answers for the agent. Each reading counts against that person's assistant allowance in the deployment's organization.

What is sent: the card, the agent's recent lines and its instruction's text, to OpenAI, with store: false. It isn't available when the workspace has the assistant turned off (the assistant is turned off for this workspace), when the allowance is used up (the assistant's allowance is used up), when the assistant has reached its daily limit (the assistant is resting for today: try again tomorrow), or for an agent that follows a sealed instruction. The rest of the conversation works the same.

Sealed conversations

An agent that follows a sealed instruction has a sealed conversation. The runner seals each line, card and error with the workspace's key on the machine, and opens answers and messages there. The server stores and relays them and can't read them; whether a card is a question or a permission stays plain, and so do interrupt and restart. See Sealed instructions for developers.

Last checked against the product:

Was this page helpful? Report a problem