hookmux 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +402 -2
- package/dist/chunks/add-ZWGK62EX.mjs +1 -0
- package/dist/chunks/chunk-2ZCM3JZR.mjs +3 -0
- package/dist/chunks/chunk-5GQP3BA6.mjs +1 -0
- package/dist/chunks/chunk-65XA3RK3.mjs +4 -0
- package/dist/chunks/chunk-6GL55FEQ.mjs +20 -0
- package/dist/chunks/chunk-7Z3AMI24.mjs +1 -0
- package/dist/chunks/chunk-AHPMRYYF.mjs +1 -0
- package/dist/chunks/chunk-BF25CRHJ.mjs +1 -0
- package/dist/chunks/chunk-CA2GWCFP.mjs +3 -0
- package/dist/chunks/chunk-CSXS5D2F.mjs +1 -0
- package/dist/chunks/chunk-CZY5UAXM.mjs +1 -0
- package/dist/chunks/chunk-DJHE642J.mjs +7 -0
- package/dist/chunks/chunk-DZU2NMID.mjs +1 -0
- package/dist/chunks/chunk-F3USS665.mjs +1 -0
- package/dist/chunks/chunk-FF55QGCZ.mjs +1 -0
- package/dist/chunks/chunk-G6SJQTFF.mjs +1 -0
- package/dist/chunks/chunk-IAGBX723.mjs +2 -0
- package/dist/chunks/chunk-IJHUIMJA.mjs +5 -0
- package/dist/chunks/chunk-K73ZPBFM.mjs +45 -0
- package/dist/chunks/chunk-L3BSVLQG.mjs +1 -0
- package/dist/chunks/chunk-OMKE4U3M.mjs +1 -0
- package/dist/chunks/chunk-OXHAGFXG.mjs +12 -0
- package/dist/chunks/chunk-OYGOSD6V.mjs +1 -0
- package/dist/chunks/chunk-QTY23VNU.mjs +1 -0
- package/dist/chunks/chunk-RG3EOP4J.mjs +1 -0
- package/dist/chunks/chunk-SXIEWTYT.mjs +1 -0
- package/dist/chunks/chunk-UERSXYXZ.mjs +3 -0
- package/dist/chunks/chunk-WZSNBZ6D.mjs +2 -0
- package/dist/chunks/chunk-XPLEWNGF.mjs +1 -0
- package/dist/chunks/chunk-ZDCAHPWY.mjs +2 -0
- package/dist/chunks/chunk-ZNEBE4WO.mjs +1 -0
- package/dist/chunks/disable-KRHQYUQU.mjs +3 -0
- package/dist/chunks/doctor-KERAJBFA.mjs +7 -0
- package/dist/chunks/enable-SWA7C4K2.mjs +4 -0
- package/dist/chunks/explain-WNQLELTA.mjs +9 -0
- package/dist/chunks/hook-main-PW67WMNF.mjs +1 -0
- package/dist/chunks/init-46THKH7Z.mjs +12 -0
- package/dist/chunks/install-J4QGOOCD.mjs +15 -0
- package/dist/chunks/list-NAFC2CUM.mjs +5 -0
- package/dist/chunks/log-ELHUFP5Y.mjs +11 -0
- package/dist/chunks/new-UASRUAP2.mjs +186 -0
- package/dist/chunks/promote-4RJUMW7Y.mjs +24 -0
- package/dist/chunks/registry-P6V5HZQN.mjs +1 -0
- package/dist/chunks/remove-XCOCPNJJ.mjs +3 -0
- package/dist/chunks/schema-FFOAJAET.mjs +4 -0
- package/dist/chunks/sync-UCVS5O2X.mjs +4 -0
- package/dist/chunks/test-BCLMCB5A.mjs +8 -0
- package/dist/chunks/uninstall-ZMGYPYVA.mjs +7 -0
- package/dist/chunks/validate-ICFP6TSC.mjs +1 -0
- package/dist/cli.mjs +4 -0
- package/dist/hook.mjs +1 -0
- package/launcher/hookmux-hook.sh +83 -0
- package/launcher/opencode-plugin.js +236 -0
- package/package.json +57 -4
- package/plugins/hookmux-authoring/plugin.toml +65 -0
- package/plugins/hookmux-authoring/tests.toml +119 -0
- package/skills/hookmux/SKILL.md +102 -0
- package/skills/hookmux/references/check-kinds.md +124 -0
- package/skills/hookmux/references/effects.md +24 -0
- package/skills/hookmux/references/examples/moodboard/plugin.toml +72 -0
- package/skills/hookmux/references/examples/moodboard/tests.toml +20 -0
- package/skills/hookmux/references/hosts.md +173 -0
- package/skills/hookmux/references/plugin-format.md +400 -0
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
<!-- Generated by scripts/gen-skill-refs.ts from docs/plugins.md. Do not edit; run `pnpm gen:refs`. -->
|
|
2
|
+
# plugin.toml reference
|
|
3
|
+
|
|
4
|
+
A hookmux plugin is a folder with a `plugin.toml` manifest and, usually, a `tests.toml` with test prompts. This page lists every manifest key, check kind, effect, template placeholder and setting.
|
|
5
|
+
|
|
6
|
+
The engine reads manifests when you add or promote a plugin, or when its saved registry is out of date. It never parses TOML while it evaluates a prompt. `hookmux schema --json` prints what the installed engine accepts, and it wins when it disagrees with this page.
|
|
7
|
+
|
|
8
|
+
## Folder layout
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
my-plugin/
|
|
12
|
+
plugin.toml # required
|
|
13
|
+
tests.toml # optional, used by `hookmux test`
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- The folder name must equal the manifest `id`.
|
|
17
|
+
- `plugin.toml` must be 256 KiB or smaller, owned by you, and not writable by group or others (`chmod go-w`).
|
|
18
|
+
- A plugin folder may not contain symlinks, and it holds at most 200 files and 4 MiB.
|
|
19
|
+
|
|
20
|
+
## A complete example
|
|
21
|
+
|
|
22
|
+
```toml
|
|
23
|
+
schema = 1
|
|
24
|
+
id = "changelog-reminder"
|
|
25
|
+
version = "1.0.0"
|
|
26
|
+
description = "Remind the agent to update the changelog when a prompt mentions a release."
|
|
27
|
+
events = ["prompt.submit"]
|
|
28
|
+
phase = "route"
|
|
29
|
+
dedupe = "session"
|
|
30
|
+
when = "mentions_release and not is_question"
|
|
31
|
+
|
|
32
|
+
[checks.mentions_release]
|
|
33
|
+
kind = "keywords"
|
|
34
|
+
words = ["release", "ship it", "cut a version"]
|
|
35
|
+
|
|
36
|
+
[checks.is_question]
|
|
37
|
+
kind = "regex"
|
|
38
|
+
patterns = ['^\s*(what|why|how|when)\b']
|
|
39
|
+
|
|
40
|
+
[[then]]
|
|
41
|
+
effect = "inject"
|
|
42
|
+
text = "This prompt mentions a release. Update CHANGELOG.md as part of the change."
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
TOML literal strings (`'...'`) keep regular expressions readable, because backslashes stay as written.
|
|
46
|
+
|
|
47
|
+
## Manifest keys
|
|
48
|
+
|
|
49
|
+
| Key | Type | Default | Meaning |
|
|
50
|
+
| ------------------ | -------------- | ---------- | ---------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `schema` | integer | required | Manifest format. Must be `1`. |
|
|
52
|
+
| `id` | string | required | Lowercase letters, digits and dashes, up to 64 characters. Must match the folder name. |
|
|
53
|
+
| `version` | string | `"0.0.0"` | The plugin's own version. |
|
|
54
|
+
| `description` | string | `""` | One line shown by `hookmux list`. |
|
|
55
|
+
| `events` | list | required | Canonical events the plugin listens to (see [Events](#events)). |
|
|
56
|
+
| `hosts` | list | every host | Host ids the plugin is limited to, such as `["claude-code"]`. |
|
|
57
|
+
| `phase` | string | `"route"` | `guard`, `route`, `enrich` or `observe` (see [Phases and order](#phases-and-order)). |
|
|
58
|
+
| `priority` | integer | `100` | Lower runs earlier within a phase. |
|
|
59
|
+
| `enabled` | boolean | `true` | `false` turns the plugin off. |
|
|
60
|
+
| `shadow` | boolean | `false` | Evaluate and log, but add nothing to the output. |
|
|
61
|
+
| `origins` | list | see below | Prompt origins the plugin runs on: `user`, `system`, `unknown`. |
|
|
62
|
+
| `dedupe` | string | `"none"` | `"session"` fires the plugin at most once per session. |
|
|
63
|
+
| `exclusive` | string | none | Group name. Of the plugins in one group that fire, only the first in output order contributes. |
|
|
64
|
+
| `on_error` | string | `"open"` | Only `"open"` is accepted, and it changes nothing: hookmux always fails open. |
|
|
65
|
+
| `when` | string | required | Expression over the plugin's checks that decides whether it fires. |
|
|
66
|
+
| `when_degraded` | string | none | Fallback expression, used when `when` stays unknown. |
|
|
67
|
+
| `params` | table | `{}` | Strings, numbers or booleans for templates, stored as strings. |
|
|
68
|
+
| `checks` | table | `{}` | Named checks, one `[checks.<name>]` table each. |
|
|
69
|
+
| `then` | list of tables | required | Effects, one `[[then]]` table each. At least one. |
|
|
70
|
+
| `host` | table | none | Per-host changes, one `[host.<id>]` table each. |
|
|
71
|
+
| `requires_hookmux` | string | none | Accepted, but this version does not check it. |
|
|
72
|
+
|
|
73
|
+
The default for `origins` depends on the phase. Guard plugins run on every origin. Every other phase uses the `route_origins` setting, which defaults to `["user"]`, so background-task notifications never trigger a suggestion. The engine ignores unknown keys and reports each as a warning.
|
|
74
|
+
|
|
75
|
+
## Events
|
|
76
|
+
|
|
77
|
+
| Event | When it fires | Text a check can read |
|
|
78
|
+
| --------------- | --------------------------------------- | ------------------------- |
|
|
79
|
+
| `prompt.submit` | The user sends a prompt | `prompt` |
|
|
80
|
+
| `session.start` | A session starts, resumes or is cleared | none |
|
|
81
|
+
| `tool.before` | Before a tool call | `tool.name`, `tool.input` |
|
|
82
|
+
| `tool.after` | After a tool call | `tool.name`, `tool.input` |
|
|
83
|
+
|
|
84
|
+
`cwd` is available on every event. Pattern checks pick their text with `field`: `prompt` (the default), `cwd`, `tool.name`, `tool.input` (the whole input as JSON) or a path into it such as `tool.input.command`. Each host adapter maps these names to its client's own hook names, and `hookmux schema --json` lists the mapping.
|
|
85
|
+
|
|
86
|
+
## Checks
|
|
87
|
+
|
|
88
|
+
Each check has a lowercase snake_case name and a `kind`:
|
|
89
|
+
|
|
90
|
+
```toml
|
|
91
|
+
[checks.secret_shape]
|
|
92
|
+
kind = "regex"
|
|
93
|
+
patterns = ['AKIA[0-9A-Z]{16}', 'ghp_[A-Za-z0-9]{36}']
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A check returns true, false or unknown. Score checks return a number from 0 to 1, which `when` must compare (`fit >= 0.7`). Unknown means the check errored, ran out of time, or could not tell, such as a host version range when the host reports no version.
|
|
97
|
+
|
|
98
|
+
Kinds have a cost tier. The engine runs tier 0 checks for every plugin first and stops as soon as each plugin's `when` is decided, so a subprocess or model check runs only when its answer could still change the result. By default a model-backed kind cannot justify a block on its own, and its output never reaches a template.
|
|
99
|
+
|
|
100
|
+
These are the kinds in this version. The [check kinds reference](https://github.com/khanglvm/hookmux/blob/main/skills/hookmux/references/check-kinds.md) lists each kind's options.
|
|
101
|
+
|
|
102
|
+
<!-- check-kinds:begin -->
|
|
103
|
+
<!-- Generated by scripts/gen-skill-refs.ts from src/checks. Do not edit; run `pnpm gen:refs`. -->
|
|
104
|
+
| Kind | Tier | Model-backed | What it does |
|
|
105
|
+
| -------------- | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
+
| `classify` | 2 (model call) | yes | Score from 0 to 1 that the field is the target label, decided by a configured model provider. |
|
|
107
|
+
| `cwd_glob` | 0 (in-process) | no | True when the working folder matches one of the globs. |
|
|
108
|
+
| `host` | 0 (in-process) | no | True when the agent client matches: its id, a version range, the effects it supports on this event, or the features it has (features) or lacks (lacks). Unknown version or feature gives unknown. |
|
|
109
|
+
| `keywords` | 0 (in-process) | no | True when any (or all) of the words appear as whole words, case-insensitive by default. |
|
|
110
|
+
| `origin` | 0 (in-process) | no | True when the prompt origin is one of the listed values. |
|
|
111
|
+
| `path_exists` | 0 (in-process) | no | True when any (or all) paths exist, relative to the working folder. |
|
|
112
|
+
| `regex` | 0 (in-process) | no | True when any (or all) of the patterns match the field. |
|
|
113
|
+
| `regex_groups` | 0 (in-process) | no | Named groups of patterns; true when every group in at least one fire_when combination matches. |
|
|
114
|
+
| `script` | 1 (subprocess) | no | Runs an executable from the plugin folder; it reads the event as JSON on stdin and prints its value. |
|
|
115
|
+
| `tool` | 0 (in-process) | no | True when the tool call names one of these tools (canonical or host name). |
|
|
116
|
+
<!-- check-kinds:end -->
|
|
117
|
+
|
|
118
|
+
Pattern checks cut their input to 8,000 characters before matching, and accept at most 200 patterns of up to 300 characters each. A pattern that repeats a group which already repeats, such as `(a+)+` or `(\w+\s?)+`, is rejected, because it can take exponential time on some input. The check is a heuristic; the launcher's watchdog is what stops a hook run that hangs. Flags default to `iu` (case-insensitive, Unicode). JavaScript's `\b` only knows ASCII letters, so put it next to ASCII characters only; the `keywords` kind handles word edges for any script.
|
|
119
|
+
|
|
120
|
+
## Effects
|
|
121
|
+
|
|
122
|
+
<!-- effects:begin -->
|
|
123
|
+
<!-- Generated by scripts/gen-skill-refs.ts from its effect table. Do not edit; run `pnpm gen:refs`. -->
|
|
124
|
+
| Effect | Fields | Behaviour |
|
|
125
|
+
| -------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
126
|
+
| `inject` | `text`, `fallback` | Adds the text to the agent's context. Dropped when the host cannot add context on this event or the context budget is used up. `fallback` lists effects to try instead where the host cannot add context. |
|
|
127
|
+
| `block` | `reason`, `suppress_original_prompt` (prompt.submit only, default false), `fallback` | Stops the prompt or tool call and shows the reason. The first block in output order wins. With `block_requires_rule` on (the default), a check that is not model-backed must be true. Where the host cannot block, a `fallback` list picks what to do instead (`inject`, `notify`, or `[]` to drop); without one it becomes a notice, or is dropped where the host cannot notify either. A block dropped for lacking a rule never falls back. |
|
|
128
|
+
| `notify` | `text`, `fallback` | Shows the text to the user, not the agent. Dropped when the host cannot notify on this event, unless `fallback` names an effect to use instead. |
|
|
129
|
+
<!-- effects:end -->
|
|
130
|
+
|
|
131
|
+
Effect text may be up to 4,000 characters and may use [templates](#templates).
|
|
132
|
+
|
|
133
|
+
```toml
|
|
134
|
+
[[then]]
|
|
135
|
+
effect = "block"
|
|
136
|
+
reason = "The prompt looks like it contains a credential. Remove it and send again."
|
|
137
|
+
suppress_original_prompt = true
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Fallback
|
|
141
|
+
|
|
142
|
+
Where a client cannot perform an effect, hookmux drops it. The one exception is a block, which becomes a notice on a client that can show one. Add `fallback` to choose something else: a list of `inject` and `notify`, tried in order, where the first one the client supports on that event is used. An empty list drops the effect.
|
|
143
|
+
|
|
144
|
+
```toml
|
|
145
|
+
[[then]]
|
|
146
|
+
effect = "block"
|
|
147
|
+
reason = "The tool already ran. Revert the change."
|
|
148
|
+
fallback = ["inject", "notify"]
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
On a client that cannot block after a tool call, this reason goes to the agent as added context. If the client cannot add context there either, it is shown to the user as a notice.
|
|
152
|
+
|
|
153
|
+
`fallback` only applies when the client lacks the effect. It cannot contain `block`, the effect's own kind, or the same entry twice. A block dropped because no rule-backed check agreed is dropped for good and never falls back. An inject reached by fallback counts against the context budget like any other. A notice that falls back to inject puts text in the agent's context, so promote lists `inject` for that plugin.
|
|
154
|
+
|
|
155
|
+
An older engine ignores `fallback` and uses its default.
|
|
156
|
+
|
|
157
|
+
## When expressions
|
|
158
|
+
|
|
159
|
+
`when` combines check names with `and`, `or`, `not`, parentheses, and the literals `true` and `false`. Score checks appear only in comparisons: `<`, `<=`, `>`, `>=`, `==`, `!=` against a number. `not` binds tightest, then `and`, then `or`. An expression is at most 2,000 characters, and validation rejects names that are not declared checks.
|
|
160
|
+
|
|
161
|
+
Evaluation uses three-valued logic, so an unknown signal only matters when it could change the answer:
|
|
162
|
+
|
|
163
|
+
| Expression | Result |
|
|
164
|
+
| ------------------- | ------- |
|
|
165
|
+
| `false and unknown` | false |
|
|
166
|
+
| `true and unknown` | unknown |
|
|
167
|
+
| `true or unknown` | true |
|
|
168
|
+
| `false or unknown` | unknown |
|
|
169
|
+
| `not unknown` | unknown |
|
|
170
|
+
|
|
171
|
+
This is also why the order of terms does not matter. `cheap and costly` and `costly and cheap` both skip `costly` when `cheap` is false.
|
|
172
|
+
|
|
173
|
+
When `when` is true the plugin fires, and when it is false the plugin stays silent. When it stays unknown, the engine evaluates `when_degraded`. If that is unknown too, or missing, the plugin contributes nothing. A failed check never makes a plugin fire, so an error can never block the agent. A plugin that adds a model check should set `when_degraded` to a rules-only expression, or to `"false"` to stay quiet when the model is unavailable.
|
|
174
|
+
|
|
175
|
+
All checks share one deadline, `deadline_ms` (2,000 ms by default). Checks still running at the deadline become unknown. The launcher stops any hook run after 5 seconds and passes nothing on, so keep `deadline_ms` well under that; a longer deadline only lets a slow check end the run with no output.
|
|
176
|
+
|
|
177
|
+
## Phases and order
|
|
178
|
+
|
|
179
|
+
| Phase | Typical use |
|
|
180
|
+
| --------- | --------------------------------------------------------------- |
|
|
181
|
+
| `guard` | Stop a prompt or tool call. Runs on every origin by default. |
|
|
182
|
+
| `route` | Suggest a skill or a next step. |
|
|
183
|
+
| `enrich` | Always-on context. |
|
|
184
|
+
| `observe` | Last in output order. This version gives it no other behaviour. |
|
|
185
|
+
|
|
186
|
+
Output order is phase (in the order above), then `priority` (lower first), then `id`. In this version the phase sets output order and the default origins. It does not limit which effects a plugin may use.
|
|
187
|
+
|
|
188
|
+
How plugins that fire together combine:
|
|
189
|
+
|
|
190
|
+
- The first block in output order wins, and the host shows the block in place of any added context.
|
|
191
|
+
- In an `exclusive` group, the first plugin in output order takes the group, and later ones in the same group are dropped.
|
|
192
|
+
- Injected text is joined in output order. The total is capped by the `context_budget` setting (9,000 characters by default) and by the host's own limit, whichever is lower. Text that does not fit is dropped whole.
|
|
193
|
+
- A `shadow` plugin is evaluated and logged, and contributes nothing.
|
|
194
|
+
- With `dedupe = "session"`, a plugin that fired once is skipped for the rest of that session.
|
|
195
|
+
|
|
196
|
+
## Client features
|
|
197
|
+
|
|
198
|
+
The effects table above says which effects a client can perform. Features describe finer behaviour: whether a block stops the tool before it runs, whether `<` and `>` in added context reach the model, whether a prompt can be told apart from an agent's message. Each adapter states every feature, per event, as yes, no or unknown. Unknown means the client's docs and source say nothing. A feature about an effect is always no where the client cannot perform that effect.
|
|
199
|
+
|
|
200
|
+
<!-- features:begin -->
|
|
201
|
+
<!-- Generated by scripts/gen-skill-refs.ts from src/core/features.ts. Do not edit; run `pnpm gen:refs`. -->
|
|
202
|
+
| Feature | Events | Meaning |
|
|
203
|
+
| ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
|
|
204
|
+
| `host.version` | `prompt.submit`, `session.start`, `tool.before`, `tool.after` | The payload reports the client version |
|
|
205
|
+
| `prompt.origin` | `prompt.submit` | hookmux can tell user prompts from system or agent sends |
|
|
206
|
+
| `tool.file-path` | `tool.before`, `tool.after` | Every file-edit tool carries tool_input.file_path |
|
|
207
|
+
| `inject.markup` | `prompt.submit`, `session.start`, `tool.before`, `tool.after` | < and > in added context reach the model unescaped |
|
|
208
|
+
| `inject.inline` | `prompt.submit`, `session.start`, `tool.before`, `tool.after` | All added context up to the context limit is shown inline |
|
|
209
|
+
| `inject.before-call` | `tool.before` | The model sees added context before the tool runs |
|
|
210
|
+
| `block.prevents` | `prompt.submit`, `tool.before`, `tool.after` | A block stops the action before it happens |
|
|
211
|
+
| `block.reason-to-agent` | `prompt.submit`, `tool.before`, `tool.after` | The agent sees the block reason |
|
|
212
|
+
| `block.suppress-prompt` | `prompt.submit` | suppress_original_prompt is honoured |
|
|
213
|
+
<!-- features:end -->
|
|
214
|
+
|
|
215
|
+
The `host` check reads them. `features` is true when every listed feature is yes. `lacks` is true when every listed feature is no.
|
|
216
|
+
|
|
217
|
+
```toml
|
|
218
|
+
# True on clients that pass < and > to the model unescaped.
|
|
219
|
+
[checks.plain_markup]
|
|
220
|
+
kind = "host"
|
|
221
|
+
features = ["inject.markup"]
|
|
222
|
+
|
|
223
|
+
# True where a block cannot stop the tool, because it already ran.
|
|
224
|
+
[checks.after_only]
|
|
225
|
+
kind = "host"
|
|
226
|
+
lacks = ["block.prevents"]
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
A check with an unknown feature is unknown, unless another part of it (the host id, say) is already false. A feature on an event it does not describe, such as `inject.before-call` on `tool.after`, is also unknown. A misspelled feature id is a validation error. An older engine rejects a `host` check that has only `features` or `lacks`.
|
|
230
|
+
|
|
231
|
+
`hookmux validate <path>` prints, for each client, what every effect will do and which features weaken it. `hookmux test` prints the same rows for the clients its cases used, and `hookmux schema` lists every client's features per event. The [host notes](hosts.md#feature-matrix) hold the full matrix.
|
|
232
|
+
|
|
233
|
+
## Per-host tables
|
|
234
|
+
|
|
235
|
+
A `[host.<id>]` table changes the plugin for one client. It uses the same keys as the manifest and merges over it:
|
|
236
|
+
|
|
237
|
+
```toml
|
|
238
|
+
[[then]]
|
|
239
|
+
effect = "inject"
|
|
240
|
+
text = "Load the `moodboard` skill and start at its first step."
|
|
241
|
+
|
|
242
|
+
[host.codex]
|
|
243
|
+
then = [{ effect = "inject", text = "Use the `moodboard` skill for this request." }]
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Tables merge key by key, and lists and plain values replace the base value. A table for a host id this engine has no adapter for is ignored with a warning, so a plugin written for a future adapter still loads. To branch inside `when` instead, use a `host` check.
|
|
247
|
+
|
|
248
|
+
## Overrides in ~/.hookmux/config.toml
|
|
249
|
+
|
|
250
|
+
You can change an installed plugin without editing its files. An `[override.<id>]` table takes the same keys as the manifest:
|
|
251
|
+
|
|
252
|
+
```toml
|
|
253
|
+
[override.moodboard]
|
|
254
|
+
priority = 20
|
|
255
|
+
shadow = true
|
|
256
|
+
|
|
257
|
+
[override.hookmux-authoring]
|
|
258
|
+
enabled = false
|
|
259
|
+
|
|
260
|
+
[override.moodboard.host.codex]
|
|
261
|
+
enabled = false
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Merge order, lowest first: the plugin, its `[host.<id>]` table, your override, then your override's `host.<id>` table.
|
|
265
|
+
|
|
266
|
+
The same file holds hub settings and model providers:
|
|
267
|
+
|
|
268
|
+
```toml
|
|
269
|
+
[settings]
|
|
270
|
+
deadline_ms = 2000 # 50 to 20000
|
|
271
|
+
block_requires_rule = true # a block needs a true check that is not model-backed
|
|
272
|
+
route_origins = ["user"] # default origins for plugins outside the guard phase
|
|
273
|
+
context_budget = 9000 # characters of injected context per event
|
|
274
|
+
auto_trust_declarative = false # see Trust below
|
|
275
|
+
|
|
276
|
+
[providers.fast]
|
|
277
|
+
kind = "..." # provider kind, used by model-backed checks
|
|
278
|
+
url = "http://127.0.0.1:8090"
|
|
279
|
+
model = "..."
|
|
280
|
+
timeout_ms = 300
|
|
281
|
+
api_key_env = "MY_PROVIDER_KEY" # name of an environment variable; the key is never stored
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
`hookmux doctor` reports an invalid config file. Until you fix it, the hook keeps running on default settings.
|
|
285
|
+
|
|
286
|
+
## Templates
|
|
287
|
+
|
|
288
|
+
Effect text can use these placeholders:
|
|
289
|
+
|
|
290
|
+
| Placeholder | Value |
|
|
291
|
+
| ----------------------------- | ----------------------------------------------------------- |
|
|
292
|
+
| `{params.<key>}` | A value from `[params]` |
|
|
293
|
+
| `{host.id}`, `{host.name}` | The calling client, such as `claude-code` and `Claude Code` |
|
|
294
|
+
| `{host.version}` | The client version, or `unknown` |
|
|
295
|
+
| `{event.name}`, `{event.cwd}` | The canonical event and the working folder |
|
|
296
|
+
| `{evidence.<check>}` | The text a check matched, cut to 80 characters |
|
|
297
|
+
|
|
298
|
+
`{evidence.<check>}` is empty for model-backed checks, so model output never becomes text in the agent's context. It is also empty for a check that matched nothing or does not exist. Any other placeholder with an unknown key stays as written.
|
|
299
|
+
|
|
300
|
+
Script checks can set their own limit with `evidence_chars`. Promote lists each requested variable as `env:NAME` and each limit above 80 as `evidence_chars:N`. An override that requests a new variable or a new limit above 80 requires another promotion, including overrides for a single host.
|
|
301
|
+
|
|
302
|
+
## Tests
|
|
303
|
+
|
|
304
|
+
`tests.toml` lists prompts and the outcome each should have:
|
|
305
|
+
|
|
306
|
+
```toml
|
|
307
|
+
[[case]]
|
|
308
|
+
prompt = "redesign the pricing page so it feels more premium"
|
|
309
|
+
expect = "fire"
|
|
310
|
+
|
|
311
|
+
[[case]]
|
|
312
|
+
prompt = "fix the crash on the settings screen"
|
|
313
|
+
expect = "silent"
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
On tool events a case can set `command`, the shell command the tool call carries, such as `command = "git push --force"`. `hookmux test` runs them and prints how long each plugin took. Write both kinds of case, in each language you write prompts in, and include the near misses you worry about.
|
|
317
|
+
|
|
318
|
+
`hookmux test` runs a plugin's scripts only once it is promoted. For a folder, or an installed plugin nobody promoted yet, script checks give unknown and their cases count as skipped. Pass `--run-scripts` to run them, which executes the scripts on disk as they are now. `hookmux explain --all` follows the same rule for unpromoted plugins.
|
|
319
|
+
|
|
320
|
+
A script runs from a private copy of the bytes that matched its hash, in `~/.hookmux/cache/scripts`, so `$0` is not inside the plugin folder. Find files next to the script through `$HOOKMUX_PLUGIN_DIR`.
|
|
321
|
+
|
|
322
|
+
## Trust
|
|
323
|
+
|
|
324
|
+
`hookmux promote <id>` records a SHA-256 hash of the plugin folder and the capabilities it has with your `config.toml` overrides applied. If any file in the folder changes afterwards, or an override adds a capability (an event, a block effect, a script or model check), the plugin stops running until you approve it again. With a standing approval (`hookmux promote <id> --standing`), `hookmux add --force` of a new version goes live without asking while its capabilities stay within the approved ones; a higher approved `evidence_chars` limit covers a lower one.
|
|
325
|
+
|
|
326
|
+
### Installing in one step
|
|
327
|
+
|
|
328
|
+
`hookmux install <source>` is for a plugin author's published install line. It sets up hookmux when needed (engine, launcher and hub entries on the chosen client, with no bundled plugins and no authoring skill), adds the plugin untrusted like `add`, and then asks for the approval below: at a terminal, the full card and a `y` prompt; from an agent, the card and a code, with exit 3. It takes `--plugin <id>` to pick plugins from a source that holds several, and `--host <id>` to name the client when no terminal or agent marker says which. `hookmux new <id> --repo owner/name` writes the matching install line and the plugin's card into the README.
|
|
329
|
+
|
|
330
|
+
### The approval card
|
|
331
|
+
|
|
332
|
+
Before anything turns on, whoever answers sees a card for the plugin: its name and version, where it came from, what it says it does, how often it runs and what it can do. The card is built from the compiled manifest, not from the plugin's own claims, and text the author wrote is stripped of control characters and cut to length before it is printed. `hookmux add` prints a one-paragraph version, `hookmux promote` prints the full card, and clients that ask in their own prompt show the paragraph.
|
|
333
|
+
|
|
334
|
+
The `Runs` line reads `<how often> · <costliest check> · <time bound>`. The time bound is the hub's deadline, and it is left out when every check runs in-process.
|
|
335
|
+
|
|
336
|
+
Each capability gets one line with a risk word:
|
|
337
|
+
|
|
338
|
+
<!-- capabilities:begin -->
|
|
339
|
+
<!-- Generated by scripts/gen-skill-refs.ts from src/core/card.ts. Do not edit; run `pnpm gen:refs`. -->
|
|
340
|
+
| Capability | Risk | Line on the card |
|
|
341
|
+
| -------------------------- | ------ | ----------------------------------------------------------------- |
|
|
342
|
+
| `script` | high | Runs guard.sh as your user, not sandboxed |
|
|
343
|
+
| `block` on a tool event | high | Can stop the agent's tool calls |
|
|
344
|
+
| `block` on `prompt.submit` | high | Can discard your prompt before the agent sees it |
|
|
345
|
+
| `model` on `prompt.submit` | medium | Sends your prompt text to your configured model provider (local) |
|
|
346
|
+
| `model` on a tool event | medium | Sends tool-call details to your configured model provider (local) |
|
|
347
|
+
| `env:NAME` | medium | Passes $NAME from your environment to its script |
|
|
348
|
+
| `inject` | medium | Adds text the agent reads and may follow |
|
|
349
|
+
| `evidence_chars:N` | medium | Can quote up to 2000 characters of script output to the agent |
|
|
350
|
+
| `notify` | low | Shows you messages the agent does not see |
|
|
351
|
+
| any other code | high | Uses something-new (hookmux has no description for it) |
|
|
352
|
+
| `event:*` | none | Not listed. The events appear in the cost line. |
|
|
353
|
+
<!-- capabilities:end -->
|
|
354
|
+
|
|
355
|
+
Two worked cards:
|
|
356
|
+
|
|
357
|
+
<!-- card-examples:begin -->
|
|
358
|
+
<!-- Generated by scripts/gen-skill-refs.ts from scripts/card-examples.ts. Do not edit; run `pnpm gen:refs`. -->
|
|
359
|
+
**A script on every tool call**
|
|
360
|
+
|
|
361
|
+
```text
|
|
362
|
+
hookmux plugin: git-guard 0.3.1
|
|
363
|
+
From: github.com/acme/git-guard @ 4f2c1a9 (hookmux has not reviewed it)
|
|
364
|
+
Does: Stops force-pushes to main.
|
|
365
|
+
Runs: Before every tool call · runs a script · can add up to 2 s
|
|
366
|
+
Can:
|
|
367
|
+
high Runs guard.sh as your user, not sandboxed
|
|
368
|
+
high Can stop the agent's tool calls
|
|
369
|
+
medium Passes $GITHUB_TOKEN from your environment to its script
|
|
370
|
+
low Shows you messages the agent does not see
|
|
371
|
+
Content: sha256:3b9e…41ac, first approval
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
**A model call on every prompt**
|
|
375
|
+
|
|
376
|
+
```text
|
|
377
|
+
hookmux plugin: topic-router 1.2.0
|
|
378
|
+
From: github.com/acme/topic-router @ 9a1b2c3 (hookmux has not reviewed it)
|
|
379
|
+
Does: Points the agent at the team wiki for billing questions.
|
|
380
|
+
Runs: On every prompt · calls your model provider · can add up to 2 s
|
|
381
|
+
Can:
|
|
382
|
+
medium Sends your prompt text to your configured model provider (local)
|
|
383
|
+
medium Adds text the agent reads and may follow
|
|
384
|
+
A model alone never blocks anything.
|
|
385
|
+
Content: sha256:77a0…c2d1, first approval
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
<!-- card-examples:end -->
|
|
389
|
+
|
|
390
|
+
### Three ways to say yes
|
|
391
|
+
|
|
392
|
+
- **At your terminal.** `hookmux promote <id>` prints the card and asks you to type `y`. It never takes `--yes`, and it treats the environment variables Claude Code, Codex and Gemini CLI set on the commands they run as "an agent is here" even on a terminal. This proves that someone answered `y` where no agent marker was set. It does not prove a person typed it, because an agent can open a pseudo-terminal and clear its environment.
|
|
393
|
+
- **In your client's permission prompt.** On Claude Code and Qwen Code, when an agent runs exactly `hookmux promote <id>` and an installed plugin listens to `tool.before` (so the hub has an entry for it), the hub makes the client ask you, with the card's paragraph as the reason. Your answer turns the plugin on. This proves the client's own prompt for that exact command was answered "allow". It does not prove who answered: a hook or an SDK callback that approves every call answers too.
|
|
394
|
+
- **By replying with a code.** Everywhere else, including `hookmux install` run by an agent, promote has no terminal to ask at, so it prints the card and a four-character code and exits 3. The agent shows you the card. If you agree, you send `approve <code>` as your next message. hookmux's own prompt hook sees that message, shows you a notice with the true card, and tells the agent the one command that finishes the job, `hookmux promote <id> --confirm <code>`. That command works only while the plugin is unchanged since the card was issued, and the card expires after 30 minutes. This proves that a prompt the client marked as yours, with the code in it, reached hookmux after the card was issued. It does not prove a human typed it: an agent that feeds the hub a made-up prompt payload, or starts a second client with the code as its prompt, can get through, as it can through a pseudo-terminal at the terminal step. It does not prove the agent showed you the card faithfully either; the notice is there so you can check. A reply that pastes promote's own output, with its `--confirm <code>` line, does not count. On Gemini CLI, Factory Droid, Qoder CLI and CodeBuddy Code the client cannot mark who wrote a prompt, so this path is weaker there.
|
|
395
|
+
|
|
396
|
+
An agent may carry the request and the card. Only your reply, seen by hookmux or by the client, carries the yes. A reply by code never grants a standing approval.
|
|
397
|
+
|
|
398
|
+
None of the three stops a process that runs as you and edits `trust.json` or the registry, or feeds the hook launcher a forged payload. That is the same kind of bypass as the pseudo-terminal, and the checkpoint is not a sandbox. What it stops is an agent that follows an injected instruction, or runs a normal command, and quietly turns on code that runs on every prompt.
|
|
399
|
+
|
|
400
|
+
With `auto_trust_declarative = true`, plugins whose effects are only inject or notify and that run no scripts are trusted without promote. Plugins that block or run a script always need it.
|