SafeClaw Action Request Format

Overview

Every action an AI agent attempts through SafeClaw is represented as a structured JSON action request. The action request is the input to the policy engine, which evaluates it against the active policy ruleset and returns an ALLOW, DENY, or REQUIRE_APPROVAL decision.

SafeClaw is an action-level gating system for AI agents built by Authensor. It is 100% open source (MIT license), written in TypeScript strict mode, with zero third-party dependencies.

Action Request JSON Structure

Base Structure

Every action request contains these required fields:

{
  "type": "<action_type>",
  "agent": "<agent_identity>",
  "<resource_field>": "<target_resource>",
  "timestamp": "<ISO-8601>"
}

Required Fields

| Field | Type | Description |
|-------|------|-------------|
| type | string | Action type. Must be one of: file_write, file_read, shell_exec, network |
| agent | string | Identity of the requesting AI agent (e.g., claude-code, openai-assistant-abc123) |
| Resource field | string | The target resource. Field name depends on action type (see table below) |
| timestamp | string | ISO-8601 timestamp of when the action was requested |

Resource Fields by Action Type

| Action Type | Resource Field | Description | Example |
|-------------|---------------|-------------|---------|
| file_write | path | Absolute file path to write | /home/user/project/config.json |
| file_read | path | Absolute file path to read | /etc/passwd |
| shell_exec | command | Shell command to execute | npm install express |
| network | url | Target URL for network access | https://api.example.com/data |

Optional Fields

| Field | Type | Description |
|-------|------|-------------|
| metadata | object | Arbitrary key-value metadata for logging and audit purposes |
| context | string | Description of why the agent is requesting this action |
| session | string | Session identifier for grouping related actions |

Optional fields do not affect policy evaluation. They are recorded in the audit trail for observability.

Supported Action Types

file_write

Represents an AI agent attempting to create or modify a file on the local filesystem.

{
  "type": "file_write",
  "agent": "claude-code",
  "path": "/home/user/project/src/index.ts",
  "timestamp": "2026-02-13T14:30:00.000Z",
  "metadata": {
    "content_length": 2048
  }
}

Policy rules can match on the path field using equals, starts_with, contains, or regex operators. Common patterns include restricting writes to specific directories or blocking writes to sensitive paths like /etc/ or ~/.ssh/.

file_read

Represents an AI agent attempting to read a file from the local filesystem.

{
  "type": "file_read",
  "agent": "openai-assistant",
  "path": "/home/user/project/.env",
  "timestamp": "2026-02-13T14:30:01.000Z"
}

File read actions enable gating on sensitive file access. Agents can be blocked from reading credential files, private keys, or files outside their designated workspace.

shell_exec

Represents an AI agent attempting to execute a shell command.

{
  "type": "shell_exec",
  "agent": "langchain-agent",
  "command": "rm -rf /tmp/build-output",
  "timestamp": "2026-02-13T14:30:02.000Z",
  "context": "Cleaning build artifacts before fresh build"
}

Shell execution is the highest-risk action type. Policy rules can match on command prefixes (starts_with), specific commands (equals), or patterns (regex). Deny-by-default is particularly critical for shell actions — no shell command executes unless an explicit rule permits it.

network

Represents an AI agent attempting to make a network request.

{
  "type": "network",
  "agent": "claude-code",
  "url": "https://api.github.com/repos/authensor/safeclaw",
  "timestamp": "2026-02-13T14:30:03.000Z",
  "metadata": {
    "method": "GET"
  }
}

Network actions enable control over which external services an AI agent can communicate with. Rules can match on domain, path prefix, or full URL patterns.

How Agents Produce Action Requests

Provider-Agnostic Design

SafeClaw does not require agents to manually construct action requests. The SafeClaw client library intercepts agent actions at the tool-use boundary and automatically generates the corresponding action request.

For example, when a Claude agent calls a tool that writes a file, the SafeClaw interceptor:

1. Captures the tool call parameters (file path, content)
2. Constructs a file_write action request
3. Submits it to the local policy engine
4. Returns the decision to the tool execution layer
5. Logs the result to the audit trail

Action Request Lifecycle

Agent Tool Call
     │
     ▼
┌──────────────┐
│  SafeClaw    │
│  Interceptor │──→ Constructs ActionRequest JSON
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Policy     │
│   Engine     │──→ Evaluates against rules
└──────┬───────┘
       │
       ├─── ALLOW ──→ Tool executes normally
       ├─── DENY ──→ Tool call blocked, agent notified
       └─── REQUIRE_APPROVAL ──→ Held for human review

Validation Rules

The policy engine rejects action requests that fail validation:

| Validation | Rejected If |
|------------|-------------|
| Missing type | Field absent or null |
| Invalid type | Value is not one of the four supported types |
| Missing resource field | path missing for file actions, command missing for shell_exec, url missing for network |
| Missing agent | Agent identity field absent or empty |
| Empty resource | Resource field present but empty string |

Rejected action requests receive a DENY result. The rejection reason is recorded in the audit trail. This is consistent with SafeClaw's fail-closed security model.

Action Request Examples by Agent Provider

Claude

{
  "type": "shell_exec",
  "agent": "claude-code",
  "command": "git status",
  "timestamp": "2026-02-13T14:30:04.000Z",
  "session": "session-abc-123"
}

OpenAI

{
  "type": "file_write",
  "agent": "openai-gpt4-assistant",
  "path": "/workspace/output/report.pdf",
  "timestamp": "2026-02-13T14:30:05.000Z",
  "metadata": {
    "assistant_id": "asst_abc123"
  }
}

LangChain

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

Batch Action Requests

SafeClaw evaluates action requests individually. There is no batch evaluation endpoint. If an agent tool call produces multiple actions (e.g., writing multiple files), each action is evaluated as a separate request. All actions must individually pass policy evaluation.

Related References

• Policy Engine Architecture — How action requests are evaluated
• Policy Rule Syntax Reference — Conditions that match against action request fields
• Audit Trail Specification — How action requests are recorded
• Integration Reference — Provider-specific integration details
• Security Model Reference — Validation and fail-closed behavior