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(defaulthttp://127.0.0.1:8787); the reference shims read it fromACS_GUARDIAN_URL. - Signing. ACS's v0.1 baseline is a shared-secret HMAC. Set
KV_ACS_HMAC_SECRETSto one or morekey_id=hexpairs (two or more lets you rotate: add the new key, roll the harness, drop the old). The signing procedure — JCS of the envelope withoutsignature, HKDF-SHA256 per session, HMAC-SHA256, replay rules, response signing andchain_hash— is inkyvvu_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, soaskis opt-in. A policy that requires a human approval gate produces anaskonly when--askis set; otherwise the Guardian answersdenywithreason_codes: ["kyvvu_block"], like any other block, and nothing waits for an approval. Set it only for a harness that really prompts a person onask: the Guardian infers the approval from the harness'stoolCallResult(see Decisions).- Fail-closed posture.
--on-decision-failuredefaults todeny— 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 arm -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-classkyvvu-claudeintegration, 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(defaultacs-<host>-<user>), which is the name it shows up under on the platform. Theagent_idan 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, asproperties.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: ausage_budgetor a rate limit counts both harnesses' steps together. To keep them apart, run one Guardian per harness, each with its own--agent-keyand 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 withSESSION_REFUSED— one Guardian per agent. There the id must be 1-255 letters, digits and. _ : -; an empty or malformed id is refused withSESSION_REFUSEDbefore 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.sampleor.env.template) /.pem/.key/.p12/.pfx/.secret/.credentials/.pgpass/.netrc/.aws/credentials/.ssh/id_*(not*.pub) path tags the stepdata.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 anaag_versionand carries no verb, input or output — outside the five fields a rule'sbehaviorblock may set — so these are built directly. - A non-message
agentTriggerwith no task open. The template maps everyagentTriggerto an inboundstep.messageGET(ascheduledtrigger on channelscheduled), but when no task is open for the session the Guardian makes it the task'stask.startinstead, evaluated likesessionStart: a policy may refuse the activation, and a refused one is not recorded. - The
task.end/task.errorsplit. 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 itPOST,PATCHorDELETE, 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 itsnamesets 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: successthe 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 gatedenyand the step's block, and never leaves a passing gate for a step that was blocked. - With
blocked,failureortimeoutthe gate is recordeddeny, 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¶
- ACS spec: v0.1.0
- ACS release: 0.1.4
- Pinned commit:
834f3f0d51e7bbbd9a68ff682bec89f97ddd72d8ofGenAI-Security-Project/agent-control-standard
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 targetingstep.model— a token budget, a model gate — never fires through the Guardian (upstream ACS issues 122 and 321).step.gateother than throughask. The onlystep.gatethe Guardian records is the one it synthesises when it answersask(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
curlorwget. 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 aPreToolUse/PostToolUsehook 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. askis recorded after the fact and rests on harness trust. A gate passed throughaskis 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
askfor a high-severity warning. Over ACS awarnis alwaysallowwithreason_codes: ["kyvvu_warn"]; anaskcomes only from a block by gate requirements. The Kyvvu Claude Code integration, from version 2, instead asks on awarnwhose worst failed policy hasseverity: 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) ongit push --force origin feature-xprompts 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 asstep_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,memoryContextRetrievalandtoolCallResultfire 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.