docs(mods): the mod host, its trust and what it serves

docs/GUIDE.md

@@ -149,6 +149,10 @@ allow = ["Bash(go test:*)"]                  # never prompted
 # max_dispatched_sessions = 8  # sessions one session may keep open from its dispatches; 0 removes the ceiling (user config only)
 # release_projects = []        # projects that take messages from your other sessions without the card; their own approvals and sandbox still apply (user config only)
 
+[mods]
+# enabled = false              # run the hooks module of installed Claude Code mods; full trust, no sandbox (user config only)
+# hook_budget_ms = 0           # one hook's own running time in milliseconds; 0 keeps 10000 (user config only)
+
 [serve]
 # auth_mode = "token"          # token (default)|password|none; none still requires the launch token for changes
 # token = ""                   # optional fixed token; empty token mode generates one at startup

docs/GUIDE.zh-CN.md

@@ -158,6 +158,10 @@ allow = ["Bash(go test:*)"]                  # 从不询问
 # max_dispatched_sessions = 8  # 一个会话通过派发最多同时开着几个会话；0 表示不限（只认用户级配置）
 # release_projects = []        # 这些项目收到你其它会话的消息时不弹批准卡；它们自己的审批与沙盒照旧（只认用户级配置）
 
+[mods]
+# enabled = false              # 运行已安装 Claude Code mod 的钩子模块；完全信任、不在沙盒内（只认用户级配置）
+# hook_budget_ms = 0           # 单个钩子自身的运行时限，毫秒；0 保持 10000（只认用户级配置）
+
 [serve]
 # auth_mode = "token"          # token(默认)|password|none；none 下修改与审批仍需启动令牌
 # token = ""                   # 可选固定 token；token 模式为空时启动时自动生成

docs/PLUGIN_PACKAGES.md

@@ -704,6 +704,67 @@ Plugin hooks receive these environment variables:
 - `CLAUDE_PROJECT_DIR`
 - `CLAUDE_PLUGIN_ROOT`
 
+## Claude Code mods
+
+A Claude Code mod is a plugin whose `hooks/hooks.json` names one ES module
+(`"modules": ["./register.js"]`) that exports `register(on, options)`.
+Reasonix installs it like any Claude plugin.
+
+The module runs only while **Run Claude Code mods** is on, in Settings or as
+`[mods] enabled = true` in the user file. It is off by default, and a project
+file cannot turn it on.
+
+A mod is **full trust**:
+
+- Its module runs on this machine as you, outside the sandbox.
+- It can read files, start processes and use the network.
+- The install preview says so and lists the module's events and `$` calls from
+  its syntax tree.
+- That listing is an aid, not a guarantee. Code the module imports, and names it
+  builds at run time, are not listed, and the preview shows them as such.
+
+How it runs:
+
+- The host script runs under Studio's own binary in Node mode, or under the
+  `node` on `PATH` for the terminal and `serve`. Node 22 or newer is required,
+  and a `node` inside the open project is never used.
+- `.js .mjs .cjs` modules run everywhere. `.ts .mts .cts` run where the runtime
+  strips types. `.jsx` and `.tsx` do not run.
+- The process is a tighten-only extension runtime. A mod can deny a call or ask
+  the user about it. The host refuses an `allow`, or a rewrite of a permission
+  decision, whatever the process writes.
+- A hook gets `[mods] hook_budget_ms` of its own running time, 10 s by default.
+  A hook stuck in a loop ends the process and the turn goes on without it.
+- The process restarts at the next reload. After three deaths the mod is
+  disabled, and its status says why.
+- Nothing a mod does changes the cached system prompt or the tool list. Its text
+  reaches the model only as data from the mod.
+
+Events served:
+
+- `tool.call`: `{ deny }` and argument rewrite. A `{ result }` answer is reported
+  to the model as the reason the call was answered in place of the tool.
+- `tool.check`: `deny` and `ask`. An `allow` is ignored.
+- `prompt.submit`: text rewrite and `{ drop }`.
+- `session.start`, `session.end`, `turn.start`, `command.run`, `ui.press`.
+- `ui.render` for the `AbovePrompt` band.
+
+`$` served:
+
+- `plugin`, `store`, `clock`, `env.get`, `fs`, `process.run`, `http.fetch`.
+- `state`, with `atom`, `read`, `update`, `derive` and `memberOf` imported from
+  `claude-code`.
+- `session.id`, `session.cwd`, `session.root`.
+- `tool.register/call/list` and `command.register/run/list`. Both register
+  while `session.start` runs.
+- `ui.toast`, `status`, `notice`, `log`, `ask`, `resolve`, `invalidate`.
+
+Anything else is registered and named in the mod's status as unserved. A call to
+an unserved `$` member rejects with the typed code `mod.unsupported`.
+
+`$.ui.ask` is a question from the mod, shown with its name. It can never approve
+a tool call or a permission.
+
 ## Studio HTTP routes
 
 Studio drives plugin packages through these kernel routes:

release-notes/studio/unreleased/mod-host.md

@@ -0,0 +1,2 @@
+- 新增：设置里的“运行 Claude Code mod”（默认关）让已安装 mod 的钩子模块运行：可拒绝或确认工具调用、改写提问、在输入框上方画一条状态带。完全信任，见 #13694。
+- Added: the "Run Claude Code mods" switch (off by default) runs an installed mod's hooks module: deny or confirm tool calls, rewrite prompts, draw a band above the composer. Full trust. See #13694.