kyvvu-claude

Kyvvu agent-security integration for Claude Code. Evaluates every tool call against Kyvvu policies before execution via Claude Code's native hook system - stopping credential leakage and destructive commands - and records all tool calls as an audit trail (the platform hash-chains it on ingestion when the trace goes there).

Installation

pip install kyvvu-claude

Requires Python 3.10+ and macOS or Linux.

Getting started

1. Create a Kyvvu account

Sign up at platform.kyvvu.com and create an API key from your organization settings. The API key starts with KvKey-.

2. Initialize kyvvu-claude

kyvvu-claude init

This interactive wizard will:

• Connect to the Kyvvu API (defaults to https://platform.kyvvu.com)
• Register your Claude Code instance as a Kyvvu agent
• Fetch policies assigned to your agent
• Install hooks into Claude Code's ~/.claude/settings.json

3. Start using Claude Code

That's it. All Claude Code tool calls are now evaluated before they run. Open the Kyvvu dashboard to see your agent's behavioral traces.

4. (Optional) Assign policies

In the Kyvvu dashboard, assign a manifest to your Claude Code agent. We recommend starting with the Claude Code Safety manifest (manifests/developer/claude-code-safety.yaml) which protects against:

• Credential exfiltration (blocks Bash after reading .env, .pem, .key files)
• Destructive commands (git push --force, rm -rf /, git reset --hard)
• Scope escape (writes to /etc, ~/.ssh, ~/.aws)
• Runaway loops (max 50 Bash calls, max 10 consecutive)
• PII in commands (SSN, credit card patterns)

How it works

kyvvu-claude uses Claude Code's hook system. Each hook invocation is a fresh process that reads JSON from stdin and writes JSON to stdout.

Claude Code                          kyvvu-claude
    |                                     |
    +-- SessionStart --stdin JSON--->  Register task, fetch policies from API
    |                                  Return status message
    |
    +-- PreToolUse ----stdin JSON--->  Map tool -> Kyvvu Behavior
    |                                  Evaluate policies (local, <50ms)
    |                                  Block or allow
    |
    +-- PostToolUse ---stdin JSON--->  Record completed step in session history
    |                                  (for path-dependent rules)
    |
    +-- SubagentStart -stdin JSON--->  Link spawned sub-agent to its parent
    |                                  Agent/Task step (back-reference)
    |
    +-- SubagentStop --stdin JSON--->  Record sub-agent boundary in the trail
    |
    +-- SessionEnd ----stdin JSON--->  Flush audit trail to API
                                       Clean up session

Policy evaluation is fully local via kyvvu-engine — no network I/O on the hot path. Policies are fetched from the API at session start and cached on disk.

LLM calls are captured from Claude Code's session transcript (model name, token usage, proposed tools) and included in the behavioral trace.

The audit trail model

The audit trail is a single flat list of steps per task — there is no nesting and no per-sub-agent task_id. Two things define ordering and structure:

• Ordering is by timestamp. Every step carries a reliable UTC timestamp: tool steps are stamped when the hook records them, and step.model (LLM call) steps reuse the timestamp from Claude Code's transcript so they sort by when the call actually happened. Read the trail in timestamp order.
• step (the step counter) is a per-task monotonic id and timestamp tiebreaker — not a causality guarantee. It increments as steps are recorded, but Claude Code issues tool calls in parallel batches and sub-agents widen that concurrency, so a higher step does not mean "caused by" a lower one. Do not infer happens-before from step alone; use it only to break ties between equal timestamps and to reference a specific step.

Sub-agent partial order (flat storage, reconstructable)

When Claude Code fans out to sub-agents (the Task/Agent tool), every sub-agent's inner tool calls are merged into the same flat task trail. Flat storage is retained, but enough structure is stamped onto each step that the meaningful partial orders reconstruct without nesting:

• Each step carries a sub-agent correlation stamp under properties["kyvvu.subagent"]: {"id": <tag>, "depth": <0|1>, "spawn_step": <parent step>}. The tag is "main" for the parent session, or the sub-agent's id derived from its dedicated transcript path (…/subagents/agent-{id}.jsonl).
• Within one sub-agent: group steps by their kyvvu.subagent.id, then order by timestamp. This keeps a sub-agent's own read-then-exec sequence intact even though a sibling's steps may be interleaved in flat storage.
• Parent → child: each sub-agent step carries spawn_step, the parent Agent/Task step that spawned it (established from the SubagentStart lifecycle hook). This preserves the platform-guaranteed "read .env, then delegate" happens-before.
• Cross-sibling order is deliberately not preserved — concurrent siblings are a genuine race, so their relative order is dropped (out of scope per design).

Enforcement is independent of these tags. Policy replay is always whole-task (conservative): at every PreToolUse the engine replays the entire task history regardless of sub-agent lineage, so a secret read in one sub-agent still taints exec anywhere in the task. The sub-agent tags are for storage and reconstruction only — they never scope enforcement.

Enforcement behavior

When a policy blocks a tool call, kyvvu-claude returns permissionDecision: "deny" to Claude Code. This denies the specific tool call but does not stop the agent. Claude Code treats it like a permission denial — the model continues reasoning and may try alternative approaches.

This is intentional and consistent with Claude Code's hook design:

• The blocked step is recorded in the audit trail with output.status = "blocked"
• The policy name and severity are logged locally in ~/.kyvvu-claude/session.log
• An incident is reported to the Kyvvu API
• The model receives the block reason and adapts

Tainted-path policies (credential exfiltration guard) are permanent within a session: after reading a secret file (.env, .pem, .key, etc.), ALL subsequent Bash commands and file reads outside the project are blocked. Use /clear in Claude Code to start a new session and reset the taint.

Tool mapping

Files matching secret patterns (.env, .pem, .key, .secret, .credentials, .pgpass, .netrc) are automatically classified with data.classification: secret for tainted-path policies. This applies both to the file tools (Read/Edit/Write/Glob/Grep) and to shell commands: a Bash command that reads a secret file (cat .env, cp *.pem …) is classified too, and a Bash shell write (>, >>, tee, cp, mv, …) sets target.host so scope-containment policies apply to shell writes — not just the Write/Edit tools.

Configuration

Stored at ~/.kyvvu-claude/config.json:

Compatibility

kyvvu-claude uses Claude Code's hook system. It works with:

• Claude Code CLI (claude command)
• VS Code extension (Claude Code in VS Code)
• JetBrains plugin (Claude Code in IntelliJ/PyCharm)
• GitHub Actions (anthropics/claude-code-action) — reads .claude/settings.json from repo

Not supported: Claude Desktop (macOS/Windows app). Claude Desktop uses MCP servers instead of hooks. Hooks are runtime-invoked (the infrastructure calls them unconditionally on every tool use). MCP tools are model-invoked, so compliance enforcement cannot be guaranteed.

CLI commands

Known limitations

• Tool blocks deny the tool call but do not stop the session — Claude Code continues reasoning and may try alternatives. This is consistent with how Claude Code handles permission denials.
• LLM calls are observed, not blocked — captured from the session transcript (model name, token usage) but cannot be intercepted pre-flight since no hook fires before model inference.
• LLM call capture may miss very short sessions — the transcript is written asynchronously by Claude Code; in sessions under ~10 seconds, LLM calls may not appear in the trace.
• Does not work with Claude Desktop — only Claude Code CLI, IDE extensions, and GitHub Actions.
• macOS and Linux only — uses fcntl.flock for session file locking (no Windows support).

Uninstalling

kyvvu-claude uninstall-hooks
pip uninstall kyvvu-claude
rm -rf ~/.kyvvu-claude