AIP-39: ACTION (action/v1): verb primitive
A markdown + frontmatter format for declaring an abstract verb / operation that can be performed on a resource — its identity, semantics, side-effect profile, approval class, and lifecycle events. The pivot primitive that TOOL implements (with LLM schema), POLICY references (for grants), INTENT routes to (from user verbs), and WORKFLOW steps invoke. Bottom-up — implementations declare which actions they implement.
| Field | Value |
|---|---|
| AIP | 39 |
| Title | ACTION (action/v1): verb primitive |
| Status | Review |
| Type | Schema |
| Domain | actions.sh |
| Requires | AIP-7 (governance), AIP-54 (REF) |
| Implemented by | Any TOOL.md declaring implements: <action-ref> |
| Referenced by | TOOL.md implements, POLICY.md grants[].actions, INTENT.md maps_to[].action, WORKFLOW.md steps[].action |
Abstract
ACTION.md is a markdown-with-frontmatter file format that packages
a single abstract verb / operation that can be performed on a
resource — its identity, semantic description, side-effect profile
(mutates), approval class, risk level, lifecycle events fired,
and category for catalog UI.
ACTION is the pivot primitive of the agentic stack: it is the verb that other AIPs reference. TOOL implements an action with an LLM-callable IO schema. INTENT routes a user-facing verb to one or more actions. WORKFLOW steps invoke actions. POLICY grants permissions on actions. LIFECYCLE events fire from actions.
The relationship is bottom-up: TOOL declares which ACTION it
implements (via implements: <action-ref>), inheriting the action's
side-effect profile and never widening it. ACTION optionally lists
known implementations as a hint for catalog UIs but the source of
truth lives on the implementations.
Motivation
Until this AIP, the AIP series fragmented "things an agent or user can do" across multiple unrelated primitives:
- AIP-14 TOOL.md had abstract LLM-callable contracts
with
mutates/requires/approvaldeclared per-tool. - AIP-28 INTENT.md routed user-facing verbs to TOOL ids.
- POLICY.md (AIP-38) needed a vocabulary of "what can
be granted" — initially proposed as bare strings (
storage:commit). - WORKFLOW.md (AIP-15) referenced TOOL ids in steps.
- Audit logs annotated tool calls with arbitrary id strings.
Five problems compound when "the verb" is not a first-class primitive:
-
N implementations of the same verb each redeclare side-effects.
git.commit,gh.commit,github.api-commitall need to declaremutates: ["storage:*"]andrisk_level: 1. Drift is inevitable — one of them eventually downgrades risk to 0 and breaks audit. -
POLICY grants are couplée to specific tool ids. Granting
git.commitdoesn't grantgh.commiteven though they do the same thing. Every new TOOL impl requires re-grant. -
INTENT can only route to TOOLs. "Save changes" intent has to list every TOOL that commits — not the abstract verb "commit".
-
WORKFLOW steps lock in implementation. A step calling
tool: git.commitcan't be retargeted togh.commitwithout editing the workflow. -
No vocabulary for non-LLM operations. Config-change verbs (
storage:swap-provider,workspace:publish) aren't really TOOLs (no LLM schema needed) but POLICY needs to grant on them.
ACTION.md extracts the verb into its own primitive. Implementations
implement actions; consumers reference actions; everyone composes
through one shared namespace.
Design principles
-
Pure semantic primitive. ACTION declares what the operation is (semantics, side effects, risk) — not how (no code, no schema, no calling convention). Implementation lives on TOOL (AIP-14) / DRIVER (AIP-30) / UI / lifecycle handlers.
-
Bottom-up implementation linking. TOOLs (and other implementers) declare
implements: <action-ref>. ACTIONs do not enumerate their implementations — that's the implementor's job. Optionalimplementations:field on ACTION is a discovery hint only, typically populated by the host scanner. -
Inheritance with narrowing. When TOOL
implements: action, it INHERITS action'smutates,risk_level,approval,requires. TOOL MAY narrow (more restrictive) but MUST NOT widen. Validators reject widening at parse time. -
One namespace across the stack.
storage:commitmeans the same thing in POLICY grants, INTENT routes, WORKFLOW steps, and audit logs. The action id is the universal verb identifier. -
Composable like everything else. ACTION refs accept the
inline | ref | filepattern. An ACTION can be inline in a consumer (one-shot), refed from a registry (@agentik/actions/standard/storage-commit), or pointed at a sibling file. -
Open extension via category + custom verbs. The
categoryfield lets catalogs group actions ("filesystem", "compute", "messaging"). Custom verbs registered by hosts use the<host>:<verb>convention; standard verbs are bare.
Specification
File location
ACTIONs are typically organized as folders under a workspace:
.actions/
storage-commit/
ACTION.md ← this AIP
README.md ← optional long-form
storage-push/
ACTION.md
sandbox-execute/
ACTION.mdFolder name SHOULD match id (kebab-cased). Authors MAY nest under
a category (e.g. .actions/filesystem/storage-commit/) — consumers
MUST NOT depend on directory depth.
Action libraries
A "library of actions" is a WORKSPACE.md with
publish.visibility: public containing many .actions/<slug>/ACTION.md
files. Other workspaces ref these via the registry address scheme
(@<owner>/<workspace-slug>/<action-slug>):
@agentik/actions/standard/ ← published action library
├── WORKSPACE.md
└── .actions/
├── storage-commit/ACTION.md
├── storage-push/ACTION.md
└── sandbox-execute/ACTION.mdConsumers reference: implements: "@agentik/actions/standard/storage-commit".
Frontmatter
YAML frontmatter, delimited by --- lines. All fields are case-sensitive.
Required fields
| Field | Type | Description |
|---|---|---|
schema | string | Always action/v1. |
id | string | Machine identifier. Lowercase, digits, dashes, dots, single colon (:). 2–80 chars. Standard format <category>:<verb> (e.g. storage:commit). Dots denote sub-namespace. Unique within the registry that hosts the action. |
description | string | One-paragraph purpose. ≤2000 chars. Written for the LLM caller. |
Optional fields
| Field | Type | Default | Description |
|---|---|---|---|
version | semver string | 1.0.0 | Spec version of THIS file. Bump on breaking change to mutates / risk_level (any tightening that requires implementor revalidation). |
category | string | "" | Discovery category for catalog UIs. Common: filesystem, compute, messaging, vcs, payment, auth, lifecycle. |
verb | string | derived from id | The bare verb (e.g. commit, execute, reveal). Derived from id after the : if absent. |
target_kind | string | derived from id | The resource kind this action operates on (e.g. storage, sandbox, secrets). Derived from id before the : if absent. |
mutates | string[] | [] | Resources the action may modify. Same vocabulary as AIP-14 mutates: <class>:<scope>. Implementors MUST honour the declared set; widening is rejected. |
requires | object | {} | Capability requirements (gated by AIP-7 governance). Subfields: network: string[], secrets: string[], tools: string[]. Implementors MAY add to this set; MUST NOT remove from it. |
approval | string | "auto" | Approval class. "auto" / "always" / "on-mutate" / "policy:<ref>". Implementors MAY narrow (auto → always); MUST NOT widen. |
risk_level | 0–3 | 0 | 0 = read-only, 1 = scoped writes, 2 = external side effects, 3 = irreversible. Implementors MAY raise but never lower. |
fires_events | string[] | [] | AIP-37 LIFECYCLE event names this action fires when invoked. Subscribers (sync layers, audit) attach to these. |
implementations | array | [] | OPTIONAL discovery hint — known implementations of this action. Format: [{ kind: "tool" | "driver" | "ui" | "lifecycle", ref: "<ref>" }, ...]. NOT authoritative — source of truth lives on the implementors via implements: <action-id>. Populated by host scanner. |
tags | string[] | [] | Free-form discovery tags. |
examples | object[] | [] | Each { name, scenario, note? } — semantic examples (NOT input/output, since action has no schema). |
metadata | object | {} | Free-form, namespaced. |
Body
Markdown body following the frontmatter. Recommended sections:
## Description— long-form purpose, when callers should use this action.## Side effects— prose explainingmutatesin human terms.## Approval rationale— why thisapprovalclass is correct.## Implementation notes— guidance for implementors (TOOL/DRIVER authors).
The body is informational. Hosts MUST function reading only the frontmatter.
The defineAction standard signature
defineAction(definition: ActionDefinition): ActionHandle
interface ActionDefinition {
schema?: "action/v1"
id: string
description: string
version?: string
category?: string
verb?: string
targetKind?: string
mutates?: string[]
requires?: {
network?: string[]
secrets?: string[]
tools?: string[]
}
approval?: "auto" | "always" | "on-mutate" | string // "policy:<ref>"
riskLevel?: 0 | 1 | 2 | 3
firesEvents?: string[] // AIP-37 event names
implementations?: Array<{
kind: "tool" | "driver" | "ui" | "lifecycle"
ref: string
}>
tags?: string[]
examples?: Array<{ name: string; scenario: string; note?: string }>
metadata?: Record<string, unknown>
}Conformance rules
-
idformat —^[a-z0-9][a-z0-9.-]*(:[a-z0-9][a-z0-9.-]*)?$. Standard shape<target-kind>:<verb>(e.g.storage:commit). Single colon only; multiple colons are reserved for future namespacing. -
mutatesare inherited downward. Every implementor of an action MUST honour every entry in the action'smutatesarray. Implementors MAY add more (be more honest about side effects). Resolvers MUST refuse implementors that drop entries. -
approvalandrisk_levelare floors. Implementors MAY narrow (approval: auto→alwaysok ;risk_level: 1→2ok). Widening is rejected at parse time. -
requiresis a floor. Implementors MAY require additional capabilities; MUST NOT remove any required by the action. -
implementations:is non-authoritative. Hosts MUST treat it as a hint. The runtime resolver scans implementors via theirimplements:field, NOT via this list. -
fires_eventsare advisory at the action layer. Implementors MAY fire MORE events than the action declares; MUST NOT drop any event the action declares as fired (or the audit trail breaks). -
No I/O at parse time. Parsing an ACTION.md MUST NOT trigger network calls, registry lookups, or implementation resolution.
Stable identity
id + version together form the action's stable identity. A
breaking change to mutates (adding an entry implementors couldn't
have known) or to risk_level (raising the floor) MUST bump major
version. Implementors pinned to ^1.0.0 of an action MAY refuse to
bind against 2.0.0 until they update.
Standard runtime actions (added 2026-10-23)
Draft AIP-39 amendment (2026-10-23). Normative identifiers (action ids, field names, literals) are English and final.
Problem. AIP-38 grants on ACTION ids, but the standard library only named storage and sandbox verbs. Runtime verbs had no declared home, so hosts invented ad-hoc access mechanisms instead of grants: a session prompt allowlist, a per-model allow/block list, an ad-hoc "use this account" check. This amendment declares the six runtime verbs as members of the standard library so AIP-38 can grant them like any other action.
The entries live under @agentik/actions/standard/:
| id | library entry | category | target_kind | mutates | risk_level | approval | semantics |
|---|---|---|---|---|---|---|---|
session:spawn | @agentik/actions/standard/session-spawn | runtime | session | ["session:*"] | 2 | auto | Start a new session. |
session:prompt | @agentik/actions/standard/session-prompt | runtime | session | ["session:conversation"] | 1 | auto | Send a prompt or steer a running session someone else owns. |
session:control | @agentik/actions/standard/session-control | runtime | session | ["session:*"] | 2 | auto | Interrupt, kill, restart, or hand off a session someone else owns. |
session:configure | @agentik/actions/standard/session-configure | runtime | session | ["session:config"] | 1 | auto | Change a running session's config axis (model, access, harness, posture, effort, route, contextProfile). |
model:invoke | @agentik/actions/standard/model-invoke | runtime | model | [] | 2 | auto | Use a model for inference. |
auth-profile:use | @agentik/actions/standard/auth-profile-use | runtime | auth-profile | [] | 2 | auto | Bill or authenticate through an auth profile. |
Risk rationale. session:spawn and session:control are risk 2:
they create or change processes with the host's authority, which is an
external side effect. session:prompt is risk 1: it writes to one
session's conversation, and any spend it enables still needs
model:invoke. session:configure is risk 1: it is a scoped write to
one session's config, and any spend it enables still needs
model:invoke. model:invoke and auth-profile:use are risk 2
because both spend money: inference is billed and an auth profile
selects the account that pays or authenticates.
Optional scope. A grant MAY narrow any of these actions with
scope, whose matching rules are defined in
AIP-38 §Scope matching.
In a label: scope, the label is the operator label of the target
session (AIP-46 §Operator label):
| id | scope |
|---|---|
session:spawn | harness slug or agent ref |
session:prompt | session id, label:<label>, or label:<prefix>* |
session:control | session id, label:<label>, or label:<prefix>* |
session:configure | config axis name (model, access, harness, posture, effort, route, contextProfile) |
model:invoke | model id, *-suffix glob, or selector:<id> |
auth-profile:use | auth profile id |
A scope MAY be a selector:<id> ref. The selector itself is defined by
AIP-43 § Selectors referenced by policy: matching is membership in the
resolved set, and evaluation fails closed when the selector cannot be
resolved.
When a non-owner restarts or hands off a session with a config
overlay, session:control is evaluated IN ADDITION to the spawn set
implied by the overlay; both evaluations must allow (ANDed).
session:prompt is evaluated the same way when steering starts a
fresh session.
Ownership. AIP-39 only declares these ids. The owning AIPs define the semantics and the evaluation points: AIP-46 for sessions (spawn, prompt, control, configure), AIP-69 for profiles, and AIP-43 for selectors. A consumer MUST NOT read this table as a permission: the effective decision is still an AIP-38 policy evaluation.
Draft AIP-39 amendment (2026-10-29). Normative identifiers (action ids, scope forms) are English and final.
Messages between sessions had the same gap: hosts decided who may message whom with their own switches instead of grants. The standard library gains a seventh runtime action:
| id | library entry | category | target_kind | mutates | risk_level | approval | semantics |
|---|---|---|---|---|---|---|---|
session:message | @agentik/actions/standard/session-message | runtime | session | ["session:conversation"] | 1 | auto | Deliver a message to another session's inbox. |
Risk rationale. A message can cause the receiver to act, so
session:message is evaluated like session:prompt, at risk 1, but
between two sessions and without a spawn.
Optional scope.
| id | scope |
|---|---|
session:message | target session id, label:<label>, label:<prefix>*, or workspace:<slug> |
workspace:<slug> is a typed scope form
(AIP-38 §Scope matching,
rule 3) defined for session:message only. It matches when the
workspace binding of the target session, which the host derives as
AIP-46 §Session messages
defines, names the registered workspace <slug>. A target bound to no
registered workspace matches no workspace: scope. A host that cannot
resolve the target's binding MUST fail closed: it evaluates an allow
grant with this scope as not matching and a deny grant with this scope
as matching.
Ownership. AIP-46 §Session messages defines when session:message
is evaluated and how it combines with the tree edges a host allows
without a grant.
Draft AIP-39 amendment (2026-10-29). Normative identifiers (action id, scope form) are English and final.
Problem. A TOOL that declares no implements is an orphan: no
action covers it, so AIP-38 can neither grant nor deny
it. The daemon's built-in tools (cron_*, session_*, ...) are such
tools. AIP-42 §Tools already defines an AGENT deny
as the AGENT-level projection of an AIP-38 explicit deny on the tool
<server>/<name>, but no action id existed to write that grant on. The
standard library gains an eighth runtime action:
| id | library entry | category | target_kind | mutates | risk_level | approval | semantics |
|---|---|---|---|---|---|---|---|
tool:invoke | @agentik/actions/standard/tool-invoke | runtime | tool | [] | 1 | auto | Call one tool. |
Risk rationale. The declared values describe the gate, not the
tool. tool:invoke names the act of calling a tool; what a call does
comes from the tool's own manifest, or from the action it implements.
mutates: [] and risk_level: 1 are therefore the floor of the gate
itself. A TOOL MUST NOT declare implements: tool:invoke: a host
evaluates this action on every call it dispatches, and a tool is never
an implementor of it.
Optional scope.
| id | scope |
|---|---|
tool:invoke | tool name <server>/<name> (AIP-54 tool-body), or a *-suffix glob such as <server>/* |
The matching rules are defined in
AIP-38 §Tool names.
They add no scope syntax: an exact name and the * suffix of
AIP-38 §Scope matching
rule 2 are the whole vocabulary. A daemon built-in tool is named with
the server agentproto (agentproto/cron_create), so a grant or an
explicit deny reaches it without any implements.
Evaluation. The host evaluates tool:invoke when it is about to
dispatch a call, with the tool's full name as the requested scope. The
server and the name come from the host's own registry of the tool
being called, never from the arguments of the call. When the tool also
declares implements: <action>, the call is the same operation under
two names, so the two requests are decided together by the AIP-38
composition rules: a matching deny on either refuses the call, and a
matching allow on either admits it. A grant on the implemented action
therefore keeps working without a tool:invoke grant, and a deny on
tool:invoke still refuses a tool whose implemented action is
granted.
tool:invoke is not a list of tools an agent is offered. An AIP-42
tools entry decides what the agent sees; this action decides whether
a call is allowed; neither grants the other
(AIP-42 §Tools).
Ownership. AIP-39 only declares the id. AIP-42
owns the AGENT tools projection, and the host that dispatches the
call owns the evaluation point. As with the other runtime actions, the
table is not a permission: the effective decision is an AIP-38 policy
evaluation.
Draft AIP-39 amendment (2026-10-30). Normative identifiers (action ids, scope forms) are English and final.
Problem. A host performs three more operations on a session that
have no standard id. It writes a checkpoint, a bounded record of the
session's state (AIP-46 §Session context).
It compacts the session's context. And it archives a finished session,
which drops it out of the default session listing. AIP-46 already
reserves the compaction to the operator by naming an action,
session:compact, that this library did not declare, and
AIP-71 reactions already name session:archive as a
host action they may target. The standard library gains three runtime
actions:
| id | library entry | category | target_kind | mutates | risk_level | approval | semantics |
|---|---|---|---|---|---|---|---|
session:checkpoint | @agentik/actions/standard/session-checkpoint | runtime | session | ["session:conversation"] | 1 | auto | Write a checkpoint of a session: a bounded record of its state, saved next to its transcript. |
session:compact | @agentik/actions/standard/session-compact | runtime | session | ["session:conversation"] | 2 | auto | Compact a session's context: the harness replaces the earlier turns with a summary. |
session:archive | @agentik/actions/standard/session-archive | runtime | session | ["session:*"] | 1 | auto | Hide a finished session from the default session listing. Its history stays readable. |
Risk rationale. session:checkpoint is risk 1: it writes one record
next to the session's transcript, which it never replaces, and it may
add one handoff turn to the session's conversation. session:compact
is risk 2: the harness replaces the earlier turns of the context with a
summary, a loss the model cannot undo; a checkpoint written first is
what makes it recoverable
(AIP-46 §Session context,
rule 1). session:archive is risk 1: it hides a finished session from
the default listing and touches neither its history nor any process.
Optional scope. A grant MAY narrow any of these actions with
scope, using the same forms as session:prompt and
session:control above:
| id | scope |
|---|---|
session:checkpoint | session id, label:<label>, or label:<prefix>* |
session:compact | session id, label:<label>, or label:<prefix>* |
session:archive | session id, label:<label>, or label:<prefix>* |
Evaluation. AIP-46 §Session context
rule 5 reserves session:compact on a session to the operator when
compactRequiresOperator is set, and a compaction the host decides
itself is not requested by a principal and is not refused by that rule.
Ownership. AIP-39 only declares the ids.
AIP-46 §Session context owns the checkpoint and the
compaction, and AIP-71 names session:archive as a host
action a reaction may target. As with the other runtime actions, the
table is not a permission: the effective decision is an AIP-38 policy
evaluation.
Composition pattern (inline | ref | file)
Like every composable block in the AIP series, ACTION refs accept three forms when consumed by other manifests:
# Inline — action defined directly in the consumer (one-shot)
implements:
inline:
id: my.local-action
description: "Workspace-specific action, not published."
mutates: ["storage:scratch"]
# Ref — registry-resolvable identifier
implements: { ref: "@agentik/actions/standard/storage-commit" }
# OR shorthand string (when no ambiguity):
implements: "@agentik/actions/standard/storage-commit"
# File — workspace-relative path
implements: { file: "./actions/storage-commit/ACTION.md" }
# OR shorthand:
implements: "./actions/storage-commit"Resolution failures MUST surface as a typed error
(action_ref_unresolvable).
Inheritance + narrowing (formal)
When TOOL.md (or any implementor) declares implements: <action-ref>,
the host loads the resolved action and merges its fields into the
implementor's view at parse time. The merged view is what the agent /
governance layer sees at runtime.
| Field | Action declares | Implementor MAY |
|---|---|---|
description | floor | Override (typically more specific). |
mutates | floor (must include) | Add more entries; never drop. |
risk_level | floor (minimum) | Raise (more risky); never lower. |
approval | floor | Narrow (auto → always → on-mutate); never relax. |
requires.network | floor | Add more hosts; never remove. |
requires.secrets | floor | Add more slugs; never remove. |
requires.tools | floor | Add more tools; never remove. |
category | inherited verbatim | Cannot override (catalog consistency). |
fires_events | floor (must fire all) | Fire more events; never drop. |
target_kind | inherited verbatim | Cannot override. |
Validator pseudocode:
function validateImplementor(impl: ToolDef | DriverDef): Result {
if (!impl.implements) return { ok: true, orphan: true }
const action = resolveAction(impl.implements)
if (!action) return { error: `unknown action: ${impl.implements}` }
if (impl.riskLevel !== undefined && impl.riskLevel < action.riskLevel)
return { error: `widens risk_level: action=${action.riskLevel}, impl=${impl.riskLevel}` }
if (impl.mutates && !isSuperset(impl.mutates, action.mutates))
return { error: `drops mutates: ${diff(action.mutates, impl.mutates)}` }
if (impl.approval && approvalRank(impl.approval) < approvalRank(action.approval))
return { error: `relaxes approval: action=${action.approval}, impl=${impl.approval}` }
// ... etc
return { ok: true, mergedView: { ...action, ...impl } }
}Example
---
schema: action/v1
id: storage:commit
version: 1.0.0
description: "Commit changes to a storage backend's tracked filesystem. Atomic with respect to the underlying provider's commit semantics (git commit-tree for github, S3 put for cloud-bucket, no-op for canonical providers)."
category: filesystem
verb: commit
target_kind: storage
mutates: ["storage:*"]
risk_level: 1
approval: auto
requires:
secrets: []
fires_events:
- write
- commit-completed
implementations:
- { kind: tool, ref: "@agentik/git/tools/commit" }
- { kind: tool, ref: "@agentik/github/tools/api-commit" }
tags: [filesystem, vcs, sync]
examples:
- name: Standard commit after agent edit
scenario: "Agent finishes a turn that wrote 3 files. Sync layer triggers commit at turn-end with auto-generated message."
- name: Manual commit
scenario: "User clicks 'Save' button in workspace UI; UI calls a TOOL implementing this action with a custom message."
---
## Description
Use when the agent (or sync layer, or UI) needs to atomically record a
set of pending writes to durable storage. Bare `commit` semantics —
this action does NOT push to a remote (use `storage:push` for that).
## Side effects
Modifies the storage backend's tracked tree. Specifically:
- For github-backed storage: creates a git commit object on the
current working branch.
- For cloud-bucket: writes a snapshot manifest under the storage
prefix.
- For canonical providers (no concept of commit): no-op (resolver
MAY refuse the call entirely).
## Approval rationale
`approval: auto` because commits are intermediate — the user-visible
moment is `storage:push`. A typing agent making 50 commits per
session shouldn't prompt 50 times. Implementors MAY narrow to
`always` for high-risk repositories.
## Implementation notes
Implementors should:
- Honour `mutates: ["storage:*"]` strictly.
- Fire `write` event for the commit's tree-write phase.
- Fire `commit-completed` event with the resolved SHA after success.
- Fall back gracefully if the storage's commit semantics differ from
git (e.g., S3 put as snapshot manifest).Connecting to other AIPs
TOOL implements ACTION
# TOOL.md
id: git.commit
implements: "@agentik/actions/standard/storage-commit" # ← bottom-up link
inputs: { type: object, ... } # tool-specific
outputs: { type: object, ... } # tool-specific
# inherits: mutates, risk_level, approval from actionPOLICY grants ACTION
# POLICY.md
grants:
- principal: "operator://bob"
actions:
- { action: "@agentik/actions/standard/storage-commit" }
- { action: "@agentik/actions/standard/storage-push" }INTENT routes to ACTION
# INTENT.md
id: save-my-work
maps_to:
- { action: "@agentik/actions/standard/storage-commit" }
- { action: "@agentik/actions/standard/storage-push" }WORKFLOW step invokes ACTION
# WORKFLOW.md
steps:
- id: commit-changes
action: "@agentik/actions/standard/storage-commit" # resolver picks tool
inputs: { message: "${{ ctx.summary }}" }LIFECYCLE event fired by ACTION
# ACTION.md
fires_events: ["write", "commit-completed"]
# STORAGE.md.sync.commit.on (subscribes)
sync:
commit:
on: write # fires when ANY storage:* action fires "write"Backward compatibility
This AIP is purely additive:
- TOOL.md
implements: <action-ref>is OPTIONAL. TOOLs withoutimplementsare "orphan" — usable but not policy-grantable as a group. A single orphan tool, or a server's whole set, is still grantable or deniable throughtool:invokescoped by tool name. - POLICY.md MAY accept bare action ids (
"storage:commit") for back-compat with pre-AIP-39 manifests; the canonical form is{ action: "<ref>" }. - WORKFLOW.md steps MAY use
tool: <id>(legacy) oraction: <ref>(preferred); resolvers SHOULD warn on legacy form.
Migration path:
- Author ACTION.md files for existing verbs (one per logical operation).
- Update TOOL.md files with
implements: <action-ref>. - Update POLICY.md grants to use
{ action: "<ref>" }form. - Update INTENT/WORKFLOW similarly.
The 2026-10-23 runtime-actions amendment (draft)
§Standard runtime actions is purely additive. It adds six entries to the standard library and names their categories, target kinds, side effects, risk levels, and scopes. An existing host that does not publish these actions is unaffected: no existing action id changes shape. A host that adopts the entries SHOULD map its existing ad-hoc grants onto these ids in its migration; it starts declaring verbs it previously enforced with ad-hoc mechanisms, and the ids are the only new contract.
The 2026-10-29 tool-invoke amendment (draft)
§Standard runtime actions gains tool:invoke. It is additive: no
existing action id changes shape, and a TOOL that implements an action
is decided exactly as before, because a grant on the implemented
action keeps admitting its calls (see §Evaluation there). A host that
does not publish tool:invoke is unaffected. A host that adopts it
SHOULD map any ad-hoc per-tool allow or deny list it enforces onto
grants on this id.
The 2026-10-30 session-actions amendment (draft)
§Standard runtime actions gains session:checkpoint, session:compact
and session:archive. It is additive: no existing action id changes
shape, and a host that does not publish them is unaffected.
AIP-46 §Session context used session:compact before
this library declared it; a host that already reserves compaction to the
operator keeps doing so, and the declaration only gives the id a home. A
host that adopts the entries SHOULD map any ad-hoc rule about who may
checkpoint, compact or archive a session onto grants on these ids.
Security considerations
ACTION.md is declarative: a malicious manifest can lie about
mutates, risk_level, approval. Hosts MUST treat the action
manifest as untrusted input until verified. Specifically:
- Action ids in trusted libraries (e.g.
@agentik/actions/standard/*) SHOULD be cached by SHA. Re-fetching with a different SHA flags a trust-tier downgrade. - Implementors that bind to an action SHOULD pin the action's major version. Resolution to a newer major MUST refuse the bind until the implementor explicitly upgrades.
implementations:hint field MUST NOT be trusted as a security signal. The fact that an action lists a tool as an implementor does NOT grant that tool any privileges — POLICY.grants is the authoritative source.
Open questions
-
Multi-namespace ids. Standard form is
<target-kind>:<verb>. Future<domain>:<target-kind>:<verb>(e.g.vcs:storage:commit) may be needed once we have many domains. Defer until concrete collision. -
Action versioning + implementation pinning. When
@agentik/actions/standard/[email protected]ships with breaking changes, do existing implementors auto-fail or auto-upgrade? Likely require explicit pin per implementor. Spec'd in [AIP-?? lockfile spec] (TBD). -
Stream / partial-completion semantics. Some actions emit progress (long-running). Currently
fires_eventscovers it; may need more structure if implementors get heterogeneous.
See also
- AIP-7 — governance —
requires,approval,mutatesenforcement - AIP-14 — TOOL.md — primary implementor (
implements: <action-ref>) - AIP-15 — WORKFLOW.md —
steps[i].actionconsumer - AIP-54 — REF.md — ref primitive used in
implementations[] - AIP-28 — INTENT.md —
maps_to[].actionconsumer - AIP-30 — DRIVER.md — implementor pattern parallel
- AIP-37 — LIFECYCLE.md —
fires_eventsvocabulary - AIP-38 — POLICY.md —
grants[].actionsconsumer ./resources/aip-39/draft/ACTION.schema.json— schema validator
Resources
Supporting artifacts for AIP-39. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-38: POLICY (policy/v1): composable policy block
A markdown + frontmatter format for declaring policy on a resource — access grants (who can perform which actions), defaults (per-block behavioural defaults), limits (rate / quota caps), and requirements (cross-cutting must-haves like MFA / approval). Composable inline | ref | file. Granted on AIP-39 ACTION ids — implementations / TOOLs are decoupled from policy.
AIP-40: EXTENSION (extension/v1): custom doctype declarations
A meta-doctype that lets a workspace declare its own custom doctype as an extension of an existing AIP — adding fields, tightening constraints, selectively removing non-required parent fields (remove_fields, guarded), choosing which aspects compose per-aspect (inherit), overriding defaults, and choosing a path convention — without going through the public AIP process. The runtime (@agentproto/manifest verbs, MCP server, scaffolder) treats local extensions identically to public AIPs.