What Shield KYA records and how the approval loop works

Shield KYA (Know Your Agent) is a record and a checkpoint for AI agents. An agent asks KYA before it runs a tool. KYA gives one of three answers: ALLOW, DENY or REQUIRE_APPROVE. Each answer goes into a trail that you can read later.

One command shows what your coding agents did

The CLI is the npm package @shield-agent/kya. It is free and MIT licensed. Run this in a project:

kya start

This command sets up KYA, connects it to your coding agents over MCP and opens a live activity report. The report shows each tool call, the answer, and the project. All projects write to one local trail, ~/.kya/trail.jsonl. To open the report again later, run kya receipt --open.

The local CLI is advisory and fails open

On your laptop, KYA gives warnings, not blocks. If KYA has an error, the tool call continues. The only exception is a small never-list: a short list of dangerous calls that KYA always denies.

This is intentional. A local tool that breaks your work when it fails is a tool that people remove. The local CLI gives you the record. It does not give you enforcement.

Hosted enforces and fails closed

Real enforcement runs on the MCP policy path against a hosted workspace. The hosted console uses fail closed defaults:

• In the approval workflow, an action that needs approval does not run until a person approves it.
• A policy DENY blocks the action. There is no silent bypass.
• Session risk can only make a decision more strict. It never allows a high-stakes action automatically.

To send events to a console, set KYA_BASE_URL and KYA_API_KEY.

Human approval is opt-in

By default, KYA only observes. It records the trail and does not ask for a second approval. Human approval is a hosted feature. When you run a tool through kya wrap against a hosted workspace (KYA_BASE_URL and KYA_API_KEY set), set KYA_HOLD=1 to hold risky actions for a person.

When KYA holds an action, the action waits in Approvals in the console. A person sees the tool, the agent and the scope. The person accepts or rejects. Until then, the write stays blocked. KYA records each check and each hold on the trail.

A chat reaction is never an approval

The hosted console can post a notice about a new approval request to a chat channel. That notice only links to the console. A chat message, a chat reaction or a webhook delivery is never an approval. Only a decision in the approval workflow approves a request. A high-risk approval needs the console and a fresh MFA code. Reject is always available.

Signed certify

kya certify checks your setup against the open Agent Trust Baseline and writes a gap report to .kya/certify/. With --sign, it also writes a signed evidence bundle. Anyone can verify the bundle offline with the public key in the bundle.

A bundle that you sign with your local key proves integrity and the continuity of a key. It does not prove identity. Only a passing bundle signed with the key of an active hosted workspace gets the green Shield Verified badge. That badge ties the bundle to a hosted account. It does not prove the legal identity of a company or an agent.

Next steps

Read How KYA works for the full model, or go to Install to start.