Claude Code¶
What you'll learn: How to add Kyvvu agent security to Claude Code sessions with the kyvvu claude commands of the kyvvu command line.
Overview¶
Claude Code support is the claude-code extra of kyvvu-cli, the kyvvu command line: it installs the kyvvu-claude plugin, which adds the kyvvu claude commands and integrates Claude Code into the Kyvvu ecosystem via Claude Code's native hook system. Every tool call (Bash, Read, Write, Edit, and the rest) is evaluated against Kyvvu policies before it runs, and all tool calls are recorded as a behavioral audit trail (the client computes chain v1 through the engine; the platform verifies the chain on ingestion).
Unlike the integrations built on the Python client (LangChain, CrewAI), kyvvu-claude does not wrap your code — it operates via Claude Code's hook system, so it works with any Claude Code session without code changes.
Installation¶
uv tool install "kyvvu-cli[claude-code]"
Requires Python 3.11+ and macOS or Linux.
Getting started¶
Install the CLI and run setup:
uv tool install "kyvvu-cli[claude-code]"
kyvvu claude setup
Setup opens Workspace → API Keys on the Kyvvu platform. Create an API key there and paste it at the prompt; that is the only question. Setup then registers this machine as an agent, installs the Claude Code hooks and shows what the policies would have flagged in your Claude Code sessions of the last 30 days. Every new Claude Code session is governed from then on.
To use kyvvu-claude without an account, run kyvvu claude setup --local. It enforces the bundled Claude Code Safety manifest, writes the trace to ~/.kyvvu/integrations/claude-code/trace.jsonl and uses no network.
Add --monitor to either command to log violations without denying or asking. kyvvu claude status shows what is configured and whether every hook event is wired.
How it works¶
A Claude Code hook event runs through a fixed pipeline. Claude Code runs the hook command (a console script) for each event, the script turns the event into an AAG action through the behaviour template, and the engine decides. One kyvvu serve process per Claude session, started at SessionStart and stopped at SessionEnd, owns the session's runner. The parts:
| Stage | What happens | Code |
|---|---|---|
| Hook | Claude Code runs the hook command for SessionStart, PreToolUse, PostToolUse, SubagentStart, SubagentStop and SessionEnd, with the event as JSON on stdin. |
~/.claude/settings.json, written by kyvvu claude hooks install |
| Hook command | The kyvvu-claude-hook console script reads the event on stdin and prints the answer. |
hook_entry.py |
| Session serve | One kyvvu serve per Claude session, spawned at SessionStart on a private Unix socket and reaped at SessionEnd. Each Claude Code session is one task of one agent. |
serve_process.py, serve_client.py |
| Mapper | Turns the hook event into a tool call or task boundary and computes the facts the template matches on: whether a path is a secret file, whether a Bash command reads one, the file a Bash command writes, and the MCP server, tool and verb. Model calls are read from the transcript. | hooks.py, mapper.py, transcript.py |
| Behaviour template | First-match YAML rules turn the event and its facts into an AAG action: kind, verb, properties. | claude-code.template.yaml |
| Engine | kyvvu-engine, unchanged, evaluates the AAG action against the manifest's policies with the task's earlier actions as history. The manifest is a YAML file: the bundled Claude Code Safety manifest with --local, the assigned manifests for a registered agent. |
evaluation.py, kyvvu-engine |
| Decision | Severity sets what Claude Code is told: deny, ask, or allow and record. | evaluation.classify_pretool_result |
Policy evaluation is local, in the session's serve: no network call is on the hot path. A registered agent's policies are fetched when a session starts and every policy_sync_interval_seconds, and cached on disk; a hook never waits for the fetch. --local fetches nothing: the serve loads the manifest when it starts and at each refresh. Pending steps are sent on the flush schedule, so a slow or unreachable platform delays the trail, never a tool call.
The trust boundary is the OS user. The session's socket (under $XDG_RUNTIME_DIR/kyvvu-claude/serve, or the temporary directory where that is unset) and its token file (under ~/.kyvvu/integrations/claude-code/serve, written fresh each time the serve starts) are both mode 0600, and kyvvu serve answers only a request that presents the token as a bearer credential. A process running as the same OS user can read that token, as it can edit the session files; kyvvu-claude governs the agent, not the user who runs it.
The hooks are thin mappers and keep no history on disk. The session's serve owns it: it keeps the task's history, pairs each PreToolUse evaluation with the PostToolUse that records its outcome, stamps the verdict and the policies it came from into the step's meta["kyvvu.eval"], and exports the trail. If the serve dies mid-session, every later hook in that session applies fail_mode, and nothing is replayed: steps the serve had not yet exported are not recovered. A serve whose session ended without a SessionEnd stops itself after serve_idle_exit_seconds (one hour) without a request, through kyvvu serve --idle-exit.
What Kyvvu sees¶
Each Claude Code tool maps to one AAG action, identified by its kind field — the behaviour type a policy matches on (step.exec for a shell command, step.resource for a file or network read, and so on). The behaviour template is a first-match list of rules; the mapper computes the facts (classification, Bash write target, parsed MCP fields) that a more specific rule matches on before the plain rule for the same tool. The table below is every rule, in order. "Set by" names where each property comes from: template (the rule's literal YAML), mapper.py (a fact the pre-pass computed), or transcript.py (read from Claude Code's session transcript).
| Rule | Claude Code tool / event | AAG kind | Verb | Properties | Set by |
|---|---|---|---|---|---|
bash_write_secret |
Bash (writes a target, reads a secret) | step.exec | — | command, target.host, target.resource_type=file, data.classification=secret |
template + mapper.py |
bash_write |
Bash (writes a target) | step.exec | — | command, target.host, target.resource_type=file |
template + mapper.py |
bash_secret |
Bash (reads a secret) | step.exec | — | command, data.classification=secret |
template + mapper.py |
bash |
Bash | step.exec | — | command |
template |
skill |
Skill | step.exec | — | command (the skill name) |
template |
read_secret |
Read (secret file) | step.resource | GET | target.host, target.resource_type=file, data.classification=secret |
template + mapper.py |
read |
Read | step.resource | GET | target.host, target.resource_type=file |
template |
glob_secret |
Glob (secret path) | step.resource | GET | target.host, target.resource_type=glob, target.pattern, data.classification=secret |
template + mapper.py |
glob |
Glob | step.resource | GET | target.host, target.resource_type=glob, target.pattern |
template |
grep_secret |
Grep (secret path) | step.resource | GET | target.host, target.resource_type=grep, target.pattern, data.classification=secret |
template + mapper.py |
grep |
Grep | step.resource | GET | target.host, target.resource_type=grep, target.pattern |
template |
write_secret |
Write (secret file) | step.resource | POST | target.host, target.resource_type=file, data.classification=secret |
template + mapper.py |
write |
Write | step.resource | POST | target.host, target.resource_type=file |
template |
edit_secret |
Edit (secret file) | step.resource | PATCH | target.host, target.resource_type=file, data.classification=secret |
template + mapper.py |
edit |
Edit | step.resource | PATCH | target.host, target.resource_type=file |
template |
notebook_edit |
NotebookEdit | step.resource | PATCH | target.host, target.resource_type=notebook |
template |
web_fetch |
WebFetch | step.resource | GET | target.host (URL), target.resource_type=url |
template |
web_search |
WebSearch | step.resource | GET | target.host (query), target.resource_type=search |
template |
agent |
Agent | step.self | POST | target.resource_type=subagent, target.description |
template |
send_message |
SendMessage | step.message | POST | message.channel=subagent, message.recipient |
template |
tool_search |
ToolSearch | step.self | GET | — | template |
ask_user_question |
AskUserQuestion | step.gate | — | kind=human (output decision=pass on completion) |
template |
task_create |
TaskCreate | step.self | POST | target.resource_type=task |
template |
task_get |
TaskGet | step.self | GET | target.resource_type=task |
template |
task_list |
TaskList | step.self | GET | target.resource_type=task |
template |
task_output |
TaskOutput | step.self | GET | target.resource_type=task |
template |
task_stop |
TaskStop | step.self | POST | target.resource_type=task |
template |
task_update |
TaskUpdate | step.self | PATCH | target.resource_type=task |
template |
enter_plan_mode |
EnterPlanMode | step.self | POST | — | template |
exit_plan_mode |
ExitPlanMode | step.self | POST | — | template |
enter_worktree |
EnterWorktree | step.self | POST | — | template |
exit_worktree |
ExitWorktree | step.self | POST | — | template |
cron_create |
CronCreate | step.self | POST | target.resource_type=cron |
template |
cron_delete |
CronDelete | step.self | DELETE | target.resource_type=cron |
template |
cron_list |
CronList | step.self | GET | target.resource_type=cron |
template |
list_mcp_resources |
ListMcpResourcesTool | step.resource | GET | target.resource_type=mcp_resource |
template |
read_mcp_resource |
ReadMcpResourceTool | step.resource | GET | target.resource_type=mcp_resource |
template |
mcp_dynamic |
mcp__server__tool |
step.resource | derived | target.resource_type=mcp, target.mcp_server, target.mcp_tool |
template + mapper.py |
unknown |
any other tool | step.unknown | — | — | template |
The verb for a dynamic mcp__server__tool is a heuristic over its name, from the one write list kyvvu-claude and kyvvu-acs share. The name is split into words at _, ., /, -, : and camelCase boundaries, case-insensitively, and the first word on the list decides the verb: delete and remove give DELETE; update, patch, set, edit, rename, move and put give PATCH; write, create, add, push, post, send, upload, comment, publish, merge, submit, share, reply, assign, invite, transfer, fork, star, append, insert, upsert, save, store, commit, deploy, execute, run and trigger give POST. So mcp__github__add_comment and mcp__slack__post_message are writes. A name with no word on the list counts as a read (GET), so after a secret read an MCP tool that writes under some other name is allowed. To reclassify a specific tool, add a template rule for it before mcp_dynamic (see Enriching the AAG with your own template).
A file is classified data.classification=secret when its path matches a secret pattern — .env and .env.<name> (but not .env.example, .env.sample, .env.template), .pem, .key, .p12, .pfx, .secret, .credentials, .pgpass, .netrc, ~/.aws/credentials, and ~/.ssh/id_* private keys. Through Bash, a secret read is a heuristic, recognised from an explicit list rather than from any command that names a secret file: one of cat, less, more, head, tail, cp, mv, xxd, base64, od, strings, grep, egrep, fgrep, rg, ag, source, ., sed, awk, jq, yq, diff, cmp, sort, uniq, cut, tr, wc, nl, tac, rev, paste or column with a secret file among its arguments (directly or through xargs), dd if= a secret file, a < input redirect from one for any command, or python, node, ruby or perl with an inline -c/-e program whose text names one. A secret read through any other command (perl script.pl that opens .env) or through shell indirection (variables, eval, encoded commands) is not recognised and does not arm the taint, and ls .env names a secret but reads nothing. Glob and Grep read a secret when their path or glob names one, not when only Grep's search pattern contains .env. For secrets that must never leave the machine, use OS file permissions as well. A Bash shell write (>, >>, tee, cp, mv, dd of=, sed -i) sets target.host so containment policies apply to shell writes, not only to the Write and Edit tools.
Model calls are recorded as step.model with metadata only — model name, token usage, stop reason and proposed tool names (output.proposed_tools); no conversation content. Tool arguments for every tool, including unknown tools, are recorded under input.
Gaps¶
What kyvvu-claude does not see or cannot act on:
- AAG kinds the template never emits. No rule emits
step.credential, and AAG has nostep.memorykind, so policies on either never fire for kyvvu-claude. - Events captured but not governed. Model calls (
step.model) are read from the transcript after the fact, so a policy cannot stop one. TheNotification,UserPromptSubmit,StopandPreCompacthooks are not installed, so those events are not seen at all. - No event at all for what a Bash command does beyond its text. Detection is a regular expression over the command string, so a variable,
eval,base64orpython -cevades it, and a network call from inside a program the agent runs is not seen. A secret read is recognised only from the list of reading commands above. - The secret taint has a window. It lasts for the last
enforcement_history_limitsteps of the task (default 10,000), and transcriptstep.modelentries count toward that limit. In a long session a secret read can age out of the window, and data can leave afterwards without the exfiltration policies firing. Raiseenforcement_history_limitto widen it; see Tainted-path enforcement. - A
task.startpolicy fires only for an explicitSessionStart. A task opened by its first tool call, because Claude Code sent noSessionStart(a sub-agent, or a session already open at install), gets atask.startmarker that is recorded but not evaluated, as in kyvvu-acs. Claude Code Safety has notask.startpolicy, so nothing it ships is affected; atask.startpolicy you assign yourself is not enforced on such a task. - Decisions that cannot be enforced as such. A deny stops the tool call, not the session: Claude Code continues and may try another route. A
step.gatefromAskUserQuestionis recorded, not enforced. - A session already open when you install the hooks is governed only from that point on. It never receives a
SessionStart, so its first governed tool call opens the trail with atask.startmarker and governance begins there; tool calls it already made are not recorded, and model calls from before the install are not replayed. For a complete trail, run/clearor start a fresh Claude Code session afterkyvvu claude setup.
Enriching the AAG with your own template¶
The behaviour template (claude-code.template.yaml) is the one place that turns a Claude Code tool call into an AAG action. You can replace it with your own to add properties a policy can act on.
- Copy the built-in template out of the installed package to a file of your own, for example
my-template.yaml. - Add or change a rule. For example, tag a specific MCP tool so a policy can single it out — put the rule before
mcp_dynamic, since rules are first-match:
- id: github_issue
match: {tool_name: "mcp__github__create_issue"}
behavior: {kind: "step.resource", verb: "POST", step_name: "{{ tool_name }}", properties: {target: {resource_type: "ticket", mcp_server: "github", mcp_tool: "create_issue"}}}
Rules match by equality on the facts listed in What Kyvvu sees, so a rule selects a tool, not part of a command. 3. Activate it:
kyvvu claude set template-file my-template.yaml
The file replaces the built-in template; it does not extend it, so start from a copy and keep the rules you still need. The mapper's pre-pass (secret classification, Bash write targets, parsed MCP fields) still runs and its facts are added on top of whichever template is loaded. A template that cannot be loaded fails setup and set with the load error rather than on the first governed tool call. See Writing a Custom Template for the rule grammar.
Default policies¶
A registered agent enforces the manifests assigned to it on the platform. With --local, kyvvu-claude enforces the Claude Code Safety manifest bundled with the package. When kyvvu claude setup registers the agent, the platform applies Kyvvu's baseline in its Claude Code form:
| manifest | what it does |
|---|---|
| Claude Code Safety | credential exfiltration after a secret read, destructive commands (rm -rf /, git push --force, git reset --hard), project containment, persistence and self-protection |
| EU AI Act minimal/limited risk | registration documentation and Article 50 transparency |
Every other kind of agent gets the OWASP Top 10 for Agentic Applications template in place of Claude Code Safety. A Claude Code agent does not, because two of its policies cannot work with Claude Code: "Code execution requires a preceding gate" needs an approval step recorded before every shell command, and Claude Code does not report its own permission prompts to a hook, so it would deny every Bash call; and the tool allowlist cannot name MCP tools, which exist only once a session calls them. The choice is made by the platform from the registration's metadata.integration (kyvvu-claude).
Severity decides what the developer is shown:
| Severity | Decision | What Claude Code is told |
|---|---|---|
| critical | deny | The tool call is denied. |
| high | ask | Claude Code asks the developer before running the call. |
| medium, low | allow | The call runs and is recorded in the trace. |
The Claude Code Safety manifest blocks data leaving the machine after a secret was read (shell network commands, web requests, MCP writes, and a network command naming a secret file), irreversible destruction (recursive deletes of /, home, parent traversals and system directories, and a force push to main or master), and persistence and self-protection (writes to credential stores, shell start-up files and system directories, and any change to kyvvu-claude's own state or Claude Code's settings). It asks before git reset --hard, other force pushes, writes outside the project, sudo, piping a download into a shell (curl … | sh), and publishing a package. It records secret reads, which also arm the tainted-path policies below for the last enforcement_history_limit steps of the task (default 10,000, transcript step.model entries included).
The policies deny or ask when enforce is true. In monitor mode (--monitor) they are evaluated and violations recorded, but nothing is denied or asked. Run kyvvu claude policies, or open the agent in the dashboard (tagged Baseline), for the current list. Unassigning either manifest works as for any baseline manifest, see Removing and restoring the baseline.
Adding more manifests¶
The baseline needs nothing from you. To add a manifest on top of it, use the dashboard (Manifests, then assign the manifest to the agent) or the kyvvu command line you installed kyvvu claude with:
kyvvu auth # a CLI session, not the agent's API key
kyvvu claude status # the "Agent key" line names the agent
kyvvu list-manifests # the REPO ID and FILE of what you can assign
kyvvu assign-manifest --agent-id claude-code-laptop-ada --repo-id 1 --manifest manifests/operational/demo.yaml
--agent-id takes the agent key from kyvvu claude status or the Agent ID beside it. The new policies reach a session soon after it starts, a running one within policy_sync_interval_seconds, and both straight away with kyvvu claude refresh. See kyvvu assign-manifest.
Tainted-path enforcement¶
A secret read taints the task. After it, network commands, web requests and MCP writes are denied; reads, edits and local commands stay allowed. Use /clear in Claude Code to start a new session and reset the taint.
The taint lasts for the last enforcement_history_limit steps of the task (default 10,000), not for the whole session: the tainted-path policies look back over the steps the session's serve keeps for policy replay, which drops the oldest first whatever they are, and transcript step.model entries count toward the limit. A secret read that has aged out of that window no longer taints the session, and a network command after it is allowed. Raise enforcement_history_limit in config.json to widen the window, or set it to 0 to keep the whole task.
What this does not prevent¶
For Bash calls, kyvvu-claude uses regular expressions over the command text to infer secret-file reads and write targets. This is a best-effort signal, not a shell security boundary. A python -c or here-doc program can write outside the project without a detected target. Writes hidden behind bash -c, eval, xargs, or base64-decoded commands can do the same. Secret reads through a variable, split quotes such as cat .en''v, command substitution such as env $(cat .en''v), or backticks can escape classification. The reverse also happens: echo "value > /etc/hosts" only prints text, but the > inside quotes is treated as a redirect and can trigger a false block.
Use OS controls alongside the hook: a read-only bind mount over protected paths, a restricted PATH, network egress controls, and an agent user that cannot read secret files. We intentionally do not add a shell parser because syntactic parsing still cannot resolve eval, variables, or decoded commands at runtime.
Enforcement¶
When a policy denies a tool call:
- kyvvu-claude returns
permissionDecision: "deny"to Claude Code - Claude Code shows the block reason to the user and the model
- The blocked step is recorded in the audit trail with
output.status = "blocked" - An incident is sent to the incident sink (the Kyvvu API by default)
- The model continues reasoning, and may try alternative approaches
Tool blocks deny the specific tool call but do not stop the session. This is consistent with how Claude Code handles permission denials from users. A high-severity policy returns permissionDecision: "ask" instead, so Claude Code asks the developer before running the call.
Configuration¶
All settings are in ~/.kyvvu/integrations/claude-code/config.json, written by kyvvu claude setup:
| Setting | Default | Description |
|---|---|---|
api_url |
https://platform.kyvvu.com |
Kyvvu API URL |
agent_key |
claude-code-<hostname>-<user> |
The key the agent registers under. Set with kyvvu claude setup --agent-key |
owner_id |
(empty = the API key owner) | Email of the workspace member accountable for the agent, sent as owner_id at registration. Set with kyvvu claude setup --owner |
environment |
production | development, qa, staging or production; KV_ENVIRONMENT is the default and a saved value wins. Set with kyvvu claude setup --environment |
enforce |
true |
true denies and asks on violations; false (monitor) evaluates and records but allows. --monitor sets it false |
fail_mode |
open | What the hook answers when evaluation cannot happen. open allows; closed denies a PreToolUse, even in monitor mode. Other hook events stay nonblocking. Set with kyvvu claude setup --fail-mode closed or kyvvu claude set fail-mode closed |
log_location |
auto | WHERE the trace goes. auto follows the policy source: the platform for a registered agent, a local file for --local. stdout, none, or a URL or file path also work |
log_format |
kv | HOW the trace is formatted: kv, json, or otlp |
incident_location |
(inherits trace sink) | WHERE incidents go. Same vocabulary as log_location; empty inherits the trace sink |
incident_format |
(inherits log_format) | Incident format: kv, json, or otlp. Empty inherits log_format |
log_full_content |
false |
false exports tool input and output as {redacted, bytes, sha256} summaries; true exports the full recorded input, output and properties. Local policy checks always use full input |
risk_classification |
limited |
EU AI Act tier: high, limited, or minimal |
policy_file |
(empty = platform) | Path to a local manifest YAML the engine loads policies from, set by kyvvu claude setup --local. A registered agent fetches from the platform and this is ignored; switching to the platform clears it |
template_file |
(empty = built-in) | Path to a behaviour template YAML that replaces the built-in claude-code.template.yaml. Set with kyvvu claude set template-file PATH. The mapper's pre-pass still runs on top; an unloadable file fails setup/set |
serve_idle_exit_seconds |
3600 |
How long the session's kyvvu serve runs without a request before stopping itself (kyvvu serve --idle-exit), for a session that ended without a SessionEnd. Set with kyvvu claude set serve-idle-exit-seconds N |
policy_sync_interval_seconds |
300 |
How often the session's serve refreshes the policy set while sessions are active |
flush_threshold |
100 |
Flush logs every N steps (0 = no count-based flush) |
flush_interval_seconds |
60 |
How often pending steps are sent; an ended session's go at once (0 = no interval flush) |
enforcement_history_limit |
10000 |
How many of a task's most recent steps, transcript step.model entries included, the session's serve keeps for policy replay. The secret taint lasts this many steps (see Tainted-path enforcement); 0 keeps the whole task |
fail_mode decides what the hook answers when evaluation cannot happen — a session whose serve is not running, a policy set that could not be loaded: open allows the tool call, closed denies a PreToolUse. A serve that is running but gives no verdict (a timeout, an error or an empty reply) is not covered by it: under enforce the PreToolUse is denied, and in monitor mode it is allowed. A config.json that cannot be read or validated denies every PreToolUse ("configuration cannot be read or validated") whatever enforce and fail_mode say, until the file is fixed or kyvvu claude setup is run again.
One setting is not in config.json but read from the environment Claude Code runs its hooks in:
| Variable | Default | Description |
|---|---|---|
KV_POLICY_CACHE_MAX_AGE_SECONDS |
86400 |
policy_cache_max_age_seconds: how long a cached policy answer counts as current. Past it, a set that could not be refreshed is reported as stale, and a cached "no policies configured" stops being honoured as an allow in enforce mode |
OTLP export¶
To send traces to an OpenTelemetry collector (Jaeger, Grafana Tempo, and the like), set log_location to the collector URL and log_format to otlp:
kyvvu claude set log-location http://localhost:4318
kyvvu claude set log-format otlp
CLI reference¶
| Command | Description |
|---|---|
kyvvu claude setup |
Configures kyvvu-claude and installs the hooks. Asks only for an API key, or nothing with KV_API_KEY or --local. --monitor, --fail-mode, --agent-key, --environment, --owner, --api-url, --api-key and --manifest (with --local) all have options |
kyvvu claude report [--since 30d] [--project PATH] [--manifest FILE] [--json] |
Replays past Claude Code sessions from ~/.claude/projects and shows what the manifest would have denied or asked. Reads only; uploads nothing |
kyvvu claude hooks install |
Install the hooks into ~/.claude/settings.json. --project writes .claude/settings.json in the current directory instead, which governs Claude Code only in that project and can be committed with it |
kyvvu claude hooks remove |
Remove the hooks, and remove a retired per-user sidecar service an earlier release left behind. --project removes only the current directory's hooks and leaves the service alone |
kyvvu claude status |
Show the configuration, the policy count, and whether every hook event is wired |
kyvvu claude set |
Change a saved option, for example enforce true, fail-mode closed, or template-file PATH |
kyvvu claude set template-file PATH |
Replace the built-in behaviour template with PATH; an unloadable file is refused |
kyvvu claude policies |
Display cached policies |
kyvvu claude refresh |
Force a policy refresh |
Compatibility¶
kyvvu-claude governs Claude Code on macOS and Linux. It works with every Claude Code surface that reads ~/.claude/settings.json:
- Claude Code CLI
- VS Code extension
- JetBrains plugin
- GitHub Actions (
anthropics/claude-code-action)
Troubleshooting¶
A session's serve is not running¶
The session shows a warning at start and the hooks apply fail_mode. The serve log under ~/.kyvvu/integrations/claude-code/serve says why it would not start. After upgrading kyvvu-claude, run kyvvu claude setup again: it rewrites the hook commands and removes the retired per-user sidecar service an earlier release installed.
Nothing is being enforced¶
A session says how many policies are in force, and why when the answer is none. The states are distinct, and they need different fixes:
Session banner / status |
What happened | Fix |
|---|---|---|
Policies: N loaded |
N policies are being applied. | — |
Policies: N loaded (cache not refreshed) |
The last fetch failed; the last known set is still being applied. | kyvvu claude refresh when the API is reachable again. |
UPGRADE REQUIRED / Policies: N loaded (kyvvu-claude too old to refresh them) |
The platform refused this kyvvu-claude as too old to serve (426 client_upgrade_required). The N cached policies are still enforced, but they will not be refreshed. |
uv tool upgrade kyvvu-cli, then kyvvu claude refresh. |
No policies are configured for this agent |
The platform answered, and this agent has nothing assigned. | Assign a manifest or create a policy. |
NOT ENFORCING — the last recorded fetch did not succeed |
A fetch failed and there was no usable cache. No tool call is being checked. | Check api_url, the API key and network reachability, then kyvvu claude refresh. |
NOT ENFORCING — the policy set was REJECTED |
The set arrived but a policy in it could not be loaded (unknown rule_type, invalid or missing params, a duplicate name, a regex that does not compile). A set loads whole or not at all. |
Fix the policy definitions named in the message; kyvvu claude status shows the detail. |
NOT ENFORCING — the platform refused this kyvvu-claude as too old; Policies: NONE LOADED (kyvvu-claude is too old for this platform) |
The platform refused this version (426 client_upgrade_required) and there is no cached set to fall back on. No tool call is being checked. |
uv tool upgrade kyvvu-cli, then kyvvu claude refresh. |
NOT ENFORCING — the cached policy set was served for ANOTHER agent |
The cache holds the set the platform served for one agent and the config names another. No tool call is being checked. See below. | kyvvu claude setup; kyvvu claude status shows both ids. |
NOT ENFORCING — the policy cache could not be read |
The cache file exists and is corrupt, unreadable or not a policy list. | Delete ~/.kyvvu/integrations/claude-code/policy_cache.json and start a new session, or kyvvu claude refresh. |
kyvvu claude status prints the same verdict, and the session log records an
unchecked tool call as UNCHECKED, never ALLOWED.
In enforce mode, every NOT ENFORCING row denies every tool call rather
than allowing it unchecked — including a corrupt cache, which is deliberate: a
session that cannot read its policies is in exactly the position of one that
never had any. No policies are configured stays an allow in both modes, so a
workspace with nothing assigned yet remains usable, and it keeps that
tolerance across a failed refresh for as long as the recorded answer is within
policy_cache_max_age_seconds.
The policy set is for another agent¶
Every hook evaluates under the agent_id in ~/.kyvvu/integrations/claude-code/config.json, and the platform's agent-specific policies, the claude-code baseline profile among them, apply only to the agent they were served for. The policy cache records that agent, and every hook compares it with the configured one. They disagree when the agent was deleted and registered again on the platform, when kyvvu claude setup registered another agent and its policy refresh failed, or when the config was edited by hand or copied from another machine. status flags a MISMATCH and names both ids. In enforce mode every tool call is denied until it is fixed; in monitor mode tool calls run and are logged UNCHECKED. To recover, run kyvvu claude setup: it registers this machine's agent again, saves the id the platform returns, and fetches that agent's policies.
Hooks not firing¶
kyvvu claude status and kyvvu doctor check ~/.claude/settings.json and name every hook event that is missing, including one whose command names a kyvvu-claude-hook script that no longer exists (a moved or rebuilt environment). If any are, run kyvvu claude hooks install, which writes the path of the script the installer actually placed, wherever the installer put it: a virtualenv, ~/.local/bin for a user install, or a uv tool environment. Hooks installed with --project are in .claude/settings.json of that project, which status reads only for the current directory.
Agent not appearing in dashboard¶
kyvvu-claude caches its registration in ~/.kyvvu/registrations/<agent-key>.json and skips the API call while nothing in the registration has changed. Clear it and run setup again:
rm -f ~/.kyvvu/registrations/claude-code-laptop-ada.json
kyvvu claude setup
rm -rf ~/.kyvvu/integrations/claude-code also works, but deletes the configuration, the policy cache and the session state along with it.
LLM calls missing from trace¶
LLM calls are captured from Claude Code's session transcript. In very short sessions (under ~10 seconds), the transcript may not be flushed to disk before the hook reads it. This is a known limitation.