Muse Code hooks: where they live in the 0.2.1 beta, and the ACP plugin built on them
Muse Code, Meta Superintelligence Labs’ terminal coding agent, has been in beta since August 5. It now has an ACP plugin: @agenticcontrolplane/muse-code (npm). Once it’s installed, every tool call Muse Code makes is checked against your ACP workspace before it runs.
Building it meant answering a question the docs don’t: where are Muse Code’s hooks? The documented interface and the shipped binary disagree.
The documented CLI isn’t in the binary
Meta’s docs describe a muse hooks CLI (list, validate, trust, run --fixture) and a .muse/hooks.json file for registering hooks. We installed the current beta (0.2.1) and tried it:
$ muse hooks list
invalid TUI options: unknown argument `hooks`
A project .muse/hooks.json is ignored with no error. The docs are ahead of the binary. That is normal for a beta, but you can’t build a control layer on a door that doesn’t open, so we kept looking.
Where the hooks live
The hook engine is in the binary. The lifecycle events (PreToolUse, PermissionRequest, PostToolUse, Stop and the rest) and the decision words are visible in it. Only the management CLI is missing. So what does register a hook? The binary ships a built-in plugin-authoring skill, and inside it a file named native-plugin-contract.md, Meta’s own spec for the interface that is wired up. Hooks are capabilities of a native plugin, behind an experimental flag:
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins install ./my-plugin --scope user
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins approve my-plugin
A plugin is a directory with a .muse-plugin/plugin.json manifest. Each hook names a lifecycle event and a command to run. The flag gates only the install and approve commands. Once a plugin is approved, its hooks fire in ordinary sessions with no flag set.
The wire format is Claude Code’s
This is why the integration was quick. We drove a probe hook through Muse’s own capability runner and read back what it accepts, field by field. It is Claude Code’s hook schema:
- Payload in (snake_case JSON on stdin):
hook_event_name,tool_name,tool_input,session_id,permission_mode,cwd. - Decision out: a
hookSpecificOutputobject withpermissionDecision(allow/ask/deny) andpermissionDecisionReason. A bare{}means allow.PostToolUseblocks with{ "decision": "block", "reason": … }. Exit code 2 plus stderr is the fallback block channel. An unknown output key fails the hook run, so the parser tells you exactly what it takes.
If you have written a Claude Code hook, you have written a Muse Code hook. That is a gift to anyone building tooling across harnesses, and it is why our plugin is small.
What the ACP plugin does
The plugin is one file with no dependencies, plus a four-line entry stub per event (Muse wants a separate source file per hook). Each Muse event maps to one ACP call:
| Muse event | ACP endpoint | What happens |
|---|---|---|
PreToolUse |
POST /govern/tool-use |
allow / ask / deny before the tool runs |
PermissionRequest |
POST /govern/tool-use |
a policy deny settles Muse’s own approval prompt; anything else leaves the prompt alone |
PostToolUse |
POST /govern/tool-output |
output scanning; a block from the gateway becomes feedback the model sees |
Stop |
none | one session receipt with a link to the session timeline |
- An ask is a block on Muse Code. Only Claude Code shows an ACP hold inline. On Muse Code, a call that policy says to ask about is blocked, waits on the Approvals page and in the approval email, and runs when you approve it and ask Muse to retry. The coverage table says how this works on each harness.
- A new workspace starts in audit mode. Every call is recorded and the safety floor applies (a force-push waits for your approval;
rm -rf /is always denied), but your own rules don’t block until you turn enforce on.
We checked each path with Muse Code’s own muse plugins hook test runner driving our plugin against the production gateway: an rm -rf / comes back denied with the floor’s reason attached, a plain file read passes, a PermissionRequest that policy denies is settled. One caveat: that runner replays fixtures. As of launch we had not watched a live model session’s ask round-trip, because the beta’s offline provider makes no tool calls.
Muse runs hooks with a cleared environment. That is a sound hardening choice. It also means an ACP_BEARER_TOKEN you export never reaches the hook. The plugin reads its credential from ~/.acp/credentials (written once by the installer) and takes overrides from ~/.acp/config.json. The no-dependencies rule comes from the same fact: a hook runs outside Muse’s sandbox with your credential nearby, so it should be one file you can read in a few minutes.
If the gateway can’t be reached, an interactive session proceeds with a loud [ACP] ⚠ UNGOVERNED warning and a line in ~/.acp/lapse.log. An unattended run (CI, headless, or agent_tier set to background) stays blocked. A policy deny is enforced either way.
Where Muse Code lands on the coverage table
(The living version of the table is at /coverage.)
Muse Code routes every tool call through one hook pipeline, so the pre-call check sees everything. A PostToolUse block becomes feedback the model reads, so the plugin can act on output rather than only log it. That puts it with Claude Code, dsh, pi and Prime Agent in the column where a result can be changed before the model sees it. The gap is the one above: a hold is a block you approve on the console, not a prompt in the session.
Credit here goes to Meta. Muse Code ships with an OS sandbox and approvals on from the first run, an LLM approval judge, and a hook engine that borrowed the right contract. The docs just haven’t caught up to it yet.
Install
npm install -g @agenticcontrolplane/muse-code
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins install "$(npm root -g)/@agenticcontrolplane/muse-code" --scope user
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins approve acp
The full guide, including the credential path and config overrides, is at /integrations/muse-code. What Muse Code ships on its own (approval modes, the judge, the sandbox, and where the docs run ahead of the binary) is at /controls/muse-code.
Muse Code is days into a beta that promises breaking changes. Treat the plugin the same way: early, tested against the harness’s own runtime, tracking a fast-moving target. Re-check the install command after each Muse Code update.
Running Muse Code? One command adds a hook. Each tool call it sees is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex
What the installer writes · Muse Code guide · free up to 5 agents