AIP-71: ACTION-HOOKS (action-hooks/v1): portable action hooks and native harness projections
Defines three hook paths over AIP-37 lifecycle events and AIP-39 actions, plus a native-first harness projection contract that uses harness hooks when available and a host runtime fallback otherwise without double execution.
| Field | Value |
|---|---|
| AIP | 71 (provisional, editors assign the final number) |
| Title | ACTION-HOOKS (action-hooks/v1): portable action hooks and native harness projections |
| Status | Draft |
| Type | Core |
| Requires | AIP-37, AIP-38, AIP-39, AIP-41, AIP-42, AIP-45, AIP-60 |
| Created | 2026-10-23 |
Abstract
Agent harnesses expose useful lifecycle seams, but each names and executes them differently. Codex and Claude Code both expose callbacks around tool use, prompts, compaction, subagents, session boundaries and stopping. A host runtime also owns lifecycle transitions that no harness can observe, such as machine-load admission, duplicate-task checks, sandbox retirement and durable session maintenance.
AIP-71 defines one portable contract over both layers. It has three paths:
- admission, a synchronous decision before a host-owned action, layered on top of AIP-38 authorization;
- lifecycle, a non-blocking event emitted after a transition;
- reaction, an AIP-37 event bound to an AIP-39 action.
A harness SHOULD project a binding into one of its native hooks when it can do so faithfully. The host supplies the fallback when they cannot. Exactly one owner executes each logical binding.
This AIP does not define a universal callback runtime, a second prompt queue, or a general durable event bus.
Motivation
There are two bad extremes:
- A host ignores native hooks and reimplements every seam above the harness. Timing becomes less precise and native admission or context injection is lost.
- Every harness exposes its vendor's callback names directly. Agent manifests become harness-specific and cannot move between Codex, Claude Code and other runtimes.
The projection contract keeps portable intent in AIP configuration while leaving mechanism in the harness that understands it.
Specification
The key words MUST, MUST NOT, SHOULD and MAY are interpreted as described in AIP-1.
1. Hook paths
| Path | Timing | Result | Default delivery |
|---|---|---|---|
admission | Before a host-owned action starts | synchronous allow, deny, reuse or defer | in-process |
lifecycle | After a state transition | no blocking result | best effort |
reaction | After an event is accepted | invoke an AIP-39 action | best effort |
The paths MUST remain distinct. A lifecycle observer cannot retroactively deny an action. A reaction cannot be treated as synchronous admission merely because one harness happens to run its callback inline.
Admission and authorization
Whether a subject may perform an action at all is an
AIP-38 policy decision over the AIP-39 action id, for example
the runtime actions session:spawn, session:prompt and session:control
in the AIP-39 runtime-actions amendment. An admission hook MUST NOT grant
what AIP-38 denies: it runs only after policy allows the action, and it can
only narrow the outcome.
Besides allow and deny, a host-owned admission hook MAY return:
reuse: an existing target already satisfies the request, and the host returns it instead of starting a new one;defer: the host holds the request and retries it later.
Both depend on live runtime state, such as a session already running the same
task or a full provisioning queue, which a static policy cannot express. A
native harness hook can express only allow and deny. reuse and defer
are therefore always host-owned.
2. Portable event and action references
A hook event is an AIP-37 event name. Standard, alias, templated and custom
bare names are portable. A namespaced <host>:<event> name is non-portable and
MUST be registered by that host before use.
A reaction target is an AIP-39 action reference. Resource-qualified action ids
are preferred; unqualified AIP-39 ids remain valid. AIP-42 AGENT.md on: is
the agent-manifest shorthand for reaction bindings:
on:
turn-end: session:child-housekeeping
conversation-idle-7200:
- session:compactAIP-41 schedule.kind: event is the routine form of the same event-to-target
relationship. Implementations MUST use the same resolver and execution rules
for both surfaces rather than creating two reaction engines.
3. Native hook projection capability
An AIP-45 harness MAY declare native hook support under
capabilities.hooks. Each entry has this shape:
interface NativeHookCapability {
event: string
native_event: string
path: "admission" | "lifecycle"
can_block: boolean
handlers: readonly ("command" | "mcp" | "http" | "prompt" | "agent")[]
async?: boolean
context?: "none" | "append"
}eventMUST be the portable AIP-37 semantic event.native_eventis the harness callback identifier. It is descriptive and harness-owned; portable configuration MUST NOT reference it.pathstates whether the native seam runs before an operation or observes a lifecycle transition.can_blockis true only when a successful native callback can prevent the corresponding operation. A timeout or malformed callback response MUST NOT be advertised as a successful denial.handlerslists mechanisms the harness can execute at that seam.asyncadvertises that the harness can run a handler at this seam in the background. It does not say that every handler runs that way. An entry withcan_block: trueandasync: trueis consistent: it blocks only through a handler projected in the synchronous form (section 4).context: appendmeans a successful handler may add bounded context to the next model turn. It does not permit replacing the user's prompt.
Capability declarations are metadata. They MUST NOT install handlers, bypass a harness trust review, grant tools, or weaken an existing permission policy.
A manifest is valid only if every hooks entry satisfies these rules. Rules 1
to 3 are also encoded in the AIP-45 harness schema; rule 4 spans entries and
cannot be expressed in JSON Schema, so a reader enforces it.
eventandnative_eventMUST be non-empty and MUST NOT contain whitespace.handlersMUST list at least one mechanism, and MUST NOT list the same mechanism twice.- When
pathislifecycle,can_blockMUST befalse. A lifecycle seam observes a transition and cannot prevent it. hooksMUST NOT contain two entries with the same(event, native_event)pair. A harness that exposes one native callback through several handler mechanisms lists them in one entry'shandlers.
A reader MUST refuse a manifest that breaks any of these rules. It MUST NOT
repair the entry silently, for example by dropping a duplicate or by clearing
can_block.
4. Resolution and ownership
For every resolved binding, the host chooses exactly one owner:
type HookOwner = "harness" | "host"The harness MAY own a binding only when its AIP-45 manifest declares a
matching native capability whose timing and result semantics satisfy the
binding. Otherwise the host owns it. A host MUST NOT silently downgrade a
blocking admission hook to a non-blocking observer. A host that projects a
blocking binding MUST use the synchronous form of the native hook: a native
hook that runs in the background cannot block, whatever can_block says.
The resolution order is:
- validate the portable event and action references;
- inspect the selected harness's effective hook capabilities;
- choose
harnessonly for a faithful native projection; - otherwise choose
hostwhen the host implements the seam; - otherwise mark the binding unsupported and do not run it.
Capability read surfaces SHOULD report the selected owner and any unsupported event. Absence is not support.
Several binding sources
A binding can come from several sources: the daemon configuration, a
workspace file, an agent manifest (the AIP-42 on: shorthand), an AIP-41
routine, or a native projection the host writes. AIP-71 defines no
precedence between these sources.
- The bindings of each source MUST have binding ids that no other source uses.
- When one occurrence matches bindings from several sources, the host MUST deliver it to each matching binding independently.
- A binding from one source MUST NOT suppress, replace or override a binding from another source. Deduplication uses the section 5 key, and that key carries the binding id.
- The owner is chosen per binding. A harness that owns one binding of an event does not make the host skip another binding of the same event.
Two sources that bind the same target to the same event therefore run it twice. A host that wants only one of them to run MUST express that choice as AIP-38 policy on the target action, not as a precedence between hook sources.
5. At-most-one local execution
Native and host event streams may describe the same occurrence. A host MUST prevent double execution using a stable occurrence key scoped to the session:
<session-id>/<event>/<occurrence-id>/<binding-id>The occurrence id MAY be a harness callback id, tool-call id, turn id, or a host-generated monotonic id. It MUST remain stable when the same native event is retried. This rule is local deduplication, not an exactly-once delivery claim. It is also per binding: two bindings reached by the same occurrence have two keys, and executing one never counts as executing the other.
Every segment MUST be non-empty and MUST NOT contain whitespace or control
characters. The session id, the event and the occurrence id MUST NOT contain
/. The binding id is everything after the third /; it MAY itself contain
/, for example a hierarchical id built from an agent id and an index, as long
as each /-separated part is non-empty. This keeps the key parseable without
escaping.
6. Delivery and failure
- Admission runs synchronously and MUST have a finite timeout.
- Lifecycle emission is non-blocking and best effort.
- Reaction delivery is best effort unless a durable host explicitly records a receipt before acknowledging the event.
- A failed native hook MAY fall back to host execution only when the action has not started and the occurrence key is preserved.
- Unknown action outcome MUST NOT be replayed unless the action is idempotent or otherwise declared safe to reconcile.
7. Sentinel boundary
AIP-60 Sentinel remains a separate primitive. It watches an external or long-lived subject, persists provider cursors and dedup state, and delivers matching events into a session inbox. Hooks observe execution seams inside a host or harness.
Therefore:
- implementations MUST NOT turn every hook into a Sentinel;
- hook configuration MUST NOT reuse the Sentinel store as a generic receipt database;
- a reaction MAY invoke a Sentinel action such as creating or cancelling a watch;
- a future durable reaction implementation SHOULD reuse the proven idempotency, parking and outbox patterns where applicable, without merging the two public contracts.
8. Security and trust
Native hook code executes with the harness process's authority. Native hook projection MUST preserve the harness's trust rules and the precedence the harness applies between its own settings files. That harness ordering is not a precedence between binding sources (section 4). A host MUST NOT mark project-local hooks trusted on behalf of a user unless an explicit managed policy authorizes that behavior.
Hook inputs may contain prompts, tool arguments and filesystem paths. Logs and receipts MUST redact credentials and MUST NOT persist full sensitive payloads by default. Admission failures MUST fail according to the declared policy; a transport error is not an implicit policy denial unless the binding explicitly chooses fail-closed behavior.
Native callbacks
A native hook may run a command the host provides, either because the host
projected the hook (section 4, owner harness) or because a user installed
the command in the harness's own settings. Such a command calls back the
host. Rules 1, 2, 4 and 5 apply to every host-provided command a native hook
runs; rules 3, 6 and 7 apply to the hooks the host projects.
- The callback MUST name the host session from the environment the host
gave the harness process, for example
AGENTPROTO_SESSION_ID, or from an argument written into the hook command by whoever installed it. It MUST NOT take the session from an identifier in the hook payload: a payload session id belongs to the harness. - The callback MUST authenticate to the host as one of the principals of
AIP-46 §Session principals, on the same per-session
authenticated surface as any other caller. Until the host places the
session credential in the environment it gives the harness process, the
callback presents the operator credential and the host evaluates it as
the operator. Once the host places it there, the callback MUST present
the session credential, the host evaluates it as that session, and a
credential minted for a session other than the one the callback names is
refused with
identity_mismatch. - The host MUST NOT write that credential into the harness's settings file.
- The callback MUST NOT log or forward its environment. The harness may place its own credentials there.
- A callback that fails, times out or cannot reach the host is a transport error, as defined above. It MUST NOT be treated as a refusal. It MUST NOT block the harness step it observes unless the binding was explicitly authored as blocking.
- The host MUST write a projected hook only into a settings file that the host itself creates for that session and rewrites at each spawn, such as a per-session isolated settings file. That file is the host's even where the harness reads it as its user-level file. The host MUST NOT add a hook to a settings file that belongs to the user or to the project, and MUST NOT mark such a hook approved or trusted on the user's behalf.
- A projected non-blocking hook SHOULD bound its own run time below the timeout the harness applies to the hook. It SHOULD exit successfully in every case, including a failed callback.
Conformance
An implementation conforms to AIP-71 when it:
- preserves the three hook paths and their timing;
- accepts AIP-37 event refs and AIP-39 action refs, and leaves authorization to AIP-38;
- reports native support rather than guessing it, and refuses a
hooksdeclaration that breaks the section 3 rules; - assigns one owner per binding and prevents local double execution, without a precedence between binding sources;
- preserves harness trust boundaries and authenticates native callbacks as section 8 requires;
- treats missing events as unsupported, not successful execution;
- keeps Sentinel's durable watch contract separate.
Rationale
The portable event name belongs in AIP-37 because manifests and routines need one stable vocabulary. The native callback name belongs in the AIP-45 harness capability because only that harness can prove what it supports. The owner decision belongs here because neither vocabulary alone can prevent a native callback and a host observer from executing the same binding twice.
Authorization stays in AIP-38 because a second allow and deny language would let a hook contradict a policy. What AIP-38 cannot express is a decision that depends on live state, so admission is the narrow place where a host may reuse or defer.
A single universal callback was rejected. Admission, observation and reaction have different timing and failure semantics. Treating them as one mechanism would either make lifecycle emission blocking or make policy admission best-effort.
Using Sentinel as the hook runtime was also rejected. Sentinel's durable watch and inbox delivery semantics are valuable for external subjects, but imposing provider cursors, parking and at-least-once delivery on every tool call or prompt submission would add the wrong cost and lifecycle.
Reference Implementation
The reference implementation is the daemon runtime in
@agentproto/runtime,
which already holds the session event bus, the semantic permission hooks and
the routine registrar that this AIP generalizes. The event names live in
@agentproto/lifecycle
(AIP-37), which carries the harness extension events and the hooks contract
with its conformance fixtures. The AIP-45 capabilities.hooks declaration is
typed in the agent-cli driver, reported by the harness and session capability
surfaces, and declared today by the Codex and Claude Code adapters. The
internal contract types (admission decisions and occurrence keys) are in
@agentproto/runtime, together with the durable reaction receipts (one file
per workspace bucket, keyed by the occurrence key), the reaction runner that
executes a binding once per key with the running state written before the
target starts, and the agentproto:session-completed host event. Spawn
admission wraps session spawn and returns reuse and deny decisions. Three
reactions run on this path today: an opt-in ingestion of completed sessions
into the workspace brain, an opt-in dispatch of the AIP-68 clerk pass (each
workspace is served either by the reaction or by the legacy code path it
replaces, never both; that path is not a binding, so this is a migration
switch and not a precedence between sources), and AIP-41 event
routines, whose target is dispatched through the same authorized path as a
scheduled routine or, for an action target, through a typed registry of host
actions (the daemon registers session:archive, which archives the session of
the event). The AIP-42 on shorthand of a workspace AGENT.md resolves to the
same bindings, is rescanned on every routine reconcile, and fires only for the
sessions of the agent that declares it. A reaction that starts a session leaves
a causation chain: the runtime stamps the new session with the originating
event and a depth, and a cap (default 4) bounds the chain. The runner also
exposes a read model of its receipts (counts per binding, queue age, latency
and dead reasons) and writes one structured log line per attempt. Prompt
delivery has a persisted, bounded dedupe key, so a retried prompt is delivered
at most once inside a window; the hold barrier of prompt admission is not built.
One native projection ships, off by default
(agentproto/ts#2346): with
defaults.nativeHooks.preCompactCheckpoint: "on", the claude-code driver
writes one synchronous PreCompact hook (matcher auto, harness timeout
30 s) into the isolated per-session settings file it rewrites at every
spawn. The hook runs agentproto hook pre-compact, which reads
AGENTPROTO_SESSION_ID, posts a checkpoint with reason
native-pre-compact and an occurrence id derived from the transcript size,
authenticated by the daemon's per-boot token, so the daemon evaluates it as
the operator, gives up after 20 s and always exits 0.
agentproto hook inbox still falls back to the payload's session_id and
reads CLAUDE_CODE_SESSION_ID; both fallbacks are to be replaced by
AGENTPROTO_SESSION_ID. The daemon dedupes the checkpoint under the key
<session>/compact-start/<occurrence>/builtin:pre-compact-checkpoint.
Native compactions are also observed after the fact as
agentproto:context-compacted
(agentproto/ts#2342).
The other native hook projections, prompt admission and the admission of
tool dispatch are follow-up work in the same repository. This AIP
defines no package of its own. Until a native projection
ships for an event, the host MUST NOT claim native ownership of it, even where
the harness declares the capability.
Verified live for Claude Code (informative). On 2026-10-28 the reference implementation ran a synchronous probe hook from a project-level settings file in daemon-spawned Claude Code sessions. It verified that:
PreCompactfires for bothtrigger: "manual"andtrigger: "auto". The payload carries Claude Code's ownsession_id, not the host's, withtranscript_path,cwd,prompt_id,hook_event_name,triggerandcustom_instructions.- The hook process inherits the session environment, including
AGENTPROTO_SESSION_IDequal to the daemon session id. The environment also carries a harness-internal credential (rule 4 of section 8). - The harness awaits the hook before it applies the compaction.
- Exit code 2 blocks a manual compaction.
- The daemon transcript shows no hook event. It shows only the compaction itself.
It did not verify the user-level variant that the projection writes (the
isolated settings file) live, an auto compaction with exit code 2, the
managed policies that disable or restrict hooks, the checkpoint time on a
large transcript against the 20 s budget, or any Codex hook.
Security Considerations
Section 8 is normative. In short: native hook code runs with the harness process's authority, so a binding is an execution grant and not only a routing rule. A host that projects a binding into a native hook inherits the harness's trust prompts, and a host that runs it as the fallback owner inherits the AIP-39 approval class and the AIP-41 identity checks of the target action. Payload redaction applies to receipts and logs, not only to the wire. A capability declaration never substitutes for an OS or sandbox boundary: a blocking native hook is a policy aid, not a security perimeter.
Reference mapping
| Portable event | Typical native seam |
|---|---|
conversation-start | session-start callback |
conversation-end | session-end callback |
prompt-submit | user-prompt-submit callback |
tool-call | pre-tool-use callback |
permission-request | permission-request callback |
tool-result | post-tool-use callback |
compact-start | pre-compact callback |
compact-end | post-compact callback |
subagent-start | subagent-start callback |
subagent-end | subagent-stop callback |
turn-interrupt | interrupt callback |
turn-end | stop callback |
The right column is illustrative. Native callback spelling and exact support remain harness-owned.
References
AIP-70: GLOSSARY (glossary/v1): canonical names and vocabulary for every AIP
One name per AIP, used the same way in its title, its schema ids, its package, its define function and its tool names; one meaning per term across the specs and the reference implementation. Fixes the naming rules, the names.json registry and the ratchet check that enforces it, the vocabulary with the senses each term must not take, and the deprecated aliases with their replacements.
AIP-72: MEMORY (memory/v1): typed memory items about a principal and its work
Fixes the stored memory document, one markdown file per memory item: a small typed assertion (user, feedback, project, reference) about a principal or its work, with AIP-10 base fields, a lifecycle (active, then superseded or archived), a lifetime, provenance and capture blocks, and a free markdown body; then the memory store a host reads and writes items through (propose or commit, read, list, search, supersede, archive, compare-and-set, no hard delete) and the projection of items into each harness session (a bounded digest injected natively or through the system prompt, native-memory changes captured back as proposals); then the node and operator anchors, which scope an item's visibility by AIP-34 node and mark its ownership by AIP-9 operator, and the rule that every store operation applies the session's node projection.