When an agent needs your input
How an agent asks for your input, and where you can see and answer its questions and notes.
When a running agent reaches a decision point it cannot resolve on its own, it reaches out to a human. CodeHerder surfaces these requests as soon as they arrive, wherever you happen to be working, and keeps every surface updated in real time.
Agents can reach out in two ways:
- A question that needs an answer — a structured set of choices the agent presents, raised with
ch agent ask. You pick from the options provided and click Submit. No terminal required. Every question pauses the task until you answer. - A heads-up note (input needed) — a short notice that a session needs attention, such as a permission prompt. CodeHerder records it from the harness. The agent keeps working; you simply Acknowledge the note. There is nothing to type in response. An agent that wants to inform you posts a task comment instead.
Both kinds show up in more than one place, and answering from any of them does exactly the same thing.
Where you’ll see these
An open question or note follows you around the web app rather than waiting on one specific page. Wherever you land, if something needs you, it’s there:
| Where | Section you’ll see | What it shows |
|---|---|---|
| Dashboard | Needs attention — “Agents waiting on your response.” | Every open question and note you can see, across the workspace. The section appears only when something is open. |
| A session’s page | Needs your answer — “This session is waiting on you.” | Every open question or note that session is waiting on |
| An agent’s page | Needs attention | Only that agent’s open items. An agent with none shows “No open questions yet.” |
| My work | Needs you — decisions on your own work | Questions on tasks you filed or watch, across your workspaces, with the other decisions waiting on you. See My work for which items appear. |
| A task’s page | Questions and answers | That task’s questions and notes, open and resolved. See The task’s record below. |
The card works the same everywhere: the same options, the same free-text box, the same Submit or Acknowledge button, the same result. Use whichever page you are already on. The task title appears on the card only where the task is not already the context, so you do not see it on the task’s page or the session’s page.
How you are alerted
Dashboard sidebar badge — the Dashboard link in the sidebar shows a pulsing red count badge when something needs you. The count adds open questions, open notes and pending network access approvals. See Network access approvals.
The Needs attention tile — the Dashboard’s summary tiles include a Needs attention tile. It counts open questions and notes only, so it can differ from the sidebar badge. The tile turns red when the count is above zero. Click it to jump to the section below.
The Needs attention section — appears on the Dashboard when at least one item is open. The tile and the section are for human members only.
Answering a question
A question is a structured prompt with a defined set of options. The agent poses one or more questions, each with a multiple-choice set of answers, and waits for you to respond.
Each answer card shows:
- Agent and task — the agent’s name at the top of the card, with the task it is working on where the task is not already the context.
- One or more questions — each question may include a short header label as a context chip. Options appear as radio buttons for single-select questions (pick exactly one) or checkboxes for multi-select questions (pick all that apply). Each option has a label and may include a short description.
- Extra context from the agent — an agent can add a plain-language brief to a question. It can add a consequence to each option, which says what happens if you pick it. It can also mark one option as recommended. These appear where you answer from Needs you in My work. The brief shows above the options. A Recommended badge marks the suggested option. “If you pick this:” and the consequence show under each option. The other cards show each option’s label and description only. There, a recommended option has “(Recommended)” at the end of its label.
ch task questionsprints the brief and consequences too, as described below. - Other answer — a free-text field below each question’s options. Use it when none of the preset options fit.
- Submit — disabled until every question has at least one option selected or some text typed in. Hover over the disabled button and it says “Answer every question first.” On a multi-question card, Next says “Answer this question first.” in the same way.
A card with a single question shows just that question and a Submit button. A card with several questions is a short step-by-step form instead: it shows Question 1 of N, one question per screen, with Next to move on and Back to return. After the last question, you land on a review screen — “Review your answers, then submit.” — showing every answer with an Edit link back to that question, and a final Submit button.
Click Submit to send your answers. If you leave the page half way through, CodeHerder keeps your selections and text, and they are there when you return. See Unsaved changes and drafts. On the Dashboard, and on a session’s or agent’s page, the card disappears once the submission is recorded. On a task’s page the row stays put instead — it flips from Open to Answered and keeps the answer, since that section is a record rather than a to-do list (more in The task’s record below).
If somebody else answers first, you see a notice, “Someone already answered this question.”, instead of an error. For a note, the notice says “Someone already acknowledged this.”
Who sees which questions
On the Dashboard and a session’s page, only human members see open items. Workspace admins and owners see every open item. Other members see items from agents they operate. An agent’s page shows that agent’s open items to its operator or a workspace admin or owner. A task’s page works differently. See The task’s record below.
What happens after you answer
What happens depends on how the agent asked.
- A question always parks the task, and the agent’s session ends while it waits. The task’s blocker shows the first line of the question as its reason. See Blockers and blocked tasks. Your answer clears the blocker. CodeHerder then starts a fresh session on the same stage, with your answer in its brief, and the work continues from where it stopped. Nothing else clears the blocker.
ch task unblockand the web app’s Resolve button refuse it, and so does moving the task out ofblocked. An empty answer doesn’t count. Cancelling the task is the one exception: it closes the question.
If the task has already finished when you answer, CodeHerder saves your answer but does not deliver it.
The task’s record
Every task that has had a question or a heads-up note keeps a Questions and answers section on its own page. It records the whole exchange, not just what is open.
- Each row is badged Open, Answered, or Closed.
- An answered row shows the answer, “Answered by” the person’s name, and the time.
- A closed row has no submitted answer. Either someone acknowledged a note, or the item stopped being relevant. The row shows one line instead of an answer: Acknowledged, Closed — session ended (notes only), Closed — task completed (also used when the task is cancelled or archived), Closed — blocker resolved (the question’s blocker was cleared before anyone answered), or a plain Closed.
- An open row is answerable (or, for a heads-up note, acknowledgeable) right there, with the same form described above.
- The Dashboard, session and agent surfaces show only open items. A task’s page is the one place that also keeps resolved items visible.
- CodeHerder keeps an answered or closed row for 365 days by default, and an open row stays until it is resolved. Self-hosted owners can change this. See Self-hosted retention and data subject requests.
Any human member of the question’s workspace can answer an agent’s question. This includes a role the member inherits from a parent group. You do not need to operate the agent. Agents, session credentials, and people outside the workspace cannot answer.
One kind of question keeps a stronger rule: an approval for an integration write, such as a Jira comment. Only the agent’s operator (the human who created it) or a workspace admin or owner can answer it.
The server tells the app whether you can answer each question. When you cannot, the app disables Submit and says why. If your access changes while you work, a refused answer refreshes the question and shows “You can no longer answer this question.”
Reading and answering from the terminal
You can read the exchange from a terminal:
ch task questions <taskId>
ch task questions <taskId> --active
ch task show <taskId> prints a QUESTIONS & ANSWERS section with the first page of rows. ch task questions prints the full list, oldest first. Each row shows the time, the agent, its state, the row ID, the full text, any options, and the answer. When the agent added a brief, a Brief: line follows the question. A → and the consequence follow an option that has one. The state is one of:
OPEN — awaiting answeranswered by <name>resolved (<reason>)— CodeHerder closed the row. A closed row never shows as answered.
Flags:
--activeshows open rows only.--allshows every row, which is the default.--limit Nsets the page size. The default is 200 and the maximum is 500.--cursor <token>fetches the next page. The command prints the token when more rows remain.--jsonprints the response as JSON.
Seeing earlier decisions
To see what people already decided, run:
ch task decisions <taskId>
The command lists earlier human decisions on the task and on its ancestors, newest first. A decision is an answered question or an approved or rejected stage advance. Each row says whether you made it on (this task) or on an ancestor, such as (ancestor 1). An agent’s answer, a withdrawn request, a heads-up note and a question closed with its task do not appear.
Flags:
--limit Nsets the page size.--cursor <token>fetches the next page.
If you leave out <taskId>, the command uses the task in the CH_TASK_ID environment variable.
Answering from the terminal
ch task show shows the task’s outstanding question and prints the command to answer it. It uses the same answer route as the web app, so the same permission rule applies: you must be a human member of the question’s workspace. For an integration write approval, you must be the agent’s operator, or a workspace admin or owner.
To answer at the prompt, run:
ch task questions answer <taskId>
The command prints each question with its numbered options and asks for one line per question. Type the option’s label to select it. Typing the number does not select it. CodeHerder records “1” as free text. Any text that is not an exact option label is saved as free text. This needs an interactive terminal. It does not combine with --json.
To answer without a terminal, give the answer in a file, or on standard input with -:
ch task questions answer <taskId> --from-file answer.txt
echo "Use the second approach." | ch task questions answer <taskId> --from-file -
For a one-question ask, plain text is the answer. If the text matches an option label, that option is selected. When the agent asked several questions, the file must be JSON with one entry per question, in order:
{"answers": [
{"header": "", "question": "Which database?", "selected": ["Postgres"], "text": ""},
{"header": "", "question": "Anything else?", "selected": [], "text": "Keep the old column for now."}
]}
CodeHerder matches each entry to a question by its position, so keep the entries in the same order as the questions. Put the chosen option labels in selected, and free text in text. You can leave header and question empty.
If the task has more than one open question, add --question <id> to pick one. Without it, the command fails and lists the ids. If nothing is open, it prints “no outstanding question to answer”.
On success the command prints “answer recorded”, or “answer recorded — the task is back in queue” after a question. See What happens after you answer. The command does not answer heads-up notes. It skips them.
A question closes only when you answer it. ch task blockers resolve refuses a question’s blocker, and the refusal points back to the answer command. Cancelling the task also closes its open questions. See Blockers and blocked tasks.
Heads-up notes (input needed)
Sometimes a harness session needs attention, such as a permission prompt or an idle stall. CodeHerder surfaces these as input-need cards in the same places as questions, including a task’s page when the note is tied to one.
An input-need card shows the agent’s name, the task it’s working on (if any), and the note itself, with an Acknowledge button. It also has a Drop in button, which opens the live session, or a View task link.
The agent is not blocked. Unlike a question, the agent keeps working while the note sits waiting for you — there’s no response for it to wait on.
Acknowledge clears the note. Clicking it removes the card from the Dashboard, the session’s page and the agent’s page. On the task’s page the row stays, marked Closed with the line Acknowledged. Acknowledging does not send anything back to the agent — there’s nothing to send, since the agent was never waiting on a reply.
An agent keeps at most one open note at a time. If it files a new one before the last is acknowledged, the new note replaces it in place — you’ll see the latest note, not a growing pile.
Notes also close automatically when the agent’s session ends or the task finishes, so you rarely need to clean up stale ones.
How an agent asks a question — ch agent ask
An agent raises a question with ch agent ask, run from its own session. It is not something you run yourself. Heads-up notes do not come from this command. The harness records them.
A question
The agent authors a question — the prompt, its options, and whether you can pick one answer or several — in a small file or piped in on standard input, then posts it with:
ch agent ask --from-file question.json
cat question.json | ch agent ask
Posting a question this way pauses the agent’s task until you answer. When the question belongs to an unfinished task, the task moves to blocked. See What happens after you answer.
An agent can add a brief, a consequence for each option, and a recommended option, so you can decide without opening the task. See Answering a question.
To inform you without waiting, an agent posts a task comment instead (ch task comment). To decide, an agent asks. Every question blocks, and ch agent ask has no option to skip that.
Talking to a running agent directly
The two mechanisms above cover an agent reaching out to you. If instead you want to check in on a running agent yourself, you have two options:
- Live terminal — open the agent’s live session and interact with it directly in the terminal. See Following a live agent session for how to open a session and send input.
- @-mention (async) — type
@and pick the agent in a task comment. CodeHerder notifies it through the same channel as a direct message and prompts it to read the comment and respond. It’s a lighter-weight way to redirect a running agent than opening its live terminal. See Mentioning people and agents for how mentions work and what does and doesn’t trigger one.
For an overview of the Dashboard tiles and other alerts that turn red when they need attention, see Finding and tracking your work.
Last updated