Asking a human
How an agent writes a block that a person can act on, and how the person's choice runs.
An agent sometimes needs a person. A person reads the request in Needs you. That person has not seen the task. The request must explain itself.
What a request holds
A block meant for a person carries a human ask. It has three parts.
- What happened. Say what happened in plain words. Name the task, the repo and the people. Do not write a raw id.
- What you need. Say the one thing you need from a person.
- Options. Give 1 to 4 options. Each option has a label, an action and a consequence.
The server refuses an ask with a missing part. It refuses a raw id in the first two parts. It also refuses a part that is too long.
| Part | Limit |
|---|---|
| What happened | 1,000 characters |
| What you need | 300 characters |
| An option label | 80 characters |
| An option consequence | 500 characters |
| External steps | 1,000 characters |
What an option does
The action is a fixed word. The server runs it. The consequence is your sentence. It tells the person what happens after the click.
| Action | What the server does |
|---|---|
cancel |
The task is cancelled. |
resume |
The task returns to the stage it was blocked from, and an agent starts again. |
move_to:<stage> |
The task moves to that stage of its workflow. |
answer |
The person types a reply. The server posts it as a comment, then resumes the task. |
external |
The person does the work outside CodeHerder. The option holds the steps. The button reads “Done, resume”. |
Write the consequence for the action. Do not promise more than the action does.
How to file an ask
Write the ask to a file. Do not put it in a quoted argument.
{
"happened": "The push of task 'Fix the login bug' to the core repo failed with a 403. The agent's key has no write access.",
"ask": "Grant the agent write access to the core repo, or cancel the task.",
"options": [
{
"label": "I granted access",
"action": "external",
"consequence": "The agent starts again and pushes the branch.",
"steps": "Open the core repo settings. Give the agent's key write access."
},
{
"label": "Cancel the task",
"action": "cancel",
"consequence": "The task is cancelled. No change reaches the repo."
}
]
}
Pass the file with --ask-file.
ch task block --reason-file reason.md --ask-file ask.json
ch session refuse --reason-file reason.md --ask-file ask.json
ch agent ask files a question. Fill brief for what happened. Fill consequence on every option. A question without them is refused.
A bad ask and a good ask
A bad ask says “Blocked: gate loop budget exhausted (5/5). Please advise.” The person does not know which task, which gate or which choice to make.
A good ask names the task and the gate. It says why the agent stopped. It offers a choice, and each choice says what happens next.
What a person sees
The card shows what happened, what you need and one button per option. The consequence sits under each button. It also shows your comments on the task since you filed the ask. Post a comment for context. Do not repeat it in the ask.
A block with no ask is a note. It stays on the Blockers page and the task page. It never appears in Needs you. A note with no ask that stays open for more than 7 days is flagged as stale on the Blockers page.
Last updated