OPopal
agent-activity

Set the agent kill switch

Changed on

Prototype (AG-297). Turns the org-level agent kill switch on or off. Admin only.

While it is on, Opal answers every PreToolUse hook POST to /agent-activity with a deny decision, so a cooperating Claude Code client stops running tools.

It is not a security boundary, and it fails open. It reaches only clients that are configured to POST to /agent-activity and that honour the answer; a client on a non-default base URL, an older build, or with no hook deployed is unaffected. If Opal is unreachable or slow the tool call proceeds, because Claude Code treats a failed PreToolUse hook as a non-blocking error by design.

Activation is always time-bound: duration_minutes is capped, and an activation that reaches expires_at stops denying on its own.

put/agent-kill-switch

Request

  • Base URL
    https://api.opal.dev/v1
  • Auth
    HTTP bearer

Request body

activeboolean required

True denies agent tool calls for this organization; false lifts the denial.

duration_minutesinteger

How long the denial lasts, from now. Ignored when active is false. Capped server-side - a kill switch with no end is how an organization discovers months later that its engineers have been quietly working around it.

reasonstring

Why. Shown verbatim to the developer whose tool call is denied, so write it for them rather than for the audit log - it is the only explanation they get.

Response

The state of the kill switch after the change.

activeboolean required

Whether agent tool calls are being denied right now. This is the field to read; it already accounts for expiry.

activated_atstring date-time

When the latest activation was turned on. Absent if it never has been.

activated_by_user_idstring uuid

The admin who turned it on. Absent when that user has since been hard-deleted - the activation record outlives them deliberately.

expires_atstring date-time

When the latest activation stops denying on its own. In the past for an activation that already ran out.

deactivated_atstring date-time

When the latest activation was turned off before its expiry, either by an admin or by being superseded. Absent when it ended at expires_at, or has not ended.

reasonstring

The admin's stated reason. Not an internal note - it is shown to the developer whose tool call is denied, in their own terminal.

Changes