Held calls and approvals

When an agent asks for something outside its Card, and the Card says Ask, KIFF holds the call for an authorized approver. Nothing runs until someone who may approve answers. If nobody answers before the hold expires, the call is refused; silence never approves. A Card that says Stop refuses the call instead, and nothing is held.

Where the owner hears about it

A held call reaches the owner in three places. All three lead to the same page, and the answer is given there.

  1. Needs you, in KIFF Cloud, and the bell. Every held call is listed with the agent, the action, the Card and how far over it is.
  2. Email. One email per held call, to the account owner, with what the agent wanted, which Card, how far over, and when the hold expires. Each button opens the call’s Needs you page.
  3. The agent’s chat, for clients KIFF has verified (Claude Code 2.1.287 or later). The chat shows a prompt to open the Needs you link. This is on by default for a personal account and off for a company’s, where the person running the agent is usually not the owner. Change it in Settings → Account → Held calls.

Who can answer

A signed-in person with approval authority, or an external approver explicitly granted bounded authority by an admin.

External approval is optional behind Ask. Connect a separate approver from the Card. An unavailable service or an out-of-scope request leaves human review available until the original deadline. External answers record the service’s name and reason separately from the tool’s outcome.

  • The email and the chat only carry a link to the Needs you page. Neither can approve anything, so a forwarded email or a copied link answers nothing without a signed-in session that may approve.
  • The agent’s key cannot answer, and a “yes” typed in the chat is not an approval.
  • KIFF approval links always go to app.kiff.dev. A link to answer from anywhere else is not from KIFF.

The three answers

  • Approve once: waives the reviewed per-action threshold for this call only. Collection charges its full quantities against every applicable Card. Approval cannot waive a cumulative ceiling.
  • Revise the Card: a cumulative ceiling needs a separate management decision. Review extra room shows the quantity, measure and fixed end time before confirmation. The default is This window only; an end date or a permanent base revision must be selected explicitly. Recorded usage stays in place when the allowance expires.
  • Reject: the call is refused, and the agent is told not to retry it.

What the agent does

The agent gets a result that says the call is waiting for the owner, with the link and when the hold expires. Nothing has been sent to the tool.

To get the answer, the agent retries the same call: the same tool, the same arguments, and the same kiff_operation_id if it used one. Through the MCP gateway, an approved call is then forwarded once; a rejected or expired one is refused. A program can read the same facts in the result’s _meta (state, retry, retry_after_s, hold_expires_at).

If other spending uses the available room before collection, the call stays Approved, waiting for room (approved_no_room). It has not been sent or refused. The owner can revise the applicable budget; collection then rechecks all Cards under the authorization locks. A new or tighter per-action threshold needs another review, rather than inheriting the earlier waiver. Previous approvals remain in the record.

Read the answer without executing the call

The gateway’s read-only kiff_pending tool lists this credential’s held, sending and unknown calls. A held entry includes the owner’s answer, the original tool arguments, and the kiff_operation_id used to collect it. Reading the list sends nothing to the business tool and uses no approval. Follow next_cursor as cursor to read older pages.

An answer of approved_no_room in kiff_pending is not a collectible approval (owner_answer on the API’s hold reads). Keep the original arguments and operation id and wait for room. An unavailable answer means the read failed, not that the owner refused.

Collect an approved call with the same tool and original arguments. Use its original operation id, or KIFF’s listed id if the original call had none. The latter lets the agent collect that held call after the usual 10-minute identical-call window. An unknown outcome is for reconciliation: the gateway does not automatically resend it.

Bring the answer back into Claude Code

The optional kiff plugin reads kiff_pending while this session has a held call. It shows the owner’s answer once and submits a turn telling the agent; the agent decides whether to collect an approved call. The plugin does not approve or execute the call itself.

The plugin shows an approved call waiting for room without starting a collection turn. When the call becomes collectible, the usual single notice and turn apply. After background checks stop, /kiff performs another read; it does not resend the business action.

If permissions stopped the reads, allow kiff_card and kiff_pending and run /kiff again. Checks continue through older pages and preserve recovery when KIFF cannot read the owner’s answer. An answer given in time still counts when read after an outage. Install steps and exact permission rules are in the plugin guide.

Approval and the tool’s outcome

Approval records who authorized the request. It does not establish that the tool performed it. KIFF records the tool’s reported outcome beside the authorization decision:

  • Tool reports success: the delivered call has a successful response. This is what the tool reported, rather than independent verification of the external action.
  • Tool reports an error: the call was authorized and delivered, but the tool returned an error. Do not describe it as done or assume that the error proves there were no partial effects.
  • Outcome unknown: the call was sent but its response was lost or timed out. Reconcile with the tool before deciding what to do next.
  • Outcome not recorded: an older call has no explicit outcome record. While its stored tool response is retained, KIFF uses that response; after it is purged, an approved call is shown with an outcome-not-recorded warning. Missing evidence does not establish success.

For example, a person can approve a €25 refund and the provider can refuse it because only €20 remains refundable. The approval and the refusal both belong in the record. Recording the outcome does not itself restore the Card’s budget.

How long a call waits

Each Card sets how long a held call waits: 10 minutes by default, from 1 minute to 7 days. A held call never runs on silence:

  • if nobody answers in time, the call is refused and nothing is sent;
  • a late answer is not accepted;
  • the agent has to ask again, as a new call.

The prompt in the chat does not extend this. An approval given before expiry remains valid when the agent collects it later; a late read is different from a late approval.

Next