writ policy

An organization policy sets an outer limit for every Writ mode in a project. It can restrict tool names, require approval, lower task bounds, and add record redaction rules.

A project can make these rules narrower. It cannot make them wider.

1. Create a signing key

Run this step in the policy publisher’s environment:

writ policy keygen --out keys/organization-policy.key.json

The command creates a private key and a public key. Keep the private key with the publisher. Distribute the public key through a trusted channel.

2. Write one policy release

Create an unsigned JSON file:

{
  "version": 1,
  "organization": "Example Org",
  "sequence": 12,
  "issued_at": "2026-08-28T10:00:00Z",
  "expires_at": "2026-09-04T10:00:00Z",
  "rules": {
    "allowed_tools": ["read", "search", "edit", "mcp__github__*"],
    "require_approval": ["edit"],
    "redact": ["/arguments/customer_email"],
    "limits": {
      "iterations": 40,
      "cost_microdollars": 2500000,
      "wall_clock_ms": 1200000,
      "max_files": 10,
      "max_changed_lines": 500
    }
  }
}

allowed_tools and require_approval match normalized or provider tool names. Redaction values are exact JSON Pointers. A zero or omitted limit leaves that value to the project.

Increase sequence for every new release. Do not reuse a sequence with different content.

3. Sign the release

writ policy sign organization-policy-12.json \
  --key keys/organization-policy.key.json \
  --out published/organization-policy-12.signed.json

Publish the signed JSON over HTTPS, or place it at a local absolute path.

4. Set the project source and trust key

writ policy set \
  --source https://policy.example.com/writ/current.json \
  --trust keys/organization-policy.key.public.json

This writes the project policy configuration under ~/.writ/projects/<project-id>/. Writ fetches and verifies the policy before it saves the configuration.

Use a local signed file when needed:

writ policy set \
  --source published/organization-policy-12.signed.json \
  --trust keys/organization-policy.key.public.json

5. Check the effective policy

writ policy status
writ check task.yaml --effective --explain

status prints the organization, sequence, expiry, policy hash, signer, and source state. check --effective applies organization bound ceilings to the explained writ.

Runtime behavior

The policy applies automatically to native agent hooks, local and remote MCP proxies, and writ issue runs. Its hash and source state are written to each new run.

Remote policies use a short project cache. If the source is unavailable, Writ can use a verified cached policy until its signed expiry time. It rejects an expired cache, a lower sequence, a changed bundle at the same sequence, an untrusted signature, or a source that is not HTTPS.

Writ denies an action when a required organization policy cannot be verified.