mods
Claude Code mod capabilities and limits for developing construct. Use when designing or changing a construct feature, a hook, the band, routing, a command, or a gate, to decide whether a mod (hooks/register.js), a settings hook (hooks/scripts/*.mjs), a skill, or an MCP server is the right mechanism.
- License 许可
- MIT
- 最近更新
- 2026-10-30
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- mods
- description
- Claude Code mod capabilities and limits for developing construct. Use when designing or changing a construct feature, a hook, the band, routing, a command, or a gate, to decide whether a mod (hooks/register.js), a settings hook (hooks/scripts/*.mjs), a skill, or an MCP server is the right mechanism.
03 SKILL.md 正文
Mods in construct
Source: https://code.claude.com/docs/en/plugins/mods/overview (read 2026-10-23). Re-read the linked page before relying on a detail that may have changed; the docs win over this file.
A mod is plugin code (JS/TS) that Claude Code runs in its own process. register(on) registers handlers ("hooks") for events. Settings hooks (our hooks/scripts/*.mjs, exec form in hooks.json) are external processes; the docs call those "settings hooks".
What only a mod can do
- Draw UI: a pane beside the transcript or a band above the prompt, with tabs, buttons, text fields. → interface
- Restyle Claude Code's own UI: tool-call rows, spinner, the question dialog. Never the permission prompt.
- Step into a tool call or request: hold it while asking the user, answer it without running the tool, send one request to another model. → events
/commandthat runs a function at once, with no Claude turn, even while Claude works. → api- Share state between hooks through module variables (one hook records, another shows).
Handler semantics
Each handler runs before Claude Code acts and receives ($, e, next):
- Observe:
return next(e). - Rewrite:
return next({ ...e, ...changes }). - Answer: return a result without calling
next; the default behavior does not run.
Anything outside the handler's own code (draw, command, model call, file read, process, network) goes through $ (the mods API). That is why claude plugin validate can list a mod's hooks: and calls: without running it; check that output after adding a new $ call.
Where it runs (matters for evals and tests)
| Host | Hooks run | Drawing shows |
|---|---|---|
claude terminal, JetBrains |
yes | yes |
| Desktop Code tab (not WSL) | yes | yes, except terminal-only elements |
| VS Code panel | yes | yes, extension ≥ 2.1.299 (≥ 2.1.304 without feature-flag fetch, e.g. Bedrock) |
claude -p, Agent SDK |
yes | no |
| Remote Control | yes, on the local machine | local terminal only |
| Cloud session | yes, if the plugin reaches it | no |
Consequences for construct:
scripts/eval.shrunsclaude -p: routing hooks fire, the band never draws. Test band behavior withclaude plugin test plugins/construct, not evals. → test- A drawing feature needs a fallback (a transcript line or a command's text reply) where nothing draws.
- Minimum versions: terminal v2.1.287, Desktop v2.1.286. Keep
MIN_CLAUDEinhooks/status/consistent with any new API used.
What turns a mod off
disableAllHooks: true,--safe-mode,--bare, and an org'sallowManagedModsOnlystop the mod but leave the plugin's skills, agents, commands, and MCP servers loaded. Agent frontmatter is construct's fallback for routing; any new mod feature needs an equivalent "mod absent" behavior.CLAUDE_CODE_ENABLE_FUNCTION_HOOKSis ignored from v2.1.287.- Built-in mods (
cc-plugin-sec-default,cc-plugin-diff, ...) are not stopped by those flags.cc-plugin-sec-defaultruns first and can skip later handlers for an event. - Check what loaded:
/pluginshowsN mod active · <names>. → troubleshoot
Trust and permission limits
- Mods are not sandboxed: they run as the user (files, processes, network, env secrets, every prompt and tool call, model usage).
- A mod can approve a tool call before the user is asked. With managed settings or a Team/Enterprise login, that approval does not pass
askrules orPreToolUsehooks by default; without them it can. Never rely on a mod approval to get past construct's own gates, and never use one to skip a gate. → permissions precedence - The publication gate, surface guard, and command guard stay settings hooks: they must also work when mods are disabled.
Choosing the mechanism
| Need | Use |
|---|---|
Pane, band, spinner/tool-row restyle, instant /command, rewriting an event, per-role model/effort routing |
Mod (hooks/register.js) |
Block, allow, or log an event with a script; also usable as a git hook or from the CLI (pre-push.mjs) |
Settings hook (hooks/scripts/) |
| Instructions Claude should follow | Skill |
| Claude needs to reach an external system | MCP server |
disableAllHooks stops settings hooks too; see what runs under allowManagedHooksOnly before claiming a mechanism survives a setting.
What construct already uses
hooks/register.js handles session.start, turn.start, turn.step, turn.complete, tool.call, tool.check, agent.spawn, command.run (/construct), and ui.render (AbovePrompt, the band; it composes with await next(e) so other mods keep their rows). It calls $.ui.invalidate, $.command.register, $.process.run, $.fs.list/read, $.session.*, $.clock.now. The band must not repeat what a user's status line already shows (model, effort, branch, diff, context, plan limits). Unused capabilities worth considering before adding a settings hook or more prompt text: spinner/tool-row restyle, holding a tool call for a user question, answering a tool call directly, and model calls from a hook.
References
- Reference (events, methods, elements, limits): https://code.claude.com/docs/en/plugins/mods/reference.md
- Create: https://code.claude.com/docs/en/plugins/mods/create.md
- Admin and policy mods: https://code.claude.com/docs/en/plugins/mods/admin.md
- Built-in mod sources (
diff,agents-md,sec-default,telemetry): https://github.com/anthropics/claude-code/tree/main/mods - Samples (
token-weather,blast-radius,replay-theater): https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods
04 同仓库更多 Skills
workflow
The ADD protocol for every implementation request, feature plan, resume, task sizing, and the closing Risk line.
sources
Ground version-dependent code in official documentation. Use when you name a specific uncertainty about a library or framework API, a version-dependent pattern, or a deprecation. Skip when the repository already shows the pattern.
review
Mandatory outside review of high-risk work units, by lens agents the hooks feed and record, plus the dual blind review on request. Trigger: a unit whose Risk names an item is ready to publish, the publication gate denied a push, PR, or release, or the user asks for a review, a dual review, or an adversarial review.
migration
Plan and verify risky migrations and removals. Use when changing a schema or stored data, removing or renaming a public API, flag, config format, or export, replacing a system, or when the task's Risk names item 1 or 3.
delivery
Plan commits, branches, and pull requests as reviewable units. Use when deciding commit contents, opening or preparing a PR, splitting large work into sub-branches of a feature branch, or preparing a release.
delegation
When and how the ADD orchestrator delegates to construct agents: role mapping, allowed edit surfaces, parallel writers, verifier timing, handoff prompts, and relaying a subagent's blocking question or choice menu. Trigger: deciding to delegate, launching an agent, writing a handoff, or a subagent or tool returns a question, menu, or consent request.