Decisions

A decision is a small, fast request with a typed answer: the probability a condition is true, one value from a fixed set, or a position on a scale. Zidane calls the provider's Decisions endpoint and normalizes the answer, so hooks can make cheap routing and policy calls.

Ask from a hook#

Every hook context has ctx.decide, bound to the active run. Aborting the run cancels the decision, and decision:* hooks carry the run id. Outside hooks, call agent.decide(...).

const agent = createAgent({
  provider: [anthropic(), openrouter()],
  hooks: {
    'tool:gate': async (ctx) => {
      if (ctx.name !== 'shell')
        return
      const r = await ctx.decide({
        input: String(ctx.input.command),
        questions: {
          destructive: { type: 'predicate', instructions: 'Does this command delete or overwrite data?' },
        },
      })
      if (r.ok && r.answers.destructive.type === 'predicate' && r.answers.destructive.probability > 0.8) {
        ctx.block = true
        ctx.reason = 'Looks destructive'
      }
    },
  },
})

Questions and answers#

Each answer comes back under its question's key. Choice values are typed from the keys: answers.team.choice is 'payments' | 'frontend'.

const r = await agent.decide({
  input: { ticket: 'Checkout shows a blank page after Pay' },
  questions: {
    isBug: { type: 'predicate', instructions: 'Is the customer reporting a defect?', criteria: { true: 'Broken behavior', false: 'A question or request' } },
    team: { type: 'choice', instructions: 'Which team owns this?', choices: { payments: 'Checkout and billing', frontend: 'Rendering and layout' } },
    urgency: { type: 'score', instructions: 'How urgent is it?', levels: ['Next release', 'This week', { label: 'Now', description: 'Blocking revenue' }] },
  },
})

input is a string, a JSON object or prompt parts. OpenAI accepts inline base64 images. OpenRouter takes text and JSON only, and returns unsupported for images.

Failures never throw#

decide returns { ok: false, reason, message } on failure, so your hook picks fail-open or fail-closed.

Providers throw DecisionHttpError, DecisionUnavailableError, DecisionUnsupportedError, DecisionInvalidResponseError or DecisionTimeoutError. zidane maps them to these reasons.

Configuration#

By default the agent uses the first provider in provider that supports decisions and has credentials for them, with its default model. If none has credentials, it uses the first that supports decisions, which reports why it is unavailable. Override with decisions:

createAgent({
  provider: anthropic(),
  decisions: { provider: openrouter(), model: 'typesafe/jev-1.13', timeoutMs: 2000 },
})

createAgent({ provider: openrouter(), decisions: false }) // every decision returns `unavailable`

In the apps#

In the terminal app, open Settings › Agent › Models. In the desktop app, open Settings › Agent › Helper models.

Automatic session titles#

Auto-update session titles (autoTitle, next to the Decisions setting) needs decisions on. It titles a session after its first successful run. After every two new prompts, the decision model asks whether the title still fits, and rewrites it if not. The host runs this at run end, so it works the same in the TUI, the desktop app and server sessions.

Auto-titling does not show errors in the chat. The Title line in session details shows the source and the last attempt:

[auto] [checked 5m ago, still fits]
[auto] [check failed 2m ago (unavailable: …)]

Time estimates#

Estimate time remaining (runEstimates, under Auto-update session titles, desktop and web apps only) needs decisions on too. It asks how long each running session and subagent has left, and shows a countdown in the sidebar and on subagent headers. See time estimates.

Observability#

decision:* contexts have no decide, so a decision cannot trigger another.

Reference#

• zidane/types
• zidane
• zidane/providers/openrouter
• zidane/providers/openai