Skip to Content
Core ConceptsDecisions & Agent Questions

Decisions & Agent Questions

Most of the time Shep’s agents work without you. The moments when they do need you, an approval gate, a question about requirements, a choice an agent can’t make alone, are all the same thing in Shep: a decision. Every decision has options, a recommended answer that’s already selected, and is shown the same way wherever you are, so answering usually takes one keystroke.

A requirements decision in the PRD Review tab of the feature Add Stripe checkout: question 1 of 2, "Which Stripe integration should the cart use?", with "Stripe Checkout (hosted page)" marked Recommended and selected and "Payment Element embedded in the cart page" as option 2, Previous and Next buttons, and Reject and Approve Requirements below

Where decisions come from

KindRaised when
Approval gateA feature’s run stops at a gate: requirements (PRD), plan, or merge. Options: Approve or Reject; a typed note on Reject becomes the feedback
Requirements questionsIn spec-driven mode, the requirements phase asks product questions before writing the spec
Chat questionAn agent you’re chatting with asks you something (Claude Code’s AskUserQuestion, or Cursor’s equivalent)
Agent askA background feature agent is blocked on a choice it can’t make by reading the code, and asks through Shep’s ask_decision tool
Harness changeA learned-harness change waits to be adopted or rejected (experimental self-learning harness only)

Anatomy of a decision

  • Questions. A decision holds one or more questions, answered together. With several, you page through them (1/2, Next, Previous, Submit).
  • Options. Up to nine per question, each with a label and a one-line description. Some options carry a preview (code, a mockup, a diff) shown when the option is focused.
  • Recommended option. The option the agent would pick, marked Recommended and preselected. A deadline falls back to it.
  • Single or multi-select. Single-select questions advance as soon as you pick. Multi-select questions toggle.
  • Your own answer. The text box under the options takes a free-form answer. When it isn’t empty, your text wins over the selected option.
  • Deadline. Optional. Shown under the options: “If nobody answers by 11:56 AM, the agent continues with the recommended option.”

Once answered, a decision collapses to an Answered questions row with what was chosen and by whom. A decision whose agent has gone away (for example, a chat session that ended) is still shown, but marked as no longer answerable.

Keyboard

KeyAction
1–9Pick that option
n / NNext / previous question
TypingWrites your own answer

Deadlines

A background agent that asks with ask_decision must offer 2–9 options and mark exactly one as recommended. It can set its own deadline; otherwise the default applies.

A background agent's question in the Agent questions inbox, tagged Blocking and Pending: "Should GET /health also check the database connection, or only report that the process is up?" with "Split liveness and readiness" marked Recommended, two other options, a code preview, a box for your own answer, and the note "If nobody answers by 11:56 AM, the agent continues with the recommended option."

Set the default under Settings → Workflow → Question deadline. It is 30 minutes by default, and can be anything from 1 minute to 24 hours (workflow.decisionDefaultTimeoutMinutes).

When the deadline passes, the question is closed with the recommended answer, the agent carries on with it, and the feature’s activity log records that it proceeded with the recommended option. If the question is cancelled, or questions are turned off, the agent also proceeds with its recommendation.

Approval gates and chat questions have no deadline. A gate waits for you (or for your supervisor) for as long as it takes.

Background agents can ask only when the collaboration feature flag is on (the default) and the agent accepts an MCP configuration for its run. Today that is Claude Code. With other agents, or with the flag off, background runs don’t ask; they make the call themselves and you review it at the next gate.

Where to answer

The same decision shows up everywhere at once, and whichever surface answers first settles it everywhere.

SurfaceHow
ChatInline in the turn that asked. See Chat
Feature drawerGates in their review tab (with the review document and action bar); requirements questions as pages of the questionnaire
Agent Questions inboxSidebar → Collaboration → Agent Questions (/agent-questions, shown while the collaboration flag is on, the default). Every pending question across features, filterable by status and urgency, with Cancel question
Agent activity/activity and the drawer’s Agent status card say what the agent asks and link to where to answer. See Agent activity
Terminal consolea / r for gates; o to answer a chat question with a digit; d for harness changes. See Terminal console
CLIshep feat approve / shep feat reject for gates; shep agent questions for everything else (below)
MCP and A2Adecide_feature_gate and answer_agent_question on shep mcp; a reply to the task over A2A

Pending decisions also raise notifications (in the app, in the browser and on the desktop, per your notification settings) and appear in the terminal console’s NEEDS YOU strip.

From the CLI

shep agent questions ls --app <scope> --status pending shep agent questions answer <question-id> --app <scope> shep agent questions answer <question-id> --app <scope> --answer "Online, nullable column" shep agent questions cancel <question-id> --app <scope> --reason "No longer needed"

--app is required. It is the application id for an app, or the repository’s absolute path for a plain repository. Add --feature <id> to ls to narrow it to one feature. ls prints each question readably, with a short id; answer and cancel take the full question id.

Without --answer, answer shows the decision in your terminal with the recommended option preselected. With --answer, the text is matched to an option by its id or label; anything else is recorded as your own answer when the question allows it. On a gate, own text means reject with that feedback.

Answering for you

With a supervisor configured, gate decisions can be answered by it within the rules you set. Your own answer always wins over the supervisor’s.

See also