mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect

Relocated from dezren39/darwin-nix#112 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #176

Summary

mcpx exec runs a script and returns what it produced. This asks for the caller to be able to attach natural-language instructions to the edges of that run — before it, after it, on failure, on success — so the deterministic script stays deterministic and the fuzzy parts sit outside it.

That is a better factoring than it first appears. The script is the part that must be reproducible; "make sure these dependencies exist wherever this runs" and "clean up the results and transform them" are the parts that legitimately vary by environment and by caller. Keeping them out of the script means the same script file works everywhere and the variation is in the options, which is exactly the shape ExecOptions was designed for (#40, step 7: "not a new method, an option").

Original notes

mcp-owned opencode api support

accept prompt/prePrompt/postPrompt/onErrorPrompt/onSuccessPrompt

the script interface just runs the scripts, but you can provide a prePrompt saying hey i added a bunch of dependencies please make sure they exist where the job runs, postPrompt to clean up the results and transform, either prompt/pre/post could say to fix error thing but onError gets provided above or below the error and is first seen with the error if theres an error. prompts can use templatevars to put content where they want it or for prompt overall to be stopped/resumed maybe.

Current state (what mcpx does today, with file refs)

execsvc.Options (internal/execsvc/execsvc.go:101) is the designated growth point: "Deliberately one flat struct that grows rather than a new endpoint per capability." It carries Runtime, Timeout, Permissions, Placeholders, Session, Cwd, Env, Stdin, Output, Capabilities, Artifacts, Task, NS, Args, Export. There are no prompt fields.
Placeholders already exist and already have substitution semantics worth copying. Recipes declare holes in a header comment (// @param repo:string) and reference them as @repo; values are substituted as JSON, never as text, because "a recipe runs with the user's credentials; raw substitution would make every placeholder an injection site" (docs/consumer.md §3). Launchers use the same @placeholder spelling (Bump build/buck/preludes/buck2-prelude from 3a02ea3 to c77fc97 #7). A recipe with an unfilled required hole is an invalid script, which is the right way round.
ScriptConfig.Prefix (internal/config/config.go:236-248) already layers code in front of a script from config, resolved across the config chain (docs/proposals.md §"Layered script prefixes"). It is the deterministic sibling of a prePrompt and the precedent for how layering should work.
Deterministic edge hooks already ship — for the CLI and config, not for /v1/exec. (Added in the 2026-09-30 issues pass, at 05c78b2; this issue predated them being noticed.) Five settings — script.before, script.prefix, script.onSuccess, script.onError, script.suffix (internal/settings/registry.go:212-242), layered through ScriptConfig (internal/config/config.go:236-257) and rendered as runner.Phases (internal/runner/runner.go:190-205) — inject source into a file script's launcher: onSuccess sees result.value, onError sees result.error and the error is rethrown ("a hook, not a handler"), suffix runs in a finally. They run inside the script's own process, and they are deliberately not on the wire Options: execsvc.RunWith keeps phases CLI-only (internal/execsvc/execsvc.go:358-366). So Approach B below is partly built already, in a different shape; what is missing is per-call hooks over /v1 and MCP, a typed context, and prompt hooks. The shipped names are one of the four hook vocabularies in Phase 3: sync, blob gate, and relays #181 collision 2.
The exec stream has an ordering contract: start, then log/emit/stdout interleaved, then artifact, then result or error, then end, with bodies strictly after end (execsvc.Frame, docs/exec.md). Any hook output has to find a place in that order, and that is a real design constraint, not a formality.
internal/diagnose produces structured diagnostics that already sit next to an error.
Tasks (internal/tasks) provide the pause/resume machinery the note's "stopped/resumed maybe" is reaching for, and 2026-07-28's MRTR pattern gives a caller-facing way to resume a request mid-flight.
mcpx has no model; see Bump build/buck/preludes/buck2-prelude from d956689 to 52604b1 #110. Every rung below degrades to a no-op without one.

Approaches

Approach A — least recommended: five new string options, each handed to a model, each running arbitrary code

Options.Prompt, .PrePrompt, .PostPrompt, .OnErrorPrompt, .OnSuccessPrompt, each sent to a model with a general-purpose agent loop that can do whatever it decides is needed.

Why not:

Four of the five are the same thing at different times. Five independent fields means five code paths, five sets of semantics, and five places to fix a bug. Lifecycle hooks are a list of (phase, instruction), and modelling them as one list with a phase is strictly better — prompt is then just "the phase is main", which is also what makes "either prompt/pre/post could say to fix error thing" fall out naturally instead of needing to be special-cased.
An unbounded prePrompt is arbitrary code execution as a side door. "make sure these dependencies exist where the job runs" resolved by a general agent means installing packages, which is the provisioning problem from Update module github.com/jackc/pgx/v5 to v5.5.4 [SECURITY] - autoclosed #113 and needs its own confinement decisions. An exec option should not quietly be the more powerful interface.
It puts the model on the default path. Every run pays a round trip even when the hooks do nothing surprising. docs/consumer.md's rule — "never sample on a path that doesn't need it" — is violated by construction if hooks are evaluated eagerly.
Nothing is reproducible. The same script plus the same prompts gives different behaviour run to run, which destroys the one property that makes exec worth having over a chat turn.

Approach B — middle: one `hooks` list, deterministic hooks only

Add one field:

"options": {
  "hooks": [
    { "phase": "pre",     "script": "ensure-deps.ts" },
    { "phase": "post",    "script": "normalise.ts" },
    { "phase": "onError", "script": "cleanup.ts" }
  ]
}

Phases: pre, main, post, onError, onSuccess. Each hook is a script, run in the same content-addressed workdir with the same runtime and permissions, receiving a typed context (the run id, the result or the error plus its diagnose.Diagnostic, the artifact list). post transforms the result; onError sees the error first and may return a replacement result or re-raise — which differs from the shipped script.onError, where the error always propagates.

The phase names and hook semantics are not this issue's to decide (#181 collision 2). Four vocabularies exist or are proposed — the shipped script.* phases, #81's hook points, #82's runtime hooks and this list — and the one vocabulary is being decided in a decision record SURFACES is writing under pkgs/mcpx/docs/decisions/, carried by #81. The phases here are input to that record; this issue adopts what it decides.

This is genuinely useful on its own — ScriptConfig.Prefix proves the demand for "run this code around my code" and hooks generalise it to the other three edges — and it is the thing the prompt version needs underneath it anyway, because a prompt hook's output has to become something executable. It is also fully deterministic, cacheable, and testable.

What it does not give you is the actual ask: "hey i added a bunch of dependencies please make sure they exist where the job runs" is a sentence, not a script, and the whole point is not having to write the script.

Approach C — recommended: one `hooks` list where a hook is either a script or a prompt, with a declared effect

Build B's structure, and let each entry be a script or a prompt:

"options": {
  "hooks": [
    { "phase": "pre",     "prompt": "I added @deps — make sure they exist where this runs",
                          "effect": "script", "model": "cheap" },
    { "phase": "post",    "prompt": "flatten the result to {id, title} and drop nulls",
                          "effect": "transform" },
    { "phase": "onError", "prompt": "if this is a rate limit, wait and say so; otherwise explain",
                          "effect": "advise" }
  ]
}

Four decisions make this safe and small:

1. A hook declares its effect, and the effect bounds what it may do.

`effect`	what the hook's output may be	runs code?
`advise`	text, attached to the result or error	no
`transform`	a replacement for the result value only	no
`script`	TypeScript, diagnosed and typechecked, then run in the same sandbox	yes
`retry`	a decision: retry / retry-with-changes / give up	via the repair ladder

advise is the default. This is the same dial as repair.level in #111 and should use the same vocabulary; a user who understands one understands the other. #181 collision 3: #111 carries that one dial vocabulary, via the SURFACES decision record under pkgs/mcpx/docs/decisions/; the effect values in this table are input to it, and #112 adopts what it decides rather than shipping its own. The ceiling a daemon puts on it is #185 (collision 5). A prompt hook whose effect is script is the only one that can execute anything, and it inherits Options.Permissions unchanged — a hook must never be able to do what the script it wraps could not.

2. Template variables reuse the placeholder machinery that exists, including its safety property. @name is already the spelling in recipes and launchers, and recipe values are JSON-encoded, not text-substituted, precisely so a placeholder cannot become an injection site. A prompt is text and the same discipline applies at a different layer: the substituted value must be delimited and marked as data, and a hook prompt must never be able to redefine the hook's own effect. Beyond user placeholders, offer a small set of built-ins the note is clearly asking for — @result, @error, @diagnostic, @calls, @artifacts, @source — so "onError gets provided above or below the error" is expressible as "Here is what happened:\n@error\n@diagnostic\nWhat should I do?" rather than being a positioning rule mcpx has to guess. Position by template, not by convention; when a prompt contains no built-in reference, mcpx appends the context after it, which is the sensible default the note describes.

3. Hooks are declarable in config, not just per call. ScriptConfig.Prefix and the shipped script.before/onSuccess/onError/suffix already layer across the config chain; script.hooks (or whatever collision 2's record names it) should layer the same way, so "always check dependencies before any run in this project" is written once. Per-call hooks append to config hooks rather than replacing them, with the same nearest-wins resolution ResolveLines already implements.

4. Stop/resume is internal/tasks, not a new mechanism. "for prompt overall to be stopped/resumed maybe" — a hook that needs a decision raises an elicitation through the existing broker (with a default and a deadline, as elicit.Ask enforces), and a run that must wait becomes a task with a handle, collectable from /v1/tasks/{id}. Both already exist and both already work for the recipe path. On 2026-07-28 this is also exactly MRTR: resultType: "input_required", the client answers, the request is retried.

Stream placement, since the Frame order is a contract (docs/exec.md:137). #181 collision 7: #111 owns the rule every new frame kind follows (declared placement relative to result, listed in the documented order, asserted by a test comparing documented and emitted order); the hook frame is added under that rule and the placement below is input to it: a hook emits log/emit/stdout frames tagged with its phase and a hook frame recording phase, effect, model used, duration and whether it changed anything. pre frames come after start; post/onSuccess frames come after the result frame and before end; onError frames come after error and before end. The final result reflects a transform hook's output, with the original preserved in the hook frame — a caller must be able to see what mcpx changed.

Cost and default posture. Hooks are off unless declared. A prompt hook without an available model is a warning on the run, not a failure — the script still ran, and that is the honest degradation. pre hooks with effect: script should be cached by (prompt, placeholder values, catalogue fingerprint) so the same "ensure my dependencies" instruction resolves to the same generated script on every run instead of re-generating it; that caching is also what makes the generated script reviewable and promotable to a real hook script, which is how this feature should be expected to be used — prompt once, keep the script.

Recommended because the structure is one list rather than five fields, because effect-declaration is what keeps a convenience feature from being an execution back door, because everything it needs — placeholders, prefixes, tasks, elicitation, diagnostics, artifacts — already exists and this mostly wires them to four new points in time, and because the deterministic half (Approach B) is independently valuable and ships first.

Open questions

Does onSuccess earn its own phase when post exists? post running only on success and onError on failure covers it; a separate onSuccess is only distinct if post is meant to run on both. Pick one and document it — this is the note's ambiguity, not a design difficulty.
Ordering when several hooks share a phase: declaration order across config layers, or an explicit order? Declaration order plus nearest-wins layering matches ScriptPrefix.
Should a transform hook be allowed to change artifacts, or only the result value? Only the value is far simpler and probably enough.
Timeout accounting: does a hook's time count against Options.Timeout or get its own budget? Its own, or a slow model silently eats the script's budget.
Is there a case for hooks on a tool call rather than a run (before every call to this server, ...)? That is closer to a server-level middleware feature and may belong with tool views.
Should a hook be able to abort the run before it starts (pre returning refuse)? Useful and cheap, but then a pre hook is a policy mechanism and needs the floor/ceiling clamping Phase 5: who may clear a tag claim #185 owns.

Ease · Impact · Related

Ease M (S for the deterministic half — much of it already ships as script.* launcher phases, so what remains is exposing them per call with a typed context; M with prompt hooks and effects; L if stop/resume gets its own machinery rather than reusing tasks) · Impact medium-high — it is what makes one script file portable across environments without the script knowing where it runs, which is the same goal #40 had for artifacts.

Depends on / related: #81 (owns the hook vocabulary via the SURFACES decision record — #181 collision 2), #111 (owns the autonomy dial and the frame-order rule — collisions 3 and 7), #185 (owns ClampedBy — collision 5), #82 (runtime hook registration, the fourth vocabulary), #40 (closed, fixed in #57: ExecOptions is the home; "not a new method, an option" is the governing precedent), #41 (closed, fixed in #58: placeholders, elicitation defaults/deadlines, diagnostics as hook context), #7 (launcher @placeholder spelling), #5 (config chain, for layered hooks), #79 (hook cost must not regress exec latency). Siblings: #110 (where a prompt hook's model comes from), #113 (the dependency-provisioning half of the pre example; also #103/#104 in #175).

Security/auth deferred; see tracker.

CODE-855

@dezren39

History carried over from dezren39/darwin-nix#112 (verbatim, oldest first):

@dezren39 · 2026-09-30T07:21:51Z

Integration pass. Placed in the DAG rooted at #181.

Tracker: Nix Playwright E2E suite fails after vendoring dependencies #176 (the AI layer and search)
Siblings under that tracker: Bump build/buck/preludes/buck2-prelude from d956689 to d460fcc #109 Bump build/buck/preludes/buck2-prelude from d956689 to 52604b1 #110 Bump checkmarx/ast-github-action from 2.0.19 to 2.0.23 #111 Update module github.com/jackc/pgx/v5 to v5.5.4 [SECURITY] - autoclosed #113 Update checkmarx/ast-github-action digest to 6c56658 - autoclosed #114 Update github.com/charmbracelet/promwish digest to 6c16e8f - autoclosed #115
Root: Phase 3: sync, blob gate, and relays #181
Proposed order: phase 6 -- the big bets, in dependency order

@dezren39 · 2026-09-30T07:27:50Z

Integration pass -- cross-theme collision. Surfaced only when the themes were put side by side; the authors of these issues could not see each other's work. Recorded at the root in #181.

Four hook vocabularies, and no issue owns the reconciliation

script.* (shipped), #81's hook-point table, #82's runtime hook registration, and #112's prePrompt/postPrompt/onError list are four vocabularies for one concept. #112 sits in a different theme (#176) from #81/#82 (#173), so nobody currently owns the overlap. Reconciling them after the fact is a breaking config change -- design them as one.

Also on: #81 #82. Nobody currently owns this.

@dezren39 · 2026-09-30T07:27:53Z

Integration pass -- cross-theme collision. Surfaced only when the themes were put side by side; the authors of these issues could not see each other's work. Recorded at the root in #181.

Three autonomy dials, independently invented

#111's repair.level, #112's hook effect, and #113's prompt.mode: plan are the same dial. Settle it in #111, which is the earliest of the three. Otherwise a user learns three vocabularies for one concept.

Also on: #111 #113. Nobody currently owns this.

@dezren39 · 2026-09-30T07:28:01Z

Integration pass -- cross-theme collision. Surfaced only when the themes were put side by side; the authors of these issues could not see each other's work. Recorded at the root in #181.

`ClampedBy` is a settings-registry feature with no owner

#111 proposes floor/ceiling clamping -- a daemon sets a maximum, a caller may lower but not raise -- and #112 and #113 both need it. It currently exists only as a paragraph inside #111. It is an internal/settings capability, not a repair feature; whoever reaches it first will implement it, and the other two will implement it again differently.

Also on: #111 #113 #172. Nobody currently owns this.

@dezren39 · 2026-09-30T07:28:09Z

Integration pass -- cross-theme collision. Surfaced only when the themes were put side by side; the authors of these issues could not see each other's work. Recorded at the root in #181.

The exec `Frame` ordering contract is extended by two issues independently

#111 adds a call frame; #112 adds a hook frame with explicit before/after-result placement rules. docs/exec.md states the frame order as a contract. Neither issue knows about the other's placement rules, and no issue owns updating the contract.

Also on: #111. Nobody currently owns this.

@dezren39 · 2026-09-30T11:06:07Z

Collision ownership (issues pass, 2026-09-30, at 05c78b2). #181 listed these cross-theme collisions with no owner. Each now has one:

#181 row	Collision	Owner	What the owner decides
2	four hook vocabularies (`script.*` shipped, #81, #82, #112)	#81, via a decision record SURFACES is writing under `pkgs/mcpx/docs/decisions/` (in flight; linked here when it merges)	The vocabulary is decided in the decision record; #81 is the issue that carries it. #82 and #112 adopt it rather than defining their own.
3	three autonomy dials (#111 `repair.level`, #112 hook `effect`, #113 `prompt.mode: plan`)	#111, via a decision record SURFACES is writing under `pkgs/mcpx/docs/decisions/` (in flight; linked here when it merges)	One dial vocabulary; #111 carries it because it is the earliest of the three. The ceiling mechanism is #185.
5	`ClampedBy` -- a daemon ceiling a caller may lower but not raise	#185 (new)	A settings-registry capability, owned by its own design issue under #176. #111, #112 and #113 consume it.
7	the exec `Frame` ordering contract, extended by #111 (`call`) and #112 (`hook`)	#111	#111 extends `docs/exec.md`'s order first and states the rule every new frame kind follows (declared placement relative to `result`, listed in the documented order, asserted by a test that compares documented and emitted order). #112 adds its kind under that rule.

Where this issue is the owner, the decision is made here; where it is not, it adopts the owner's decision rather than making its own.

@dezren39 · 2026-09-30T11:57:45Z

Issues pass (2026-09-30, at 05c78b2).

Added Parent: #176.
Current state was missing a shipped feature. Deterministic edge hooks already exist: script.before, script.prefix, script.onSuccess, script.onError and script.suffix (internal/settings/registry.go:212-242, ScriptConfig internal/config/config.go:236-257, runner.Phases internal/runner/runner.go:190-205). They inject source into the launcher. onError rethrows ("a hook, not a handler") and suffix runs in a finally. They are CLI and config only; /v1/exec does not carry them by design (internal/execsvc/execsvc.go:358-366). Approach B is therefore partly built already. The body says so and flags that B's onError (may replace the result) differs from the shipped one (always rethrows).
Deferrals, per Phase 3: sync, blob gate, and relays #181: the phase names and semantics defer to the hook-vocabulary decision record carried by chore(deps): bump stefanzweifel/git-auto-commit-action from 4 to 5 #81 (collision 2). effect defers to Bump checkmarx/ast-github-action from 2.0.19 to 2.0.23 #111's dial (collision 3), with Phase 5: who may clear a tag claim #185 as its ceiling (collision 5). The hook frame is added under Bump checkmarx/ast-github-action from 2.0.19 to 2.0.23 #111's frame-order rule (collision 7). The design text is kept as input to those owners.
Ease note: "S for the deterministic script-hook list alone" becomes "S for the deterministic half — much of it already ships…". Still M / medium-high; Nix Playwright E2E suite fails after vendoring dependencies #176 updated to match.
Related: adds chore(deps): bump stefanzweifel/git-auto-commit-action from 4 to 5 #81, chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 5f79ad1 #82, Bump checkmarx/ast-github-action from 2.0.19 to 2.0.23 #111 and Phase 5: who may clear a tag claim #185, marks Bump openssl from 0.10.54 to 0.10.55 in /sources/pavex/examples/realworld #40 and Bump build/buck/preludes/buck2-prelude from d956689 to 6f75473 #41 as closed (fixed in chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to 677e9eb #57 and chore(deps): bump rustix from 0.38.3 to 0.38.21 in /build/nix/setup #58), and names siblings by number. Label design added.

@dezren39 · 2026-09-30T16:58:17Z

Decided (SURFACES, 0001 and 0002, merged in #228).

What changes in this issue:

pre → before, post → onSuccess; main is not a hook, it is /v1/intent. prePrompt/postPrompt/onErrorPrompt are the prompt action at before/onSuccess/onError.
effect takes the autonomy levels: transform → apply; script → run (or propose to hand the script back); retry → run; a pre hook that refuses is ask.
script.hooks becomes entries of the one hooks setting with on: script.
Frame order: onSuccess/onError hook frames come before the single final result/error; suffix after it.
Found while deciding, and to fix before building on the phases: mcpx exec accepts --before/--on-success/--on-error and drops them; a top-level throw skips onError and suffix because the import sits outside the launcher's try; no phase reaches /v1/exec or --remote.

@dezren39 · 2026-09-30T19:35:58Z

Follow-up: two of the three phase holes named in the decision comment are closed in #265 -- mcpx exec now runs --before/--on-success/--on-error (and script.before/onSuccess/onError), and a top-level throw runs onError and suffix (the import moved inside the launcher's try). The third, phases on /v1/exec and --remote, is #192. #265 also fixed mcpx exec --remote losing its output.

@dezren39 · 2026-10-28T22:22:42Z

Triage verdict (task 2154, repo-health-nix-pilot): PARTIALLY LANDED + CONFIRMED remainder, RELOCATED — deterministic script phases are now on the wire; prompt hooks (the actual ask) are unimplemented. Implementation routes in developing-today/code; no fix packet in this repo.

Verified against current main on both sides (nix 224c7b738e88c7a8e5d406987a7d88257e229db2, code d2cb60fe8e08cd6fee149b930187b610299c1fa7):

Update module gopkg.in/go-jose/go-jose.v2 to v2.6.3 [SECURITY] - autoclosed #112 is OPEN with labels enhancement, design — no hard-stop labels. Parent tracker Nix Playwright E2E suite fails after vendoring dependencies #176 is OPEN.
The mcpx source no longer lives in dezren39/nix: no pkgs/mcpx at HEAD; the extraction plan (planning/plans/mcpx-extraction.md, steps 4–5, lab-ops-hub container crawler accepts inet_aton IPv4 spellings (127.1, 2130706433, 0x7f.1) — loopback SSRF bypass in validate_crawl_url #468) records the build switch and deletion done 2026-10-19, and this repo now only builds mcpx from the pinned code rev.
Landed since this issue was written, in developing-today/code: the deterministic sibling is no longer CLI-only. execsvc.Options now carries Phases *Phases (pkgs/mcpx/internal/execsvc/execsvc.go, wire struct) with before/prefix/onSuccess/onError/suffix source lines, and the comment records why: "Before Phase 4 fix: a joiner fetches the epoch it missed #192 a remote mcpx exec parsed every one of these and sent none, so the daemon ran a different program from the one asked for." Per-call script hooks over /v1 therefore exist; the script.before/script.onError settings family is still registered for the CLI (internal/settings/registry.go:291,309).
Still unimplemented at code HEAD: the prompt half, which is the issue's actual ask. Options has no prePrompt/postPrompt/onErrorPrompt/onSuccessPrompt fields and no declared prompt-hook list with a declared effect — the fields are Runtime…Export plus the program-shaping group (TypeCheck, Launcher, AllowRepeat, CaptureConsole, Phases), all deterministic source, no natural-language hook anywhere in execsvc or internal/api/ops_exec.go. Prompt hooks also depend on Bump build/buck/preludes/buck2-prelude from d956689 to 52604b1 #110's unsettled question of where a model comes from, so they cannot land before that design does.
No re-homed equivalent of Update module gopkg.in/go-jose/go-jose.v2 to v2.6.3 [SECURITY] - autoclosed #112 exists in developing-today/code; the relocation pass for the Nix Playwright E2E suite fails after vendoring dependencies #176 tree is still owed under mcpx: re-home the open mcpx backlog from dezren39/nix, with this repo as the single source #309, OPEN.

Route: no small_fix packet in dezren39/nix — this repo holds no mcpx source to fix. The remainder (one declared hook list unifying the script Phases vocabulary with prompt hooks, gated on #110) belongs with the source in developing-today/code, referencing #112, via the #309 relocation pass; per the cross-repo rule, do not re-file it there. #112 stays open on the nix side until implemented there or transferred.

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane C
Session / ID: queue task 2825
Found via: queue claim
Task: Triage relocated mcpx lifecycle-hooks issue mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929 — dedupe check, scope confirmation against current pkgs/mcpx main, enqueue implementation follow-up. No implementation in this task.
Expectation: s — done looks like a triage verdict posted here, dedupe checked, and a follow-up packet enqueued (or duplicate/closure with reasons).
Links: queue task 2825

Triage verdict — task 2825 (2026-10-29)

Scope confirmed against current pkgs/mcpx main (verified via gh api on current main, 2026-10-29):

execsvc.Options (pkgs/mcpx/internal/execsvc/execsvc.go, ~:101) still has no hooks or prompt fields — no Hooks, Prompt, PrePrompt, or PostPrompt. The issue's premise holds unchanged.
The shipped deterministic phases are still CLI/config-only: script.before, script.prefix, script.onSuccess, script.onError, script.suffix (pkgs/mcpx/internal/settings/registry.go:291-317), layered through ScriptConfig and not on the wire Options.

Dedupe — not a duplicate. Searched open code issues for mcpx hooks: #1872 (config-declared hooks over the event bus) and #1873 (privileged plugin surface / runtime hook registration) are the sibling scopes #1929 itself names as separate vocabularies — neither covers a per-call hooks list on ExecOptions. Trackers #1885, #1891, #1900 aggregate related work but do not cover this. No closure, no duplicate link needed.

Split, per the issue's own recommendation ("the deterministic half is independently valuable and ships first"):

Approach B (deterministic script hooks) — implementation follow-up enqueued as queue task 3224: one hooks list on execsvc.Options ({phase, script}; phases pre/main/post/onError/onSuccess adopting the shipped script.* semantics), typed hook context (run id, result/error + diagnostic, artifacts), same runtime/permissions as the wrapped script, config layering append/nearest-wins like ScriptConfig.Prefix, and hook frames placed per the docs/exec.md stream-order contract. Verification for the follow-up: pkgs/mcpx: go test ./... via CI, including tests for pre/post/onError execution and frame placement.
Approach C (prompt hooks with declared effects) — stays tracked on this issue, not yet enqueued: it is dependency-gated on the SURFACES hook-vocabulary and effect/dial decision records and on a model source for prompt hooks (tracker mcpx: the AI layer and search -- where a model comes from, and everything that would use one (tracker) #1891; mcpx has no model today, so prompt hooks would degrade to no-ops). Enqueue it once those land; the phase/effect names in this issue are input to those records, not decisions this issue makes.

This issue stays open as the tracker for both halves.

🤖 Agent note · done

Agent: queue worker (repo-worker-code), lane C
Session / ID: queue task 2825
Found via: queue claim
Task: Triage complete — scope confirmed against current pkgs/mcpx main, dedupe checked (not a duplicate; siblings mcpx: config-declared hooks over the event bus, running any command, JS/TS or Python module #1872/mcpx: the privileged plugin surface -- runtime hooks, variables, internal commands, detachment #1873 are distinct scopes), verdict posted above.
Expectation: done — implementation follow-up for Approach B enqueued as queue task 3224; Approach C remains tracked on this issue pending its decision-record and model-source dependencies.
Links: queue task 3224 (follow-up), queue task 2825 (this triage)

agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 30 (priority/none). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03

agent-note:v1
task: 8728
queue: repo-health-code-pilot
worker: repo-worker-code
lane: openchamber-scheduled-lane
lane_id: c29174f1-48e0-4b13-b4ff-9b73ab67e9ab
event: picked_up
at: 2026-11-04T04:04:22Z

Picked up triage task 8728 for #1929. Fresh GitHub state: issue OPEN; no open PR found by searching for #1929; no held/user-owned/do-not-merge/do-not-auto-edit labels. Scope is triage only, no implementation. Verification will use a dedicated worktree based on freshly fetched origin/main eb362463a; the primary clone has diverged local history, so it was preserved rather than rewritten.

Branch: queue/8728-1929-lifecycle-hooks-triage · worktree: /home/user/git/fleet/8728-1929-lifecycle-hooks-triage.

🤖 Agent note · done — triaged and routed (task 8728)

Agent: repo queue worker, OpenChamber scheduled lane c29174f1-48e0-4b13-b4ff-9b73ab67e9ab
Verdict: mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929 remains OPEN. Approach B (deterministic per-call exec hooks) is implemented by merged PR feat(mcpx): per-call script hooks on exec — one hooks list on execsvc.Options (#1929) #2616 (1fb0ae473caf5aedd12f0374be5c0d488808fcde). The prompt-action half is still missing: current execsvc.Hook only accepts scripts, and its implementation explicitly says prompt run/ask effects are not implemented.
Gate revalidated: the configured internal/model.Provider layer and cross-provider profiles are on main (mcpx: thin provider layer core — internal/model, model.* settings, intent routing (#1925 slice 1) #2592, mcpx: provider-keyed model settings and model profiles (#1925 slice 2) #4836), and the accepted hook vocabulary/autonomy decisions (0001/0002) plus settings clamps are implemented. #1925 remains open only for its plugin-provider remainder; that backend is not needed when using an already-configured provider.
Routing: created child issue Implement prompt-action advise hooks for mcpx exec (#1929 Approach C, first slice) #5276 for the first bounded safe slice (prompt action with effect: advise, using data-safe placeholders and deterministic fallback), and enqueued implementation task 9174. The old fix task 3224 for mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929 is already done and owns that issue dedupe key, so the child issue avoids a terminal dedupe hit. Remaining prompt effects and plugin provider are explicitly deferred.
Verification: fresh main/code inspection at eb362463a5d4295d96564563da11f44970763fb1; mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929 open, PR feat(mcpx): per-call script hooks on exec — one hooks list on execsvc.Options (#1929) #2616 merged; no open PR or other active queued/claimed/parked/blocked task for this remainder at triage time.

Navigation Menu

Repository navigation

mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929

Summary

Original notes

Current state (what mcpx does today, with file refs)

Approaches

Approach A — least recommended: five new string options, each handed to a model, each running arbitrary code

Approach B — middle: one `hooks` list, deterministic hooks only

Approach C — recommended: one `hooks` list where a hook is either a script or a prompt, with a declared effect

Open questions

Ease · Impact · Related

Four hook vocabularies, and no issue owns the reconciliation

Three autonomy dials, independently invented

`ClampedBy` is a settings-registry feature with no owner

The exec `Frame` ordering contract is extended by two issues independently

Triage verdict — task 2825 (2026-10-29)

62 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

mcpx: lifecycle hooks on exec — prePrompt/postPrompt/onError as one declared list, script or prompt, with a declared effect #1929

Description

Summary

Original notes

Current state (what mcpx does today, with file refs)

Approaches

Approach A — least recommended: five new string options, each handed to a model, each running arbitrary code

Approach B — middle: one hooks list, deterministic hooks only

Approach C — recommended: one hooks list where a hook is either a script or a prompt, with a declared effect

Open questions

Ease · Impact · Related

Activity

developing-today commented on Oct 28, 2026

dezren39 commented on Oct 28, 2026

Four hook vocabularies, and no issue owns the reconciliation

Three autonomy dials, independently invented

ClampedBy is a settings-registry feature with no owner

The exec Frame ordering contract is extended by two issues independently

dezren39 commented on Oct 29, 2026

dezren39 commented on Oct 29, 2026

Triage verdict — task 2825 (2026-10-29)

dezren39 commented on Oct 29, 2026

62 remaining items

dezren39 commented on Nov 3, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Approach B — middle: one `hooks` list, deterministic hooks only

Approach C — recommended: one `hooks` list where a hook is either a script or a prompt, with a declared effect

`ClampedBy` is a settings-registry feature with no owner

The exec `Frame` ordering contract is extended by two issues independently