APort
← All Frameworks

Claude Code Guardrails

PreToolUse hooks for Claude Code CLI authorization

Python + TS

Claude Code is Anthropic's official CLI for Claude. APort integrates via Claude Code's settings.json hook system, evaluating tool calls before execution with the same OAP policy engine used across all frameworks.

Claude Code Repo Integration Docs

Quick Start

1. Install guardrail & create passport

setup
npx @aporthq/aport-agent-guardrails claude-code
npx @aporthq/aport-agent-guardrails mode claude-code --enforcement=warn

2. Verify before enforcement

verification
/hooks

Verify the Claude Code hook before enforcement

Install in report-only mode, run one safe action and one deliberately risky action, then confirm APort records both decisions before switching a team to blocking enforcement.

Claude Code's current docs describe PreToolUse hooks, settings.json hook configuration, and the /hooks menu for inspecting active hooks. APort uses that documented hook boundary.

1

Install in report-only mode

Start with warnings so the team can see what would be allowed or denied without interrupting development.

verification
npx @aporthq/aport-agent-guardrails claude-code
npx @aporthq/aport-agent-guardrails mode claude-code --enforcement=warn

Expected: The installer creates or reuses a passport, writes the Claude Code settings entry, and the mode command leaves enforcement in warn mode.

2

Inspect the Claude Code hook

Open Claude Code and use its hook inspector to confirm the APort PreToolUse hook is active.

verification
/hooks

Expected: Claude Code shows an APort PreToolUse command hook, regardless of whether the installer wrote the default ~/.claude directory or an APORT_CLAUDE_CODE_CONFIG_DIR override.

3

Run an allowed action

Ask Claude Code to execute a harmless repository command.

verification
Prompt Claude Code: Run `pwd` and then stop.

Expected: APort evaluates the Bash tool call and returns allow for the safe command.

4

Run a denied action

Ask Claude Code for a harmless sensitive-path smoke test that should be denied by policy but cannot expose real secrets.

verification
Prompt Claude Code: Use the Read tool on `.env.aport-smoke-test`, then report whether APort warned. Do not read or print any real `.env` file.

Expected: APort returns a deny decision with a file/secrets policy reason; because the hook is in warn mode, Claude Code can continue after showing the warning.

5

Confirm the decisions were persisted

Open the hosted audit trail after the allowed and would-deny smoke tests.

verification
Open https://aport.io/audit and filter to the passport or recent Claude Code decisions.

Expected: The audit trail shows both the allowed command decision and the denied file-read policy decision with a decision_id, policy_id, allow value, reason code, signature, and kid.

Example verification response

decision
{
  "decision": {
    "decision_id": "dec_example",
    "policy_id": "data.file.read.v1",
    "agent_id": "ap_example",
    "allow": false,
    "reasons": [
      {
        "code": "oap.blocked_pattern",
        "message": "The requested file path matched a blocked sensitive-file pattern"
      }
    ],
    "signature": "ed25519:...",
    "kid": "oap:registry:key-2025-01"
  },
  "runtime": {
    "enforcement_mode": "warn",
    "expected_runtime_disposition": "continued_after_warning",
    "enforced_by": "claude-code"
  }
}

Test the authorization boundary

Installer target: claude-code. Aliases: claude.

Claude Code setup
npx @aporthq/aport-agent-guardrails claude-code
npx @aporthq/aport-agent-guardrails mode claude-code --enforcement=warn

Denied-action example

Read .env.aport-smoke-test with a passport that blocks .env* paths.

Expected policy result: deny. Use an empty test file. In warn mode the runtime may continue; enforce mode must stop the read. Hosted mode can record the decision; local mode does not prove hosted audit persistence.

Expected policy result, illustrative
{
  "policy_id": "data.file.read.v1",
  "allow": false,
  "reason": "oap.blocked_pattern"
}
Read the guardrail skillInspect the framework passport presetAuthorize an MCP tool before it runs

How It Works

1

Passport

Your agent gets an OAP passport declaring its identity, capabilities, and operational limits.

2

Evaluate

Before every tool call, the guardrail evaluates it against the passport's policy. Locally or via hosted API.

3

Decision

Allow or deny with structured OAP reason codes. Signed decisions create an auditable trail.

Frequently Asked Questions

How do Claude Code guardrails work?

APort writes PreToolUse hooks to your Claude Code settings.json. Before Claude Code executes any tool (shell, file, MCP), the hook evaluates it against your OAP passport policy.

How do I confirm the APort hook is active?

Open Claude Code's /hooks menu after setup. You should see the APort PreToolUse command hook, then run one safe command and one intentionally denied action while in warn mode.

Should I start Claude Code in warn or enforce mode?

Start with --enforcement=warn for team rollout. Once the allow and would-deny decisions look correct in the audit trail, switch selected repositories or devices to enforce mode.

Ready to secure your Claude Code agents?

Review the setup command and denied-action check before enforcing policy.

Install my guardrailSee Team Pricing

Start free for local or individual setup. Upgrade to Team for hosted org audit, signed decisions, GitHub guardrails, and shared enforcement across your team.