When an agent needs your input

The two ways an agent asks for your input — structured questions and free-text heads-up notes — and the four places you can see and answer them, the Dashboard, an agent's page, a session's page, and the task itself, which keeps a permanent record of every question and its answer.

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, then resumes automatically.
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	Only the item 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.)
A task’s page	Questions & Answers	That task’s questions — open ones and already-answered 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).

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

The agent receives your answers and resumes from where it stopped. If the agent’s task was paused waiting for your response, CodeHerder automatically re-activates the task so the agent picks up where it left off.

While a question is open, its task sits at the blocked status with a blocker reading “Waiting for human answer to agent question” — submitting your answer clears that blocker and resumes the task in the same step. See Blockers and blocked tasks for the full blocker lifecycle.

The task’s permanent record

Every task that has ever had a question keeps a Questions & Answers section on its own page — a running record of the exchange, not just whatever is currently open.

Each row is badged Open or Answered.
An answered row shows the answer that was submitted and who submitted it. This is the only one of the four places that keeps answered questions visible; the Dashboard, session, and agent surfaces only ever show what’s still open.
An open row is answerable right there, with the same form described above.
Heads-up notes don’t appear here — they aren’t tied to any particular task.

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 fails rather than going through — 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 — the Dashboard, a session’s page, and an agent’s page — but not on a task’s page, since a heads-up note isn’t tied to any particular task.

An input-need card shows the agent’s name, the task it’s working on, 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. It does not send anything back to the agent — there’s nothing to send, since the agent was never waiting on a reply.

Notes also clear 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)

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 pauses the agent’s task until you answer it, as described in Answering a question above. Once you submit your answers, CodeHerder resumes the agent automatically.

A heads-up note (non-blocking)

The agent adds --reason, with the note text again coming from a file or stdin rather than typed inline:

ch agent ask --reason --from-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.