Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions schemas/1.1.0/hooks.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@
"$ref": "#/$defs/handlers"
},
"PreToolUse": {
"$ref": "#/$defs/handlers"
"$ref": "#/$defs/toolHandlers"
},
"PostToolUse": {
"$ref": "#/$defs/handlers"
"$ref": "#/$defs/toolHandlers"
}
},
"additionalProperties": false
Expand Down Expand Up @@ -64,6 +64,45 @@
"required": ["command"],
"additionalProperties": false
},
"toolHandlers": {
"title": "Tool event handlers",
"type": "array",
"items": {
"$ref": "#/$defs/toolHandler"
},
"minItems": 1
},
"toolHandler": {
"title": "Tool event handler",
"type": "object",
"properties": {
"command": {
"$ref": "#/$defs/handler/properties/command"
},
"args": {
"$ref": "#/$defs/handler/properties/args"
},
"toolProfiles": {
"type": "array",
"items": {
"enum": [
"mcp",
"shell",
"file.read",
"file.modify",
"web.fetch",
"web.search"
]
},
"minItems": 1
},
"extensions": {
"$ref": "#/$defs/handler/properties/extensions"
}
},
"required": ["command"],
"additionalProperties": false
},
"extensions": {
"type": "object",
"description": "Client-specific handler settings keyed by reverse-domain extension namespace. Agent Plugins assigns no semantics to namespace object contents.",
Expand Down
43 changes: 29 additions & 14 deletions spec/1.1.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -462,24 +462,23 @@ The hooks configuration path is `hooks.json` at the plugin root. Hook configurat

`hooks.json` MUST be a JSON object containing the required `$schema` and `hooks` fields, with no other top-level fields. `hooks` MUST be an object whose member names identify hook events and whose member values are nonempty arrays whose elements configure handlers. An empty `hooks` object is valid.

The official machine-readable schema is [`schemas/1.1.0/hooks.schema.json`](../schemas/1.1.0/hooks.schema.json). The specification text is authoritative if it conflicts with the schema. The schema exposes `#/$defs/handlers`, `#/$defs/handler`, and event input and output definitions so that clients can validate configuration entries, event inputs they produce, and handler results they consume while preserving the failure boundaries in §7.3.2. Event input definitions are version-specific producer schemas; handler acceptance is governed by §7.3.3.
The official machine-readable schema is [`schemas/1.1.0/hooks.schema.json`](../schemas/1.1.0/hooks.schema.json). The specification text is authoritative if it conflicts with the schema. The schema provides definitions for validating configuration entries, event inputs, and handler results separately while preserving the failure boundaries in §7.3.2. Event input definitions are version-specific producer schemas; handler acceptance is governed by §7.3.3.

The required `$schema` field identifies the Agent Plugins specification version targeted by the hooks configuration and its corresponding hooks schema. For Agent Plugins 1.1.0, its value MUST be the canonical identifier `https://agent-plugins.org/schemas/1.1.0/hooks.schema.json`.

Clients MUST use a recognized `$schema` value to select locally supported hooks validation and interpretation rules. A client MAY map multiple canonical identifiers to the same implementation only when it explicitly recognizes those Agent Plugins versions as compatible. Clients MUST NOT retrieve a schema while loading a plugin.

Each handler is a closed object with the following fields:
Each handler configuration is a closed object with the following fields:

| Field | Type | Required | Description |
| ------------ | -------- | -------- | ---------------------------------------------- |
| `command` | string | Yes | Executable token to launch. |
| `args` | string[] | No | Arguments passed to the executable. |
| `extensions` | object | No | Client-specific handler settings. See §8.1. |
| Field | Type | Required | Description |
| -------------- | -------- | -------- | ----------------------------------------------------------------------- |
| `command` | string | Yes | Executable token to launch. |
| `args` | string[] | No | Arguments passed to the executable. |
| `toolProfiles` | string[] | No | Profile-name filter. Permitted only for `PreToolUse` and `PostToolUse`. |
| `extensions` | object | No | Client-specific handler settings. See §8.1. |

Each array element configures an independent handler.

The optional `extensions` field contains client-specific settings for that handler, keyed by extension namespace as defined in §8.1. Client-specific handler settings MUST preserve the portable hook requirements in §7.3.

The `command` field MUST contain a single executable token, not a shell command string. It MUST be either a bare executable name or a plugin-relative path beginning with `./`. Clients MUST resolve bare names using the platform's executable search rules and MUST resolve plugin-relative paths against the plugin root. Clients MUST NOT perform placeholder expansion in `command`.

The `args` field MUST support `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expansion.
Expand All @@ -488,6 +487,10 @@ A bare `command` creates an external runtime dependency and may not resolve on e

Clients MAY use a platform-specific command interpreter when required to launch the resolved executable, such as a `.bat` or `.cmd` script on Windows, but MUST preserve `command` as one token and pass `args` separately.

The optional `toolProfiles` field is permitted only in handler configurations for `PreToolUse` and `PostToolUse`. When present, it MUST be a nonempty array of portable tool profile names. The available profile names are defined in §7.3.6.

The optional `extensions` field contains client-specific settings for that handler, keyed by extension namespace as defined in §8.1. Client-specific handler settings MUST preserve the portable hook requirements in §7.3.

Example: `hooks.json`

```json
Expand Down Expand Up @@ -517,7 +520,8 @@ Example: `hooks.json`
],
"PostToolUse": [
{
"command": "./hooks/review-tool-result"
"command": "./hooks/review-file-changes",
"toolProfiles": ["file.modify"]
}
],
"Stop": [
Expand Down Expand Up @@ -552,7 +556,9 @@ Example: a handler with client-specific settings

#### 7.3.3 Command execution and results

For each occurrence of a hook event, the client MUST invoke every handler for that event that was not skipped under §7.3.2, across all enabled plugins, with the same event input. A client MAY schedule handler invocations sequentially or concurrently, including with bounded concurrency and across overlapping event occurrences. It MUST NOT provide one handler with another handler's result. Handlers MUST NOT depend on invocation order or on side effects from another handler for the same event occurrence.
For each occurrence of a hook event, the client MUST invoke every applicable handler for that event across all enabled plugins, except those skipped under §7.3.2. All invoked handlers MUST receive the same event input.

A client MAY schedule handler invocations sequentially or concurrently, including with bounded concurrency and across overlapping event occurrences. It MUST NOT provide one handler with another handler's result. Handlers MUST NOT depend on invocation order or on side effects from another handler for the same event occurrence.

For each hook invocation, the client MUST launch a fresh handler process with the configured `command` and `args`, use the plugin root as its working directory, and provide the subprocess environment defined in §9.1. The client MUST write exactly one UTF-8 JSON object, followed only by optional JSON whitespace, to the handler's standard input and then close standard input. It MUST consume standard output while the handler runs, ensure that standard error cannot prevent the process from completing, and wait for the handler to exit or time out before processing its result. A client MAY impose implementation-defined time and process-output size limits; exceeding a limit is a handler failure.

Expand Down Expand Up @@ -677,6 +683,8 @@ If the request proceeds, the client MUST include the content of every successful

`PreToolUse` runs after the client has determined a tool call's name and input, but before it requests any discretionary permission that the hook result could satisfy or begins executing the tool. The event applies to every root-agent or subagent tool call that the client mediates and can intercept at that point. Operations that the client cannot observe and prevent before execution are outside the event's coverage.

If a handler's configuration in `hooks.json` omits `toolProfiles`, the handler runs for every occurrence of this event. Otherwise, the client MUST NOT launch the handler process unless the event input's `tool_profile.name` exactly matches one of the configured names. An event input without a `tool_profile` does not match.

`hook_event_name` MUST be `"PreToolUse"`.

In addition to the common input fields in §7.3.3, the handler receives:
Expand Down Expand Up @@ -941,7 +949,9 @@ Example:

`PostToolUse` runs when a tool call produces its completed result for the agent, including a result reporting failure of the requested operation. The event applies to every root-agent or subagent tool call that the client mediates and for which it controls delivery of the result to the agent. A call denied before execution, an intermediate tool exchange, or an invocation that ends without a completed tool result does not reach this event.

Before the agent continues from the associated tool result, the client MUST finish invoking the event's handlers and processing their successful results. This requirement does not impose an order among handlers or require a separate model request for each completed tool call.
If a handler's configuration in `hooks.json` omits `toolProfiles`, the handler runs for every occurrence of this event. Otherwise, the client MUST NOT launch the handler process unless the event input's `tool_profile.name` exactly matches one of the configured names. An event input without a `tool_profile` does not match.

Before the agent continues from the associated tool result, the client MUST finish invoking the event's applicable handlers and processing their successful results. This requirement does not impose an order among handlers or require a separate model request for each completed tool call.

`hook_event_name` MUST be `"PostToolUse"`.

Expand Down Expand Up @@ -1401,7 +1411,8 @@ A client is not required to support every component type. For example, a skills-
- [ ] Run `Stop` when the root agent completes a response normally and would otherwise yield control, without treating it as a pre-publication or quiescence event ([§7.3.8](#738-stop))
- [ ] Set `continuation_active` while root-agent work fulfills an honored request from the aggregate after-response hook mechanism, then combine successful `continue` results into one continuation that includes every returned reason in its prepared context ([§7.3.8](#738-stop))
- [ ] Launch a fresh handler process in the plugin root for each invocation ([§7.3.3](#733-command-execution-and-results))
- [ ] Send the same defined event object to every enabled handler, close standard input, and parse only the defined status-`0` standard output as a portable result ([§7.3.3](#733-command-execution-and-results))
- [ ] For tool events, launch each handler process only when `toolProfiles` is omitted or matches the event's emitted profile ([§7.3.6](#736-pretooluse), [§7.3.7](#737-posttooluse))
- [ ] Send the same defined event object to every invoked handler, close standard input, and parse only the defined status-`0` standard output as a portable result ([§7.3.3](#733-command-execution-and-results))
- [ ] Include only properties defined by an implemented Agent Plugins version in event-input objects whose properties Agent Plugins defines ([§7.3.3](#733-command-execution-and-results))
- [ ] Ignore unrecognized properties recursively in event-input objects whose properties Agent Plugins defines ([§7.3.3](#733-command-execution-and-results))
- [ ] Treat a `tool_profile` with an unrecognized `name` as opaque without assigning portable meaning to its `input` or `result` ([§7.3.6](#736-pretooluse), [§7.3.7](#737-posttooluse))
Expand Down Expand Up @@ -1525,7 +1536,11 @@ The initial event omits response text, transcript paths, native statuses, backgr

Clients do not share built-in tool names, argument schemas, or result schemas. Preserving the native JSON lets client-aware hooks inspect the actual call without pretending that unlike tools have a common data model. A separate portable projection captures a tool family and useful common structure where clients can map it deterministically, without making client-native names part of a registry that future versions could collide with or discarding native fields outside the portable minimum. The `tool_profile` object keeps the profile name and its input and, for `PostToolUse`, result projections together, so they are present or absent as a unit. Its closed, versioned field namespace remains separate from the opaque native data. Client-specific fields stay in `tool_input` and `tool_result` rather than sharing the portable namespace, where they could obscure portable guarantees or collide with fields added by later Agent Plugins versions.

Clients are encouraged rather than required to recognize every applicable profile, but an emitted profile is a reliable conformance claim. The hooks configuration does not include tool-name matchers because a handler can inspect the same event input itself, avoiding a second matching language and client-specific naming assumptions.
Clients are encouraged rather than required to recognize every applicable profile, but an emitted profile is a reliable conformance claim.

### Why match handlers by emitted tool profile?

The `toolProfiles` filter avoids launching processes that would immediately discard an event based on its portable profile name. Clients use different native tool names for the same kinds of operations; portable profile names let one filter configuration retain its meaning across clients. Finer filtering remains in handler code.

### Why does the `file.read` input expose only a path?

Expand Down