writ policy

An organization policy sets an outer limit for supported enforcement modes 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.

A redaction pointer can select only these data surfaces:

• a descendant of /arguments or /provider_arguments;
• a descendant of /action/arguments, /action/provider_arguments, /request/arguments, or /request/provider_arguments;
• /content or one of its descendants;
• /result or one of its descendants.

Writ rejects a pointer to a record control. This includes an ID, event, argument digest, approval event, call sequence, or organization policy hash. These fields must remain intact for correlation and approval replay.

Normal tool-call entries omit exact provider arguments. They keep a digest. When Writ creates an explicit approval request, that request can contain the exact provider arguments after redaction. Add pointer rules for sensitive fields that can occur in approval arguments.

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 that provide complete pre-tool coverage. Claude currently provides this coverage. A native hook stops the call when a project has an organization policy but the selected agent lacks this coverage. This prevents an unseen tool source from bypassing the allowlist or approval rule.

The policy also applies to attached writs, local and remote MCP proxies, and writ issue runs. Its hash and source state are written to each new run.

The model gate cannot apply organization policy at its model-only boundary. writ gate refuses to start while the project has an organization policy.

Every active layer must allow a tool call. A project or connection can narrow an organization rule. It cannot widen one. An attached writ denial and an organization allow-list denial are hard. A normal connection approval cannot replace either denial.

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.