Changelog¶
All notable changes to this specification are recorded here.
The format is based on Keep a Changelog, and editions follow Semantic Versioning. AOS has not reached 1.0.
Unreleased¶
The first edition, 0.1.0-draft, a development draft open for review.
Added¶
- Session variables (environment.md, Optional Extension, Proposed): the basic set every consumer that runs an agent
session provides in its base environment when it knows the value, never empty:
AGENTS_HOST,AGENTS_HARNESS,AGENTS_VENDOR,AGENT,AGENTS_MODEL,AGENTS_PROJECT_ROOT,AGENTS_ACCOUNT,AGENTS_ACCOUNT_KIND(subscription,api-key,gatewayorlocal) andAGENTS_ACCOUNT_PROVIDER, so one overlay adapts to every harness. A consumer MAY set moreAGENTS_*variables of its own. They are the base environment and not reserved: an overlay may set one like any other variable and its value replaces the consumer's. The well-known harness ids gainantigravity,grok,cursorandpi, each with its vendor. Vectors cover an overlay setting one throughenv, an env file, an env script and a hook's output. - A harness hint
delegate(Optional Extension, Proposed):default(the source a delegated task starts on),sources(the sources a task may name) andmax_running(how many run at once), as suggestions that only choose among what the consumer already allows, never widen it, grant nothing and may be ignored. A floatmax_runningisinteger-required. The schema, an example, fixtures and validation vectors carry it. - Knowledge served through MCP (Core, Proposed; search an Optional Extension): every consumer that runs an agent
session serves the active overlays' knowledge by relative path with
kb_listandkb_read, and may addkb_search. The tools' names and input schemas, the paths (relative to the overlay root, never leaving it, a link refused), the optionaloverlaylimit, what the listing holds and its byte order, line ranges and a read's size bound, text written out so that nothing in a file can hide or reorder what the agent reads, and the error classes are normative and have vectors; search is specified by its answer (passage, path, heading, inclusive line range, score, the mode that answered) and its ordering, over modes a server declares (words,meaning,llm), never by how it ranks. A markdown file's format is named by its first line, a shebang, and only a markdown file (.md,.markdown) reads one: without it, or with#!aos(or#!agentic), the file is expanded,${NAME}replaced and@pathincluding another file of the overlay as Claude Code's imports do (relative to the including file, never above the root, five hops, no cycle, none of it in code, an unknown name or a path that names no file left as written);#!markdown,#!mdand#!rawserve the file as it is, the line dropped, and are synonyms; any other file is served as it is. The served text is whatkb_readranges,kb_listcounts and search indexes.envsubstis envsubst, GNU's at its defaults but that a name with no value stays as written (undefined=debug), andmustacheis Mustache as its specification defines it (partials resolved inside the overlay like@path), each with options on the first line spelled as tplx spells its own (#!envsubst dialect=drone undefined=debug,#!mustache escape=none); an unknown option is ignored and a bad value is an error; any other name is the server's own, and an engine a server does not render is no error: the file is served as it is, the line kept, with the context the renderer would have used in a front matter after it. A new manifest fieldknowledge(serve) hints that an overlay's rules and context are to be served rather than injected; the user's choice wins and a consumer without MCP is never forced. Recorded in the design decisions as 32, 33, 34 and 35; vectors intests/vectors/knowledge.jsonandknowledge_search.json, theknowledgecases ofvalidation.json, an example and fixtures. - A catalog's location may name a directory: each immediate subdirectory is an overlay entry named by the directory, with that subdirectory as its source, as dotagents reads a repo that is a directory of overlays. Recorded in the design decisions as 31.
- Templating (Proposed): a consumer replaces
${NAME}in the context it assembles and in the body of each bundled skill it serves, when it serves them, never in an installed file. The names areAOS_OVERLAY_ROOT,AOS_OVERLAY_STATE,AOS_OVERLAY_NAME,AOS_OVERLAY_SCOPE,AOS_PROJECT_ROOTand the overlay's options; anything else is left as written, and$${is a literal${. A newoptionsfield declares settings (type,default,sensitive,description) whose values the user gives; a sensitive option is never put in context and has no default; a value of the wrong type is refused (invalid-option). Recorded in the design decisions as 28; vectors intests/vectors/templating.json, theoptionscases ofvalidation.json, an example and fixtures. - Settled behaviours, with vectors: a fetched skill lists the files its digest covers, byte-ordered, and an
entry under an excluded name is no refusal; a refusal's subject has its control, format and separator
characters escaped and is cut to 256 characters; a source's IPv4 host is read as a URL parser reads it
(
127.1,2130706433,0x7f.0.0.1,10.1) and100.64.0.0/10is private; applying refuses a variable name that is not a name and a path that leaves the overlay (invalid-reference) without validating the rest. OVERLAY.md(Proposed): the manifest as front matter, YAML by default or as a#!<format>first line inside the fence names, holding the same fields asoverlay.cfg,aboutincluded; a body with anything but white space is the overlay's context, andCONTEXT.mdbeside it is ignored and reported. An overlay with bothOVERLAY.mdandoverlay.cfgis refused;overlay.cfgstays readable, TOML by default. Digest rules are unchanged. A consumer that does not readOVERLAY.mdsays so, or refuses the overlay.- The split of a document into metadata and body, a normative rule with vectors in
tests/vectors/front_matter.json: no fence, unterminated, too large, empty, an unknown format, metadata that does not parse or is no mapping, as a viewer and a gate each treat them; the closing fence (---or..., blanks allowed after it); a byte-order mark and\r; the body's bytes never changed; positions; bounds as settings with no floor, and nothing read past one. skillsentries may be a name for the consumer's catalogs to resolve, or a table ofname,source,refandpin(Proposed). Catalogs gain askillstable. Missing and ambiguous names are reported and never guessed, an entry with no pin is reportedunpinned, "what it would do" lists them with their sources, and a consumer that does not fetch says so of each. A manifest names no local source and holds no credential; a fetched skill is checked against its pin first, needs aSKILL.md, and must not name another skill. Vectors intests/vectors/skills.json.- Hooks (Proposed):
hook.<ext>at the root, chosen by runtime, and ahooksfield mapping an event to a script, a table ofrun,match,timeoutandon_failure, orfalse; ahookskey indefaults. Core eventspre-env,session-start(with areason),session-end,promptandturn-end; Extendedcd,pre-compact,pre-toolandpost-tool, matched by ACP tool kind.hook.<ext>gets the events with no content by default;promptand the tool events only when declared. A hook is told its event as its first argument andAOS_HOOK_EVENT, and a payload of that event's keys alone on standard input; its output adds context, blocks, denies or asks, and sets variables where the consumer can, through a loader with no decision for a shell. No output approves: any other decision is refused (grant). Time, output and payload bounded by settings; a failure is reported (hook-failed), andon_failure = "refuse"fails a guard closed. An overlay's hooks are off until the user allows them at its digest (hook-not-allowed), a running one is the weakeninghook, and an event a consumer cannot fire is reported (hook-unsupported), as is an output it cannot apply (hook-not-applied). A scope's own configuration may declare hooks too, the user's with no allowance.pre-envoutput applies after the root variables and before every overlay's declarations. Vectors intests/vectors/hooks.json, withpre-envcases incompose.jsonand the field's invalidation.json. - Hooks, after a security review: one allowed digest per identity, checked at each activation; an
overlay with a
refuseguard is not activated while its hooks are off; a project's hooks are allowed at the digest of every file beside their configuration and run from the consumer's copy with the base environment;setslists the variables a hook may set;contextandreasonhold no control or bidirectional character, and a reason at most 1024 code points; a call of kindotherruns every hook; an event has its own time bound (event-timeout); an event fired in part is reportedhook-partial, and no decision is never an approval.CLAUDE_CONFIG_DIRandCODEX_HOMEare sensitive variables. - Env scripts are gated by the hooks' allowance: an overlay's env scripts, declared or default, run only
while its digest is the one the user allowed, by the same rule and the same single digest, and are
reported
env-script-not-alloweduntil then. No list is added; setup and servers stay under the decision to activate. -
Vectors for what the hooks text left open: a context part past the context bound is not added, whole and never cut, and a later part that fits still is; the order of an event's hooks (overlays in composition order, then the user's, then the project's); and the environment a hook is given (its own overlay's declarations only,
AOS_*variables, the base environment for a scope's own). -
The package format, manifest fields, composition, dependencies, sources, skills, commands, MCP declarations, security and conformance, grounded in the dotagents overlay format.
- A JSON Schema for the manifest, examples, and schema fixtures.
- The manifest is
overlay.cfg: TOML unless its first line names another format (#!json,#!yaml,#!/usr/bin/env yaml), one leading byte-order mark ignored, nothing guessed from content. TOML is required of every reader; JSON and YAML are optional, and an unsupported format is refused by name. The schema describes the data model, the same in every format. - Static reading: no include, import, interpolation, templating, YAML tag, anchor, alias or merge key; no null, date or non-finite value.
- Environment (Proposed):
envwith literals, paths under the root and secret references ({ provider, key }or{ secret }, withif_unsetandoptional);env_filesin the manifest's own format ordotenv;pathsadditions toPATH,PYTHONPATHor any list variable, prepended or appended with the separator of the OS; the<NAME>_OVERLAY_ROOTvariable defined;env_scriptswith a named interpreter and a timeout, opt-in. - Runtime and setup (Proposed):
runtimewith supported OSes, required commands and Python and Node.js variants (minimum version,requirementsorlockwithlock_digest);setupvariants per OS with an interpreter (python,bash,sh,powershell,node), a timeout (default 300 seconds), and a network need, run withAOS_OVERLAY_ROOT,AOS_OVERLAY_NAMEandAOS_OVERLAY_STATE. skillslists an overlay's skills;contextlists initial-context files;[harness.<id>]gives per-harness context, skill delivery, model and effort hints (all Proposed).-
[scripts]entries may name an interpreter and OSes; a string path's interpreter follows from its extension. MCP serverenvvalues may be secret references, and stdio servers start in the overlay root (Proposed). -
Integrity (Proposed): the tree digest (
path NUL sha256:<hex> LFper regular file, sorted by path bytes, SHA-256 of the lines; no normalization;.git, caches and.pycexcluded; links, special files, non-UTF-8 names and\refused; Git sources hashed from blob bytes), with 20 test vectors intests/vectors/digest.json. Pins live in the consumer's configuration; a mismatch refuses the overlay. - The source form
[git+]<location>[@<ref>][#<path>], specified with examples. A#pathmust be a relative path; a Git location holding::, a host or ref starting with-, or a scheme other thanhttps,http,ssh,gitandfileis refused. - Weakenings a consumer reports every time it applies one:
unpinned,setup-network,network-not-enforced,no-timeout,env-script,env-passthrough,secret-read,env-sensitive,unlocked-dependencies,insecure-transport, with the list of sensitive variables (names, prefixes such asGIT_andPIP_, and the suffixes_PROXYand_BASE_URL). - Secret references resolve only when the consumer's configuration grants them to that overlay; nothing is granted by default. Each overlay's own processes get only its own environment.
AOS_*,*_OVERLAY_ROOTand*_OVERLAY_STATEare reserved: no overlay sets them.- One rule for relative paths and digest members: no excluded or device name in any case, no
trailing dot or space, no
\ : * ? " < > |, control or invisible characters, no~and digit; a tree with two members equal under ASCII case has no digest. - Reading refuses a byte-order mark after the format line, YAML directives and the characters U+0085, U+2028 and U+2029 in YAML. TOML constructs newer than TOML 1.0 are not portable: a reader refuses them or reads them with their TOML meaning.
- Harness hints act only on
context,skills,modelandeffort; other keys are kept and not applied. MCP stdio commands with a separator are paths under the root; a batch file is never run as an interpreter or server on Windows. - Lock and requirements files hold requirement lines only, and a lock installs binaries with hashes from an index the consumer names. Setup runs in its own process group, and the state directory is read-only inside the agent's sandbox.
- Defaults: files in conventional places take effect without a manifest.
bin/is prepended toPATHandlib/python/toPYTHONPATH;rules/*.mdare rules (Proposed),CONTEXT.mdis context,skills/*/SKILL.mdare skills; the rootenvis an env file read asdotenv(Proposed); oneenv.<ext>and onesetup.<ext>run, the first in the order.py,.js,.mjs,.cjs,.ps1(Windows),.bash,.sh(other systems) that the consumer can run. Each stays on unless[defaults]turns it off (bin,lib,env,env_scripts,setup,context,skills,rules). Declared entries add to the defaults, and one naming the same file or directory as a default replaces it. A default setup is taken to need the network; the weakeningscript-not-runreports a default script that cannot run.local.envis not an overlay file. Examplesbin-onlyandconventions, and vectors for each default on, off, declared and not runnable. - An env script's output may also be one JSON object over several lines, as a pretty-printer writes it; reading vectors for that output.
- Substitution in env values (Proposed):
${NAME},$$, defaults-:-(=:=assign nothing), alternates+:+, nested words,${#NAME}, slices, glob replacements (/,//,/#,/%), trims (#,##,%,%%) and case changes (^,^^,,,,,), thedroneenvsubst dialect plus alternates; nothing runs, and$NAME,$(...)and backticks are characters. It applies to text inenv,aosanddotenvfiles and MCPenv, one value at a time in the order of application, so each value sees every earlier one, across lines, files and overlays, and its own earlier value; an overlay's ownAOS_OVERLAY_ROOT,AOS_OVERLAY_NAMEandAOS_OVERLAY_STATEare readable. An undefined name is an error; a variable holding a secret is never read; a single-quoteddotenvvalue is kept as written. Reading vectors for every operator, escapes, undefined names, quotes, nesting, chaining and secrets, and composition vectors for chains across overlays. - Setup phases (Proposed): setup gets
install,syncorremoveas its first argument and inAOS_SETUP_PHASE:installon the first add,syncon every sync (a fetch of the source whatever it finds, a change of source, ref or pin, or setup run again on request),removeon removal; a consumer with no sync of its own runssyncbefore activating a digest other than the recorded one. The record per identity and OS holds the digest and phase of the last preparation that succeeded. The state directory belongs to the identity and OS, kept across syncs and digests, made empty beforeinstall, deleted afterremove, read-only in the sandbox. A failedinstallorsynckeeps the record and blocks the digest it ran for, except the recorded one; a failedremoveis reported and the overlay removed anyway; an overlay under a new identity is removed and added again. A script treats an unknown phase as nothing to do. Vectors for the phase, the steps, the record and activation of each operation, with failures. - Dependencies (Proposed):
lib/python/requirements.txtandlib/node/package.jsoninstall by default atinstalland everysync, before setup ([defaults] deps), unless aruntime.pythonfile or aruntime.nodepackagereplaces them. A hash on every requirement, or apackage-lock.jsonbesidepackage.json(npm ci), pins a file; an unpinned one installs and is reportedunlocked-dependencies; a partly hashed one is refused. Each install is reporteddeps-network, and needs its interpreter and package manager (npm).lib/node/is onNODE_PATH.environment("shared"by default, a name, or"isolated") chooses the environment: shared ones install every member's file in one run, in composition order, block overlays whose pins conflict, are rebuilt on every install, sync and removal, and live while an overlay uses them. Vectors for each default, overrides, pins, sharing, conflicts and removal. A consumer may isolate every overlay, per digest too, but never shares an overlay that chose a name orisolated. - Store metadata (Proposed): an informational
[about]table withsummary,icon,homepage,repository,license(an SPDX expression),authorsandtags. Only a store and a validator read it; nothing in it changes what an overlay does, and a problem in it never stops the manifest from applying. Icons are PNG or WebP, never SVG, checked against size and dimension limits (512 KiB and 1024 pixels a side by default) before decoding, with a store's own placeholder when one is missing or refused. -
Catalogs: the registry, extended. A string entry is the minimal form dotagents reads; a table entry (
source,ref,pin,description,about) and catalog-levelname,descriptionandhomepagemake the full form (Proposed). The file extension selects the format; relative sources resolve beside the catalog; a catalog from a repository or a URL cannot name a local source; a bad entry is refused alone. Several catalogs are labelled by the consumer, a name they share is shown qualified and never picked silently. Catalog metadata is advertising: the fetched overlay is authoritative, a catalog pin is checked, and what an overlay would do is shown from its own manifest before it is installed. A Store conformance class,catalog.jsonvectors (catalogs, collisions, icons),catalogreading cases andaboutvalidation cases; examplesaboutandregistry/catalog.toml. -
Conformance vectors as JSON data in
tests/vectors/: reading (format line, data model, static reading, limits,dotenv), validation of every field, names and root variables, source strings, the tree digest, resolution and composition, and one overlay's effective environment, setup, runtime, needs and weakenings. Conformance classes name the vectors each one passes.
Changed¶
- Hooks run like a harness's own. A
pre-toolhook may printdecision = "allow"; hooks combine to the tightest (a deny beats an ask, an ask beats an allow) and an allow never lifts the user's own refusals, so "tightens, never grants" and the failure causegrantare gone and any other decision value is anoutputfailure. An allow may carry a rewritteninput, which later hooks see and a deny or ask beats. A hook runs in the session's working directory, and every overlay's setup, env scripts, hooks, servers and commands get the session's environment (overlays stack, a later one on top of an earlier), so one overlay reads what another declared; apre-envhook sees what earlierpre-envhooks set; the consumer stops only the hook's own process at its timeout, with no process group or job object. On a call of kindother, a hook whosematchdoes not nameotherstill runs and its deny and ask count, but its allow and input do not (hook-not-applied,allow); a hook with nomatch, or one that namesother, may allow it. Recorded in the design decisions as 29 and 30; new and changed vectors intests/vectors/hooks.json. - Breaking: a weakening is now a non-default setting. The word goes from the security section, the glossary, the
site and the reference reader; the vectors' keys
weakeningsandhook_weakeningsbecomenon_defaultsandhook_non_defaults. The identifiers (unpinned,env-passthrough, ...) and the pairs are unchanged. - YAML is required of every reader, as a restricted subset of YAML
1.2; TOML stays required and
overlay.cfgkeeps its default of TOML. JSON stays optional. The depth bound holds while parsing, in every format, and a mapping key<<is refused in any scalar style. - A validator no longer refuses a listed skill with no directory: it flags it (
skill-from-catalog), and refuses a table whose name is also bundled and a name differing from a bundled one only in case. A skill name is also a single path component. - Sources: an
@in a URL's authority is user information, never a ref; a source holds no control or reordering character and an authority no backslash; a user, port or scp-like path starting with-, percent-decoded, is refused. A catalog from elsewhere names no host that is this machine, no location that is neither Git nor the web, and no credential (source-credentials). - A skill from elsewhere never takes a name another overlay's skill holds by default; a fetched skill has
YAML front matter naming it, and its other keys are reported (
skill-keys); a bundledSKILL.mdnaming another skill is not delivered. A source overhttporgit://is reportedinsecure-transport, one at a private addressprivate-source. - A document that looks like front matter and is not is refused at a gate (
malformed-fence); U+FEFF is refused in YAML; an integer past 64 bits is refused before it is converted; reading is linear in the text; no field names a manifest (manifest-file); a consumer bounds the context it adds. - A front matter block in a context file follows the split: blanks after a fence are allowed, and only a line
feed ends a line. A catalog may hold
overlays,skillsor both, and one from elsewhere cannot name afile:URL of any kind. -
The order of application gains a step: every overlay's allowed
pre-envhook output, after the root variables and before any overlay's declarations. A harness hint still adds no hook;hooksis the one route, and is listed before installing. -
overlay.tomlis nowoverlay.cfg, with no second name. setup_timeoutis replaced bysetupvariants;setup.pyis one case of the default setup.- Env scripts run by default in an activated overlay, each run reported, unless the consumer's policy turns them off; they are no longer a separate opt-in.
- A plain
envfile is read asdotenvinstead of being sourced by a shell, andpre.envfiles mean nothing by name. - Env values written as text are substituted instead of literal;
$$writes a$. - Setup runs
installon the first add, thensyncon every sync, whether or not the digest changed, instead of the same run once per digest, andremoveon removal. The state directory belongs to the overlay's identity and OS instead of its digest. lib/python/requirements.txtinstalls by default instead of meaning nothing, into the scope's shared environment instead of one per digest, andruntime.nodecan name apackage.json.NODE_PATHjoinsPATHandPYTHONPATHas a variablepathsadds to withoutenv-sensitive.skillsadds to the skills found underskills/instead of replacing them; to offer only some, set[defaults] skills = falseand list them.- Composition order is
(priority, name, identity)with code-point string comparison, for every contribution, not only rules and routing. - Test, release and docs workflows; the docs site is published at
https://boriken-dev.github.io/agent-overlay-spec/.