Skip to content

ACS Guardian

What it is

The ACS Guardian governs an agent that speaks the OWASP Agent Control Standard (ACS). An ACS-emitting harness — a Claude Code or OpenCode shim, for example — posts its lifecycle hooks as JSON-RPC to POST /acs, and the Guardian decides each action against your Kyvvu policies before it runs. A framework that does not emit ACS natively needs a thin shim that posts these envelopes; kyvvu-acs/examples/claude-code/ is the template. It ships as the kyvvu-acs package and adds the kyvvu acs commands to the kyvvu command line.

The Guardian is built in three layers, each with one job:

Layer Path Owns
ACS wire kyvvu_acs/acs/ JSON-RPC framing, schema validation, signature, replay, the ContextEntry chain, the handshake, the 19-method table and its eligibility, the ask substitution, the error registry, the envelope logs
Mapping kyvvu_acs/mapping/ ACS event → match context → template → an AAG Behavior
Guardian kyvvu_acs/guardian.py session → task state, evaluate / record / end_task, the engine Action → ACS decision table, the ask → step.gate bookkeeping

The wire layer never imports the engine, and the mapping layer never imports the wire layer or the Guardian — so the mapper can be tested on captured events with no server, and the wire layer with a stub decider and no engine.

Install

uv tool install kyvvu-acs

Or, into an existing environment:

pip install kyvvu-acs

Installing kyvvu-acs pulls in the kyvvu command line and registers the kyvvu acs plugin, so kyvvu acs serve is available immediately.

Getting started

The quickest start needs no manifest and no account: --baseline enforces the ACS Guardian policies bundled in the package (below). Start a Guardian on them, then drive it with the mock harness. kyvvu acs serve comes with the installed package; the mock harness is not in the wheel — it runs from a checkout of the repository:

kyvvu acs serve --baseline --allow-unsigned
# in a second shell, from a checkout of the Kyvvu platform repository:
python kyvvu-acs/harness/mock_harness.py --url http://127.0.0.1:8787/acs --scenario full

The harness replays a whole session — a handshake, every method once, a subagent, MCP, an allowed call with its result, a credential read, and sessionEnd. It validates every response, recomputes the chain_hash sequence, verifies response signatures, prints one line per hook, and exits non-zero on a protocol failure. A Read README.md is allowed and rm -rf / is denied. The credential read needs a preceding human approval gate, so it is denied with reason_codes: ["kyvvu_block"]; start the Guardian with --ask as well and it is answered ask instead (see Decisions).

In platform mode you get the platform's default, not this set. A Guardian started with only --api-key enforces whatever the platform assigns to the agent it registers, and today that is the generic platform baseline, not the bundled ACS Guardian policies. Until the platform default for an ACS agent follows the bundled manifest, assign that manifest (kyvvu_acs/acs-guardian.yaml) to the agent yourself, or use --baseline where you need the ACS-specific policies.

Your own policies

Write a three-policy manifest — recursive delete of root, an egress allowlist, and no exec after a secret read:

name: "My ACS policies"
version: "1.0.0"
policies:
  - name: "No recursive delete of root"
    rule_type: not
    params:
      condition:
        rule_type: field_matches_regex
        params:
          field: properties.command
          pattern: "^(?:.*[;&|]\\s*)?rm\\s+(?:-\\S+\\s+)*-\\S*[rR]\\S*\\s+/(?:\\s|$|\\*)"
    severity: critical
    enforcement_point: step_execution
  - name: "Egress restricted to approved domains"
    rule_type: any_of
    params:
      conditions:
        - rule_type: not
          params:
            condition:
              rule_type: field_matches_regex
              params:
                field: properties.target.trust
                pattern: "^external$"
        - rule_type: domain_allowlist
          params:
            allowed_domains: ["anthropic.com"]
            target_kinds: ["step.resource", "step.exec"]
    severity: critical
    enforcement_point: step_execution
  - name: "No exec after secret read"
    rule_type: tainted_path_block
    params:
      taint_kind: step.resource
      taint_verb: GET
      taint_property_filter:
        data.classification: secret
      target_kinds: ["step.exec"]
    severity: critical
    enforcement_point: step_execution

Start a Guardian on it and drive it with the same harness:

# from a checkout of the Kyvvu platform repository:
kyvvu acs serve --policy-file my-policies.yaml --allow-unsigned
python kyvvu-acs/harness/mock_harness.py --url http://127.0.0.1:8787/acs --scenario full

rm -rf / is denied; the README.md read is allowed.

Wire up an ACS harness

  • URL. The harness posts to POST /acs (default http://127.0.0.1:8787); the reference shims read it from ACS_GUARDIAN_URL.
  • Signing. ACS's v0.1 baseline is a shared-secret HMAC. Set KV_ACS_HMAC_SECRETS to one or more key_id=hex pairs (two or more lets you rotate: add the new key, roll the harness, drop the old). The signing procedure — JCS of the envelope without signature, HKDF-SHA256 per session, HMAC-SHA256, replay rules, response signing and chain_hash — is in kyvvu_acs/acs/README.md (in the repository).
  • --allow-unsigned. The reference shims emit no signature, so they need this; under it the Guardian signs nothing back. Without a secret and without --allow-unsigned, the Guardian refuses to start rather than reject every request as unsigned.
  • --ask. Off by default, so ask is opt-in. A policy that requires a human approval gate produces an ask only when --ask is set; otherwise the Guardian answers deny with reason_codes: ["kyvvu_block"], like any other block, and nothing waits for an approval. Set it only for a harness that really prompts a person on ask: the Guardian infers the approval from the harness's toolCallResult (see Decisions).
  • Fail-closed posture. --on-decision-failure defaults to deny — the opposite of the reference Guardian — so a Guardian that cannot reach a verdict blocks rather than waving the action through.
  • Log files. Every request/response pair is appended to <log-root>/.acs/envelopes.jsonl, and every ContextEntry to <log-root>/.acs/session-context.jsonl.
  • Where the recorded trace goes. With a platform source (--api-key) the Guardian ships every recorded step to your workspace, under the agent it registered (named by --agent-key) — the steps appear on that agent's Logs page, like any other integration — in addition to the local .acs/ files. The Guardian self-registers that agent the first time it starts, so the trace lands without a separate setup step. With a local source (--policy-file / --baseline) there is no platform to ship to, so the trace stays in .acs/ only. A session that never sends its end boundary is not lost: the Guardian flushes buffered steps when it stops, and the engine's background sweeper flushes idle/abandoned sessions.
  • Claude Code (an ACS-interop example, not the recommended integration). A worked shim is in kyvvu-acs/examples/claude-code/: start the Guardian with --ask, copy the hook snippet, run Claude Code, and a rm -rf / is denied, a benign command allowed, and a file write prompted. It demonstrates that this Guardian governs Claude Code over ACS. To govern Claude Code in production, prefer the first-class kyvvu-claude integration, which covers more of Claude Code's surface than a lifecycle-hook shim can.
  • Agent identity — you govern a Guardian, not the harness directly. In ACS terms a harness talks to a Guardian. That Guardian is itself registered as one Kyvvu agent, tied to your API key, and every decision and log line is recorded under it — so the trace lands in the right workspace under the right agent. You name that agent with --agent-key (default acs-<host>-<user>), which is the name it shows up under on the platform. The agent_id an ACS harness puts in its envelopes is the harness's own identifier: in platform mode it is advisory — the Guardian neither requires it to match nor records under it, and accepts any value, "Claude Code" included. It is kept on every step the Guardian records, as properties.acs.agent_id, so two harnesses sharing one Guardian can be told apart in the trace. They still share one Kyvvu agent, and therefore its per-agent policies: a usage_budget or a rate limit counts both harnesses' steps together. To keep them apart, run one Guardian per harness, each with its own --agent-key and port. (With a local source there is no registered agent, so the Guardian instead binds to the first envelope's agent and refuses a later different one with SESSION_REFUSED — one Guardian per agent. There the id must be 1-255 letters, digits and . _ : -; an empty or malformed id is refused with SESSION_REFUSED before anything is bound.)

The pipeline is tested on captured events in kyvvu-acs/tests/, end to end in tests/test_e2e.py, and the Claude Code shim in examples/claude-code/.

Exactly one policy source wins. A local source (--policy-file or --baseline) outranks and clears the platform credentials; a pure-platform configuration needs only an API key (--api-key, or KV_API_KEY in the environment). --api-url defaults to https://platform.kyvvu.com, the Guardian derives a stable agent_key (acs-<host>-<user>) and self-registers the agent — assigning its baseline — then fetches that agent's assigned policies and ships its recorded trace back to that workspace. --agent-key and --api-url are optional overrides, never required. With no source named, the command exits with a three-option message — there is no default source. --baseline loads the bundled ACS Guardian manifest: a Read README.md or Bash ls -la is allowed, while Bash rm -rf / is denied. The generic platform baseline also checks the template's declared tool names and allows file reads and plain ls directory listings immediately. Other shell commands require a preceding approval gate; with --ask, that gate becomes an approval prompt.

How ACS events map to AAG

Each ACS hook is flattened into a match context (event = the method tail, name = the tool name, plus the capability, command, target host, MCP facts and so on) and run through the bundled behaviour template, which produces the AAG Behavior your policies evaluate. That behaviour's kind field names the action type — step.exec for a command, step.resource for a file or network access, step.message for a message, task.start/task.end for a session boundary — and is what a rule's target_kinds match against.

For shell tools and the process capability, the command context supplies exec_kind and exec_verb: a literal ls with simple options and paths maps to step.resource GET; other commands map to step.exec. Commands containing shell operators, redirects, expansions, quotes or newlines remain execution.

Capabilities use the action's verb: read/list → GET, create/write → POST, update → PATCH, and delete/remove → DELETE. The secret, secrets, credential and vault domains map to step.credential; other capabilities with these actions map to step.resource, even without arguments. MCP rules run first so tool names retain their server and tool identity.

For an unrecognised tool, a command argument uses the execution mapping; otherwise a URL argument maps to an external resource GET, and a path/file argument to a local one. Shell commands expose the host of their first URL, or with no URL a bare curl/wget destination, as target.host, with target.trust: external except for localhost and loopback addresses. The example egress allowlist covers both resource and execution steps.

One row per template rule, generated from acs.template.yaml:

Rule Matches when AAG behaviour
mcp_tools_call mcp_method = tools/call step.resource {{ mcp_verb }}
mcp_resources_read mcp_method = resources/read step.resource GET
mcp_other is_mcp = True step.resource GET
cap_process_execute capability_domain = process {{ exec_kind }} {{ exec_verb }}
cap_credential is_credential_capability = True step.credential {{ capability_verb }}
cap_resource has_capability_action = True step.resource {{ capability_verb }}
cap_network_egress capability = network.egress step.resource POST
tool_exec name_pattern = ^(bash|shell|run_shell|run|sh|exec|cmd)$ {{ exec_kind }} {{ exec_verb }}
tool_read name_pattern = ^(read|read_file|glob|grep|cat|view)$ step.resource GET
tool_write name_pattern = ^(write|write_file|create_file|put)$ step.resource POST
tool_edit name_pattern = ^(edit|patch|apply_patch|multiedit)$ step.resource PATCH
tool_web name_pattern = ^(webfetch|web_fetch|fetch|websearch|web_search|http_get|curl|wget)$ step.resource GET
user_message event = userMessage step.message GET
agent_response event = agentResponse step.message POST
agent_trigger_message event = agentTrigger, trigger_type = user_message step.message GET
agent_trigger_activation event = agentTrigger step.message GET
memory_context_retrieval event = memoryContextRetrieval step.self GET
memory_store_delete event = memoryStore, operation = delete step.self DELETE
memory_store_update event = memoryStore, operation = update step.self PATCH
memory_store_create event = memoryStore step.self POST
knowledge_retrieval event = knowledgeRetrieval step.resource GET
skill_register event = skillRegister step.self POST
skill_load event = skillLoad step.self POST
skill_unload event = skillUnload step.self DELETE
argument_command has_command_argument = True {{ exec_kind }} {{ exec_verb }}
argument_url has_url_argument = True step.resource GET
argument_path has_path_argument = True step.resource GET
unknown (catch-all) step.unknown

ACS defines 19 lifecycle methods; four carry no AAG step and are ignored, each with a reason from the AAG ↔ ACS mapping document:

Method Why it carries no AAG step
turnStart AAG has no turn level between task and step. A user-message turn is already visible as the step.message that received it.
turnEnd No AAG turn level. AAG carries taint across the whole task, so "deny consequential actions after an untrusted turn" already holds; what AAG cannot express is a per-turn count.
preCompact AAG records the path outside the model's context, so compacting that context does not change the path.
postCompact Same: the path is recorded outside the model context.

Mapping outside the template

A few mapping facts the template format cannot express stay in Python (kyvvu_acs/mapping/mapper.py):

  • Secret classification on a path. A .env / .env.<name> (not .env.example, .env.sample or .env.template) / .pem / .key / .p12 / .pfx / .secret / .credentials / .pgpass / .netrc / .aws/credentials / .ssh/id_* (not *.pub) path tags the step data.classification: secret, the same files Claude Code treats as secrets. The template engine interpolates strings but cannot include a key based on a value's shape.
  • Output truncation. A toolCallResult's concatenated outputs are truncated at 2000 characters; a rule sets only static output fields.
  • Task boundaries. A task.* kind needs an aag_version and carries no verb, input or output — outside the five fields a rule's behavior block may set — so these are built directly.
  • A non-message agentTrigger with no task open. The template maps every agentTrigger to an inbound step.message GET (a scheduled trigger on channel scheduled), but when no task is open for the session the Guardian makes it the task's task.start instead, evaluated like sessionStart: a policy may refuse the activation, and a refused one is not recorded.
  • The task.end / task.error split. Chosen from the end payload's enum value (error / timeout / failed → task.error), a value-conditional kind a rule cannot select.
  • MCP verb derivation. The verb is a heuristic over the tool name, from the one write list kyvvu-acs and kyvvu-claude share: the first word of the name on the list (add_comment, github_add_comment, sendEmail) makes it POST, PATCH or DELETE, and a name with no word on the list counts as a read (GET). A rule interpolates the derived value but cannot compute it; to reclassify a specific tool, an overlay rule matching its name sets the verb itself.

Enriching the mapping with an overlay

A tool call the base template cannot classify maps to step.unknown. You refine this without waiting for a release by passing a --template overlay. The overlay is deep-merged onto the bundled template with its rules placed first, so a rule that recognises your harness's tool wins the first-match evaluation.

For example, this overlay (overlay.yaml) classifies a harness tool HttpGet as an external resource GET:

rules:
  - id: http_get
    match:
      name_pattern: "^HttpGet$"
    behavior:
      kind: step.resource
      verb: GET
      step_name: HttpGet
      properties:
        target:
          resource_type: url
          trust: external
kyvvu acs serve --policy-file my-policies.yaml --template overlay.yaml --allow-unsigned

Before the overlay, a HttpGet call that passes its destination as address, an argument name the shape rules do not know, is step.unknown, and the egress policy does not see it. After it, the call is a step.resource GET with trust: external, which the egress allowlist constrains like any other external-network step.

Decisions

The Guardian renders the engine's verdict into an ACS decision:

Engine ACS decision Fields
allow allow policy_references
warn allow reason_codes: ["kyvvu_warn"], reasoning, policy_references
block, every violated policy a gate requirement, on a tool call, with --ask ask reasoning, ask_details, reason_codes: ["kyvvu_gate_required"], policy_references
block, otherwise deny reasoning, reason_codes: ["kyvvu_block"], policy_references

A warn is always allow, whatever the severity of the policy that fired; the Guardian never turns a warning into an ask (see Known limitations).

ask → step.gate. ACS answers "this action needs approval" with ask; AAG answers it with a step.gate on the path before the action (step_requires_gate). The Guardian connects the two. When --ask is set and a steps/toolCallRequest or protocols/MCP/tools/call is blocked only by gate requirements, it registers an intended step.gate (properties.kind: human) on the task path and answers ask. Those are the two hooks a result settles; any other gate-only block is a plain deny.

ACS v0.1.0 has no hook that carries an approval outcome, so the Guardian infers it. The only signal it receives is the toolCallResult whose request_id_ref names the asked request:

  • With exit_status: success the action ran, so it was approved. The Guardian first checks that the approved step is still allowed once the gate passes (the path may have become tainted meanwhile). If it is, it records the gate passed (output.decision: pass) and then the approved step, completed. If it is not, it records the gate deny and the step's block, and never leaves a passing gate for a step that was blocked.
  • With blocked, failure or timeout the gate is recorded deny, and the step is not recorded, because it did not run.

The result hook itself is audit-only and is always answered allow. The approval is only as trustworthy as the harness's report of it: a harness that runs the tool without prompting anyone, and then sends a successful result, creates a passing gate. That is the same trust the Guardian places in every hook a harness signs, and ACS gives it no stronger signal.

How far an approval reaches is set by the policy, not by the Guardian. step_requires_gate allows a step if any passing gate lies within its window, and a later deny gate does not withdraw an earlier pass. The Guardian cannot limit an approval to the one request it was asked for; the policy's max_steps_since_gate does. The bundled manifest's credential gate sets max_steps_since_gate: 1, so an approval covers exactly the access it was asked for and the next credential read asks again. Without it, one approval lets every later step that policy targets through for the rest of the task.

Version support

The ACS JSON schemas are vendored into the package and pinned by SHA-256 in acs-schemas/pin.json; a refresh script re-downloads, re-hashes and rewrites the pin, and a test verifies every vendored schema against it.

Known limitations

The ACS surface is a stream of lifecycle hooks, narrower than a code-level integration.

AAG kinds and verbs the Guardian never emits

  • step.model. ACS has no model-call hook, so a policy targeting step.model — a token budget, a model gate — never fires through the Guardian (upstream ACS issues 122 and 321).
  • step.gate other than through ask. The only step.gate the Guardian records is the one it synthesises when it answers ask (see Decisions). A harness cannot emit a gate hook of its own for the Guardian to evaluate.

A tool call reaches step.exec only through a process.* capability, a shell tool name or a command argument, and step.credential only through a secret.*, secrets.*, credential.* or vault.* capability. A call with no recognised capability, tool name or argument shape is step.unknown; add a --template overlay to classify your tools.

Events captured but ignored

Four ACS methods are recorded for the audit chain but never evaluated for a verdict, because AAG has no level they map onto: turnStart, turnEnd, preCompact and postCompact. AAG has no turn level between task and step, and it records the path outside the model's context, so compacting that context does not change the path. The per-method reasons are in the "How ACS events map to AAG" table.

Things the Guardian does not see

  • Every destination in a shell command. The Guardian reads one destination from a shell command's text: the host of its first URL or, with none, the first bare host after curl or wget. A second destination, or one built when the command runs (a variable, eval, a script), is not checked by the egress policy.
  • Task boundaries from the reference Claude Code shim. The reference shim sends no sessionStart / sessionEnd, so the Guardian's tasks stay open; it is wired as a PreToolUse / PostToolUse hook only.

Decisions that cannot be enforced as such

  • No modify. AGT's redact has no Kyvvu counterpart — Kyvvu has no payload-modifying action — so a secret-pattern policy denies the step instead of redacting. AGT's confidence gating, content-hash pinning and drift detection likewise have no Kyvvu rule and are documented as inexpressible rather than faked.
  • No defer. The Guardian has no way to pause an action for later resolution.
  • ask is recorded after the fact and rests on harness trust. A gate passed through ask is recorded after the action ran, because ACS v0.1.0 gives the Guardian no earlier signal than the result. The record rests on the harness only running an action it was told to approve; a harness that runs it without prompting creates the passing gate all the same (Decisions).
  • No ask for a high-severity warning. Over ACS a warn is always allow with reason_codes: ["kyvvu_warn"]; an ask comes only from a block by gate requirements. The Kyvvu Claude Code integration, from version 2, instead asks on a warn whose worst failed policy has severity: high, so the same manifest can answer the same action differently. For example, under Claude Code Safety 2.0, "Ask before force push" (severity: high) on git push --force origin feature-x prompts the developer through the Kyvvu Claude Code integration, while through this Guardian's Claude Code shim it is allowed and only logged. A policy that must stop for approval under ACS should be written as step_requires_gate, not as a high-severity warn. One meaning of "ask the human" across integrations is an open design question.
  • After-the-fact hooks are recorded and allowed, not evaluated. knowledgeRetrieval, memoryContextRetrieval and toolCallResult fire once the read or call has already happened, so the Guardian writes them to the chain and allows them; it cannot deny what is already done.

A misclassified tool is reclassified with a --template overlay (above), not by editing the engine. A policy that is too strict or too loose is a change to your manifest; nothing in the Guardian reloads a manifest, so a changed manifest takes effect on the next restart.

The bundled ACS manifest

kyvvu-acs/kyvvu_acs/acs-guardian.yaml ships in the package and is loaded by --baseline. It re-expresses AGT's stock bundle as Kyvvu policies, changing the mechanism while preserving the effect: four destructive-shell patterns (not(field_matches_regex) on properties.command), an egress allowlist (domain_allowlist, a listed domain covering its subdomains), secret patterns that deny where AGT would redact, information-flow control (tainted_path_block), a credential gate (step_requires_gate with max_steps_since_gate: 1, so each credential read asks again) and per-task budgets (usage_budget, execution_max_steps). Regex over an opaque command string cannot catch quoting, env indirection or semantic equivalents; pair it with OS-level controls.