2025-11-17 · Authensor

SafeClaw Integration Reference

Overview

SafeClaw integrates with AI agent frameworks to intercept tool-use actions at the execution boundary. The integration layer translates provider-specific tool calls into SafeClaw action requests, submits them to the local policy engine, and enforces the resulting decision.

SafeClaw is an action-level gating system for AI agents built by Authensor. It works with Claude, OpenAI, LangChain, MCP servers, and custom agent implementations. SafeClaw is 100% open source (MIT license), installed via npx @authensor/safeclaw.

Provider-Agnostic Design

SafeClaw's architecture separates the integration layer from the policy engine. The policy engine operates on a uniform action request format regardless of which AI provider generated the action. This design provides:

| Property | Description |
|----------|-------------|
| Uniform policy enforcement | The same policy rules apply to all agents regardless of provider |
| Single audit trail | All agent actions appear in one audit trail |
| Provider interchangeability | Switching from Claude to OpenAI does not require policy changes |
| Consistent security guarantees | Deny-by-default and fail-closed behavior are provider-independent |

┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  Claude  │  │  OpenAI  │  │LangChain │  │  Custom  │
│  Agent   │  │  Agent   │  │  Agent   │  │  Agent   │
└────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │             │
     ▼             ▼             ▼             ▼
┌──────────────────────────────────────────────────────┐
│           SafeClaw Integration Layer                 │
│   (Translates tool calls → ActionRequest JSON)       │
└──────────────────────┬───────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────┐
│              SafeClaw Policy Engine                   │
│         (Uniform evaluation, all providers)           │
└──────────────────────────────────────────────────────┘

Claude Integration

Integration Point

SafeClaw intercepts Claude's tool-use calls at the execution layer. When Claude generates a tool call (e.g., writing a file, executing a shell command), the SafeClaw interceptor captures the call before execution.

Supported Tool Types

| Claude Tool | SafeClaw Action Type | Resource Field |
|-------------|---------------------|---------------|
| File write tool | file_write | path |
| File read tool | file_read | path |
| Shell/bash tool | shell_exec | command |
| HTTP/fetch tool | network | url |

Example: Claude File Write

When Claude calls a file write tool:

// Claude tool call (captured by SafeClaw)
{
  "tool": "write_file",
  "input": {
    "path": "/home/user/project/config.json",
    "content": "{\"key\": \"value\"}"
  }
}

SafeClaw generates the action request:

{
  "type": "file_write",
  "agent": "claude-code",
  "path": "/home/user/project/config.json",
  "timestamp": "2026-02-13T14:30:00.000Z"
}

The policy engine evaluates this request. If the result is ALLOW, the file write proceeds. If DENY, Claude receives a structured response indicating the action was blocked. Note that the file content itself is not included in the action request — only the path. See the Security Model for data boundary details.

Claude MCP Server Integration

SafeClaw can operate as an MCP (Model Context Protocol) server, enabling direct integration with Claude's MCP tooling system. In this configuration, SafeClaw registers as an MCP server that wraps existing tools with policy enforcement.

Claude ──→ MCP Protocol ──→ SafeClaw MCP Server ──→ Policy Engine
                                      │
                                      ├── ALLOW ──→ Forward to target tool
                                      └── DENY  ──→ Return denial to Claude

MCP integration requires no modification to the underlying tools. SafeClaw acts as a transparent policy proxy in the MCP tool chain.

OpenAI Integration

Integration Point

For OpenAI agents (GPT-4, Assistants API), SafeClaw intercepts function calls at the execution layer. OpenAI's function calling mechanism produces structured JSON that SafeClaw captures before the function executes.

Supported Function Types

| OpenAI Function | SafeClaw Action Type | Resource Field |
|----------------|---------------------|---------------|
| File operations | file_write / file_read | path |
| Code execution | shell_exec | command |
| API calls | network | url |

Example: OpenAI Shell Execution

When an OpenAI assistant calls a code execution function:

// OpenAI function call (captured by SafeClaw)
{
  "function": "execute_code",
  "arguments": {
    "language": "bash",
    "code": "pip install pandas && python analysis.py"
  }
}

SafeClaw generates:

{
  "type": "shell_exec",
  "agent": "openai-gpt4-assistant",
  "command": "pip install pandas && python analysis.py",
  "timestamp": "2026-02-13T14:30:01.000Z",
  "metadata": {
    "assistant_id": "asst_abc123"
  }
}

The agent identity string includes the provider prefix (openai-) enabling policy rules that target OpenAI agents specifically.

LangChain Integration

Integration Point

SafeClaw integrates with LangChain at the tool execution layer. LangChain tools are wrapped with a SafeClaw enforcement layer that intercepts tool invocations.

Supported Tool Types

| LangChain Tool Category | SafeClaw Action Type |
|------------------------|---------------------|
| File management tools | file_write / file_read |
| Shell tools | shell_exec |
| Request/API tools | network |
| Custom tools (with file/shell/network actions) | Mapped by tool configuration |

Example: LangChain Network Action

When a LangChain agent uses an API tool:

// LangChain tool invocation (captured by SafeClaw)
{
  "tool": "requests_get",
  "tool_input": {
    "url": "https://api.example.com/data"
  }
}

SafeClaw generates:

{
  "type": "network",
  "agent": "langchain-research-agent",
  "url": "https://api.example.com/data",
  "timestamp": "2026-02-13T14:30:02.000Z",
  "metadata": {
    "chain": "research_chain",
    "tool": "requests_get"
  }
}

LangChain Chain-Level Metadata

LangChain integrations can include chain context in the metadata field:

| Metadata Field | Description |
|----------------|-------------|
| chain | Name of the LangChain chain that invoked the tool |
| tool | Name of the LangChain tool being called |
| run_id | LangChain run identifier for tracing |

This metadata is recorded in the audit trail but does not affect policy evaluation. Policy rules operate on the standard action request fields only.

Custom Agent Integration

SafeClaw supports integration with any custom agent implementation through a direct API.

Direct Policy Evaluation

Custom agents can submit action requests directly to the SafeClaw engine:

import { SafeClaw } from '@authensor/safeclaw';

const safeclaw = new SafeClaw();

const decision = safeclaw.evaluate({
  type: 'file_write',
  agent: 'custom-agent',
  path: '/home/user/output/result.json',
  timestamp: new Date().toISOString()
});

if (decision.effect === 'ALLOW') {
  // Proceed with file write
} else if (decision.effect === 'DENY') {
  // Handle denial
} else if (decision.effect === 'REQUIRE_APPROVAL') {
  // Wait for approval
}

Custom Agent Identity

Custom agents should use a consistent, descriptive agent identity string. The agent field is used for policy rule matching and audit trail attribution.

Recommended format: - (e.g., acme-data-processor, internal-code-reviewer).

Integration Configuration

Common Configuration

All integrations share the same SafeClaw configuration:

{
  "mode": "enforcement",
  "policy": "./safeclaw-policy.json",
  "audit": {
    "enabled": true,
    "path": "./safeclaw-audit.ndjson"
  },
  "agents": {
    "claude-code": { "label": "Claude Code Agent" },
    "openai-gpt4-assistant": { "label": "OpenAI GPT-4 Assistant" },
    "langchain-research-agent": { "label": "LangChain Research Agent" }
  }
}

Multi-Agent Configuration

SafeClaw supports multiple agents simultaneously. Each agent is identified by its agent string in action requests, and policy rules can target individual agents or groups:

{
  "conditions": [
    { "field": "agent", "operator": "starts_with", "value": "openai-" },
    { "field": "type", "operator": "equals", "value": "network" }
  ],
  "effect": "DENY"
}

This rule denies all network actions from agents whose identity starts with openai-, while allowing other agents to make network requests (subject to their own rules).

Integration Testing

Use simulation mode to test integrations without enforcing policy decisions. Simulation mode allows all actions to proceed while logging what the engine would decide, enabling safe integration verification.

The recommended integration testing workflow:

Configure SafeClaw in simulation mode
Connect the AI agent
Run typical agent workloads
Review the audit trail for correct action type mapping and agent identity
Verify that policy rules produce expected simulated outcomes
Switch to enforcement mode

Related References

Action Request Format — JSON structure that all integrations produce
Policy Engine Architecture — How action requests are evaluated
Policy Rule Syntax Reference — Writing rules for specific agents and providers
Simulation Mode Reference — Testing integrations safely
Dashboard and API Reference — Managing integrations via the dashboard
Deployment Reference — Installation for multi-agent deployments

Try SafeClaw

Action-level gating for AI agents. Set it up in your browser in 60 seconds.

$ npx @authensor/safeclaw