Shield KYA — public baseline

Know Your Agent control plane for agent tools: identity, policy, dual-plane host labels, human approval, trail.

One command

npx @shield-agent/kya@latest --help

Free try (offline, no account):

npx @shield-agent/kya@latest eval-tool --offline --tool-id org.sample.never.event --irreversible
# → DENY
npx @shield-agent/kya@latest eval-tool --offline --tool-id org.sample.data.write --irreversible
# → REQUIRE_APPROVE

npx @shield-agent/kya@latest dash --once --offline
# → free terminal dashboard (sample policy pane; not production PEP)

Public GitHub: https://github.com/The-Pixel-Boys/shield-kya

This directory is the thin public surface (MIT) for PLG: sample custom tools only, honest LIMITATIONS, dual-plane diagram, comparison table. The monorepo may stay private; publish this tree (or the npm package) for stars/downloads.

Dual plane (host=ide | host=runtime)

┌─────────────────────┐         ┌──────────────────────┐
│  host=ide           │         │  host=runtime        │
│  authoring / dry-run│         │  production work     │
└──────────┬──────────┘         └──────────┬───────────┘
           │                               │
           └────────────┬──────────────────┘
                        ▼
              ┌───────────────────┐
              │  Shield KYA PEP   │
              │  sole enforcement │
              │  ALLOW | DENY |   │
              │  REQUIRE_APPROVE  │
              └─────────┬─────────┘
                        │
              human plane (approve)
                        │
              trail / observe metrics

Same agent identity, policy, approval, and trail on both hosts. Missing APPROVED ⇒ no irreversible side effect. Risk may only raise severity, never auto-ALLOW.

Sample custom tools only

No vertical packs required (disputes optional elsewhere).

Custom tools are first-class via stable toolId + metadata. Register your own; no prebuilt adapter required.

Commands

Package: @shield-agent/kya · MCP: server.json / mcpName in package.

Comparison (honest)

Positioning: own protocol-first dual-plane identity + approval + trail (“KYA checkpoint”). Do not try to out-AGT on multi-lang runtime governance, out-OPA as general policy infra, or out-NeMo-class dialog rails.

LIMITATIONS

• Offline --offline evaluate / dash is a sample fixture for demos and tests — not the production PEP.
• Production enforcement requires a control plane (local free console or hosted). Empty API key against an auth plane fails closed.
• This baseline ships sample custom tools only — no disputes pack, no vendor marketplace adapter as a core dependency.
• ORR / scanners produce evidence; they never ALLOW irreversible side effects (no dual PEP).
• Enterprise pin/private registry, multi-tenant density, ORR board ops, and support are a separate tier — they must not block day-1 solo PLG.
• Growth unit economics for KYA = observe metrics (principals, evaluates, approvals, orphans) — not quality/speed OKRs.
• Monorepo internals may remain private; npm package + this baseline are the public surface.

Good first issues

• Add a sample custom toolId descriptor + offline test
• Host-agnostic MCP snippet for your editor
• Translate LIMITATIONS for a new language
• ORR probe for an additional first-party signal (read-only)

Enterprise (distinct)

Never block PLG on enterprise gates.

Links

• Install: https://shield-agent.com/install
• Package source (when monorepo visible): sdks/kya/
• Doctrine: sole PEP = Shield KYA · dual-plane labels · custom tools first-class

License: MIT — see LICENSE.