This page explains what happens when an agent asks for something its policy marks ask: the request waits for you, you approve or deny it, and the agent goes on. For a job over several items or sites, the agent asks once for a task instead.
An approval
When the policy says ask, the request waits. On the command line the agent gets exit code 4, with the commands to approve and to wait:
klav agent totp klav://Personal/General/GitHub --reason "Finish signing in to GitHub to open the release PR"klav: waiting for approval 800d8b83-…: `totp` needs the person's approval: they approve it with `klav approval approve 800d8b83-…`; wait for it with `klav approval wait 800d8b83-…`, then retry with this approval (`--approval 800d8b83-…` or approval_id)Through klav mcp, the tool waits up to 60 seconds, then answers status: "pending" with approve_command, wait_command and next.
You decide
You see the request in the Mac app’s Requests, as a notification on the iPhone, in the extension’s popup, or in a terminal:
klav approval listID STATUS AGENT WANTS ON SITE (AGENT SAYS) REASON TASK
800d8b83-… pending claude-code totp klav://Personal/General/GitHub Finish signing in to GitHub to open the release PRklav approval approve prints the whole request before it signs anything. The site and the reason are marked “according to the agent”, because the agent wrote them:
klav approval approve 800d8b83 --for 15mRequest 800d8b83-…
agent: claude-code (bfa85942…)
wants: totp
on: klav://Personal/General/GitHub
site: none given
reason: Finish signing in to GitHub to open the release PR (according to the agent)
decide: before 2026-11-12 23:13:00Z
Approved for 15 min: claude-code may `totp` klav://Personal/General/GitHub.- Once: without
--for, the approval is good for one request that matches it (same permission, item and site), within 10 minutes. - For a while:
--for 15m(at most24h) lets the agent repeat the same action on the same item without asking. - Deny:
klav approval deny <id>. - In your commands (
klav approval approveanddeny,klav task show,approve,denyandend), an ID can be shortened to its first 6 characters or more. The agent’s commands (klav approval wait,--approval,klav agent task wait,showandend) need the full ID, as Klav printed it. - Approving asks for Touch ID, Face ID or your master password. Denying asks for nothing.
- Your account signs the decision, so the server can’t approve for you. If the request changes while you are looking at it, nothing is signed.
The agent goes on
The agent waits in the background, so you don’t have to tell it you decided:
klav approval wait 800d8b83-… --json{"approval_id":"800d8b83-…","expires_at":…,"lease_until":…,"status":"approved","used":false}It exits with 0 when you approve, 5 when you deny, and 6 when the request expires; 4 means nobody decided before --timeout. Then the agent repeats the same request with --approval <id> (or approval_id in klav mcp). An approval for another action, item or site doesn’t work.
Tasks
Before a job that touches several items or sites, an agent asks for one task, and you approve it on one card instead of one request at a time. With klav agent, the task is a file:
task = "Download October's invoices"
reason = "Reconcile the month's expenses"
duration = "2h"
[[access]]
ref = "klav://Invoices/General/AWS"
permissions = ["fill", "totp"]
[[access]]
ref = "klav://Invoices/General/Telmex"
permissions = ["fill"]
domain = "telmex.com"klav agent task request task.toml --waitThrough klav mcp, it is request_task with the same fields.
durationis between5mand24h, from your approval. A task holds 1 to 50 items.- A task can ask for
fill,totp,inject,update,passkeyandrotate.revealanddeletenever go in a task. passkeyandrotatework only inside a task.
You review the card
klav task list
klav task show <id>
klav task approve <id> [--without REF[:permission]]… [--for 1h]
klav task deny <id>The card comes from your own vault, not from what the agent says: each item’s title, username and sites. Klav marks what you should look at:
- an item whose sites don’t match the
domainthe agent gave can’t be approved; fillon a login with a one-time code addstotp, marked “added by Klav”: for that agent, two-factor stops being a second factor;- what your policy denies with a
denyrule can’t be approved.
--without leaves out an item or one of its permissions; --for makes the task shorter, never longer. The Mac app, the iPhone and the popup show the same card, where you uncheck what you don’t want.
While it runs
- Inside the task, the agent’s
fill,totp,injectandupdateon what you approved don’t ask again, even where the policy saysask. - A request outside the task follows the usual path. You can approve it once, or add it to the task with
klav approval approve <id> --add-to-task(“Add to the task” in the apps): it ends when the task ends. - A task ends when its time is up, when the agent ends it (
end_task), when you end it (klav task end <id>, “End task” in the apps), or when you revoke the agent. - Each agent can have at most 5 pending and 10 running tasks. A request nobody decides expires after 10 minutes.