Capabilities

A capability is a named, narrow power an agent can be granted, such as mail.send to specific colleagues or forge.write on specific repos through pull requests. You list capabilities in the agent's personnel file instead of writing raw allow and deny rules.

capabilities:
  - vault.write
  - mail.send: { to: ["*"] }
  - mail.read
  - office.read
  - forge.read: { repos: ["northwind-handbook"] }
  - forge.write: { repos: ["northwind-office"], via: pull_request }
  - hr.propose
  - approval.request
  - net.egress: ["api.anthropic.com"]
  - shell: { profile: basic }

The full list, with what each one compiles into, is in the capability catalog.

One declaration, many enforcement points#

The capability compiler is a pure function, compile(personnel, office, context), where the context names the state directory, the vault, the forge and office hosts and the other agents' homes. It produces everything a run needs:

Because one declaration drives all of these, the rings can't drift apart. Something allowed in the harness but missing from the token simply fails at the forge.

The fixed floor#

Some rules apply to every run, whatever its capabilities:

• No reading or editing the office's state directory, /etc or other agents' homes, and no reads outside the working directory.
• No sudo, su or doas. No WebSearch. No WebFetch, curl or wget unless the agent has net.egress, and then only the sandbox's network allowlist is reachable.
• No edits to the vault's CLAUDE.md or .office/.
• bypassPermissions and auto mode are disabled. A personnel file asking for bypassPermissions fails validation, and the compiler refuses it too.
• The sandbox is on and fails closed: if it isn't available, the run doesn't start.
• The office MCP is the only MCP server (--strict-mcp-config), project-level MCP servers are not loaded, and no user or project settings files are read.

A system-wide version of this floor (sandbox on and fail-closed, no bypass or auto mode, the state directory unreadable) is also installed in Claude Code's managed settings file by officectl install. Managed settings can't be overridden by a run's own settings.

Risky actions are office tools, not shell commands#

Merging into the policy repo, granting access and messaging other agents aren't things an agent does with its shell. They are office MCP tools (hr_propose_hire, hr_propose_change, mail_send, approval_request). The office checks the capability server-side before acting, and ledgers a denial (run.denied) if the check fails. For example, hr.propose lets an agent open a PR on the policy repo. Merging it is still a human's job.

Changing capabilities#

Capabilities change through a policy PR, like everything else. The Needs you page shows the compiled diff in plain English, so the approver sees "gains: open PRs on northwind-office" instead of a YAML diff. See Permissions and capabilities.

Beyond standing capabilities#