\r \r

Kevros\r

\r Cryptographic governance for autonomous agents: precision decisioning, provenance attestation, intent binding, capability delegation, policy analysis, and compliance export.\r \r Every decision gets a signed release token. Every action gets a hash-chained record. Every intent gets a cryptographic binding to its command. Downstream services verify independently — no callbacks, no trust assumptions.\r \r Base URL: https://governance.taskhawktech.com\r \r

Data Handling\r

\r This plugin sends data to the Kevros governance gateway. Understand what is transmitted before installing.\r \r Before tool execution (before_tool_call hook):\r

• Tool name and full input payload are sent to POST /governance/verify for policy evaluation.\r
• The gateway hashes raw payloads (SHA-256) on receipt. Only digests are stored in the provenance chain.\r \r After tool execution (after_tool_call hook):\r
• Tool name, a truncated output summary (up to 500 characters), and governance metadata (release token, epoch, verification ID) are sent to POST /governance/attest.\r
• If tool output contains sensitive data, the 500-char summary may include it. Review your tool outputs before enabling attestation, or disable post-execution attestation by setting autoAttest: false in config.\r \r Network behavior:\r
• All transmissions use HTTPS to https://governance.taskhawktech.com.\r
• If KEVROS_API_KEY is not set, the plugin calls POST /signup to auto-provision a free-tier key on first use (1,000 calls/month). Set the key explicitly to avoid implicit network signup.\r
• In enforce mode (default), unreachable gateway blocks high-risk tool calls. Use advisory mode for evaluation — it logs decisions without blocking.\r \r

Quick Start\r

\r Get an API key (free, instant, no payment):\r \r

curl -X POST https://governance.taskhawktech.com/signup \\r
  -H "Content-Type: application/json" \\r
  -d '{"agent_id": "your-agent-id"}'\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "api_key": "kvrs_...",\r
  "tier": "free",\r
  "monthly_limit": 1000,\r
  "usage": {\r
    "header": "X-API-Key"\r
  }\r
}\r
```\r
\r
Use the API key in all subsequent requests via the `X-API-Key` header.\r
\r
## Precision Decisioning\r
\r
**POST /governance/verify**\r
\r
Verify an action against policy bounds before execution. Returns ALLOW, CLAMP, or DENY with a cryptographic release token that any downstream service can verify independently.\r
\r
Request:\r
\r
```json\r
{\r
  "action_type": "api_call",\r
  "action_payload": {\r
    "endpoint": "/deploy",\r
    "service": "api-v2",\r
    "replicas": 3\r
  },\r
  "agent_id": "your-agent-id",\r
  "policy_context": {\r
    "max_values": { "replicas": 5 },\r
    "forbidden_keys": ["sudo", "force"]\r
  }\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "decision": "ALLOW",\r
  "verification_id": "a1b2c3d4-...",\r
  "release_token": "f7a8b9c0...",\r
  "applied_action": {\r
    "endpoint": "/deploy",\r
    "service": "api-v2",\r
    "replicas": 3\r
  },\r
  "reason": "All values within policy bounds",\r
  "epoch": 42,\r
  "provenance_hash": "e3b0c442...",\r
  "timestamp_utc": "2026-02-26T12:00:00Z"\r
}\r
```\r
\r
- **ALLOW** — proceed as planned. The `release_token` is proof.\r
- **CLAMP** — action was adjusted to safe bounds. Use `applied_action` instead of your original.\r
- **DENY** — action rejected. Do not proceed. `release_token` is null.\r
\r
Share the `release_token` with collaborating agents so they can independently verify the decision.\r
\r
## Provenance Attestation\r
\r
**POST /governance/attest**\r
\r
Record a completed action in a hash-chained, append-only evidence ledger. Each attestation extends your provenance chain. Your raw payload is SHA-256 hashed — actual data is never stored.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "action_description": "Deployed api-v2 with 3 replicas",\r
  "action_payload": {\r
    "service": "api-v2",\r
    "replicas": 3,\r
    "status": "success"\r
  },\r
  "context": {\r
    "environment": "production",\r
    "triggered_by": "scheduled"\r
  }\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "attestation_id": "b2c3d4e5-...",\r
  "epoch": 43,\r
  "hash_prev": "e3b0c442...",\r
  "hash_curr": "a1b2c3d4...",\r
  "timestamp_utc": "2026-02-26T12:00:01Z",\r
  "chain_length": 43\r
}\r
```\r
\r
A longer chain with consistent outcomes builds a higher trust score over time.\r
\r
## Intent Binding\r
\r
**POST /governance/bind**\r
\r
Bind a declared intent to a specific command. Creates a cryptographic link between what you plan to do and the command that does it. Prove later that you did exactly what you said you would.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "intent_type": "MAINTENANCE",\r
  "intent_description": "Scale api-v2 to handle traffic spike",\r
  "command_payload": {\r
    "action": "scale",\r
    "service": "api-v2",\r
    "replicas": 5\r
  },\r
  "goal_state": {\r
    "replicas": 5,\r
    "healthy": true\r
  }\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "intent_id": "c3d4e5f6-...",\r
  "intent_hash": "d4e5f6a7...",\r
  "binding_id": "e5f6a7b8-...",\r
  "binding_hmac": "a7b8c9d0...",\r
  "command_hash": "b8c9d0e1...",\r
  "epoch": 44,\r
  "timestamp_utc": "2026-02-26T12:00:02Z"\r
}\r
```\r
\r
Save `intent_id` and `binding_id` to verify outcomes later.\r
\r
## Verify Outcome\r
\r
**POST /governance/verify-outcome**\r
\r
Verify whether a bound intent achieved its goal state. Free when used with a prior `bind()` call.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "intent_id": "c3d4e5f6-...",\r
  "binding_id": "e5f6a7b8-...",\r
  "actual_state": {\r
    "replicas": 5,\r
    "healthy": true\r
  },\r
  "tolerance": 0.1\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "verification_id": "f6a7b8c9-...",\r
  "intent_id": "c3d4e5f6-...",\r
  "status": "ACHIEVED",\r
  "achieved_percentage": 100.0,\r
  "discrepancy": null,\r
  "evidence_hash": "c9d0e1f2...",\r
  "timestamp_utc": "2026-02-26T12:00:03Z"\r
}\r
```\r
\r
Status values: `ACHIEVED`, `PARTIALLY_ACHIEVED`, `FAILED`, `BLOCKED`, `TIMEOUT`. Free when used with a prior `bind()` call.\r
\r
## Compliance Bundle\r
\r
**POST /governance/bundle** — $0.05 per call\r
\r
Export your agent's full cryptographic trust record for compliance, auditing, or regulatory review.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "time_range_start": "2026-02-25T00:00:00Z",\r
  "time_range_end": "2026-02-26T12:00:00Z",\r
  "include_intent_chains": true,\r
  "include_pqc_signatures": true,\r
  "include_verification_instructions": true\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "bundle_id": "d4e5f6a7-...",\r
  "agent_id": "your-agent-id",\r
  "record_count": 42,\r
  "truncated": false,\r
  "chain_integrity": true,\r
  "time_range": {"start": "2026-02-25T00:00:00Z", "end": "2026-02-26T12:00:00Z"},\r
  "records": ["..."],\r
  "intent_chains": ["..."],\r
  "pqc_signatures": ["..."],\r
  "verification_instructions": "Recompute SHA-256...",\r
  "bundle_hash": "e5f6a7b8...",\r
  "timestamp_utc": "2026-02-26T12:00:04Z"\r
}\r
```\r
\r
## Batch Operations\r
\r
**POST /governance/batch**\r
\r
Execute up to 100 governance operations (verify, attest, bind) in a single call. Each sub-operation is metered individually at standard rates. Use for bulk processing or multi-step workflows.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "operations": [\r
    {\r
      "type": "verify",\r
      "params": {\r
        "action_type": "api_call",\r
        "action_payload": {"endpoint": "/deploy", "replicas": 3}\r
      }\r
    },\r
    {\r
      "type": "attest",\r
      "params": {\r
        "action_description": "Deployment completed",\r
        "action_payload": {"status": "success"}\r
      }\r
    }\r
  ],\r
  "stop_on_deny": false\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "batch_id": "g7h8i9j0-...",\r
  "agent_id": "your-agent-id",\r
  "total": 2,\r
  "executed": 2,\r
  "results": [\r
    {"index": 0, "type": "verify", "status": "ok", "result": {"decision": "ALLOW", "...": "..."}},\r
    {"index": 1, "type": "attest", "status": "ok", "result": {"attestation_id": "...", "...": "..."}}\r
  ],\r
  "summary": {"allow": 1, "clamp": 0, "deny": 0, "attest": 1, "bind": 0, "error": 0},\r
  "batch_hash": "a1b2c3d4..."\r
}\r
```\r
\r
If `stop_on_deny` is true, processing halts on the first DENY decision.\r
\r
## Capability Delegation\r
\r
**POST /governance/delegate**\r
\r
Grant scoped, time-limited capabilities to another agent. The delegation is HMAC-signed and recorded in the provenance chain. Supports hierarchical sub-delegation with restrictive scope intersection.\r
\r
Request:\r
\r
```json\r
{\r
  "delegator_agent_id": "your-agent-id",\r
  "delegatee_agent_id": "helper-agent-42",\r
  "scope": {\r
    "allowed_endpoints": ["verify", "attest"],\r
    "policy_overrides": {"max_values": {"replicas": 3}},\r
    "max_calls": 100\r
  },\r
  "ttl_seconds": 3600,\r
  "description": "Handle deployment verification",\r
  "allow_subdelegation": false\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "delegation_id": "h8i9j0k1-...",\r
  "delegation_token": "f7a8b9c0...",\r
  "delegator_agent_id": "your-agent-id",\r
  "delegatee_agent_id": "helper-agent-42",\r
  "scope": {"allowed_endpoints": ["verify", "attest"], "max_calls": 100},\r
  "expires_utc": "2026-02-26T13:00:00Z",\r
  "provenance_hash": "b8c9d0e1...",\r
  "chain_depth": 1\r
}\r
```\r
\r
The delegatee passes the `delegation_token` as `X-Delegate-Token` header when acting on behalf of the delegator.\r
\r
**GET /governance/delegations/{agent_id}** — list active delegations for an agent.\r
\r
**DELETE /governance/delegations/{delegation_id}** — revoke an active delegation.\r
\r
## Reversibility Check\r
\r
**POST /governance/check-reversibility**\r
\r
Check whether an intent chain can be reversed. Pre-abort safety check for multi-step workflows.\r
\r
Request:\r
\r
```json\r
{\r
  "intent_id": "c3d4e5f6-...",\r
  "include_children": true\r
}\r
```\r
\r
Returns reversibility status, constraints, time elapsed, and child dependency analysis.\r
\r
## Policy Replay\r
\r
**POST /governance/replay**\r
\r
Replay provenance records through an alternative policy. Deterministic "what-if" analysis: "What would have happened if we'd used policy X instead?"\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "template_id": "strict_safety",\r
  "limit": 50\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "total_replayed": 50,\r
  "replay_policy": {"max_values": {"speed": 3.0}},\r
  "changes": {"upgraded": 5, "downgraded": 12, "unchanged": 33},\r
  "results": [\r
    {\r
      "epoch": 42,\r
      "agent_id": "your-agent-id",\r
      "action_type": "motor_command",\r
      "original_decision": "ALLOW",\r
      "replayed_decision": "CLAMP",\r
      "change": "more_restrictive"\r
    }\r
  ]\r
}\r
```\r
\r
Use for policy regression testing before deploying new policies, or forensic investigation.\r
\r
## Counterfactual Analysis\r
\r
**POST /governance/counterfactual**\r
\r
Simulate an action against multiple policies simultaneously. Returns a decision matrix showing how each policy handles the same action.\r
\r
Request:\r
\r
```json\r
{\r
  "action_payload": {"endpoint": "/deploy", "replicas": 10},\r
  "action_type": "api_call",\r
  "policies": [\r
    {"label": "conservative", "template_id": "strict_safety"},\r
    {"label": "permissive", "policy_context": {"max_values": {"replicas": 20}}},\r
    {"label": "deny-all", "policy_context": {"forbidden_keys": ["replicas"]}}\r
  ],\r
  "include_historical": true,\r
  "agent_id": "your-agent-id"\r
}\r
```\r
\r
Response includes consensus analysis (do all policies agree?), decision distribution, and optional historical comparison.\r
\r
## Intent Navigation\r
\r
**GET /governance/intents/{intent_id}/children**\r
\r
Return all direct child intents of a parent intent. Audit multi-agent delegation hierarchies.\r
\r
**GET /governance/intents/{intent_id}/ancestry**\r
\r
Walk up the intent hierarchy from leaf to root. Full authorization chain for auditing.\r
\r
**GET /governance/intents/{intent_id}/tree**\r
\r
Return the full delegation tree rooted at an intent. Accepts optional `max_depth` query parameter (default 10).\r
\r
## Policy Templates\r
\r
**GET /governance/policy-templates** — free, no API key required\r
\r
List available named policy templates. Use template IDs with verify, replay, and counterfactual endpoints instead of inline policy definitions.\r
\r
## Export\r
\r
**POST /governance/export/csv** — export provenance records as CSV.\r
\r
**POST /governance/export/sarif** — export provenance in SARIF format (Static Analysis Results Interchange Format) for security tooling integration.\r
\r
**POST /governance/export/merkle** — export provenance as a Merkle tree with root hash and leaf hashes for independent integrity verification.\r
\r
All export endpoints accept optional `agent_id`, `time_range_start`, `time_range_end`, and `limit` parameters.\r
\r
## Health and Audit\r
\r
**GET /governance/health-score** — overall gateway health score including agent count, healthy agent count, and chain integrity rate.\r
\r
**GET /governance/audit-summary** — aggregate statistics across all provenance: total records, total agents, decision distribution, and chain integrity status.\r
\r
**GET /governance/agent-compliance/{agent_id}** — compliance profile for a specific agent: compliance score, chain integrity, total decisions, and outcome success rate.\r
\r
## Media Attestation\r
\r
**POST /media/attest** — $0.05 per call\r
\r
Attest media files (photos, videos, audio, documents) with SHA-256 hashing and provenance chain inclusion.\r
\r
Request:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",\r
  "media_type": "PHOTO",\r
  "media_size_bytes": 2048576,\r
  "capture_timestamp_utc": "2026-02-26T12:00:00Z",\r
  "description": "Generated report screenshot"\r
}\r
```\r
\r
Required fields: `agent_id`, `media_hash` (64-char hex SHA-256), `media_type` (PHOTO | VIDEO | AUDIO | DOCUMENT), `media_size_bytes`, `capture_timestamp_utc`.\r
\r
Optional fields: `description`, `tags`, `capture_location` (lat/lng), `device_info`, `frame_hashes` (for video).\r
\r
Response:\r
\r
```json\r
{\r
  "attestation_id": "e5f6a7b8-...",\r
  "certificate_id": "mca_abc123",\r
  "media_hash": "a1b2c3d4e5f6...",\r
  "media_type": "PHOTO",\r
  "epoch": 45,\r
  "hash_prev": "...",\r
  "hash_curr": "b8c9d0e1...",\r
  "verification_url": "https://governance.taskhawktech.com/media/verify/mca_abc123",\r
  "chain_length": 45,\r
  "timestamp_utc": "2026-02-26T12:00:05Z"\r
}\r
```\r
\r
## Media Verify\r
\r
**POST /media/verify** — free, no API key required\r
\r
Verify that media content matches a specific attestation certificate.\r
\r
Request:\r
\r
```json\r
{\r
  "media_hash": "a1b2c3d4e5f6...64-char-hex-sha256",\r
  "certificate_id": "mca_abc123"\r
}\r
```\r
\r
Response:\r
\r
```json\r
{\r
  "verified": true,\r
  "certificate_id": "mca_abc123",\r
  "media_hash_match": true,\r
  "chain_integrity": true,\r
  "pqc_signature_valid": true,\r
  "reason": "Media hash matches certificate, chain intact"\r
}\r
```\r
\r
## Media Verify Lookup\r
\r
**GET /media/verify/{certificate_id}** — free, no API key required\r
\r
Look up a specific media attestation by its certificate ID. Returns the full attestation record including attesting agent, epoch, and chain integrity.\r
\r
## Passport\r
\r
All Passport endpoints are free and require no authentication.\r
\r
**GET /passport/{agent_id}**\r
\r
Returns an agent's trust passport including score, tier, badges, and activity stats.\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "trust_score": 0.95,\r
  "tier": "gold",\r
  "badges": ["verified", "consistent", "high_volume"],\r
  "stats": {\r
    "total_decisions": 1250,\r
    "attestations": 890,\r
    "bindings": 340,\r
    "outcomes_achieved": 310,\r
    "chain_intact": true,\r
    "active_days": 45,\r
    "current_streak": 12\r
  }\r
}\r
```\r
\r
**GET /passport/{agent_id}/badge.svg**\r
\r
Returns an embeddable SVG trust badge. Use in agent descriptions, documentation, or dashboards.\r
\r
**GET /passport/{agent_id}/history**\r
\r
Returns full decision history for an agent.\r
\r
**GET /passport/leaderboard**\r
\r
Returns top trusted agents by trust score. Accepts optional `limit` query parameter (1-200, default 50).\r
\r
Response:\r
\r
```json\r
{\r
  "agents": [\r
    { "agent_id": "top-agent", "trust_score": 0.98, "tier": "gold" }\r
  ],\r
  "total": 150\r
}\r
```\r
\r
**POST /passport/{agent_id}/claim** — requires API key\r
\r
Link an agent's passport to your operator account. Must provide `X-API-Key` header.\r
\r
Response:\r
\r
```json\r
{\r
  "agent_id": "your-agent-id",\r
  "claimed": true,\r
  "profile": { "...passport profile..." }\r
}\r
```\r
\r
Returns 409 if already claimed by another operator, 404 if no passport exists yet.\r
\r
## Agent Discovery\r
\r
**GET /.well-known/agent.json**\r
\r
Returns the A2A protocol agent card. No authentication required.\r
\r
```bash\r
curl https://governance.taskhawktech.com/.well-known/agent.json\r
```\r
\r
Returns capabilities, supported skills, SDK references, and free-tier signup details.\r
\r
## MCP\r
\r
For MCP-native agents, connect directly via streamable-http transport:\r
\r
```\r
https://governance.taskhawktech.com/mcp/\r
```\r
\r
360 tools, 2 resources, 2 prompts. Auto-provisions a free-tier key on first tool call if no API key is provided.\r
\r
## Python SDK\r
\r
```bash\r
pip install kevros\r
# or\r
uv pip install kevros\r
```\r
\r
```python\r
from kevros_governance import GovernanceClient\r
\r
client = GovernanceClient(agent_id="your-agent-id")\r
result = client.verify(\r
    action_type="api_call",\r
    action_payload={"endpoint": "/deploy"},\r
    agent_id="your-agent-id",\r
)\r
print(result.decision)  # ALLOW, CLAMP, or DENY\r
```\r
\r
## Enforcement Modes\r
\r
Every operator key has an enforcement mode that controls how decisions are applied:\r
\r
- **enforce** (default) — fail-closed. DENY means DENY. Release tokens are only issued for ALLOW/CLAMP.\r
- **advisory** — shadow mode. DENY decisions are logged but overridden to ALLOW. No release token is issued for would-be denials. Use for testing policies before enforcing them.\r
- **gated** — human-in-the-loop. DENY decisions are held for operator approval. Poll `/governance/gated/{request_id}` for status.\r
- **deny** — kill-switch. ALL requests are blocked regardless of policy evaluation. Use for emergency shutdown.\r
\r
The `enforcement_mode` field is returned in every verify response. Use `/enforcement` to check your current mode.\r
\r
Enforcement mode changes require admin-level access and are not available through the plugin. Contact your administrator or use the admin API directly.\r
\r
## Decision Approach\r
\r
When collaborating with another agent:\r
\r
1. **Check their passport first** — `GET /passport/{agent_id}` returns trust score, tier, and history\r
2. **Embed badges** — Use `GET /passport/{agent_id}/badge.svg` in your agent's description to show your trust level\r
3. **Trust thresholds:**\r
   - **Gold tier (score >= 90%)** — proceed with normal collaboration\r
   - **Silver tier (score 50-89%)** — verify their actions before relying on results\r
   - **Bronze tier (score \x3C 50%)** — require bound intents with outcome verification\r
   - **No history** — start with small, low-risk interactions and build trust incrementally\r
4. **Verify before you rely** — Use `/governance/verify-token` to independently confirm any release token a peer shares with you\r
\r
## Pricing\r
\r
**Subscriptions:**\r
- **Free tier:** 1,000 calls/month, instant signup, no payment required\r
- **Scout:** $29/mo — 5,000 calls\r
- **Sentinel:** $149/mo — 50,000 calls\r
- **Sovereign:** $499/mo — 500,000 calls\r
\r
**Per-call (via x402 USDC, no subscription required):**\r
- Verify: $0.01\r
- Attest: $0.02\r
- Bind: $0.02\r
- Media Attest: $0.05\r
- Compliance Bundle: $0.05\r
- Batch: each sub-operation metered individually\r
- Verify Outcome: free with Bind\r
- Delegation, Replay, Counterfactual, Export, Health, Audit: metered per call\r
- Passport, Media Verify, Reputation, Verify Token, Policy Templates: free\r
\r
Subscription calls are metered against your monthly allowance. x402 per-call pricing applies when paying per-call without a subscription.\r
\r
Upgrade at `https://www.taskhawktech.com/pricing`\r