Hosted-plane hook (early access)

Early access. Any API key you create today has write scope, not evaluate-only scope; evaluate-only keys are planned. The local hook stays offline and fails open. Hosted mode is opt-in from the command line only: kya hook --host claude --plane-config <absolute path>.

What it does

• Calls POST /api/v1/kya/policy/evaluate with requireRegisteredAgent: true, so a killed agent is denied AGENT_NOT_ACTIVE on its next tool call.
• The local never-list and guard pack always win: a plane ALLOW cannot override them. The guard pack denies destructive shell commands, credential reads, secret-shaped writes and exfiltration, with the same rules and reason codes as the local hook.
• Plane down, key rejected, timeout, 429 or a bad config file: the call is denied (PLANE_UNREACHABLE, PLANE_AUTH_REJECTED, PLANE_TIMEOUT, PLANE_RATE_LIMITED, PLANE_CONFIG).
• REQUIRE_APPROVE is allowed and recorded; --strict denies it with a console link (no approval request is opened yet).
• --plane-shadow records without blocking (except the never-list and the guard pack), for pilots.
• 429, 5xx and network errors retry with exponential backoff and jitter, honouring Retry-After, inside one budget (--plane-budget-ms, default 3000, max 4000).

Config file

One JSON file with baseUrl, apiKey and agentId, mode 0600, owned by you, not a symlink, outside the project and its git work tree. A repository can set environment variables for hooks (the env block of a trusted project's .claude/settings.json), so hosted mode treats env as untrusted: KYA_OFFLINE, KYA_API_KEY, proxy variables and the project's .kya/config.json are ignored, and TLS, CA, proxy or code-loading overrides (NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS, NODE_USE_ENV_PROXY, NODE_DEBUG and every other NODE_*, SSL_*, OPENSSL_* or UV_* variable except NODE_ENV, NODE_NO_WARNINGS, NODE_DISABLE_COLORS and NODE_VERSION, any NODE_OPTIONS flag outside a small allowlist) are refused with PLANE_ENV_REFUSED. Certificates are always verified, redirects are never followed, the answer is capped at 64 KiB, and once the config is loaded the exact key (also split across two writes, or URL-encoded or aligned base64 within one write) is redacted, best effort, from string and Buffer writes to stdout and stderr; other encodings, Uint8Array writes and direct fd writes are not covered. DYLD_* and LD_* are refused too. A NODE_OPTIONS preload or a loader injection (LD_PRELOAD, DYLD_INSERT_LIBRARIES) has already run before this check, so the check can only stop the key from being sent; do not allow env overrides for agent sessions. A crash never lowers a decision: the local never-list still denies, even in shadow. Some failures kill node before kya runs (an invalid NODE_OPTIONS, a tiny heap), so hosted mode requires the host's "onFailure": "block". On Node 20 and Node 22 before 22.21, NODE_OPTIONS=--use-env-proxy is one of these; use Node 22.21+ or 24 for hosted mode.

Fleets

A repository can turn off user-level hooks with disableAllHooks. Deploy the hook in Claude Code managed settings with allowManagedHooksOnly and "onFailure": "block" for a hook that the repository cannot switch off.

Limits

The agent runs as you: it can read the key file and edit user settings. Removal is detected (evaluate traffic stops), not prevented. The full guide, managed-settings snippet and behaviour table ship as docs/hosted-hook.md in the public kya package with the release that includes this hook.