devleaps-agent-policies 1.0.4

Policy framework for Claude Code and Cursor hooks

AI Agent Policies

Policies turn your Cursor Rules or CLAUDE.md into hard guardrails which an AI Agent cannot simply ignore, or forget. They handle what to do when an agent wants to make a decision, along with other hooks-supported events. Policies can yield both decisions and guidance.

This framework supports Claude Code. Support for Cursor is in beta.

Why Policies

Automating Decisions

Rule files can be forgotten or ignored completely by LLMs. Policies are unavoidable:

if re.match(r'^terraform\s+apply(?:\s|$)', command):
    yield PolicyDecision(action=PolicyAction.DENY, reason="terraform apply is not allowed. Use `terraform plan` instead.")

if re.match(r'^terraform\s+(fmt|plan)(?:\s|$)', command):
    yield PolicyDecision(action=PolicyAction.ALLOW)

[!WARNING]
Be aware when automatically allowing that Bash tools use strings can invole more than one underlying tool. Consider also commands such as find having unsafe options like -exec.

Automating Guidance

Aside from denying and allowing automatically, policies can also provide guidance:

if re.match(r'^python\s+test_', input_data.command):
    yield PolicyGuidance(content="Consider using pytest instead of running test files directly")

Usage

At DevLeaps we developed an internal policy set for AI Agents. To create your own, refer to the example server as a starting point The example server contains:

• A basic server setup demonstrating the use of policies and middleware.
• Rudimentary policies showcasing how to automatically deny, allow and provide guidance.
• Rudimentary middleware showcasing how multi-command tool use could be handled.

To run the example server:

devleaps-policy-example-server

This starts a minimal server running just our example policies.

Architecture

graph TB
    subgraph "Developer Machine"
      Editor[Claude Code / Cursor]
        Client[devleaps-policy-client]
    end

    subgraph "Policy Server"
        Server[HTTP API]
        Policies[Your policies<br/>kubectl, terraform, git, python, etc.]
    end

    Editor -->|Hooks| Client
    Client --> Server
    Server -->|Events| Policies
    Policies -->|Decision and Guidance| Server
    Server --> Client
    Client -->|Decision and Guidance| Editor

Quick Start

Installation

Update your local profile with;

# Add the bin directory to $PATH
export PATH="$PATH:/path/to/agent-policies/bin/"

Running an Example Server

devleaps-policy-example-server

The example server runs on port 8338 by default and serves endpoints for both Claude Code and Cursor.

Configure Claude Code

Add devleaps-policy-client to your Claude Code hooks configuration in ~/.claude/settings.json:

Click to expand Claude Code configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "matcher": "*",
            "type": "command",
            "command": "devleaps-policy-client claude-code"
          }
        ]
      }
    ]
  }
}

Configure Cursor

Create or edit ~/.cursor/hooks.json:

Click to expand Cursor configuration

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": "devleaps-policy-client cursor" }
    ],
    "beforeMCPExecution": [
      { "command": "devleaps-policy-client cursor" }
    ],
    "afterFileEdit": [
      { "command": "devleaps-policy-client cursor" }
    ],
    "beforeReadFile": [
      { "command": "devleaps-policy-client cursor" }
    ],
    "beforeSubmitPrompt": [
      { "command": "devleaps-policy-client cursor" }
    ],
    "stop": [
      { "command": "devleaps-policy-client cursor" }
    ]
  }
}

The devleaps-policy-client cursor command will forward hook events to the policy server running on localhost:8338.

Development

This project is built with uv.