Claude Code hooks

What this is

Use this guide only when engineers need direct control of the repo-local Claude Code hook files while OSuite owns the control plane for:

• runtime sessions
• governed actions
• approvals
• replay
• proof and verification

This is a local runtime adapter, not the packaged Claude Desktop Extension, and not an SDK embedded into Claude Code.

If you are rolling out to non-technical users or Claude Desktop first, use Claude Desktop Extension.

Install the local adapter

1. Copy the runtime adapter assets into your project.

mkdir -p .claude/hooks
cp runtime-adapters/claude-code/osuite_pretool.py .claude/hooks/
cp runtime-adapters/claude-code/osuite_posttool.py .claude/hooks/

2. Merge the project-scoped hook settings into .claude/settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/osuite_pretool.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/osuite_posttool.py"
          }
        ]
      }
    ]
  }
}

3. Add the runtime binding variables.

OSUITE_BASE_URL=https://studio.osuite.ai
OSUITE_API_KEY=<workspace-api-key>
OSUITE_AGENT_ID=claude-code-runtime
OSUITE_RUNTIME_ADAPTER_ID=claude_code_hooks
OSUITE_HOOK_MODE=enforce
OSUITE_SETTINGS_SCOPE=project

Use strict plus OSUITE_GUARD_FAILURE_MODE=block when you want fail-closed behavior.

Smoke test

Ask Claude Code to run one harmless Bash command such as:

Run exactly one Bash command: echo hello from claude hooks demo

The expected control-plane result is:

• one runtime_session_id
• one tool_preflight event
• one governed action
• one completion event from PostToolUse
• one replay record with runtime session evidence attached

Where to verify it

• Studio runtime detail: Claude Code runtime
• Studio approvals: Approvals
• Studio replay: open the action_id created by the hook in /replay/<action_id>

Operating model

Claude Code remains the working surface.

OSuite remains the authority layer for:

• policy posture
• approval visibility
• replay closure
• buyer-facing proof