zidanezidane-ui/
import { … } from 'zidane-ui/approvals/headless'ui/src/approvals/headless/index.ts
Functions#
allowDecisionFunction#
The decision an "allow" makes with a hunk selection: a partial decision when only some hunks
of a multi-hunk edit are checked, else accept-once.
function allowDecision(mask: readonly boolean[]): ApprovalDecisionParameters
| Name | Type | Description |
|---|---|---|
| mask | readonly boolean[] | One entry per hunk, |
Returns
approvalPathFunction#
The file a file-edit request writes: its edit payload's path, else a loose read of the input
(file_path, path, filePath) for requests that came without a payload.
function approvalPath(request: Pick<ApprovalRequest, 'edit' | 'input'>): string | nullParameters
| Name | Type | Description |
|---|---|---|
| request | Pick<ApprovalRequest, 'edit' | 'input'> | The pending approval. |
Returns
string | nullapprovalPreviewFunction#
Returns what an approval card shows for a tool call's input: a non-empty command as bash
with its cwd and timeout, anything else as indented JSON.
function approvalPreview(
input: Record<string, unknown>,
labels?: Pick<ApprovalsLabels, 'approvalCwd' | 'approvalTimeout'>,
): ApprovalPreviewParameters
| Name | Type | Default | Description |
|---|---|---|---|
| input | Record<string, unknown> | The tool call's input. | |
| labels? | Pick<ApprovalsLabels, 'approvalCwd' | 'approvalTimeout'> | DEFAULT_APPROVALS_LABELS | The wording of the facts under a command. |
Returns
createApprovalHeadsFunction#
Indexes a pending queue by session: the first request of each session (first arrival wins). It listens to the queue only while a session has a subscriber; a read without one indexes the queue as it is.
function createApprovalHeads(
pending: Readable<readonly WireApprovalRequest[]>,
): ApprovalHeadsParameters
| Name | Type | Description |
|---|---|---|
| pending | Readable<readonly WireApprovalRequest[]> | The pending approvals, oldest first. |
Returns
createPendingApprovalsFunction#
Creates a pending-approvals queue.
function createPendingApprovals(
connect?: (sink: PendingApprovalsSink) => () => void,
): PendingApprovalsParameters
| Name | Type | Description |
|---|---|---|
| connect? | (sink: PendingApprovalsSink) => () => void | Starts listening to the backend with the queue's sink; returns how to stop. Runs while the queue has subscribers. |
Returns
createSafelistFunction#
Creates an ApprovalsSafelist over a backend's list and remove calls.
function createSafelist(backend: SafelistBackend): ApprovalsSafelistParameters
| Name | Type | Description |
|---|---|---|
| backend | SafelistBackend | The calls that read and change the safelist. |
Returns
initialHunkMaskFunction#
The starting hunk selection of a file-edit request, one entry per hunk: only hunks the resolver found in the file start checked (an ambiguous or missing hunk would fail if applied).
function initialHunkMask(request: Pick<ApprovalRequest, 'edit' | 'preview'>): boolean[]Parameters
| Name | Type | Description |
|---|---|---|
| request | Pick<ApprovalRequest, 'edit' | 'preview'> | The pending approval. |
Returns
boolean[]isFileEditApprovalFunction#
Whether a request gets the file-edit review rather than the inline card.
function isFileEditApproval(request: Pick<ApprovalRequest, 'tool'>): booleanParameters
| Name | Type | Description |
|---|---|---|
| request | Pick<ApprovalRequest, 'tool'> | The pending approval. |
Returns
booleanConstants#
DEFAULT_APPROVALS_LABELSConstant#
The default English strings of the approval components. Override any of them through ApprovalsProvider or LabelsProvider.
const DEFAULT_APPROVALS_LABELS: { approvalAllow: string; approvalAllowForSession: string; approvalAllowNoneSelected: string; approvalAllowOnce: string; approvalAlwaysAllow: string; approvalApplySelected: (selected: number, total: number) => string; approvalClose: string; approvalConcern: (concern: ModelApproval) => string; approvalCwd: (cwd: string) => string; approvalDeny: string; approvalFileEditNoPath: string; approvalFileEditReview: string; approvalFileEditTitle: (tool: string, path: string | null) => string; approvalFromSubagent: (label: string) => string; approvalRunAfter: string; approvalRunBefore: string; approvalsError: (error: ApprovalsError) => string; approvalTimeout: (timeout: string) => string; hunkAdded: (count: number) => string; hunkAmbiguous: (matches: number) => string; hunkAmbiguousHint: (matches: number) => string; hunkFile: string; hunkInclude: (index: number, total: number) => string; hunkNewFile: string; hunkNotInFile: string; hunkNotInFileHint: string; hunkRemoved: (count: number) => string; hunkReplaceAll: string; hunksClear: string; hunksOf: string; hunksSelectAll: string; hunksSelected: string; hunksSomeMissing: string; hunkTitle: (index: number, total: number) => string; hunkVia: (via: string) => string; hunkViaHint: (via: string) => string; safelistCount: (count: number) => string; safelistDescription: string; safelistEmpty: string; safelistEmptyHint: string; safelistLoading: string; safelistProject: string; safelistRevoke: string; safelistRevoking: string; safelistTitle: string }FILE_EDIT_TOOLSConstant#
The tools that write files: their approvals get the file-edit review (the diff, per-hunk choices).
const FILE_EDIT_TOOLS: ReadonlySet<string>Interfaces#
ApprovalHeadsInterface#
Per-session heads of a pending queue.
interface ApprovalHeadsProperties
| Name | Type | Description |
|---|---|---|
| get | (sessionId: string | null) => WireApprovalRequest | null | The first pending approval of |
| subscribe | (sessionId: string | null, onChange: () => void) => () => void | Calls |
ApprovalPreviewInterface#
What an approval card shows for a tool call's input.
interface ApprovalPreviewProperties
| Name | Type | Description |
|---|---|---|
| code | string | The command, or the input as indented JSON. |
| language | 'bash' | 'json' | How to highlight |
| meta | string[] | Small facts shown under a command ( |
ApprovalsErrorInterface#
What went wrong, for the UI to word through its labels. detail is the backend's own message.
interface ApprovalsErrorProperties
| Name | Type | Description |
|---|---|---|
| detail | string | The backend's message, shown as is by the default labels. |
| kind | 'read' | 'revoke' |
|
ApprovalsHostInterface#
What the approval components read and the decisions they send.
interface ApprovalsHostProperties
| Name | Type | Description |
|---|---|---|
| pending | Readable<readonly WireApprovalRequest[]> | The approvals waiting for a decision, oldest first. The host keeps it current: new requests, requests answered elsewhere (another window, a terminal), and a re-read after a reconnect. The host starts listening when the store gets its first subscriber. |
| safelist? | ApprovalsSafelist | The "Always allow" entries. Absent: no safelist panel. |
| denyAll? | (sessionId?: string) => Promise<void> | Denies every pending approval, or only those of |
| resolve? | (requestId: string, decision: ApprovalDecision) => Promise<void> | Answers a pending approval. The request leaves |
ApprovalsSafelistInterface#
The safelist: what the user allowed with "Always allow", and revoking an entry.
interface ApprovalsSafelistProperties
| Name | Type | Description |
|---|---|---|
| state | Readable<SafelistState> | The safelist as last read. |
| refresh | () => Promise<void> | Reads the safelist again. Never rejects: a failure lands in |
| remove? | (project: string, entry: string) => Promise<void> | Removes one entry, then reads the safelist again. Rejects with an |
PendingApprovalsInterface#
The queue: a readable list, what a backend does to it, and taking requests out to answer them.
interface PendingApprovals extends Readable<readonly ApprovalRequest[]>, PendingApprovalsSinkProperties
| Name | Type | Description |
|---|---|---|
addfrom PendingApprovalsSink | (request: WireApprovalRequest) => void | Appends a request, unless one with its id is already pending. |
dropfrom PendingApprovalsSink | (requestId: string) => void | Drops a request answered elsewhere. Unknown ids do nothing. |
getfrom Readable | () => readonly WireApprovalRequest[] | Returns the current value. |
mergefrom PendingApprovalsSink | (requests: readonly WireApprovalRequest[]) => void | Appends the requests of a re-read that are not pending yet (a re-read never removes). |
subscribefrom Readable | (onChange: () => void) => () => void | Registers a listener called after the value changes. Returns a function that removes the listener. |
| take | (requestId: string) => WireApprovalRequest | undefined | Takes a request out to answer it. |
| takeAll | (sessionId?: string) => WireApprovalRequest[] | Takes out every pending request, or those of |
PendingApprovalsSinkInterface#
What a backend does to the queue: what connect receives.
interface PendingApprovalsSinkProperties
| Name | Type | Description |
|---|---|---|
| add | (request: WireApprovalRequest) => void | Appends a request, unless one with its id is already pending. |
| drop | (requestId: string) => void | Drops a request answered elsewhere. Unknown ids do nothing. |
| merge | (requests: readonly WireApprovalRequest[]) => void | Appends the requests of a re-read that are not pending yet (a re-read never removes). |
SafelistBackendInterface#
The backend calls createSafelist wraps.
interface SafelistBackendProperties
| Name | Type | Description |
|---|---|---|
| describeError? | (error: unknown) => string | The message to show for a failed call. Default: the error's |
| list | () => Promise<readonly SafelistProject[]> | Lists every project with at least one entry. |
| remove? | (project: string, entry: string) => Promise<void> | Removes one entry. Absent: the safelist is read-only. |
SafelistProjectInterface#
The "Always allow" entries of one project.
interface SafelistProjectProperties
| Name | Type | Description |
|---|---|---|
| entries | readonly string[] | The entries, as zidane stores them ( |
| project | string | The project the entries apply to (its root folder). |
SafelistStateInterface#
Where the safelist is: not read yet, being read, read, or failed.
interface SafelistStateProperties
| Name | Type | Description |
|---|---|---|
| error | ApprovalsError | null | Why the last read failed, |
| projects | readonly SafelistProject[] | null | The projects from the last read that succeeded, |
| status | 'error' | 'idle' | 'loading' | 'ready' |
|
Types#
ApprovalDecisionType#
Outcome of an approval prompt. Four bulk decisions match the original
single-edit modal contract; partial is the multi-edit branch — the
user accepted a subset of an edit / multi_edit / write_file call.
partial.mask is 1:1 with the call's hunks (in input order): true
means apply, false means deny. The gate handler walks the mask to
build per-hunk outcomes; the TUI rebinds ctx.input.edits to the
approved subset and the renderer reconstructs the full per-hunk view
from the <edit-outcomes> annotation appended to the tool result.
type ApprovalDecision =
| 'accept-once'
| 'accept-session'
| 'accept-safelist'
| 'deny'
| { kind: 'partial'; mask: readonly boolean[] }ApprovalRequestType#
A tool call waiting for the user's decision: the tool and its input, the session that raised it, the safelist entries "Always allow" adds, and for edit tools the edit and its diff preview.
type ApprovalRequest = WireApprovalRequestApprovalsLabelsType#
The approval components' strings: the shape of DEFAULT_APPROVALS_LABELS.
type ApprovalsLabels = typeof DEFAULT_APPROVALS_LABELS