> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Needs you — decisions the agent won't make alone

> Needs you lists the approvals and decisions waiting on you, grouped by kind, each with the action to clear it.

**Needs you** is your inbox from the agent. It only holds things the agent should not decide by itself: approvals, risky tool calls, and recommendations that change your setup.

> [!NOTE]
>
> You only see actions you have permission to take. If an action is missing, ask a project editor or admin.

## The groups

Items are grouped by kind, with approvals first.

| Group | What waits on you |
| - | - |
| **Approvals** | Changes ZespanPilot proposed that need a teammate's sign-off |
| **Tool calls** | Tool calls from your agent that are held until someone approves them |
| **Issues** | Recurring failures that need a decision. Issues with the same title are told apart by error code and first and last seen |
| **Guardrails** | Guardrail drafts ready to turn on, and near-miss suggestions for a new guardrail |
| **Cost savings** | Cost recommendations to mark as applied or look into |

Each item shows a title, a detail line, and sometimes an impact line, with its buttons on the right.

**1. Open Needs you**

Click **Needs you** in the **Agent** group of the sidebar. Home shows the top three; click **All** to see the rest.

**2. Read the item**

The detail line says what the agent saw. Use the item's button to open the related page if you want more context.

**3. Decide**

For an approval, click **Approve** or **Reject**. Both open a confirmation, and a rejection asks for your reason. Other items have their own button: **Mark as applied** or **See details** for a cost saving, **Open the issue** for an issue, **Review the guardrail** or **Create a guardrail** for a guardrail. **Mark as applied** records the recommendation as applied; it does not change your configuration.

After you act, the list, the sidebar count, Home, and the notes on other pages update together. When nothing is left you see: *Nothing needs you. I'll put decisions here when I can't make them alone.*

If I could not read part of the list, I say so instead of saying nothing needs you, and the sidebar count is hidden until I can read all of it. A long list shows as "5+" and the page tells you there may be more.

## Item types and lanes

With the new agent layout on, Needs you sorts every item by what *you* can do with it. The lanes sit on the left and the selected item opens as a card on the right. The filters above the lanes show how many items each one holds. If I could not read part of the queue, the filters and lane headings show no numbers. When the list is cut, the numbers are shown with a "+" (for example "5+"), because there may be more.

| Type | What it is | Counts in the badge | Who sees it |
| - | - | - | - |
| **Tool approvals** | A tool call from your agent that is held until someone approves it | Yes | Owners and admins decide it. Editors and viewers see it as waiting on an admin |
| **Decide** | A change to your agents that you can apply: a guardrail draft, an alert, a cost saving, a fix, a layer label, a model retirement alert or a postmortem | Yes | Only people who hold the permission the change needs |
| **Answer** | A question whose answer settles a cause | Yes | Only people who hold the permission to answer it |
| **FYI** | Something to read, with nothing for you to decide. FYI is folded, and it holds the items waiting on an admin and the note that three or more tool approvals expired unanswered | No | Everyone on the project |
| **Waiting on an admin** | A change you can read but not apply. It sits inside FYI, with no apply button, and says that an owner or admin decides | No | Editors and viewers, for items an owner or admin decides |
| **Waiting on others** | Your own requests, decided by someone else. It is shown only by its own filter, never in **All** | No | The person who made the request |

Whether you may decide an item is checked on the server, not only in the page. If you lack the permission, the item moves to FYI as waiting on an admin; it does not show a button that would fail.

A tool approval shows how long it has left, as "expires in 28 min", "expires in 2 h" or "expired". Approve and Reject open the same confirmation as before. Any other action on an item stays available as a secondary button, such as opening the related page.

When you finish an action, focus moves to a line that says what was done. Nothing on the page announces changes on its own.

> [!NOTE]
>
> Tool approvals are in the app and in the daily digest only. They are for owners and admins, and they are not sent to chat.

> [!WARNING]
>
> A tool approval can expire after 15 minutes. If nobody opens Needs you in that time, the held tool call is not approved, and the SDK raises an approval-rejected error for that call. Check the **Tool approvals** lane when your agents call tools that need a person.

## Deciding in place

With the new agent layout on, a **Decide** item has its own primary button on the card, so you can act without leaving Needs you. You only see the button when you hold the permission the change needs; the server checks it again when you press it. If it refuses (a plan limit, a missing permission), the card shows the server's message and stays where it is.

| Button | What it does |
| - | - |
| **Turn on guardrail** | Turns on a ready guardrail draft in **dryrun**. It records what it would block and blocks nothing yet. If the change touches anything else in your guardrails, the line above the card says it needs the full review and gives an **Open the policy review** link. If the guardrail cannot be turned on from here, it says so and links to the draft. Nothing opens by itself |
| **Turn on alert** | Turns on an alert rule that a draft saved |
| **Mark as applied** | Records a cost recommendation as applied. It does not change your configuration |
| **Apply fix** | Asks you to confirm the change, then applies it. If the change can be applied straight away, it applies without that step. If your team needs to approve it first, the card says **Sent for team approval.** and nothing changes yet |
| **Confirm layer** | Saves the layer the agent named as your own label for that issue, incident or finding |
| **Alert me before it retires** | Turns on the model retirement alert. Any email list or webhook already saved on it is kept as it was |
| **Publish postmortem** | Asks you to confirm, then publishes the saved postmortem. If no postmortem was written yet, it says so |
| **Approve** | Opens the same confirmation as before |

When an apply goes through, the card turns into an **Applied** line that says what was done, and the list, the sidebar count and Home update together. An apply is a change, not proof that it worked: the line never says a problem is fixed. With fix tracking on, an applied card about an issue also shows the state of the fix it started, in Zespan's own words and with its numbers (for example "Measuring · 3 of 200 runs"). See [the fix path](https://docs.zespan.com/dashboard/issues.md#the-fix-path) for the states. If the state cannot be read, the card says so and offers **Retry**.

Turning on a guardrail or an alert is recorded in the Audit log. These changes do not appear in [Activity](https://docs.zespan.com/dashboard/activity.md) yet.

### Draft an alert from an issue

With the new agent layout on, an issue page has a **Draft an alert** button when the issue has a metric an alert can watch. It shows the rule it would save (the metric, the threshold and the window) and a 30-day backtest, for example "Would have fired 3 times in the last 30 days". Opening the draft saves nothing: the rule is created only when you press **Turn on**. If the last 30 days cannot show the rule would have caught the issue, the draft says why and offers no button. Alerts need the Pro plan.

### Drafts from an agent run

When runs are available for the project, a run can leave drafts here. A drafted alert is a **Decide** item for people who can manage alerts; for everyone else it waits on an admin. Its **Review alert** button opens the same **Draft an alert** dialog as the issue page, so you read the rule and its 30-day backtest and press **Turn on** only if you want it. Closing the dialog returns focus to the button, or to the page heading if the item has left the list.

A run that stopped before it could check everything marks its drafts as partial. The card says so in its **Not checked** line, for example "Partial · cause not confirmed · 3 of 5 sample runs read". Read that line before you act on the draft.

### Code fix drafts

When a run drafts a code fix, it is a **Decide** item for people who can manage alerts, titled like "I drafted a code fix for `tool.x`." The button is **Review the fix**. It opens the issue's [fix path](https://docs.zespan.com/dashboard/issues.md#the-fix-path), where you read the suggestion, change your code, and mark the fix as shipped. It is a link, not an approval: I do not change your code myself, and the card never says **Approve**. For everyone else the item waits on an admin. When the same issue also has a suggested fix to apply, you see one item, not two.

When three or more tool approvals expire unanswered within a week, one **FYI** says so and suggests a confirm-first policy or a longer wait. Neither counts in the badge.

## I try first, then ask

When investigations are on for the project, I investigate an issue whose cause is unclear before I ask you to label runs. This happens within your run limits: it uses the same daily limits as other automatic investigations, and it waits when a limit is reached.

While I am trying, the label ask is hidden, so you are not asked for something I may settle myself. If I could not try, or could not settle the cause, the ask shows with one line that says why:

| Line on the ask | What it means |
| - | - |
| I investigated this and could not settle the cause. | My investigation finished without a grounded cause. |
| My investigation stopped before it settled the cause. | The run stopped early. |
| I could not try first: today's run limit is reached. | A daily run limit is used up. |
| I could not try first: many new issues came in this hour. | I hold back automatic runs during a burst of new issues. |
| I could not try first: I could not read my run limits. | I will not start a run on a number I could not read. |
| I could not start an investigation for this. | The run did not start. |

Each line ends with "Your labels on a few sample runs settle it." If I could not read part of this, the ask shows as it always did, with no claim that I tried.

Label asks come last. In the queue they sit after every decision, and on Home the batch titled "I need your labels on 2 issues." is shown after the others and is the first to drop when there are more than three groups. The headline names a decision before it names a label ask.

## Model tests

When a model you call is about to retire and it names a successor, I can test the successor on your own calls first. Two cards belong to this.

| Card | What it says | What you can do |
| - | - | - |
| **Ready to test** | "`gpt-4o-old` is retiring. I can test `gpt-4o-new` on 4 of your recent `support` calls first, on your `Prod OpenAI` connection, for up to \$0.02." | **Run the test** (owners and admins) opens a fresh estimate and runs nothing until you confirm. Others read "`gpt-4o-old` is retiring. An owner or admin can ask me to test `gpt-4o-new` on 4 of your recent calls first." with no button and no dollar figure. When the calls cannot be priced, the card says "It would run up to 8 calls on your own endpoint, and I can't see what they cost." and never "\$0". A test through your endpoint names no model connection. The price is not repeated in the headline |
| **Result** | "I tested `gpt-4o-new` against `gpt-4o-old` on 4 test runs. `gpt-4o-new` passed 8 of 8 checks; `gpt-4o-old` passed 6 of 8." A stopped test says it is partial. | **Switch `triage` to `gpt-4o-new`** (owners and admins, only where Zespan manages the model) asks first, then makes a new prompt version. Clients that fetch the latest version get it now; clients pinned to a label keep theirs. Where I do not manage the model, the card says to change it in your code and I watch the change |

A result is checks passed on a small sample. It is not an accuracy figure. See [Test the successor](https://docs.zespan.com/dashboard/model-lifecycle.md#test-the-successor).

## Fixes I drafted on my own

When an issue is proven, I can draft its guardrail myself, without waiting for a person. It lands here as the same **Decide** card as any guardrail draft ("I drafted 1 guardrail for you to decide."), with the line "It would have stopped 9 of 14 failing runs in the replay." when I have the numbers. The draft says "Drafted by Zespan at" with the time. I only draft: applying it stays yours, and pressing **Turn on guardrail** turns it on in dryrun first. A fix I drafted shows in Done for you once, and is left out there while its card here shows the same numbers. See [Drafted by Zespan](https://docs.zespan.com/dashboard/guardrails.md#drafted-by-zespan).

## Version regressions and agents I cannot stop

With the new agent layout on, three kinds of card are about one of your [agents](https://docs.zespan.com/dashboard/agents.md). On Home they share one group, "I need you to look at 2 of your agents."

| Card | What it says | What you can do |
| - | - | - |
| **Roll back** | "I tied a drop in `refund_agent` to version v14: errors went from 3 of 400 to 21 of 410 calls. `refund_prompt` changed from v3 to v4 in that version." | **Roll back `refund_prompt` to v3** moves the prompt label back. It needs permission to deploy prompts, and I check the rule again at the click. **Not the cause** closes it. Fix tracking then measures whether errors came back down |
| **Tied drop, nothing I manage changed** | "I tied a drop in `refund_agent` to version v14. What changed: model gpt-4o to gpt-4o-mini. Roll it back in your own deploy if you agree." | **See the versions**. I draw no rollback button, because I do not manage what changed |
| **I can't stop an agent** | One sentence per reason. OpenTelemetry only: "I can't stop `refund_agent`: it sends spans through OpenTelemetry, not the Zespan SDK. Turn the stop off or add the SDK." Older SDK: "I can't stop `refund_agent` yet: its Zespan SDK is older than 1.8.0. Update the SDK and I can stop it when it spends its budget." Agent name not set: "I can't stop `refund_agent`: its agent name is not set in code. Wrap its calls in `withAgent` (TypeScript) or `with_agent` (Python) and I can stop it when it spends its budget." SDK in log mode: "I can't stop `refund_agent`: its SDK runs with ZESPAN\_AGENT\_STOP=log, so it only records that it would stop. Remove that setting and I can stop it when it spends its budget." | **Open the agent**. It shows only for an agent that has a budget with the stop on, while stops are on, and not for one that is already stopped or past its budget (Home says that instead) |

A tied drop is said once: here, or in the Agents row on Home when this card is not shown. Someone who cannot deploy prompts sees the plain card without the **Roll back** button.

## Answer items

With the new agent layout on, an **Answer** item is a question Zespan cannot settle from your traces. You answer it on the card, without leaving Needs you. You only see the controls when you hold the permission to answer; otherwise the item waits on an admin and is read-only.

| Item | Control on the card | What it does |
| - | - | - |
| Is this tool one that moves money (or deletes, sends, and so on)? | **Yes, it moves money** or **Yes**, **No**, **Not sure** | **Yes** confirms the tool's role for that pack, **No** rejects it. **Not sure** sends nothing |
| Which fields identify one record? | A checkbox for each field, **Save**, **Not sure** | **Save** confirms the picked fields. With none picked, nothing is sent |
| Label sample runs to settle a cause | **Open a labelling queue** | Opens the issue's labelling queue, or reuses the one already open |

One press sends one request. After the answer, one line stays on the card and keyboard focus moves to it, even after the item leaves the list. It repeats what the server returned: *Saved. The Payments pack is now on.* (a pack is named only when it changed), or *Saved. No pack changed: packs are picked once enough tool calls arrive.* For a queue, **Opened a queue with 3 sample runs.** or **Opened the existing queue.** An **Open the queue** link goes to it. If the request fails, the card says *Couldn't save your answer. Nothing changed. Try again.* (or *Couldn't open the queue…*) and keeps the buttons.

If a refresh of the list fails after you answer, the page stays with a note and **Retry**, and the outcome line keeps focus. On Home, a queue question links to [Annotation queues](https://docs.zespan.com/dashboard/annotation-queues.md#answer-items), where the button is.

The same tool and field questions are on [Detector packs](https://docs.zespan.com/dashboard/detector-packs.md#questions), and the queue question on [Annotation queues](https://docs.zespan.com/dashboard/annotation-queues.md#answer-items).

## Next steps

* [Home](https://docs.zespan.com/dashboard/home.md): the top three items live here too
* [Activity](https://docs.zespan.com/dashboard/activity.md): see what happened after you decided
* [Agent runs](https://docs.zespan.com/dashboard/agent-runs.md): the investigations that leave drafts here, and that try first before asking for labels
* [Notifications](https://docs.zespan.com/dashboard/notifications.md): the daily digest of what waits here, by email or chat
* [Detector packs](https://docs.zespan.com/dashboard/detector-packs.md): where tool and field questions are answered in full
* [Model lifecycle](https://docs.zespan.com/dashboard/model-lifecycle.md#test-the-successor): test a successor model on your own calls
* [Guardrails](https://docs.zespan.com/dashboard/guardrails.md#drafted-by-zespan): the fixes I draft on my own
* [Agents](https://docs.zespan.com/dashboard/agents.md#the-rollback-card): targets, the daily stop, versions and the rollback card
* [Issues](https://docs.zespan.com/dashboard/issues.md), [Guardrails](https://docs.zespan.com/dashboard/guardrails.md), [Costs](https://docs.zespan.com/dashboard/costs.md): the pages behind each group
* [ZespanPilot](https://docs.zespan.com/dashboard/zespanpilot.md): where approvals begin


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.