Held calls and approvals

When an agent asks for something outside its Card, and the Card says to hold such calls, KIFF holds the call and asks the owner. Nothing runs until the owner answers. If nobody answers in time, the call is refused.

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

Only the owner, or an admin, signed in to KIFF Cloud.

  • 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 the owner’s session.
  • 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: this call only. The Card stays as it is, and its balance does not move.
  • Change the card to allow it: raises the Card’s limits just enough for this call, and for everything after it. The change is recorded on the Card’s statement.
  • 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).

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.

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.

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