Claude Agent SDK¶

At a glance

Use when: Your agent runs on Claude Agent SDK (Managed Agents) · Setup: 5 min · Mechanism: PreToolUse / PostToolUse hooks · Best for: Code agents, research agents, autonomous workflows

Integrate Identity OS with Claude Managed Agents via the Hooks system. All 5 control dimensions active — the agent's tools are gated by Identity OS before Claude sees them.

Quick Start¶

from claude_agent_sdk import query, ClaudeAgentOptions
from identity_os.integrations.claude_agent_sdk import create_identity_hooks
from identity_os.models.types import IdentityProfileConfig

hooks = create_identity_hooks(
    identity_profile=IdentityProfileConfig(
        core_modes=["exploration", "connection"],
        risk_posture="seeking",
        description="A curious research agent",
    ),
)

async for message in query(
    prompt="Research recent papers on AI agent safety",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
        hooks=hooks,
    ),
):
    print(message)

One function call. Identity OS handles the rest.

How It Works¶

Claude Agent SDK tool call
    ↓
PreToolUse hook → Identity OS checks:
    ├── Is this action allowed? (ExecutionContract)
    ├── Should the agent pause? (Timing control)
    ├── Is this goal acceptable? (Goal filtering)
    └── Block or allow
    ↓
Tool executes (if allowed)
    ↓
PostToolUse hook → Identity OS updates:
    ├── Feed outcome to engine (success/error)
    ├── Update stress from errors
    └── Adjust energy, coherence, self-model

What Gets Controlled¶

Dimension	How It Works
Action Space	`PreToolUse` checks if the tool's action is in `allowed_actions`. Stress narrows available actions.
Timing	If `should_pause` is true, all tools are blocked. If `should_escalate`, the hook returns a block with reason.
Goals	Write/Edit/Bash/Agent tools are checked via `assess_goal()`. Complex tasks rejected under stress.
Trust	Trust profile available via `runtime.get_status()`. Delegation caps affect Agent subagent spawning.
Personality	Preferred/discouraged actions influence which tools feel natural for this agent's personality.

Tool → Mode Mapping¶

Claude Agent SDK Tool	Identity OS Mode	Identity OS Action
Read, Glob, Grep	PERCEPTION	QUESTION
WebSearch, WebFetch	EXPLORATION	EXPLORE
Write, Edit, Bash	ASSERTION	EXECUTE
Agent (subagent)	ORDER	SUGGEST

Accessing Identity State¶

The hooks expose a runtime object for monitoring:

hooks = create_identity_hooks(identity_profile=profile)
runtime = hooks["_runtime"]

# After some agent activity...
status = runtime.get_status()
print(status["energy"])        # 0.72
print(status["stress"])        # "MED"
print(status["blocked_count"]) # 3
print(status["should_pause"])  # False

# Get identity context for custom prompts
prompt_addition = runtime.get_system_prompt_addition()
# "A curious research agent. Resilience: 0.65. Trust: 70%."

With Identity Profile¶

Configure the agent's personality:

hooks = create_identity_hooks(
    identity_profile=IdentityProfileConfig(
        core_modes=["exploration", "perception"],
        suppressed_modes=["assertion"],
        risk_posture="seeking",
        energy_policy="conservative",
        stress_tolerance="resilient",
        description="A careful researcher who explores thoroughly",
    ),
)

This affects:

Arbitration weights: exploration/perception tools get priority
Action space: assertion-related tools (Write, Edit, Bash) are discouraged
Energy: conservative policy = lower energy drain
Stress: resilient = higher threshold before HIGH stress triggers

Error Handling¶

The integration handles errors gracefully:

# Tool errors automatically feed stress to the engine
runtime.on_tool_complete("Bash", success=False)
# → StressSignalMonitor generates stress observation
# → Engine updates stress level
# → If stress reaches HIGH, risky tools get blocked

# Consecutive blocks also increase stress
# 3+ consecutive blocks → stress observation injected

Comparison with Other Integrations¶

Feature	LangGraph	CrewAI	OpenAI Agents	Claude Agent SDK
Hook mechanism	Graph node	Callback	Guardrail	PreToolUse hook
Tool gating	State-based	`is_action_allowed()`	Tripwire	Block return
Identity in prompt	Graph state key	`get_identity_status()`	Dynamic instructions	`get_system_prompt_addition()`
Goal filtering	`assess_goal()`	`assess_goal()`	—	Automatic in PreToolUse
Setup	`IdentityOSNode()`	`IdentityOSCallback()`	`create_identity_agent()`	`create_identity_hooks()`

Install¶

pip install identity-os-sdk claude-agent-sdk

The integration is included in the Identity OS package. No additional dependencies needed beyond the Claude Agent SDK itself.