Claude Policy Objects

A policy is a Markdown file with a YAML frontmatter: which events it watches, the condition that triggers it, and what happens then (block, ask the user, steer Claude, log…). CPO evaluates every policy that applies to an event, in a fixed order, and answers Claude Code. No model is involved: conditions are code checks and CEL expressions.

---
description: Keep source files under 400 lines
on: [file.write]
paths: ["src/**/*.{ts,tsx}"]
when: { builtin: max-lines, with: { max: 400 } }
---
`{{ file.relative }}` would have {{ facts.lines }} lines (max {{ params.max }}). Split it.

When Claude writes a 450-line file under src/, the write is refused and Claude reads the body as the reason. It splits the file and tries again.

What CPO adds to hooks

Claude Code runs matching hooks in parallel and unordered, with loosely typed payloads. CPO routes every hook to one entry point, ccpp cpo hook, and takes over from there:

• One ordered evaluation. Policies run by priority, then by cost, then by id. The result does not depend on which hook process finished first.
• Typed events. A Bash call becomes tool.call, then shell.exec with every parsed command, then one file.write per redirection. Policies target the action, whatever tool performs it.
• State and history. Counters per session, turn or tool use; the git status; a ledger of what Claude changed this session.
• Protection. Claude cannot quietly edit or disable the policies that guard it.

Quick start

1. Install the plugin in Claude Code (details):

   claude plugin marketplace add CCPP-dev/CCPP
   claude plugin install cpo@ccpp

   Copy

2. Set a ready-made profile for the project, from inside Claude Code:

   ! ccpp cpo profile set secrets-baseline

   Copy

3. See what is in force. Claude can run this too, and refusals tell it to:

   ccpp cpo view

   Copy

4. Add a rule of your own in .claude/policies/<id>.policy.md, then validate it:

   ccpp cpo lint

   Copy

5. Dry-run a hook input to see which policies would fire, without writing state or logs:

   ccpp cpo trace hook-input.json

   Copy

Reference