# Hold a call for a person

The command kubectl apply waits for a holder of an approver role, and the agent runs it once after the approval.

- Who: Admin, and lena as the approver
- Where: Console or strazactl, and the agent's machine

In short: A hold is an allow that needs approval first: a rule with `mode: approve` waits for a holder of a named approver role. The hook denies the first call with a reference, and the same call passes once after the approval. A timeout, a no or an unreachable approval service ends in a deny.


A hold is an allow that needs approval first. A rule with `mode: approve` lets the call through only after someone in a named approver role says yes. The call is denied when the wait times out, when the decider says no, or when the approval service is unreachable. The agent is told that the call is waiting, where a person decides, and that it may retry the exact same call once the decision lands. Because the wait is bounded, a request nobody answers ends in a deny after minutes.

Diagram: On the gateway a held call stays open while a person decides. In a hook the first call is denied with a reference, and the retry of the same call passes once after the approval.

On the gateway a held call stays open while a person decides, 90 seconds by default, and goes on when approved. In a hook the first call is denied with a reference, and the retry of the same call passes once after approval.

1. The agent calls a tool. On the gateway it also states why, in a required justification field.
2. The rule says a person decides. The gateway keeps the call open, 90 seconds by default. The hook answers at once with a deny and a reference.
3. The agent's sponsor, or a holder of an approver role the rule names, decides in the console, on a phone, on the self-service page or in Slack.
4. Approved: the held gateway call goes on to the MCP server. The hook's retry of the exact same call passes once, within 60 seconds by default.

## Before you start

- An administrator's console sign-in, or `strazactl` on an admin API token that holds read and write on the `identity` and `policy` areas and read on the `approvals` and `audit` areas, minted in the console as [Mint an admin API token](https://docs.straza.ai/guides/console/settings/index.md#mint-an-admin-api-token) shows.
- The `local-tools` allow rule from [Your first deny](https://docs.straza.ai/guides/write-policy/first-deny/index.md) live for your role, and an enrolled machine held by a user of that role, here `dana`.
- A person who decides, here `lena`.

## Create the approver role

Approvers are a role of kind `approver`. It carries the right to decide and never a tool, and it is the only kind a policy may name in `approve.roles` besides `straza-admin`. In a deployment fed by your identity manager, the assignment comes over SCIM instead.

In the console:

Click path in the console: "Roles" › "New role" › "Approver role" › "Next" › "Save and publish"

![New role with the kind Approver role and the name release-approvers](https://docs.straza.ai/shots/role-new-approver-dark.png)

New role with **Approver role** picked and the name `release-approvers`.

Type `release-approvers` under Name before **Next**. Then assign it to the person who decides:

Click path in the console: "Roles" › "release-approvers" › "Assign to a user" › "lena" › "Assign role"

With the CLI:

Terminal, administration:

```sh
strazactl roles create release-approvers --kind approver --description "Decides approval requests raised under local-tools"
strazactl assign release-approvers --user lena
```

```text
created role release-approvers (01a0e996-0900-76b1-9ad1-5224e9fc1f79)
assigned release-approvers to lena
```

## Write the rule

In the console:

The New policy wizard writes this rule whole, one question per step:

Click path in the console: "Policies" › "New policy" › "Needs approval" › "Next" › "A role" › "local-tools" › "Next" › "Shell command"

1. Under Command patterns, type `kubectl apply *` and press **Add**, then **Next**.
2. Under Who decides, pick **An approver role** and `release-approvers`. Under How, pick **A hold, up to** and set 5 minutes. Type the reason under Reason the agent reads, then press **Next**.
3. On Review, name the set `kubectl-apply-hold` and press **Save and publish**, then **Publish**.

![New policy, step How, with release-approvers deciding and a hold of up to 5 minutes](https://docs.straza.ai/shots/policy-new-how-dark.png)

The Who decides step, with `release-approvers` deciding and a hold of up to 5 minutes.

The wizard stores the set at priority 150, names the rule itself, and leaves the retry window at its default of 60 seconds. Later records name that rule where this page shows `hold-kubectl-apply`.

With the CLI:

Save this as `kubectl-apply-hold.yaml`:

```yaml
apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: kubectl-apply-hold
  description: Hold a cluster change until a release-approvers holder decides
spec:
  priority: 10
  match:
    roles: [local-tools]
  rules:
    - id: hold-kubectl-apply
      events: [tool.pre]
      tools: [shell.exec]
      command:
        allowPatterns: ["kubectl apply *"]
      effect: allow
      mode: approve
      approve:
        roles: [release-approvers]
        timeoutSeconds: 300
        retryTTLSeconds: 300
      reason: "Straza: kubectl apply needs approval before it runs"
```

Terminal, administration:

```sh
strazactl policy apply -f kubectl-apply-hold.yaml
strazactl policy activate kubectl-apply-hold
```

```text
applied kubectl-apply-hold (Off, 01a0e996-09ff-7256-b67a-5a49d2f0f2ac)
published kubectl-apply-hold, it is live now; new snapshot 0094bf062e44cc47e98b921d390041e930b728de6b540e0f37785593bb29ff38
```

`priority: 10` only orders which rule a decision is reported under when several plain allows fire, and an approval record always names the approve rule.

The rule allows `kubectl apply` and marks that allow as needing approval. `timeoutSeconds` bounds how long the request stays open, 90 seconds by default and at most 3600. `retryTTLSeconds` bounds how long the agent has to retry after the approval, 60 seconds by default and at most 600. Five minutes for the wait gives the approver time to reach the console. [Lifetimes and timeouts](https://docs.straza.ai/reference/lifetimes-and-timeouts/index.md#approvals) lists every approval window with what happens when it runs out.

Leave the approver role out and the request routes to the person behind the agent. For an agent, that is its sponsor, the accountable person your identity manager records on it. A person who runs their own agent and has no sponsor confirms the call themselves, on their enrolled phone or browser. When a person does have a sponsor, that sponsor decides. An agent with neither an approver role on the rule nor a usable sponsor is denied at request time with a reason that names the fix, because a request nobody is told about could only expire.

## Raise the request

CLI only: The call comes from dana's enrolled machine, where the hook decides it.

Start a new session so the snapshot is current, then run the gated command. The hook never waits, because harnesses kill a slow hook on their own clock. Instead the server opens a pending record, and the hook answers with a deny that carries the reference, the roles that were notified and where a person decides.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"PreToolUse","session_id":"c3f1b8d2-5e7a-4f60-9b3c-1a2d4e6f8a03","cwd":"/home/dana/work","tool_name":"Bash","tool_input":{"command":"kubectl apply -f deploy/app.yaml"}}' | straza hook --harness claude-code; echo "exit $?"
```

```text
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Straza: approval requested (notified roles [release-approvers]); a person decides on the self-service page (http://localhost:8420/self-service/), the console, or an enrolled phone. Retry this exact call after approval (ref 01a0e996-3036-7f10-8c30-b2317bb9f09c)"}}
Straza: approval requested (notified roles [release-approvers]); a person decides on the self-service page (http://localhost:8420/self-service/), the console, or an enrolled phone. Retry this exact call after approval (ref 01a0e996-3036-7f10-8c30-b2317bb9f09c)
exit 2
```

An MCP tool call through the gateway behaves differently: the gateway holds the call open and returns the result when the decision lands. The wait is capped at 120 seconds by `approval.gatewayHoldSeconds`, after which the model gets a structured pending reason and the same retry path.

## Decide

This step is lena's. The console, the self-service page and an enrolled phone decide the same record, and the first decision wins.

In the console:

An approver who is also an administrator decides in the console. Approvals opens on the Waiting filter, and a row opens the request with its parameters and who decides.

Click path in the console: "Approvals" › "Requests" › "kubectl apply -f deploy/app.yaml" › "Approve" › "Approve request"

![The Approve dialog with an optional reason and the button Approve request](https://docs.straza.ai/shots/approval-approve-dark.png)

The Approve question for dana's `kubectl apply`, with the optional reason.

A reason is optional, under `Reason, optional`. An approver who is no admin decides on the self-service page instead. Once the browser is enabled under This browser, which needs the role `straza-enroll-browser` or `straza-admin`, its Requests tab lists the calls that are theirs to decide. Until then the tab says `This browser is not enrolled to decide.` and lists nothing. [Approve in the console](https://docs.straza.ai/guides/approve/console/index.md) shows that screen in detail.

With the CLI:

Administrators see the pending record at once. The wide view adds the redacted call preview and says exactly what an approval covers.

Terminal, administration:

```sh
strazactl approvals list --wide
```

```text
01a0e996-3036-7f10-8c30-b2317bb9f09c  [pending]  dana  shell.exec: kubectl apply -f deploy/app.yaml
  roles: release-approvers   expires: in 5m0s
  parameters (preview):
    kubectl apply -f deploy/app.yaml
  preview only; this approval covers the exact call (sha256:d43b1452c5b4)
```

This listing is trimmed to dana's request. strazactl does not decide, because a decision must name the person who made it and a token is not one. lena decides in the console under **Approvals**, on the Requests tab of the self-service page, or on her phone, as the console form of this step shows.

## Retry the call

CLI only: The retry comes from dana's machine. The records are read in either form.

Retrying the identical call now succeeds. The approval left one run of the call, keyed on the session, the rule and the call's fingerprint, so a different command, a different session or a second run of the same command raises a new request.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"PreToolUse","session_id":"c3f1b8d2-5e7a-4f60-9b3c-1a2d4e6f8a03","cwd":"/home/dana/work","tool_name":"Bash","tool_input":{"command":"kubectl apply -f deploy/app.yaml"}}' | straza hook --harness claude-code; echo "exit $?"
```

```text
{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}
exit 0
```

The approval writes a record of its own for each phase: the request, the resolution and the retry that used it. That retry also writes its allow. The resolution names the decider and the channel, and a decision made in the console is recorded under the channel `console`.

In the console:

Click path in the console: "Audit" › "Lens" › "approvals"

![The Audit page under the lens approvals, with the request and decision records](https://docs.straza.ai/shots/audit-approvals-dark.png)

The `approvals` lens, with one record for each phase of dana's requests.

With the CLI:

Terminal, administration:

```sh
strazactl audit tail --limit 30
```

```text
#233 [dana] {"data":{"approvalId":"01a0e996-3036-7f10-8c30-b2317bb9f09c","lane":"hook","phase":"request","rule":"hold-kubectl-apply","set":"kubectl-apply-hold","state":"pending","summary":"shell.exec: kubectl apply -f deploy/app.yaml"},"type":"straza.audit.approval"}
#235 [dana] {"data":{"approvalId":"01a0e996-3036-7f10-8c30-b2317bb9f09c","channel":"console","decidedBy":"01a0e993-ed60-7df4-915f-8c00baa3accd","lane":"hook","phase":"resolution","rule":"hold-kubectl-apply","set":"kubectl-apply-hold","state":"approved","summary":"shell.exec: kubectl apply -f deploy/app.yaml"},"type":"straza.audit.approval"}
#236 [dana] {"data":{"approvalId":"01a0e996-3036-7f10-8c30-b2317bb9f09c","channel":"console","consumedAt":"2026-09-28T19:55:46Z","decidedBy":"01a0e993-ed60-7df4-915f-8c00baa3accd","lane":"hook","phase":"consumed","rule":"hold-kubectl-apply","set":"kubectl-apply-hold","state":"approved","summary":"shell.exec: kubectl apply -f deploy/app.yaml"},"type":"straza.audit.approval"}
#238 [dana] {"data":{"command":"kubectl apply -f deploy/app.yaml","effect":"allow","event":"tool.pre","reason":"Straza: approved by lena (ref 01a0e996-3036-7f10-8c30-b2317bb9f09c)","ruleId":"hold-kubectl-apply","setName":"kubectl-apply-hold","tool":"shell.exec"},"type":"straza.audit.tool"}
```

This listing is trimmed to the four records and to the fields that matter here.

## Let the requester confirm instead

A rule with `mode: confirm` holds the call until the person driving the session confirms it themselves. It defends against an agent's mistake and a prompt injection, and deliberately not against that person. Only the requester decides, and nobody else can, `straza-admin` included. The decider is not configurable, so the rule names no approver role.

```yaml
apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: kubectl-delete-confirm
  description: The person at the session confirms a kubectl delete before it runs
spec:
  match:
    roles: [local-tools]
  rules:
    - id: confirm-kubectl-delete
      events: [tool.pre]
      tools: [shell.exec]
      command:
        allowPatterns: ["kubectl delete *"]
      effect: allow
      mode: confirm
      approve:
        timeoutSeconds: 300
      reason: "Straza: kubectl delete needs your own confirmation before it runs"
```

Terminal, administration:

```sh
strazactl policy validate -f kubectl-delete-confirm.yaml
```

You should see: `kubectl-delete-confirm.yaml: PolicySet "kubectl-delete-confirm" OK (1 rules, priority 0)` and the note about roles that every validate prints.

Its `approve` block keeps the timeouts, the class and the binding of a hold. The New policy wizard has no confirm outcome, so in the console the rule goes in through Write YAML instead, and its card reads `The requester confirms it themselves. Change it on the YAML tab.`

When the rule fires, the hook denies the call at once with a reason that starts `Straza: this call needs the requester's confirmation, on their enrolled phone, or the self-service page under This browser`, followed by the page's address and the reference. Once the person confirms there, the agent retries. An autonomous agent has no person to confirm, so the same rule denies its call outright with `Straza: rule kubectl-delete-confirm/confirm-kubectl-delete requires the requester's confirmation; an autonomous session has no human to confirm`.

If this fails:

`mode confirm may not set approve.roles (the requester is the decider)`
: Remove `roles` from the `approve` block, or use `mode: approve` for a rule that someone else decides.

## Hold a tool of an MCP server

A hold on an MCP tool is the same rule with `tools: [mcp.call]`, the server in `apps` and the tool in `toolNames.allow`, as [Access per role](https://docs.straza.ai/guides/serve-mcp-apps/catalogs-per-role/index.md#gate-a-tool-in-policy) writes it. `approve.binding` decides what an approval of an MCP call covers. `call`, the default, covers the call's arguments, so any real change in them raises a new request. `binding: tool` covers the server and the tool alone, a deliberate loosening for a frequent tool whose arguments change on every call. [PolicySet grammar](https://docs.straza.ai/reference/policyset-grammar/index.md) lists every key of the `approve` block.

## Undo

In the console:

Click path in the console: "Policies" › "kubectl-apply-hold" › "More" › "Turn off" › "Turn off"

![The Turn off confirmation on the kubectl-apply-hold policy page](https://docs.straza.ai/shots/policy-turn-off-dark.png)

The question that turns kubectl-apply-hold off, which says what stops governing.

A request that is still waiting is denied from its row with **Deny**, then **Deny request**, which is final for that request. The same call in the same session is then refused, without a new request, until the request's decision window ends.

With the CLI:

`strazactl policy deactivate kubectl-apply-hold` turns the set off and compiles the snapshot again. A request that is still pending is denied in the console under **Approvals**, which is final for that request.

## Limits

Five limits apply before the first real use:

- On a rule that names roles, the requester never decides their own request unless the rule says `selfApproval: true`, and an autonomous agent never gets that right whatever the rule says.
- An AI agent never decides anything, even if an approver role was assigned to it by mistake.
- A person who may decide their own request decides it on their enrolled phone, or on the self-service page under This browser, because those sign the decision with the device's own key. The console refuses it and says where to go, unless the operator set `approval.unsignedOwnDecisions` to true in the server config and accepted that an agent on the person's machine can then approve its own calls. An agent that can read an admin API token holding `approvals:write` can mint an enroll token for the person and decide with a device of its own, which is one more reason never to put a token where an agent runs, as [Known limits](https://docs.straza.ai/security/known-limits/index.md) says.
- A session that a coding harness checked in never decides a request for anybody.
- An approve rule only ever marks an allow. A deny from any set still wins, so a command that another set denies is denied, and no request opens.

## Next

When the wait should be a day rather than minutes, use a [ticket](https://docs.straza.ai/guides/write-policy/tickets/index.md).


Walked on v1.1.0 on 2026-09-28, except the decision in the console, which replaced the strazactl decision of the walk. Linux, against the enterprise demo stack under the enterprise profile, with the hook events fed to straza hook by hand in a Linux container enrolled as dana. The waiting row was read in the console and on the self-service page in a headless browser, and the approver decided with strazactl from her own login, which reaches the endpoint the console decides on. strazactl no longer signs in or decides, so a person now decides in the console, on the self-service page or on a phone. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

