Claude Code

Claude Code connector wires the documented lifecycle hook set plus native OTel. Thirteen current events can return block decisions, and PreToolUse supports native HITL ask.

The Claude Code connector wires DefenseClaw into Anthropic's documented hook surfaces without inserting a proxy in the data path. Claude Code talks directly to its native upstream; DefenseClaw inspects via hooks + native OTel.

The Claude Code connector is hook-only. There is no LLM-proxy data path — Claude Code talks directly to api.anthropic.com and DefenseClaw observes via hooks + native OTel.

mode=action is supported on Claude Code's declared blocking hook events. PreToolUse can return deny or native ask before the tool. Post-result events are advisory: they preserve findings and shadow would_block telemetry without stopping Claude's next turn. No proxy listener is involved.

Platform support

Platform	Status	Connector path
macOS and Linux	Supported	Portable command hooks plus Claude Code's native OTel exporter.
Native Windows x64	Supported	Shell-free native executable hooks using Claude Code's `command` plus `args` exec form. Official-client validation metadata remains empty and `live=false`; support availability is not a certification claim.

Setup

defenseclaw setup claude-code                # observe (default) — record only
defenseclaw setup claude-code --mode action  # block on policy hits via PreToolUse deny

DefenseClaw installs the portable Claude Code hook and configures the native OTel exporter in the user settings.

defenseclaw setup claude-code                # observe (default) — record only
defenseclaw setup claude-code --mode action  # block on policy hits via PreToolUse deny

Install and run Claude Code directly from PowerShell or CMD using Anthropic's native setup. DefenseClaw registers the protected defenseclaw-hook.exe through Claude Code's shell-free command plus args exec form. Git for Windows is recommended upstream when Claude should use its Bash tool, but it is optional; without it Claude uses its native PowerShell tool. Git for Windows is not part of the DefenseClaw hook contract. WSL, Git Bash, Cygwin, MSYS, containers, and virtual machines are outside this native connector path.

setup claude-code is the dedicated Claude Code setup alias. It uses the same setup backend as setup guardrail, adds or reconfigures claudecode, wires hooks + native OTel, and can join an existing hook-connector roster when you choose Add. No proxy listener binds in either mode.

Native OTLP uses managed loopback exporter settings with a Claude-scoped Authorization bearer. Logs and metrics are enabled; traces are explicitly disabled. Prompt and assistant-response content logging are independent vendor opt-ins and DefenseClaw explicitly defaults both off; downstream redaction settings do not silently authorize source capture. The scoped credential cannot authenticate management or another connector and must never be printed or copied.

Redaction is configured through the v8 bucket/profile policy: edit observability.destinations[].routes[].selector.buckets and observability.redaction_profiles, then follow Redaction → Verify policy.

The alias defaults to observe mode and accepts the common hook-connector options, including --mode, --workspace, --rule-pack, --human-approval, --hilt-min-severity, --fail-mode, --block-message, --replace, --with-local-stack, and restart controls. Use the quick-alias reference for that surface. Use the full guardrail setup when you also need scanner, detection-strategy, or judge-provider configuration. Defaults are documented once on the Defaults page.

Files DefenseClaw will modify

DefenseClaw manages marked hooks and OTLP environment entries in %CLAUDE_CONFIG_DIR%\settings.json; the default directory is %USERPROFILE%\.claude. Generated runtime and protected connector credentials live below %USERPROFILE%\.defenseclaw\hooks. See the Windows path reference.

settings.json (hooks block + managed native OTel environment entries)

DefenseClaw stores a hash-checked backup of settings.json before edits. Teardown restores it byte-for-byte when the identity still matches; if the file drifted, only DefenseClaw-owned entries are removed.

Claude Code keeps user/local MCP registration state in ~/.claude.json (%CLAUDE_CONFIG_DIR%\.claude.json when that override is set) and project MCP state in <workspace>/.mcp.json; these are inventory surfaces, not hook setup files. See Anthropic's MCP scope reference. The current connector inventories those local, project, and user manual scopes. Plugin-provided MCP and claude.ai connector MCP are not attributed from these files. Marketplace plugin cache artifacts honor CLAUDE_CODE_PLUGIN_CACHE_DIR; retained versions are not presented as active without semantic client evidence. Managed enabledPlugins takes precedence over user, project, and local preferences; a dynamic policyHelper is reported as unverified instead of guessed. Skill inventory covers the launch directory, every parent through the repository root, and existing nested .claude/skills roots that Claude can lazily activate after file activity. Nested skills remain discoverable-unverified until session activity proves activation; true skills take precedence over legacy commands, and documented skill-directory symlinks are canonicalized and de-duplicated. Recursive user/project agents use required frontmatter identity and closest-project precedence. Managed/plugin agents and session --agents remain unverified. Auto-memory resolves file-based autoMemoryDirectory precedence or the shared repository/worktree default under ~/.claude/projects/<project>/memory; it is marked unverified when session --settings, remote settings, or native policy could change the active path. Runtime /add-dir roots remain outside persistent passive inventory. Claude Code 2.1.219+ emits DirectoryAdded, so DefenseClaw records the added path and source without treating the observation as durable discovery authority.

Hook capabilities

Block events

UserPromptSubmit
UserPromptExpansion
PreToolUse
PermissionRequest
TaskCreated
TaskCompleted
TeammateIdle
Stop
SubagentStop
ConfigChange
PreCompact
Elicitation
ElicitationResult

Native ask events

PreToolUse

Claude Code's post-result surfaces (PostToolUse, PostToolUseFailure, PermissionDenied, and PostToolBatch) carry returned content rather than a new typed action request. DefenseClaw still scans that content for trust, secret, and PII findings, but command, path, cognitive-file, and C2 rules do not block on literals found in the returned bytes. For example, source text that explains rm -rf / can produce telemetry without being mistaken for a request to execute it. If Claude later proposes that command, PreToolUse evaluates the typed tool arguments and can deny it before execution.

A standalone PostToolUse response may also use physically verified local source provenance to lower source-code trust findings to detection-only telemetry. Batch, failure, denial, and mixed outputs remain untrusted content; they are still advisory because they cannot be attributed to one executable request safely.

Protection for active AGENTS.md and MEMORY.md files is similarly context-bound. DefenseClaw accepts an active file only from an authenticated InstructionsLoaded event that names the exact absolute, regular, non-symlinked file. A later PreToolUse mutation is enforcement-eligible only in that same Claude Code session and for that exact path. A file mention, a Read call, a generic payload field, or an event from another session cannot claim this authority. If an authenticated event names a recognized absolute AGENTS.md or MEMORY.md path but native file identity cannot be proved, DefenseClaw records bounded session uncertainty and fails closed only for a statically proven mutation of the corresponding canonical instruction-file name. Relative, malformed, and unrelated instruction loads remain ignored. Distinct lexical same-name mutation aliases remain visible as detection-only unless cached identity or filename-case proof establishes the exact active path.

Claude Code is one of the few connectors that supports native PreToolUse ask. HITL approvals surface inside the agent UI itself, so the operator never has to leave Claude Code to decide.

Setup is observation-only and is not registered. WorktreeCreate is not registered because a handler replaces Claude Code's default worktree creation and must return the new path. The exact version-selected contract registers 28 events for Claude Code >=2.1.154,<2.1.219 and 29 for >=2.1.219. The added DirectoryAdded hook is synchronous, matcherless, bounded to 30 seconds, and observation-only: it runs after the directory is added and has no block, ask, or decision authority.

Telemetry channels at boot

Two telemetry channels: hooks for per-tool-call decisions and native OTel for model/token metrics plus privacy-gated events.

Disable

defenseclaw guardrail disable --connector claudecode --yes