Lesson 25 — Decisions and Needs You

Outcome

Create durable Decisions that survive restart and move a blocked Task into and out of NEEDS_YOU.

Why this comes now

Before injecting a tool into a real provider, the domain/UI path for human judgement must work independently.

Understand

A Decision is more than a transient question dialog. It has a reason, context, options, recommendation when applicable, origin Run/Turn, blocking semantics, and a Resolution. Blocking unresolved Decisions are why a Task shows NEEDS_YOU.

Persist the Decision before notifying the UI. The process/channel used to deliver an answer is temporary; the Decision is durable truth.

Build the real project

1. Add Decision, Option, Resolution tables/domain.
2. Define the initial escalation reason enum from current product vocabulary.
3. Add application command to open a blocking Decision from Fake Adapter.
4. Move Task Working → Needs You based on the durable blocked state.
5. Build Task Decision panel and basic global Decision Inbox.
6. Resolve with human action and return Task to Working.
7. Restart while a Decision is open and prove it still appears.

Completion gate

Open Decision survives core/desktop restart. Human resolution is distinguishable from any future default resolution. Task returns to Working only after the blocking condition is resolved.

Pitfalls to avoid

Do not store pending questions only in channels. Do not mark agent recommendation as human judgement. Do not notify before persistence and risk a ghost question.

References

Sculptor pending questions: https://github.com/imbue-ai/sculptor/blob/main/docs/help/integrated_harnesses.md ; Forge vocabulary.

Checkpoint

Use the Fake Adapter to exercise several Decision shapes before deciding final visual density.