claims

Claims-based authorization for agents and operations. Grant, revoke, and verify permissions for secure multi-agent coordination. Use when: permission management, access control, secure operations, authorization checks. Skip when: open access, no security requirements, single-agent local work.

Claims Authorization Skill

Purpose

Claims-based authorization for secure agent operations and access control.

Claim Types

Claim	Description
`read`	Read file access
`write`	Write file access
`execute`	Command execution
`spawn`	Agent spawning
`memory`	Memory access
`network`	Network access
`admin`	Administrative operations

Commands

Check Claim

npx claude-flow claims check --agent agent-123 --claim write

Grant Claim

npx claude-flow claims grant --agent agent-123 --claim write --scope "/src/**"

Revoke Claim

npx claude-flow claims revoke --agent agent-123 --claim write

List Claims

npx claude-flow claims list --agent agent-123

Scope Patterns

Pattern	Description
`*`	All resources
`/src/**`	All files in src
`/config/*.toml`	TOML files in config
`memory:patterns`	Patterns namespace

Security Levels

Level	Claims
`minimal`	read only
`standard`	read, write, execute
`elevated`	+ spawn, memory
`admin`	all claims

Best Practices

Follow principle of least privilege
Scope claims to specific resources
Audit claim usage regularly
Revoke claims when no longer needed

Cross-Host Work Claims (federation, v3.40.0+)

Distinct from the authorization claims above: work claims coordinate ownership of a task or resource across agents, and now propagate across a cross-host federation so a claim made on one node is visible to the whole swarm.

Runtime tools (local ledger)

Tool	Purpose
`claims_claim`	Take ownership of an issue/resource (with optional TTL).
`claims_release`	Give up a claim you hold.
`claims_handoff` / `claims_accept-handoff`	Transfer a claim to another agent.
`claims_steal` / `claims_mark-stealable`	Work-stealing for stalled claims.
`claims_status` / `claims_list`	Inspect current ownership.

Federated (cross-host)

Publish claim events into a federation room (federation_bbs_publish) so ownership converges across hosts. Message types: ClaimIssued / ClaimReleased / ClaimHandoff / ClaimAck.

Rules: one owner per resourceId; first valid ClaimIssued wins (ties → earliest ts, then smallest from); ClaimReleased or expired TTL frees it; ClaimHandoff only from the current owner; a coordinator posts ClaimAck naming the authoritative owner.

Before shared work: claim, sync, and proceed only if you are the acknowledged owner. When a claim must be both cross-host visible and runtime-enforced, mirror the two — publish the federation claim message and call claims_claim. See the cross-host-federation skill (ruflo-bbs-federation plugin) for the transport.

Scoping a claim stream to a channel (ADR-386)

By default every claim event lands in the shared swarm stream, where any relay member reads it. To keep a team's ownership ledger separate — or unreadable by the rest of the relay — publish claim messages into a channel instead:

npx ruflo federation channel --action create --name platform-team --visibility private
npx ruflo federation channel --action grant --channel prv:<hex> --pubkey <teammate 64-hex>
npx ruflo federation channel --action publish --channel prv:<hex> \
  --type ClaimIssued --payload '{"resourceId":"repo/foo","ttlSeconds":7200}'
npx ruflo federation channel --action read --channel prv:<hex>

Reduction rules are unchanged; only the audience changes. Two caveats before relying on it: a private channel hides content but not metadata (the relay still sees who published and when), and a claim nobody outside the channel can read cannot arbitrate against a claim made outside it. If ownership must be swarm-wide, keep it on the open stream. See the open-federation skill for channel mechanics.