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, both raised with the same command, ch agent ask:

A question that needs an answer — a structured set of choices the agent presents. You pick from the options provided and click Submit. No terminal required. The agent usually pauses until you answer.
A heads-up note (input needed) — a short free-text note about something the agent wants a human to see. The agent keeps working while it waits; you simply Acknowledge the note. There is nothing to type in response.

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’re allowed to see, across the workspace
A session’s page	Needs your answer — this session is waiting on you	Every open question or note that session is currently waiting on
An agent’s page	Needs attention	Only that agent’s open items (an agent with none shows No open questions yet.)
A task’s page	Questions and answers	That task’s questions and heads-up notes — open ones and already-resolved ones — see The task’s permanent record below

The card itself is identical everywhere: the same options, the same free-text box, the same Submit or Acknowledge button, the same result. There’s no need to navigate to one particular page just to answer — use whichever one you’re already on.

How you are alerted

Dashboard sidebar badge — the Dashboard link in the sidebar shows a pulsing red count badge whenever agents need attention. The badge combines the count of open questions and open input-need notes.

The Needs attention tile — the Dashboard’s row of summary tiles includes a Needs attention tile with the same combined count. The tile turns alert-red when the count is non-zero. Click it to jump to the section below.

The Needs attention section — appears on the Dashboard whenever at least one item is open, as described in the table above.

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 and the task it is working on, at the top of the card.
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.
Other (optional) — a free-text field below each question’s options. Use it when none of the preset options fit your situation.
Submit — disabled until every question in the card has at least one option selected or something typed into its free-text field (hover over the button while it’s disabled and it tells you why).

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. 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 permanent record rather than a to-do list (more on that in The task’s permanent record below).

If somebody else gets to a question before you do, you’re told so rather than getting an error.

Who sees which questions

On the Dashboard, a session’s page, or an agent’s page, questions are visible to human members only. Workspace admins and owners see every open item across the workspace; other members see only items from agents they operate. A task’s page works differently — see The task’s permanent record below.

What happens after you answer

Submitting your answer clears the “Waiting for human answer to agent question” blocker on the task (see Blockers and blocked tasks for the full blocker lifecycle), and the agent picks up your answer one of two ways:

If the agent’s session is still running, your answer is delivered to it directly, and it carries on in the same session.
If the session had already ended while it waited, CodeHerder starts a fresh session on the same stage, with your answer included from the start, so the work continues from where the task left off.

The task’s permanent record

Every task that has had a question or a heads-up note keeps a Questions and answers section on its own page — a running record of the exchange, not just whatever is currently open.

Each row is badged Open, Answered, or Closed.
An answered row shows the answer that was submitted and who submitted it.
A closed row has no submitted answer. Either someone acknowledged a heads-up note, or the item stopped being relevant while it was still open. In place of an answer, the row shows one line: Acknowledged, Closed — session ended, or Closed — task completed.
An open row is answerable (or, for a heads-up note, acknowledgeable) right there, with the same form described above.
Unlike the Dashboard, session, and agent surfaces — which only ever show what’s still open — a task’s page is the one place that keeps resolved items visible too.

Reading and answering a task’s questions follow different rules. Anyone who can read the task can read the exchange, but only the agent’s operator (the human who created it) or a workspace admin or owner can submit an answer. If you’re outside that group, you’ll still see the form, but submitting it shows an error instead of going through: “Only this agent’s operator or a workspace admin can answer its questions.” You can’t answer on behalf of an agent you don’t operate.

Answering is a web app action only. Running ch task show <taskId> prints the same exchange — every question and its answer — but this is a read-only view; no ch command submits an answer.

Heads-up notes (input needed)

Sometimes an agent wants to flag something for a human without stopping to wait for an answer — for example, a heads-up about a judgment call it made. 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 a single Acknowledge button.

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 resolves the situation itself or its session ends, so you won’t generally find stale ones to clean up.

How an agent raises these — `ch agent ask`

Both mechanisms above come from the same command, ch agent ask, which an agent runs from its own session. It is not something you run yourself — it’s how an agent reaches out to you.

A question (blocking by default)

This is the default mode. 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 — the task moves to blocked — until you answer it, as described in Answering a question above.

Adding --no-block posts the same kind of question without pausing the task: the agent keeps working while it waits, and your answer reaches it whenever you submit it.

A heads-up note (non-blocking)

The agent adds --reason, with the note text given inline, from a file, or from stdin — whichever suits the situation:

ch agent ask --reason "Picked the simpler of two equally valid approaches."
ch agent ask --reason-file note.md
echo "Picked the simpler of two equally valid approaches." | ch agent ask --reason -

This posts a non-blocking input-need note — the agent keeps working while it sits waiting for you, and you clear it with Acknowledge as described in Heads-up notes (input needed) above.

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.