Integrate canonical v0.1.0#2
Open
afogel wants to merge 14 commits intoAgent-Control-Standard:mainfrom
Open
Conversation
Replace the single legacy specification/ACS/acs_schema.json with the modular
v0.1.0 schema package from canonical ACS. The legacy file becomes an
aggregator manifest that cross-references the new modular files.
Adds:
specification/v0.1.0/{request,response}-envelope.json
specification/v0.1.0/{handshake,provenance,provenance-summary}.json
specification/v0.1.0/{context-entry,ask-details,defer-details,modifications}.json
specification/v0.1.0/hooks/*.json (19 per-hook schemas: session-start/end,
agent-trigger, turn-start/end, user-message, agent-response,
knowledge-retrieval, memory-context-retrieval, memory-store,
tool-call-request/result, pre/post-compact, subagent-start/stop,
system-ping, agbom-snapshot/changed)
specification/v0.1.0/agbom/{component,document}.json
specification/v0.1.0/inspect/format-mapping.json
specification/v0.1.0/trace/{otel,ocsf}-mapping.json
specification.md and hooks.md now mirror the canonical ACS v0.1.0 spec proposal: design principles, two-layer Guardian architecture, JSON-RPC 2.0 envelope with stdio + HTTP transports, capability-negotiation handshake (handshake/hello), 16 native steps/* hooks, full disposition vocabulary including DEFER, decision-result fields supporting paradigm composition (FIDES / CaMeL / AARM / IBAC), provenance with optional trust enum and default channel-to-trust mapping, SessionContext with normative chain hashing (RFC 8785 JCS + SHA-256), Intent immutability and intent-extension via ASK, crypto-agile signature registry (HMAC, ECDSA, RSA-PSS, ML-DSA, SLH-DSA, hybrids), replay protection, OPA policy-engine reference binding, the new lifecycle hooks (sessionStart/End, turnStart/End, pre/postCompact, subagentStart/Stop), system/ping liveness, multi-tenancy reservation, and the v0.2 / future deferred list.
Refresh docs/spec/trace/{events.md,extend_opentelemetry.md,extend_ocsf.md}
to align with the canonical v0.1.0 mapping:
- OpenTelemetry: span-name + required-attribute table for every step,
decision-as-span-event rule, provenance attributes, span-link rule for
cited_provenance_ids.
- OCSF: class assignments per step (Authentication 3002, Application
Activity 6002, Process Activity 1007, Datastore Activity 6005, Detection
Finding 2004 for deny/modify/ask/defer, Inventory Info 5001 for
agbom/*) and disposition -> severity_id mapping.
- ACS-Trace conformance bar.
- Failure isolation: trace sink failure MUST NOT change the disposition.
Refresh docs/spec/inspect/{README.md,extend_cyclonedx.md,extend_spdx.md,
extend_swid.md} to align with the canonical v0.1.0 Inspect pillar:
- agbom/snapshot and agbom/changed wire methods, with audit-chain
integration.
- Canonical component graph with seven types (model, mcp_server, a2a_peer,
tool, knowledge_source, memory_store, agent_capability).
- registration_provenance on every component (REQUIRED under
ACS-Provenance).
- CycloneDX 1.6, SPDX 3.0, SWID derivations from the canonical document.
- ACS-Inspect and ACS-Inspect-Dynamic conformance bars.
New docs/spec/conformance.md defining the v0.1.0 profile system: ACS-Core (mandatory baseline) plus five optional profiles deployments declare in the handshake's profiles_supported / profiles_accepted fields. - ACS-Core: handshake, envelope, hooks, dispositions (incl. DEFER), SessionContext, Intent, replay protection, ping, wrapped MCP. - ACS-Trace: OTel + OCSF event emission, decision-as-span-event. - ACS-Inspect / ACS-Inspect-Dynamic: agbom/snapshot, agbom/changed. - ACS-Provenance: field-level Provenance with optional trust enum. - ACS-Crypto: ML-DSA-65 primary, SLH-DSA-128s backup, hybrids. - ACS-Audit: request_hash on every ContextEntry. Profiles compose; the page includes a quick-reference matrix.
core_concepts.md now introduces the v0.1.0 vocabulary: - Three pillars (Instrument / Trace / Inspect) as co-equal. - Two parties (Observed Agent / Guardian Agent with deterministic + optional agent layers). - Session, Turn, Step, Hook Response, Provenance, SessionContext, Intent with the immutability rule. - Default channel-to-trust mapping and the optional wire-level trust enum. ACS_in_action_example.md now mirrors the canonical Appendix C worked example: handshake, agbom/snapshot, sessionStart, userMessage, toolCallRequest with argument-level provenance, IBAC + FIDES decision envelope with reason_codes / policy_references / policy_data / cited_provenance_ids, plus a parallel deny-shaped example.
- docs/references/hook_surfaces.md: survey of lifecycle-hook systems across coding agents (Claude Code, Cursor, Codex, Copilot, Replit, Tabnine, Windsurf) with a semantic-event matrix and migration notes. Source for the v0.1.0 hook taxonomy and the DEFER disposition design. - docs/references/standards_compatibility.md: comparison of CaMeL, FIDES, AARM, IBAC, Conseca, MELON, ControlValve, AgentSentry, LlamaFirewall, PROV-AGENT/Flowcept; Google secure-agent guidance, Chrome User Alignment Critic, MCP security best practices, OWASP Agentic Top 10. Source for the deterministic-mediation core + pluggable detectors architecture. - docs/assets/ibac-paper.pdf: primary source for the Intent model. - docs/references/README.md: index linking the three sources.
Replace the work-in-progress intro with a v0.1.0 summary: what ACS is, the three pillars (Instrument / Trace / Inspect), and the six profiles (ACS-Core mandatory plus ACS-Trace, ACS-Inspect/-Dynamic, ACS-Provenance, ACS-Crypto, ACS-Audit). Leaves the existing aspirational SDK/MCP/A2A code samples below intact.
- Add Specification > Conformance Profiles entry pointing at the new spec/conformance.md page. - Add a top-level References section exposing hook_surfaces.md and standards_compatibility.md.
- Schema-file references now point at GitHub blob URLs under https://github.com/Agent-Control-Standard/ACS/blob/dev/specification/v0.1.0/... Schemas live outside docs_dir, so relative links from the docs tree cannot reach them; absolute URLs work both in the rendered site and when reading docs raw. - Update §13 anchor slug (OWASP#13-liveness-system-methods) to match Python-Markdown's TOC slugifier. - A2A hook docs: replace stale spec-anchor links (OWASP#48-a2a-protocol-methods, OWASP#51-acssuccessresponse-object) with code spans for the method names and a pointer to the new dispositions section. The protocols/A2A/* namespace remains reserved for v0.2. - extend_mcp.md: point at the new protocols/MCP/* anchor in hooks.md (the old #mcp-protocol-hooks anchor is gone). - gitignore: add site/ (mkdocs build artifact). `uv run mkdocs build --strict` now succeeds.
The hook-surfaces and standards-compatibility surveys plus the IBAC paper are local research artifacts, not site content. Move them to references/ at the repo root, gitignore that path, and drop the References section from the mkdocs nav. Files remain on disk locally; they no longer ship in the repo or build into the site.
ACS_in_action_example.md now shows one denial-shaped envelope per paradigm so readers can see how the same wire format expresses each: - IBAC: Intent.parsed mismatch with intent_parsed and closest match exposed in policy_data. - FIDES: P-T (planner-taint) failure with violating_argument_path, lineage_origins, and earliest_untrusted_provenance_id. - CaMeL: per-argument dependency-graph violation showing the actual vs. expected lineage roots. - AARM: cumulative-context denial with earliest_untrusted_step_id and the entry_count_by_origin aggregate from provenance_summary. - IBAC + FIDES composition: a single decision citing both paradigms in policy_references, reason_codes, and a policy_data object keyed by paradigm name. Also: repoint all schema GitHub URLs from Agent-Control-Standard/ACS (404) to afogel/ACS_official (the actual configured remote).
ClientHello now carries an optional approver_types_supported array (human / agent / service) mirroring the existing ServerHello field. New §9.2 normatively requires Guardians to substitute DEFER or DENY for ASK whenever the client/Guardian approver-type sets do not intersect. This lets headless automation, IDE plugins, and runtimes with allow/deny policy models (e.g., Microsoft Agent Governance Toolkit) participate in ACS sessions as fully conformant ACS-Core deployments — without silently allowing actions that would have been ASK'd elsewhere. Updates: - specification/v0.1.0/handshake.json: add approver_types_supported to ClientHello. - docs/spec/instrument/specification.md: §4 mentions the new field; §6 disposition table cross-references the fallback rule; new §9.2 spells out the normative substitution and the policy-driven DEFER vs. DENY choice.
…-band The handshake-field approach was over-engineered. §9.2 already preserves the security guarantee through Guardian-side substitution; the Guardian can determine client ASK-handling capability by deployment-defined means (agent identity, policy bundle, organizational configuration) without a wire-format declaration. Reverts the schema addition from a1b7958. The normative rule in §9.2 stands — Guardians MUST substitute DEFER or DENY when ASK isn't reachable — but the trigger is now 'Guardian determines the client cannot resolve ASK' rather than 'set intersection on the wire is empty.' Smaller spec surface, same outcome.
|
Heads up @afogel — doing some branch surgery that affects this PR. Want to flag it before it happens so nothing surprises you. Context (and acknowledging the screwup): when I cloned/forked this repo from the original OWASP/AOS source, I left both The change:
What this means for PR #2:
What you may want to do:
Sorry for the disruption. Should be the last branch surgery for a while. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Integrates the canonical v0.1.0 spec from
~/Pillar/ACS(the new source of truth) into this docs site. The canonical materials introduce a tiered conformance model, eight new lifecycle hooks, a normative provenance + SessionContext + Intent system, a crypto-agile signature registry, and OTel/OCSF/CycloneDX/SPDX/SWID mapping tables — all of which were either missing or sketched-only in the prior content.What's new
specification/v0.1.0/: 9 top-level objects (envelopes, handshake, provenance, context-entry, ask/defer/modifications), 19 per-hook payloads, AgBOM canonical schema, Inspect format-mapping, OTel + OCSF mappings. The legacyspecification/ACS/acs_schema.jsonis now a Draft 2020-12 aggregator manifest cross-referencing all modular schemas.docs/spec/conformance.md): ACS-Core mandatory baseline + ACS-Trace, ACS-Inspect, ACS-Inspect-Dynamic, ACS-Provenance, ACS-Crypto, ACS-Audit, with handshake-based declaration.specification.md,hooks.md): JSON-RPC 2.0 envelope with HTTP+stdio transports,handshake/hellocapability negotiation, full disposition vocabulary including DEFER, decision-result fields supporting paradigm composition (FIDES / CaMeL / AARM / IBAC), provenance with optional trust enum and default channel-to-trust mapping, SessionContext with normative chain hashing (RFC 8785 JCS + SHA-256), Intent immutability and intent-extension via ASK, crypto-agile signature registry (HMAC-SHA256 baseline; ECDSA, RSA-PSS, ML-DSA-44/65/87, SLH-DSA-128s/f, hybrids), replay protection, OPA reference policy-engine binding, and the new lifecycle hooks (sessionStart/End, turnStart/End, pre/postCompact, subagentStart/Stop, system/ping).docs/spec/trace/): OpenTelemetry semconv mapping withdecision-as-span-eventrule, OCSF event-class mapping (Authentication 3002, Application Activity 6002, Process Activity 1007, Datastore Activity 6005, Detection Finding 2004 for non-allowdecisions, Inventory Info 5001 for AgBOM), severity_id mapping, ACS-Trace conformance bar.docs/spec/inspect/): canonical AgBOM with seven component types,agbom/snapshotandagbom/changedwire methods, deterministic CycloneDX 1.6 / SPDX 3.0 / SWID derivations.core_concepts.mdupdated to introduce the v0.1.0 vocabulary;ACS_in_action_example.mdreplaced with the canonical Appendix C worked example (toolCallRequest with argument-level provenance, IBAC + FIDES decision envelope).docs/references/withhook_surfaces.md(lifecycle-hook landscape across coding agents) andstandards_compatibility.md(CaMeL/FIDES/AARM/IBAC + Conseca, ControlValve, MELON, AgentSentry, LlamaFirewall, PROV-AGENT/Flowcept comparison). IBAC paper added underdocs/assets/.Commits (in order)
Test plan
uv run mkdocs build --strictsucceeds with no warnings (only an informational notice that the existing A2A hook example pages aren't in the nav, matching pre-PR behavior — they're linked fromextend_a2a.md).uv run mkdocs serveand click through the new Specification > Conformance Profiles section, the rewritten Instrument > Specification + Hooks pages, the refreshed Trace + Inspect pages, and the new References section.