agent-governance

# Agent Governance Skill

Implement security and governance controls for custom agents using hooks.

## Purpose

Design and implement hook-based governance that controls agent permissions, blocks dangerous operations, and provides audit trails.

## When to Use

- Building agents with security requirements
- Need to block access to sensitive files/operations
- Require audit logging of agent actions
- Implementing permission policies

## Hook Architecture

### Hook Types

> **Documentation Verification:** Hook event types (PreToolUse, PostToolUse, etc.) are Claude Code internal types. For authoritative current types, verify via `hook-management` skill → `docs-management`.

| Hook | When | Use Case |
| --- | --- | --- |
| `PreToolUse` | Before tool executes | Block, validate, log |
| `PostToolUse` | After tool executes | Log results, audit |

### Hook Function Signature

```python
async def hook_function(
    input_data: dict,     # Tool call information
    tool_use_id: str,     # Unique tool call ID
    context: HookContext  # Session context
) -> dict:
    # Return empty dict to allow
    # Return with permissionDecision to block
    pass
```

## Design Process

### Step 1: Identify Security Requirements

Questions to answer:

- What files should be blocked? (e.g., .env, credentials)
- What commands should be blocked? (e.g., rm -rf)
- What operations need logging?
- What tool access needs validation?

### Step 2: Design Hook Matchers

```python
from claude_agent_sdk import HookMatcher

hooks = {
    "PreToolUse": [
        # Match specific tool
        HookMatcher(matcher="Read", hooks=[block_sensitive_files]),

        # Match all tools
        HookMatcher(hooks=[log_all_tool_usage]),
    ],
    "PostToolUse": [
        HookMatcher(hooks=[audit_tool_results]),
    ],
}
```

### Step 3: Implement Hook Functions

**Security Hook (Block Pattern)**:

```python
BLOCKED_PATTERNS = [".env", "credentials", "secrets", ".pem", ".key"]

async def block_sensitive_files(
    in