Kevros

Kevros

Cryptographic governance for autonomous agents: precision decisioning, provenance attestation, intent binding, capability delegation, policy analysis, and compliance export.

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.

Base URL: https://governance.taskhawktech.com

Data Handling

This plugin sends data to the Kevros governance gateway. Understand what is transmitted before installing.

Before tool execution (before_tool_call hook):

• Tool name and full input payload are sent to POST /governance/verify for policy evaluation.
• The gateway hashes raw payloads (SHA-256) on receipt. Only digests are stored in the provenance chain.

After tool execution (after_tool_call hook):

• Tool name, a truncated output summary (up to 500 characters), and governance metadata (release token, epoch, verification ID) are sent to POST /governance/attest.
• 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.

Network behavior:

• All transmissions use HTTPS to https://governance.taskhawktech.com.
• 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.
• In enforce mode (default), unreachable gateway blocks high-risk tool calls. Use advisory mode for evaluation — it logs decisions without blocking.

Quick Start

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

curl -X POST https://governance.taskhawktech.com/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id"}'

Response:

{
  "api_key": "kvrs_...",
  "tier": "free",
  "monthly_limit": 1000,
  "usage": {
    "header": "X-API-Key"
  }
}

Use the API key in all subsequent requests via the X-API-Key header.

Precision Decisioning

POST /governance/verify

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.

Request:

{
  "action_type": "api_call",
  "action_payload": {
    "endpoint": "/deploy",
    "service": "api-v2",
    "replicas": 3
  },
  "agent_id": "your-agent-id",
  "policy_context": {
    "max_values": { "replicas": 5 },
    "forbidden_keys": ["sudo", "force"]
  }
}

Response:

{
  "decision": "ALLOW",
  "verification_id": "a1b2c3d4-...",
  "release_token": "f7a8b9c0...",
  "applied_action": {
    "endpoint": "/deploy",
    "service": "api-v2",
    "replicas": 3
  },
  "reason": "All values within policy bounds",
  "epoch": 42,
  "provenance_hash": "e3b0c442...",
  "timestamp_utc": "2026-02-26T12:00:00Z"
}

• ALLOW — proceed as planned. The release_token is proof.
• CLAMP — action was adjusted to safe bounds. Use applied_action instead of your original.
• DENY — action rejected. Do not proceed. release_token is null.

Share the release_token with collaborating agents so they can independently verify the decision.

Provenance Attestation

POST /governance/attest

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.

Request:

{
  "agent_id": "your-agent-id",
  "action_description": "Deployed api-v2 with 3 replicas",
  "action_payload": {
    "service": "api-v2",
    "replicas": 3,
    "status": "success"
  },
  "context": {
    "environment": "production",
    "triggered_by": "scheduled"
  }
}

Response:

{
  "attestation_id": "b2c3d4e5-...",
  "epoch": 43,
  "hash_prev": "e3b0c442...",
  "hash_curr": "a1b2c3d4...",
  "timestamp_utc": "2026-02-26T12:00:01Z",
  "chain_length": 43
}

A longer chain with consistent outcomes builds a higher trust score over time.

Intent Binding

POST /governance/bind

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.

Request:

{
  "agent_id": "your-agent-id",
  "intent_type": "MAINTENANCE",
  "intent_description": "Scale api-v2 to handle traffic spike",
  "command_payload": {
    "action": "scale",
    "service": "api-v2",
    "replicas": 5
  },
  "goal_state": {
    "replicas": 5,
    "healthy": true
  }
}

Response:

{
  "intent_id": "c3d4e5f6-...",
  "intent_hash": "d4e5f6a7...",
  "binding_id": "e5f6a7b8-...",
  "binding_hmac": "a7b8c9d0...",
  "command_hash": "b8c9d0e1...",
  "epoch": 44,
  "timestamp_utc": "2026-02-26T12:00:02Z"
}

Save intent_id and binding_id to verify outcomes later.

Verify Outcome

POST /governance/verify-outcome

Verify whether a bound intent achieved its goal state. Free when used with a prior bind() call.

Request:

{
  "agent_id": "your-agent-id",
  "intent_id": "c3d4e5f6-...",
  "binding_id": "e5f6a7b8-...",
  "actual_state": {
    "replicas": 5,
    "healthy": true
  },
  "tolerance": 0.1
}

Response:

{
  "verification_id": "f6a7b8c9-...",
  "intent_id": "c3d4e5f6-...",
  "status": "ACHIEVED",
  "achieved_percentage": 100.0,
  "discrepancy": null,
  "evidence_hash": "c9d0e1f2...",
  "timestamp_utc": "2026-02-26T12:00:03Z"
}

Status values: ACHIEVED, PARTIALLY_ACHIEVED, FAILED, BLOCKED, TIMEOUT. Free when used with a prior bind() call.

Compliance Bundle

POST /governance/bundle — $0.05 per call

Export your agent's full cryptographic trust record for compliance, auditing, or regulatory review.

Request:

{
  "agent_id": "your-agent-id",
  "time_range_start": "2026-02-25T00:00:00Z",
  "time_range_end": "2026-02-26T12:00:00Z",
  "include_intent_chains": true,
  "include_pqc_signatures": true,
  "include_verification_instructions": true
}

Response:

{
  "bundle_id": "d4e5f6a7-...",
  "agent_id": "your-agent-id",
  "record_count": 42,
  "truncated": false,
  "chain_integrity": true,
  "time_range": {"start": "2026-02-25T00:00:00Z", "end": "2026-02-26T12:00:00Z"},
  "records": ["..."],
  "intent_chains": ["..."],
  "pqc_signatures": ["..."],
  "verification_instructions": "Recompute SHA-256...",
  "bundle_hash": "e5f6a7b8...",
  "timestamp_utc": "2026-02-26T12:00:04Z"
}

Batch Operations

POST /governance/batch

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.

Request:

{
  "agent_id": "your-agent-id",
  "operations": [
    {
      "type": "verify",
      "params": {
        "action_type": "api_call",
        "action_payload": {"endpoint": "/deploy", "replicas": 3}
      }
    },
    {
      "type": "attest",
      "params": {
        "action_description": "Deployment completed",
        "action_payload": {"status": "success"}
      }
    }
  ],
  "stop_on_deny": false
}

Response:

{
  "batch_id": "g7h8i9j0-...",
  "agent_id": "your-agent-id",
  "total": 2,
  "executed": 2,
  "results": [
    {"index": 0, "type": "verify", "status": "ok", "result": {"decision": "ALLOW", "...": "..."}},
    {"index": 1, "type": "attest", "status": "ok", "result": {"attestation_id": "...", "...": "..."}}
  ],
  "summary": {"allow": 1, "clamp": 0, "deny": 0, "attest": 1, "bind": 0, "error": 0},
  "batch_hash": "a1b2c3d4..."
}

If stop_on_deny is true, processing halts on the first DENY decision.

Capability Delegation

POST /governance/delegate

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.

Request:

{
  "delegator_agent_id": "your-agent-id",
  "delegatee_agent_id": "helper-agent-42",
  "scope": {
    "allowed_endpoints": ["verify", "attest"],
    "policy_overrides": {"max_values": {"replicas": 3}},
    "max_calls": 100
  },
  "ttl_seconds": 3600,
  "description": "Handle deployment verification",
  "allow_subdelegation": false
}

Response:

{
  "delegation_id": "h8i9j0k1-...",
  "delegation_token": "f7a8b9c0...",
  "delegator_agent_id": "your-agent-id",
  "delegatee_agent_id": "helper-agent-42",
  "scope": {"allowed_endpoints": ["verify", "attest"], "max_calls": 100},
  "expires_utc": "2026-02-26T13:00:00Z",
  "provenance_hash": "b8c9d0e1...",
  "chain_depth": 1
}

The delegatee passes the delegation_token as X-Delegate-Token header when acting on behalf of the delegator.

GET /governance/delegations/{agent_id} — list active delegations for an agent.

DELETE /governance/delegations/{delegation_id} — revoke an active delegation.

Reversibility Check

POST /governance/check-reversibility

Check whether an intent chain can be reversed. Pre-abort safety check for multi-step workflows.

Request:

{
  "intent_id": "c3d4e5f6-...",
  "include_children": true
}

Returns reversibility status, constraints, time elapsed, and child dependency analysis.

Policy Replay

POST /governance/replay

Replay provenance records through an alternative policy. Deterministic "what-if" analysis: "What would have happened if we'd used policy X instead?"

Request:

{
  "agent_id": "your-agent-id",
  "template_id": "strict_safety",
  "limit": 50
}

Response:

{
  "total_replayed": 50,
  "replay_policy": {"max_values": {"speed": 3.0}},
  "changes": {"upgraded": 5, "downgraded": 12, "unchanged": 33},
  "results": [
    {
      "epoch": 42,
      "agent_id": "your-agent-id",
      "action_type": "motor_command",
      "original_decision": "ALLOW",
      "replayed_decision": "CLAMP",
      "change": "more_restrictive"
    }
  ]
}

Use for policy regression testing before deploying new policies, or forensic investigation.

Counterfactual Analysis

POST /governance/counterfactual

Simulate an action against multiple policies simultaneously. Returns a decision matrix showing how each policy handles the same action.

Request:

{
  "action_payload": {"endpoint": "/deploy", "replicas": 10},
  "action_type": "api_call",
  "policies": [
    {"label": "conservative", "template_id": "strict_safety"},
    {"label": "permissive", "policy_context": {"max_values": {"replicas": 20}}},
    {"label": "deny-all", "policy_context": {"forbidden_keys": ["replicas"]}}
  ],
  "include_historical": true,
  "agent_id": "your-agent-id"
}

Response includes consensus analysis (do all policies agree?), decision distribution, and optional historical comparison.

Intent Navigation

GET /governance/intents/{intent_id}/children

Return all direct child intents of a parent intent. Audit multi-agent delegation hierarchies.

GET /governance/intents/{intent_id}/ancestry

Walk up the intent hierarchy from leaf to root. Full authorization chain for auditing.

GET /governance/intents/{intent_id}/tree

Return the full delegation tree rooted at an intent. Accepts optional max_depth query parameter (default 10).

Policy Templates

GET /governance/policy-templates — free, no API key required

List available named policy templates. Use template IDs with verify, replay, and counterfactual endpoints instead of inline policy definitions.

Export

POST /governance/export/csv — export provenance records as CSV.

POST /governance/export/sarif — export provenance in SARIF format (Static Analysis Results Interchange Format) for security tooling integration.

POST /governance/export/merkle — export provenance as a Merkle tree with root hash and leaf hashes for independent integrity verification.

All export endpoints accept optional agent_id, time_range_start, time_range_end, and limit parameters.

Health and Audit

GET /governance/health-score — overall gateway health score including agent count, healthy agent count, and chain integrity rate.

GET /governance/audit-summary — aggregate statistics across all provenance: total records, total agents, decision distribution, and chain integrity status.

GET /governance/agent-compliance/{agent_id} — compliance profile for a specific agent: compliance score, chain integrity, total decisions, and outcome success rate.