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.

FieldValue
AIP71 (provisional, editors assign the final number)
TitleACTION-HOOKS (action-hooks/v1): portable action hooks and native harness projections
StatusDraft
TypeCore
RequiresAIP-37, AIP-38, AIP-39, AIP-41, AIP-42, AIP-45, AIP-60
Created2026-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:

  1. A host ignores native hooks and reimplements every seam above the harness. Timing becomes less precise and native admission or context injection is lost.
  2. 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

PathTimingResultDefault delivery
admissionBefore a host-owned action startssynchronous allow, deny, reuse or deferin-process
lifecycleAfter a state transitionno blocking resultbest effort
reactionAfter an event is acceptedinvoke an AIP-39 actionbest 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:compact

AIP-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"
}
  • event MUST be the portable AIP-37 semantic event.
  • native_event is the harness callback identifier. It is descriptive and harness-owned; portable configuration MUST NOT reference it.
  • path states whether the native seam runs before an operation or observes a lifecycle transition.
  • can_block is 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.
  • handlers lists mechanisms the harness can execute at that seam.
  • async advertises 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 with can_block: true and async: true is consistent: it blocks only through a handler projected in the synchronous form (section 4).
  • context: append means 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.

  1. event and native_event MUST be non-empty and MUST NOT contain whitespace.
  2. handlers MUST list at least one mechanism, and MUST NOT list the same mechanism twice.
  3. When path is lifecycle, can_block MUST be false. A lifecycle seam observes a transition and cannot prevent it.
  4. hooks MUST 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's handlers.

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:

  1. validate the portable event and action references;
  2. inspect the selected harness's effective hook capabilities;
  3. choose harness only for a faithful native projection;
  4. otherwise choose host when the host implements the seam;
  5. 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.

  1. 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.
  2. 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.
  3. The host MUST NOT write that credential into the harness's settings file.
  4. The callback MUST NOT log or forward its environment. The harness may place its own credentials there.
  5. 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.
  6. 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.
  7. 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:

  1. preserves the three hook paths and their timing;
  2. accepts AIP-37 event refs and AIP-39 action refs, and leaves authorization to AIP-38;
  3. reports native support rather than guessing it, and refuses a hooks declaration that breaks the section 3 rules;
  4. assigns one owner per binding and prevents local double execution, without a precedence between binding sources;
  5. preserves harness trust boundaries and authenticates native callbacks as section 8 requires;
  6. treats missing events as unsupported, not successful execution;
  7. 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:

  • PreCompact fires for both trigger: "manual" and trigger: "auto". The payload carries Claude Code's own session_id, not the host's, with transcript_path, cwd, prompt_id, hook_event_name, trigger and custom_instructions.
  • The hook process inherits the session environment, including AGENTPROTO_SESSION_ID equal 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 eventTypical native seam
conversation-startsession-start callback
conversation-endsession-end callback
prompt-submituser-prompt-submit callback
tool-callpre-tool-use callback
permission-requestpermission-request callback
tool-resultpost-tool-use callback
compact-startpre-compact callback
compact-endpost-compact callback
subagent-startsubagent-start callback
subagent-endsubagent-stop callback
turn-interruptinterrupt callback
turn-endstop callback

The right column is illustrative. Native callback spelling and exact support remain harness-owned.

References