Approvals at the cap#

When a call would pass its task’s budget and someone is watching, Lockpin holds the call and asks whether to let it go on. This page covers when Lockpin asks, the answers, every place you can answer from, and how to pause the cap. It is for anyone who runs agents and wants them to finish instead of stopping at a 402.

Before you begin#

Lockpin is running (lockpin doctor checks it).
Your agent’s calls go through Lockpin and its task has a budget.
One of these is open: the meter, VS Code with the Lockpin extension, or the overlay. On a machine with no screen, see Answer without a desktop.

When Lockpin asks#

Lockpin holds a call and asks when all of these are true:

The call does not fit its task’s budget. Key, team, project and daily limits never ask: they refuse at once with a 402.
-ask-at-cap is above 0 (default 3m, at most 9m).
Someone is watching: the meter, VS Code or the overlay has read Lockpin’s questions in the last 30 seconds. The members’ page (/lockpin/me) does not count.

While it asks, the call is held for up to -ask-at-cap. Calls of the same task that arrive meanwhile, retries included, wait on the same question. The hold stays under the 5 to 10 minutes after which agents give up on a call and retry it.

With nobody watching, Lockpin refuses as before, with the 402 that clients do not retry.

Note

If the fallbacks file lists a cheaper model for the call and its worst case fits, the call goes there and nobody is asked. See Saving money.

The answers#

Answer	What happens
Allow this call	The budget rises by what the call needs beyond what is left, and the call goes through as if nothing happened. After the hold has ended, the same button says Allow next call.
Raise budget	The budget rises by the task’s free allowance (default +50%) while that is unused and covers the call; otherwise by one more budget (or by that need, if more). The call goes through.
Stop	The call gets the usual 402.
No answer in time	The call gets the usual 402.

A yes stands. The raised budget is recorded as approved, and the task’s X-Lockpin-Budget-Usd header may not set it lower again on the next call.
Late answers count. A question stays open for an hour. Allowing it after the hold ended still raises the budget, so the agent’s next call goes through.
Raises follow the usual rule. The meter page answers any raise. The overlay and the VS Code extension answer only within the allowance (-allowance-pct); past it, their button says On the meter page and opens it there. See Budgets and tasks.
In team mode only the admin’s meter can answer.

Answer from the meter#

Open http://127.0.0.1:8787/lockpin/.
A Call needs approval banner on the overview names the task, what the call could cost at most and what is left (“This call could cost up to $0.13, more than the $0.10 left.”), and when it is refused if nobody answers. From 75% used it says Near cap: call needs approval.
Choose Allow this call, Raise budget or Stop.

Answer from VS Code#

The Lockpin panel’s Waiting for you view shows one card per held call: Call needs approval beside the task, then for example This call could cost up to $0.07, more than the $0.03 left. Refused at 18:52:40 if nobody answers., with Allow this call, Raise budget and Stop. A button that spends asks once more before it answers. See VS Code extension.

Answer from the overlay#

On Windows, the overlay’s card has three equal buttons with the amount under each and the time the hold ends. Allow this call and Raise budget need two presses from the keyboard (Win+Shift+L gives the card the keyboard). See The meter and the desktop overlay.

Answer from a terminal#

lockpin approve and lockpin deny answer a call held by a Lockpin on this machine, without the meter.

List the held calls:
```
lockpin approve list
```

Allow one, by its ID:

lockpin approve q3                    # the budget rises by what the call needs
lockpin approve q3 -budget            # or as Raise budget does
lockpin approve q3 -raise 2           # or by $2, at least what the call needs

Or refuse it:

lockpin deny q3                       # the held call gets its 402 now

They talk to the meter on -listen (127.0.0.1:8787), then a node’s 127.0.0.1:8790. Give -admin-listen ADDR for another, -ledger FILE to name the ledger whose control token they read, and -json on list for JSON.

Answer from a phone or chat#

With -ask-remote, a call held at its task’s budget is also asked about in Slack, Teams, ntfy and on paired phones, with Stop, Allow this call and Raise budget. Answers come back through a relay that sees only the question number and the answer, signed by your machine. A yes from a phone, Slack or Teams is marked “not confirmed with a passkey” in the alert. See Alerts and phone approvals.

Answer without a desktop#

On a server, a container or a CI node, nobody watches the meter. Start Lockpin with -ask-headless so it holds calls at the cap anyway, and answer with lockpin approve and lockpin deny:

lockpin -ask-headless
kubectl -n lockpin exec deploy/lockpin-node -- /lockpin approve list

A headless Lockpin takes an answer only with its control token, which it keeps beside its ledger (LEDGER.control) for its own account. Run lockpin approve as that account.
Headless, an agent’s X-Lockpin-Budget-Usd header may only lower a task’s budget. A raise comes only from an answer, or from the meter with the control token.
Unanswered, a held call waits the whole -ask-at-cap, then gets its 402.
In team mode, -approvals-api serves the held calls on the main port to an owner or workspace admin key, and an approval webhook (LOCKPIN_APPROVAL_WEBHOOK_URL) can post each question to a bot. See Run a team node.

Loop questions#

When a task looks stuck in a loop and someone is watching, Lockpin holds the call with Let it run and Stop through the same banner, VS Code notification and overlay card. Stop refuses that one call with a 429; no answer lets it go on. From a terminal, lockpin approve ID lets it go on and lockpin deny ID stops it. See Loop checks and drift.

Who decided#

Every answer is a decision line in the ledger, with the question, the outcome, what the budget rose by and who decided: this machine (the meter, VS Code, the overlay), this machine, claimed: lockpin approve (user NAME) (the name is unchecked), key "NAME", webhook answer token, or relay (...). A hold that ends with no answer is recorded as timeout or client_left. lockpin ledger export carries these lines.

Pause and resume the cap#

A pause lets calls pass through without a cap for a while. Each call is still counted.

lockpin pause 15m
lockpin resume

pause takes 15m, 1h or 8h (1 minute to 8 hours, at most 8 hours a day). It ends by itself, or at resume.
A person confirms the pause at a terminal: it cannot be scripted.
The meter’s Detailed view offers 15 min and 1 hour at the top, and Settings (the gear) keeps the same buttons and Resume now while a pause is on.

Turn asking off#

lockpin -ask-at-cap 0

With 0, a call that does not fit its task’s budget is refused at once. For one key in team mode, lockpin keys set NAME -task-cap hard does the same for that key’s tasks.

Verify#

Give a test task a small budget with the X-Lockpin-Budget-Usd header and keep the meter open.
Make calls until one would pass the budget. The banner appears in the meter.
Run lockpin approve list in a terminal: the held call is listed with its ID.