# When an agent needs your input Source: https://codeherder.com/docs/agent-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](https://codeherder.com/docs/agent-input/#the-tasks-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](https://codeherder.com/docs/agent-input/#the-tasks-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](https://codeherder.com/docs/agent-input/#the-tasks-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](https://codeherder.com/docs/blockers/) 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 ` 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](https://codeherder.com/docs/agent-input/#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)](https://codeherder.com/docs/agent-input/#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](https://codeherder.com/docs/following-a-live-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](https://codeherder.com/docs/collaborating/#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](https://codeherder.com/docs/tracking-work/).