完整的參考資料是 Claude Code 的 mod TypeScript 宣告,其中以範例描述每個事件、方法與元素。GitHub 上的副本可能比您安裝的 Claude Code 版本更舊。兩者不一致時,請以 Claude Code 為您的版本寫入的副本為準。
檔案
mod 是包含下列檔案的外掛目錄:register 會接收 on 與 options。options 存放資訊清單所宣告之 userConfig 欄位的值,並已填入預設值。
hook 函式
mod 透過在register 內呼叫 on 來註冊其每個 hook(即事件處理常式)。on 接受事件名稱、選用的 matcher(針對事件欄位的篩選條件),以及 hook 本身,例如 on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))。on 會回傳一個只有一個方法 .catch(handler) 的註冊物件,用來設定 hook 的錯誤處理常式。
事件
事件依其相關內容分組,並列出每個事件的觸發時機,以及其上的 hook 可回傳的內容。turn.step 與 process.spawn 上的 hook 是非同步產生器,其他 hook 則是非同步函式。
每個表格的最後一欄使用簡寫。next(e) 會將事件原封不動地傳遞下去。next({ ...e, text }) 會傳遞變更了指定欄位的副本,例如 next({ ...e, text: e.text.trim() })。物件會在不呼叫 next 的情況下回應事件,而 reason 之類的詞代表您撰寫的字串,例如 { deny: 'Use the file tools.' }。
工具
工具事件在 Claude 發出的每個工具呼叫前後觸發,從 Claude 讀取的說明,到是否執行該呼叫的決定:tool.check 上的 agent 與組織欄位
在 tool.check hook 中,讀取這些欄位即可區分 subagent 的呼叫與主對話的呼叫,並查看您的組織是否要求連接器工具須經核准:
e.agentId:由 subagent 或同程序隊員發出呼叫時設定,由主對話發出時則不存在e.ceiling:對於您的組織設為ask的連接器工具,其值為ask,適用於該設定會傳達至 Claude Code 的工作階段
tool.check 上,e.agentId 與 e.ceiling 需要 Claude Code v2.1.290 或更新版本。
tool.check 上的 e.isReadOnly 欄位
在 tool.check hook 中,當工具回報此呼叫為唯讀時,e.isReadOnly 為 true。否則該欄位不存在,而非 false。此值是工具自身的回報,因此在僅依據此欄位核准呼叫之前,請先閱讀檢查工具呼叫是否為唯讀。
在 tool.check 上,e.isReadOnly 需要 Claude Code v2.1.304 或更新版本。
提示詞與 Claude 讀取的內容
提示詞事件涵蓋使用者輸入的文字,以及 Claude Code 自行傳送給 Claude 的文字,例如系統提示詞與提醒:skill.prompt 上的來源與 frontmatter 欄位
在 skill.prompt hook 中,除了 e.skill 中的 skill 名稱與 e.text 中 Claude 讀取的文字之外,您還可以讀取這些欄位:
hook 可以將變更後的
text 或 frontmatter 傳遞給 next:其後的 hook 會讀取兩者,而 Claude 會讀取最終的 text。變更任何其他欄位的 hook 會失敗。
在 skill.prompt 上,e.source、e.pluginName、e.path、e.frontmatter 與 e.frontmatterProblem 需要 Claude Code v2.1.299 或更新版本。
使用 breakPromptCache 傳送變更後的系統提示詞區段或工具說明
若要在進行中的對話中變更區段或工具說明,請呼叫 $.ui.invalidate('prompt.section') 或 $.ui.invalidate('tool.describe'),讓您的 hook 再次執行。並從該 hook 回傳 { text, breakPromptCache: true } 或 { description, breakPromptCache: true }。若沒有此欄位,對於區段或預先載入的工具,Claude 會持續讀取隨對話儲存的文字,直到新的對話開始或發生壓縮為止。
變更後的文字會在下一個回合傳達給 Claude,且提示快取會重新開始,因此該回合會較慢且成本較高。此欄位需要 Claude Code v2.1.321 或更新版本。從 v2.1.299 到 v2.1.321 之前,進行中的對話會在下一個回合取得變更後的文字。
命令與設定
settings.read 上的 e.layers 與 e.source
e.layers:每個使用中且包含設定的來源各一個{ source, settings }物件,優先順序最低者排在最前。請參閱settings.readhook 接收的內容。e.source:mod 所要求的單一來源,例如$.settings.read({ source: 'policy' })。在 Claude Code 自身的讀取,以及對合併設定的讀取中則不存在
回合
回合事件從頭到尾追蹤一次回答,包括其中每個對模型的請求:工作階段
工作階段事件標示工作階段的開始、結束、壓縮,以及與其他工作階段交換訊息:Subagent
subagent 事件在 subagent 類型提供給 Claude 時,以及 subagent 或 agent team 隊員即將啟動時觸發:
當已完成或已停止的 subagent 即將再次執行時,例如 Claude 使用
SendMessage 工具傳送訊息給它時,您的 agent.spawn hook 也會執行。在該事件上,e.resume 為 { agentId }。若您的 hook 會計算 subagent 數量,請略過設定了 e.resume 的事件,以免恢復的 subagent 被重複計算。
回傳 { deny: reason } 即可拒絕恢復的執行。該執行不會開始,subagent 會維持原狀。當該執行是由 SendMessage 呼叫所要求時,Claude 會讀取 a plugin declined the resume: 後接您的原因,作為該呼叫的結果。若您針對恢復的執行將變更後的事件傳遞給 next,例如不同的 model,Claude Code 會忽略該變更。
恢復執行的事件需要 Claude Code v2.1.299 或更新版本。在 v2.1.299 之前,subagent 恢復時您的
agent.spawn hook 不會執行。在這些版本上,若要拒絕恢復 subagent 的 SendMessage 呼叫,請在 tool.call hook 中比對該工具。介面
介面事件在 Claude Code 繪製轉譯位置時,以及使用者使用 mod 所繪製的控制項時觸發。在介面中繪製說明ui.render hook 回傳的內容:
其他 mod
這些事件讓 mod 能在其他 mod 載入時對其採取行動,例如拒絕某個 mod,或變更它所接收的 mods API:
當其他 mod 的 hook 呼叫您在
engine.create 中新增之命名空間上的方法時,您的方法所發出的 $ 呼叫會在該 hook 的上下文中執行,直到該事件上的每個 hook 都回傳為止。例如,相對路徑會以該 hook 的工作目錄為基準解析,而在回合正等待該 hook 時,$.prompt.submit 會被拒絕。在那之後您的方法所發出的呼叫,則會在您的 mod 自己的上下文中執行。
遙測
遙測事件針對 Claude Code 記錄的使用紀錄觸發:設定 hook 事件
每個設定 hook 事件都是名為classic.<Event> 的事件,例如 classic.Stop 或 classic.PostToolUse。e 是該 hook 的 stdin JSON。
mods API 呼叫
每個 mods API 方法也是一個事件,以其命名空間與方法命名,例如fs.read、model.complete 或 ui.open。其上的 hook 可回傳 next(e)、{ deny: reason } 或 { value }。
其中部分事件也會針對 Claude Code 自身的動作觸發,因此在拒絕某個事件之前,請先檢查 next.origin.plugin 是否為 engine。
Claude Code 自身 http.fetch 請求上的欄位
在 http.fetch hook 中,值為 { plugin: 'engine', tier: 'core' } 的 next.origin 標示 Claude Code 自身的請求之一,例如模型請求,而非 mod 的 $.http.fetch 呼叫。在已載入內建防護的情況下,除非您的 mod 被視為您組織的 mod,否則您的 hook 不會收到這些事件。
在這些事件上,e.init 以及 next(e) 所解析的 value 可能包含下列欄位等:
這些事件與欄位需要 Claude Code v2.1.321 或更新版本。
Mods API 方法
mods API 是每個 hook 接收的$ 引數。其方法依命名空間分組,例如 $.ui。此表依名稱列出每個命名空間的方法,因此 $.ui 列中的 open 即為呼叫 $.ui.open(...)。指南會示範常用方法的用法,而您建置版本的型別則以範例記錄每個方法。
轉譯位置
轉譯位置是 Claude Code 介面中的擴充點。每一列都是ui.render hook 中 e.component 的一個值,並列出 e.props 的欄位以及轉譯它的應用程式。e.surface 指出正在繪製的應用程式,例如 terminal、desktop 或 vscode。變更 Claude Code 既有的繪製內容說明 hook 能在某個位置做什麼,並為每種選擇提供範例。
在 VS Code 擴充功能中進行轉譯,需要擴充功能版本 2.1.299 或更新版本。不擷取功能旗標的工作階段則需要 2.1.304 或更新版本。在 VS Code 擴充功能中繪製列出該擴充功能在繪製上的不同之處。
e.viewport 存放 columns、rows 與 isFullscreen。在終端機與 Desktop 應用程式中,在應用程式量測其視窗之前,它不會存在。在這些環境中,其 rows 是整個視窗的高度,而非您窗格的高度。在 VS Code 擴充功能中,它一律存在。
若要讓樹狀結構符合其位置,請在 hook 中讀取下列 prop:
Pane或橫帶的寬度:依e.props.bodyColumns繪製- 逐字稿旁
Pane的高度:當e.props.placement為'dock'時,e.props.scroll.bodyRows是窗格可供您的樹狀結構使用的列數 - 提示詞上方
Pane的高度:當e.props.placement為'inline'時,窗格會隨您的樹狀結構增高,直到上限為止,而bodyRows即為該上限。若要要求不同的上限,請參閱$.ui.open的rows欄位。
元素
元素是ui.render hook 所回傳樹狀結構的建構區塊,您可以從 $.ui.resolve(e) 取得。從元素建立樹狀結構會展示常用元素以及終端機如何繪製它們,介面圖庫則提供大多數元素的螢幕截圖。勾號表示該應用程式可以繪製此元素。
更多
Button 規則:
action:指定 Claude Code 本身的某個快捷鍵動作,當使用者對該動作的綁定為組合鍵或修飾鍵時,該綁定會按下此按鈕- 橫帶上的數字 hotkey:橫帶中按鈕上的數字
hotkey,在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發 - 收合的橫帶:當橫帶處於收合狀態時,
action綁定和 hotkey 都不會按下其中的按鈕 - 兩個按鈕使用同一個 hotkey:當同一次繪製中有兩個您的按鈕指定相同的
hotkey時,由後者取得。若是其他 mod 的按鈕使用同一個按鍵,請參閱 Hotkey 沒有作用。 variant:primary或secondary,其他任何值都會拋出錯誤。在終端機中,primary按鈕會以強調色繪製,除非它是plain。role:dismiss將按鈕標記為關閉按鈕,其他任何值都會拋出錯誤。請在您的onPress中執行關閉動作。在包含文字和一列按鈕的橫帶中,Desktop 應用程式可以將該列的第一個dismiss按鈕繪製為其專屬的關閉控制項。終端機則會以如同未設定role的方式繪製該按鈕。
Button 可以用 children 取代 label:
- children 可以是什麼:字串和
Text元素,例如名稱後接淡色的細節,或是彩色標籤。Claude Code 會拒絕Button內的其他任何元素。 - 為按鈕命名:
label為按鈕命名,預設為其 children 的文字。若按鈕的 children 不是單一字串,請為其指定key或label。 - 在終端機中:children 會繪製在 label 原本的位置,在其上任何位置按下都算作一次按下,因此您可以將清單的每一列做成單一按鈕
- 在 Desktop 應用程式和 VS Code 擴充功能中:按鈕會繪製其
label
children 不是單一字串的
Button 需要 Claude Code v2.1.295 或更新版本。autoFocus 在任何控制項上都只接受 true,因此若要關閉,請省略此 prop。
VS Code 擴充功能會忽略部分元素 prop,並以如同您省略這些 prop 的方式繪製元素:
Box:position及其top、left、right和bottom、alignSelf、borderDimColor和hoverText:size、mono、tabular和hoverButton:hotkey、plain、autoFocus、action和hover,因此使用者在該處要透過點擊按下按鈕,或在按鈕取得焦點後按 Enter。擴充功能也會忽略variant和role。Code:language、path、startLine、format和wrap,因此程式碼繪製時不會有色彩或行號,而format: 'diff'區塊會顯示差異的原始文字Input和Select:autoFocus,以及Input上的rowsSvg:isInteractive
Box 框線樣式
若要在 Box 周圍繪製框線,請將其 borderStyle 設為下列其中一個名稱,例如 borderStyle: 'round'。每一列說明終端機針對該名稱所繪製的內容,並顯示框線的上緣。
若
Box 的 borderStyle 指定為其他任何名稱,例如 'rounded',則繪製時不會有框線。
Box 間距級距
Box 的間距 prop 包括 gap、columnGap、rowGap、padding、margin,以及 padding 和 margin 的單側與單軸形式,例如 paddingX 和 marginTop。每個 prop 都接受以終端機儲存格為單位的數字,例如 gap: 1,或是級距名稱,例如 gap: 'md'。在終端機和 VS Code 擴充功能中,每個級距對應的儲存格數如下:
若您將
gap、padding 或 margin 設為某個級距,該級距會同時套用於橫向與縱向。例如,在終端機和 VS Code 擴充功能中,padding: 'md' 表示左右兩側各兩個儲存格,上下各一列。
級距名稱需要 Claude Code v2.1.299 或更新版本。在較早的版本中,使用級距名稱的樹狀結構不會繪製。
Text 字體排版 prop
在 Text 上設定 size、weight、mono 或 tabular,即可要求繪製您樹狀結構的應用程式使用特定文字大小、字重、等寬字體或等寬數字。在依賴某個 prop 之前,請先確認終端機和 VS Code 擴充功能如何處理它。若應用程式忽略您設定的 prop,您的樹狀結構仍會在該處繪製,文字則如同您省略該 prop 一樣。
這四個 prop 需要 Claude Code v2.1.299 或更新版本。在較早的版本中,設定了
size、weight、mono 或 tabular 的樹狀結構不會繪製。
以 weight 取代 bold
Text 上的 bold 已棄用,改用 weight,但仍可正常運作。若要在未設定 weight 的 Text 上取代它,請將 bold: true 改為 weight: 'semibold',即可在 Claude Code v2.1.299 或更新版本上獲得相同結果。
在早於 v2.1.299 的版本中,設定了 weight 的樹狀結構不會繪製。若您在 Text 上同時設定 bold 和 weight,則 bold 不會有任何作用。
限制
hook 與 mods API 呼叫都在時間與大小限制下執行。Claude Code 會略過超過時間限制的 hook。超過巢狀層數、元素數、Raster 儲存格數或 Image 位元組數限制的樹狀結構不會被繪製。
設定與環境變數
以下是影響 mod 的設定與環境變數。「位置」欄說明每一項是從哪個設定檔或環境讀取:sec-default@builtin 是內建於 Claude Code 的防護,在 /plugin 與偵錯日誌中列為 cc-plugin-sec-default。在它載入的情況下,它會在使用者安裝的每個 mod 之前執行。若設定了受管 prependPlugins,則只有在該清單列出此防護時才會載入,並位於所列的位置。
其原始碼位於 Claude Code 儲存庫的 mods/sec-default 目錄。
命令
這些命令與旗標用於載入、檢查與測試 mod。claude 命令在您的 shell 中執行,/ 命令則在 Claude Code 提示詞輸入處執行。表格中的 <directory> 代表您輸入的路徑,例如 claude plugin validate ./first-mod。方括號表示選用的引數。