Claude Code mods spec

flowchart TB
  host["Where the session runs"]
  term["Terminal, editor terminal, JetBrains: hooks yes, drawing yes"]
  desk["Desktop Code tab except WSL: hooks yes, drawing yes except terminal-only"]
  wsl["Desktop WSL: hooks no, drawing no"]
  vsc["VS Code extension chat: hooks yes, drawing no"]
  pipe["claude -p and Agent SDK: hooks yes, drawing no"]
  remote["Remote Control: hooks on your machine, drawing in that terminal"]
  cloud["Cloud: hooks if a plugin reaches the session, drawing no"]
  host --> term
  host --> desk
  host --> wsl
  host --> vsc
  host --> pipe
  host --> remote
  host --> cloud

flowchart TB
  loaded["Once loaded, the mod runs as you"]
  files["Read and write files"]
  proc["Start processes"]
  net["Make network requests"]
  secrets["Read secrets in env and settings, including an API key"]
  see["See every prompt and tool call"]
  rewrite["Rewrite a prompt or tool call, submit a prompt, or message another session"]
  approve["Approve a tool call before you are asked"]
  spend["Spend usage"]
  loaded --> files
  loaded --> proc
  loaded --> net
  loaded --> secrets
  loaded --> see
  loaded --> rewrite
  loaded --> approve
  loaded --> spend

flowchart TB
  face["Interface"]
  much["Much of the interface can be restyled"]
  ask["AskUserQuestion is a render site"]
  perm["The permission prompt is not, and a mod cannot change what it shows"]
  face --> much
  face --> ask
  face --> perm

flowchart LR
  handler["Handler receives the mods API, e, and next"]
  watch["next of e: watch"]
  rewrite["next with a changed field: rewrite"]
  answer["Return without next: answer and short-circuit"]
  handler --> watch
  handler --> rewrite
  handler --> answer

sequenceDiagram
  participant Managed as Managed PreToolUse
  participant Mod
  participant Other as Other PreToolUse
  participant Perm as Permission check
  participant Tool
  Managed->>Mod: Runs before the first tool.call. A block is final
  alt Return without next
    Mod-->>Mod: Answer. Later PreToolUse hooks do not run
  else next of e
    Mod->>Other: Other PreToolUse after the last next
    Other->>Perm: Permission check
    Perm->>Tool: Then the tool
  end

flowchart LR
  dev["Person who trusts the author"]
  goal["See a tool-call count on the spinner"]
  mod["Handler on tool.call and ui.render"]
  dev --> goal
  goal --> mod

flowchart LR
  settings["Settings-file hook"]
  modh["Mod handler, called a hook on these pages"]
  both["Both are called"]
  settings --> both
  modh --> both

flowchart LR
  watch["tool.call calls next of e and counts"]
  match["ui.render matcher component Spinner"]
  rewrite["next with props.suffix changed"]
  watch --> match
  match --> rewrite

flowchart TB
  deny["A deny rule refuses the call"]
  guard["The built-in guard is loaded"]
  unset["allowModsToOverrideDenyRules is unset"]
  noApprove["A user mod cannot approve that call"]
  allow["Set true: a user mod can approve a denied call"]
  deny --> guard
  guard --> unset
  unset --> noApprove
  guard --> allow

flowchart LR
  rules["Deny rules and managed PreToolUse"]
  toolCall["They can stop a tool call"]
  ownCalls["They do not apply to the mod own fs and process calls"]
  rules -->|"apply"| toolCall
  rules -->|"do not apply"| ownCalls

flowchart LR
  crash["Hooks worker crashes three times"]
  unload["Unload every non-built-in mod"]
  back["Until reload-plugins or a new session"]
  crash --> unload
  unload --> back

flowchart TB
  sec["1 sec-default at builtin, where it loads"]
  pre["1 then prependPlugins"]
  org["1 then other organisation mods not in appendPlugins"]
  user["2 Mods you install"]
  app["3 appendPlugins"]
  builtin["4 Other built-in mods"]
  sec --> pre
  pre --> org
  org --> user
  user --> app
  app --> builtin

stateDiagram-v2
  [*] --> Running
  Running --> Skipped: no catch, and throw, timeout, or wrong shape before next
  Running --> Stands: the same failure after next has resolved
  Running --> Unloaded: hooks worker crashes three times
  Unloaded --> Back: reload-plugins or a new session

stateDiagram-v2
  [*] --> Check
  Check --> Refused: return refuse with a reason
  Check --> Loads: check passes
  Check --> LoadsOpen: throw or timeout with no catch fails open

flowchart TB
  brought["Who brought the mod"]
  yours["Counts as yours"]
  orgmod["Organisation mod"]
  blocked["allowManagedModsOnly: a user-brought mod does not load"]
  still["Organisation mods still load"]
  brought --> yours
  brought --> orgmod
  yours --> blocked
  orgmod --> still

flowchart TB
  test["Counts as organisation-owned only when all three hold"]
  en["managed enabledPlugins sets it true"]
  dir["Marketplace named as a directory by absolute path"]
  rel["Plugin listed by a relative path, so it loads in place"]
  cache["Cache copy from GitHub, git, URL, or npm"]
  userCopy["Counts as a user mod even if enabledPlugins enables it"]
  test --> en
  test --> dir
  test --> rel
  cache --> userCopy

flowchart TB
  machine["This machine"]
  managed["Has managed settings: guard loads"]
  team["Signed in with Team or Enterprise: guard loads"]
  apikey["API key, Bedrock, Agent Platform, or Foundry: guard only with managed settings"]
  unread["Guard cannot read managed settings"]
  refuseMods["Refuses every user mod"]
  unchecked["Cannot check deny rules for a call a user mod approved"]
  refuseCall["Refuses that call"]
  machine --> managed
  machine --> team
  machine --> apikey
  unread --> refuseMods
  unchecked --> refuseCall

flowchart TB
  ev["Events named in the fetched pages"]
  ev --> tool["tool"]
  ev --> prompt["prompt, skill.prompt, attribution.text"]
  ev --> turn["turn and session"]
  ev --> ui["ui"]
  ev --> other["command, config, agent"]
  ev --> meta["plugin.register, engine.create, telemetry"]
  ev --> classic["classic dot name. Full list not fetched"]
  ev --> api["namespace.method for each mods API method"]

flowchart TB
  sites["Render sites not marked terminal-only"]
  sites --> pane["Pane"]
  sites --> above["AbovePrompt"]
  sites --> user["UserMessage"]
  sites --> asst["AssistantMessage"]
  sites --> use["ToolUse"]
  sites --> result["ToolResult"]
  sites --> group["ToolGroup"]
  sites --> cmd["CommandOutput"]
  sites --> ask["AskUserQuestion"]
  sites --> spin["Spinner"]
  sites --> mode["SessionMode"]
  sites --> hint["PromptHint"]

flowchart TB
  termOnly["Marked terminal-only"]
  termOnly --> prog["ToolProgress"]
  termOnly --> dur["TurnDuration"]
  termOnly --> info["InfoNotice"]
  termOnly --> raster["Raster"]
  termOnly --> image["Image"]
  deskOnly["Desktop only"]
  deskOnly --> svg["Svg"]

flowchart TB
  root["Plugin directory"]
  manifest[".claude-plugin/plugin.json"]
  hooks["hooks/hooks.json modules array"]
  reg["exports register of on and options"]
  esm["ES module, no Node bundler, no require"]
  root --> manifest
  root --> hooks
  hooks --> reg
  reg --> esm

stateDiagram-v2
  [*] --> Written: Claude writes under dev-mods for that session
  Written --> ThisSession: you approve hot reload
  ThisSession --> Removed: folder older than cleanupPeriodDays

sequenceDiagram
  participant You
  participant Validate as claude plugin validate
  participant Test as claude plugin test
  You->>Validate: Point it at the directory
  Note over Validate: Does not run the code
  Validate-->>You: Hooks and calls it can read
  You->>Test: Run tests
  Note over Test: One test is 5 seconds unless timeoutMs

flowchart TB
  gaps["Labelled unverified or incomplete"]
  gaps --> classic["classic star list not fetched"]
  gaps --> page["allowManagedHooksOnly page not fetched"]
  gaps --> days["cleanupPeriodDays has no number here"]
  gaps --> guard["Guard hooked event names not given"]
  gaps --> readme["Sample READMEs not fetched"]
  gaps --> shape["Several UI events have no return shape"]
  gaps --> sel["selection is not in the method list"]

flowchart TB
  src["This edition"]
  docs["Mods docs fetched 4 October 2026"]
  chg["Changelog 2.1.287 and top section 2.1.288"]
  old["June 2026 what is new, older than mods"]
  yt["YouTube offered. Transcript not used"]
  src --> docs
  src --> chg
  src --> old
  src -->|"not a source"| yt