Designing Your Safety Framework

Overview

You have learned the three pillars of agent safety: permissions define what the agent can do, hooks inspect each action in context, and isolation contains the blast radius of mistakes. Now it is time to bring them together. This lesson walks you through designing and building a complete safety framework for a real project -- from the initial risk assessment to the final configuration files.

By the end of this lesson, you will have a working .claude/settings.json with permission rules, hook scripts, and a worktree setup script that you can adapt for your own codebase.

Step 1: Assess Your Risk Profile

Before writing any configuration, you need to understand what you are protecting and what the agent needs to do. This is not a theoretical exercise -- different projects have genuinely different risk profiles.

Risk assessment decision flowchart: start by checking if the repo contains secrets (if yes, add secret-scanning hook and deny network commands), then if it deploys to production (if yes, deny CI/CD modifications and push to main), then if the repo is public (if yes, deny force-push and require branch isolation), otherwise apply standard basic deny rules and allowlist common commands. All applicable rules combine into the final settings.json.

Ask yourself these questions:

• What commands does the agent need to run routinely? (build, test, lint, type-check)
• What commands should never run? (deploy, publish, force-push, destructive deletes)
• Are there directories or files that must never be modified? (CI/CD configs, infrastructure, secrets)
• Does the agent need network access? (installing packages, fetching APIs)
• Who reviews the agent's work, and when?

Write down the answers. They become the inputs to your configuration.

Step 2: Build the Permission Layer

Start with the deny list. This is the most important part of the configuration because deny rules cannot be overridden.

Next, build the allow list based on the commands your agent needs for everyday work. Group them by category for readability.

Notice the structure: deny rules block the dangerous commands unconditionally, allow rules auto-approve the routine ones, and everything else falls through to the permission mode's default behavior (ask the user).

Step 3: Add Hook Scripts

With permissions handling the broad strokes, hooks add the fine-grained control. Create a hooks directory and build the scripts.

Pre-Tool Hook: Comprehensive Command Validator

This hook combines multiple validation checks into a single script.

Post-Tool Hook: Lint and Log

This hook runs after file edits to maintain code quality and create an audit trail.

Register the Hooks

Add the hook configuration to your settings file.

Step 4: Set Up Worktree Isolation

Create a reusable script that sets up an isolated worktree for every agent session.

Step 5: Add Gitignore Rules

Make sure transient agent files do not pollute your repository.

Step 6: Document the Safety Policy

Add a section to your CLAUDE.md that tells the agent about the safety rules it is operating under. This helps the agent understand why certain actions are blocked and avoid wasting cycles trying to circumvent them.

Putting It All Together

Here is the complete directory structure for a project with a fully configured safety framework:

Adapting for Your Project

The configuration above is a starting template. Here is how to adapt it for common project types.

Python projects: Replace pnpm commands with pytest, ruff, mypy. Add Bash(python:*) and Bash(pip list:*) to the allowlist. Keep pip install in the deny list so the agent cannot add dependencies without review.

Go projects: Allow Bash(go test:*), Bash(go build:*), Bash(go vet:*). Deny Bash(go install:*) if you do not want the agent adding tools to the system.

Monorepos: Extend the file path hook to check which workspace a file belongs to and apply different rules per workspace. An agent working on the frontend should not be able to modify backend infrastructure.

CI/CD agents: Use bypass mode inside a Docker container with network_mode: none. The container itself is the safety boundary. Add post-hooks that create a PR rather than pushing directly.

The Iteration Mindset

Your safety framework is never finished. It evolves as you learn more about how agents interact with your codebase.

• Week 1: Start with strict permissions and default (ask-first) mode. Watch what the agent asks for.
• Week 2: Add frequently approved commands to the allowlist. Add hooks for any patterns that need validation.
• Month 1: Move to worktree isolation for autonomous sessions. Set up the review-gate workflow.
• Month 3: Consider container isolation for CI/CD. Build team-specific audit logging.
• Ongoing: Review the audit logs periodically. Update deny rules when you discover new risks. Remove allow rules for commands the agent no longer needs.

The goal is not perfection from day one. The goal is a framework that improves with every agent session.

Summary

Designing a safety framework means bringing together all three pillars into a coherent configuration. Start with a risk assessment to understand what you are protecting. Build deny rules for the most dangerous commands. Add allow rules for routine operations. Layer in hooks for context-aware validation and automatic quality checks. Set up worktree isolation so agent mistakes are always reversible. Document the policy in CLAUDE.md so the agent understands its boundaries. Commit the configuration to version control so every developer and CI job gets the same rules. Then iterate: watch, learn, and refine. Safety is not a one-time setup -- it is a practice that matures alongside your team's relationship with AI agents.