工作階段通道

ahp-session:/<uuid> 通道的參考資料 — 每個工作階段的狀態、回合生命週期、工具呼叫狀態機、附件、待處理訊息、輸入請求，以及每個工作階段的自訂項目。線路層級的概觀請參閱工作階段通道規格。

JSON Schema: state.schema.json

狀態類型

SessionLifecycle

工作階段初始化狀態。

成員	值
Creating	'creating'
Ready	'ready'
CreationFailed	'creationFailed'

SessionStatus

摘要層級工作階段狀態旗標的位元集。

對非終結活動使用位元檢查而非相等性檢查。例如， status & SessionStatus.InProgress 同時比對普通的進行中回合與 暫停等待輸入的回合。

成員	值	說明
Idle	1	工作階段閒置 — 沒有進行中的回合。
Error	1 << 1	工作階段以錯誤結束。
InProgress	1 << 3	回合正在串流。
InputNeeded	(1 << 3) | (1 << 4)	回合進行中但因等待使用者輸入或工具確認而阻塞。
IsRead	1 << 5	用戶端自上次修改後已檢視此工作階段。
IsArchived	1 << 6	工作階段已被用戶端封存。

SessionMetadata

完整 {@link SessionState}（當用戶端訂閱工作階段 URI 時傳遞）與輕量級 {@link SessionSummary}（承載於根通道工作階段目錄中）之間共用的中繼 資料。

這些欄位一覽地描述工作階段，且同時出現於兩處。 SessionState 擁有已訂閱工作階段的權威值； SessionSummary 將其鏡射至目錄中，讓僅呈現工作階段清單的用戶端不必 訂閱每個工作階段 URI。主機透過 root/sessionSummaryChanged 保持目錄 同步。

欄位	類型	必要	說明
provider	string	是	代理程式提供者 ID
title	string	是	工作階段標題
status	SessionStatus	是	目前工作階段狀態
activity	string	否	工作階段目前正在做什麼的人類可讀描述
project	ProjectInfo	否	此工作階段的伺服器擁有專案
workingDirectories	URI[]	否	工作階段代理程式具有工具存取權的工作目錄，由 session/workingDirectorySet / session/workingDirectoryRemoved 操作 維護。目錄為平等的同儕 — 工作階段沒有主要目錄。個別聊天 MAY 透過 {@link ChatSummary.workingDirectories | 其自身的 workingDirectories} 限制為子集，並將其自身的某個目錄指定為主要目錄（見 {@link ChatState.primaryWorkingDirectory}）；未設定子集的聊天會對此完整集合運作。
annotations	AnnotationsSummary	否	此工作階段內嵌註解通道（ahp-session:/<uuid>/annotations）的 輕量級摘要。公開以便徽章 UI 無需訂閱即可呈現註解/項目計數。 當工作階段未公開註解通道時不存在。

SessionState

單一工作階段的完整狀態，當用戶端訂閱工作階段 URI 時載入。

將每個 {@link SessionMetadata} 欄位直接內嵌（反正規化）至自身，讓 訂閱者收到一個扁平物件而非巢狀摘要。輕量級目錄表示法為 {@link SessionSummary}，公開於根通道；主機透過 root/sessionSummaryChanged 保持兩者同步。

欄位	類型	必要	說明
lifecycle	SessionLifecycle	是	工作階段初始化狀態
creationError	ErrorInfo	否	建立失敗時的錯誤詳細資訊
serverTools	ToolDefinition[]	否	伺服器（代理主機）為此工作階段提供的工具
activeClients	SessionActiveClient[]	是	目前為此工作階段提供工具與互動能力的用戶端。若同一作用中用戶端 提供多個工具或自訂，代理主機 MAY 在公開給模型時對其去重，並優先 採用起始回合的用戶端。 成員資格由主機管理：用戶端以 session/activeClientSet 新增（或重新 整理）自身，且主機在其取消訂閱、未及時重新連線的斷線，或重新連線 但未重新訂閱工作階段時，以 session/activeClientRemoved 移除它們。
chats	ChatSummary[]	是	此工作階段中的聊天目錄。
defaultChat	URI	否	當使用者在不選取特定聊天的情況下對工作階段發話時，接收輸入的 聊天。這是 UI 路由提示，而非階層標記 — 在協定層級聊天仍是平等的 同儕。主機 MAY 在工作階段生命週期中變更此值。
config	SessionConfigState	否	工作階段設定綱要與目前值
customizations	Customization[]	否	此工作階段中作用中的頂層自訂。 永遠是 {@link Customization} 變體之一： - 容器自訂（{@link PluginCustomization}、 {@link DirectoryCustomization}），其子項 — 代理程式、技能、 提示、規則、掛鉤、MCP 伺服器 — 存在於每個容器的 {@link ContainerCustomizationBase.children | children} 陣列中。 - 主機直接公開的頂層 {@link McpServerCustomization} 項目（例如 全域設定的 MCP 伺服器，未隨附於外掛或目錄中）。MCP 伺服器也可 作為容器的子項出現。 用戶端發布的外掛透過 {@link SessionActiveClient.customizations | activeClients[].customizations} 抵達，主機將其傳播至此清單（通常會設定容器的 clientId 並填入 children）。用戶端僅以容器形式發布；頂層的單獨 MCP 伺服器為 伺服器發起。
changesets	Changeset[]	否	伺服器可為此工作階段產生的變更集目錄。每個項目通告一個可訂閱的 檔案變更檢視（未提交、工作階段範圍、每回合等）以及用戶端在訂閱前 展開的 URI 範本。完整形狀見 {@link Changeset}，模型概覽見 {@link /guide/changesets | Changesets}。
inputNeeded	SessionInputRequest[]	否	工作階段受阻的待處理輸入，跨每個聊天彙總，讓用戶端能單從工作 階段通道發現並回答，而無需訂閱個別聊天。 每個項目皆自足：它承載擁有聊天的 URI 加上用戶端回應所需的所有 識別碼。用戶端透過將普通的 chat/* 操作分派至該聊天的通道來回答 — 各變體的回應路徑見 {@link SessionInputRequest}。存在且非空的 清單隱含 {@link SessionSummary.status} 上的 {@link SessionStatus.InputNeeded}。 主機管理：主機以 session/inputNeededSet 在聊天提出請求時 upsert 項目，並在底層請求解決後以 session/inputNeededRemoved 移除它們。
_meta	Record<string, unknown>	否	此工作階段的額外提供者特定中繼資料。 用戶端 MAY 在此尋找知名鍵以提供增強的 UI。例如，git 鍵可提供 關於工作階段工作目錄的額外 git 中繼資料。

SessionActiveClient

目前為工作階段提供工具與互動能力的用戶端。

一個工作階段 MAY 同時有多個作用中用戶端；{@link SessionState.activeClients} 中的項目以 clientId 為鍵。伺服器 SHOULD 在該用戶端斷線時自動移除 作用中用戶端。

欄位	類型	必要	說明
clientId	string	是	用戶端識別碼（與 initialize 中的 clientId 相符）
displayName	string	否	人類可讀的用戶端名稱（例如 "VS Code"）
tools	ToolDefinition[]	是	此用戶端為工作階段提供的工具
customizations	ClientPluginCustomization[]	否	此用戶端為工作階段貢獻的外掛自訂。 用戶端以 Open Plugins 格式發布 — 即 永遠為容器形式的外掛。它們 MAY 在記憶體中合成虛擬外掛，並依賴 主機將其展開為 {@link SessionState.customizations} 內的具體子項。

SessionInputRequestKind

工作階段可在 {@link SessionState.inputNeeded} 中公開之待處理輸入種類的 判別欄位。

這是一般/分類型聯集（非生命週期），因此判別欄位為 *Kind。

成員	值	說明
ChatInput	'chatInput'	從未解決聊天回應部分鏡射而來的面向使用者引出。
ToolConfirmation	'toolConfirmation'	等待參數或結果確認的工具呼叫。
ToolClientExecution	'toolClientExecution'	工作階段希望作用中用戶端執行的執行中工具。
ToolAuthentication	'toolAuthentication'	執行中途因 MCP 驗證而阻塞的工具呼叫。

SessionChatInputRequest

在工作階段層級公開的使用者輸入引出，鏡射自擁有聊天中未解決的 {@link InputRequestResponsePart} 請求。

透過分派 chat/inputCompleted（或以 chat/inputAnswerChanged 同步草稿） 至 {@link SessionInputRequestBase.chat | chat} 來回應，以 {@link ChatInputRequest.id | request.id} 為鍵。

欄位	類型	說明
kind	SessionInputRequestKind.ChatInput
request	ChatInputRequest	鏡射的聊天輸入請求。

SessionToolConfirmationRequest

因確認而阻塞的工具呼叫 — 可能是執行前的參數確認或之後的結果確認 — 在工作階段層級公開。

透過分派 chat/toolCallConfirmed（對 {@link ToolCallPendingConfirmationState}）或 chat/toolCallResultConfirmed（對 {@link ToolCallPendingResultConfirmationState}）至 {@link SessionInputRequestBase.chat | chat} 來回應，以 turnId 與 toolCall.toolCallId 為鍵。

欄位	類型	說明
kind	SessionInputRequestKind.ToolConfirmation
turnId	string	工具呼叫所屬的回合。
toolCall	ToolCallConfirmationState	等待確認的工具呼叫。

SessionToolClientExecutionRequest

執行委派給作用中用戶端的執行中工具。公開以便提供該工具的用戶端能 接手工作而無需訂閱擁有聊天。

{@link toolCall} 永遠是 {@link ToolCallRunningState}（處於 running 狀態的 {@link ToolCallState}），其 {@link ToolCallRunningState.contributor | contributor} 為用戶端 {@link ToolCallClientContributor}，其 clientId 與此處反正規化的 {@link clientId} 相符。透過分派 chat/toolCallComplete（並選擇性地以 chat/toolCallContentChanged 串流）至 {@link SessionInputRequestBase.chat | chat} 來執行並回報結果，以 turnId 與 toolCall.toolCallId 為鍵。

欄位	類型	說明
kind	SessionInputRequestKind.ToolClientExecution
turnId	string	工具呼叫所屬的回合。
clientId	string	預期執行該工具的 clientId。與工具呼叫之用戶端 {@link ToolCallContributor} 的 clientId 相符。
toolCall	ToolCallState	工作階段希望擁有用戶端執行的執行中工具呼叫。主機僅會以 {@link ToolCallRunningState}（即處於 running 狀態的 {@link ToolCallState}）填入此欄位。

SessionToolAuthenticationRequest

執行中途因 MCP 驗證而阻塞的工具呼叫，在工作階段層級公開。

{@link toolCall} 永遠是 {@link ToolCallAuthRequiredState}（處於 auth-required 瀑態的 {@link ToolCallState}）。與 {@link SessionToolConfirmationRequest} 不同，這不是透過直接分派 chat/* 操作來回答：用戶端為 {@link ToolCallAuthRequiredState.auth | toolCall.auth}.resource 取得 權杖，並透過現有的 authenticate 指令推送（見 {@link /specification/authentication | Authentication}）。主機在權杖被 接受後恢復工具呼叫並分派 chat/toolCallAuthResolved，此時它也會以 session/inputNeededRemoved 移除此項目。

欄位	類型	說明
kind	SessionInputRequestKind.ToolAuthentication
turnId	string	工具呼叫所屬的回合。
toolCall	ToolCallAuthRequiredState	等待驗證的工具呼叫。

SessionInputRequest

工作階段受阻的單一待處理輸入，跨 {@link SessionState.inputNeeded} 中 所有聊天彙總。

每個項目皆自足：它承載擁有的 {@link SessionInputRequestBase.chat | chat} URI 加上建構回應所需的所有 識別碼，讓用戶端能透過將普通的 chat/* 操作（chat/inputCompleted、 chat/toolCallConfirmed、chat/toolCallComplete、…）分派至該聊天的 通道來回答，而無需先訂閱該聊天 — {@link SessionToolAuthenticationRequest} 除外，它改為透過 authenticate 指令解決。主機在底層請求解決後以 session/inputNeededRemoved 移除該項目。

SessionChatInputRequest | SessionToolConfirmationRequest | SessionToolClientExecutionRequest | SessionToolAuthenticationRequest

ProjectInfo

工作階段的伺服器擁有專案中繼資料。

欄位	類型	說明
uri	URI	專案 URI
displayName	string	人類可讀的專案名稱

SessionSummary

摘要單一工作階段的輕量級目錄項目。透過 {@link RootChannelCommands.listSessions | root/listSessions} 與 root/sessionAdded/root/sessionSummaryChanged 通知公開。

跨聊天彙總。 一旦工作階段包含多個聊天，若干 SessionSummary 欄位 衍生自底層的 {@link SessionState.chats | 聊天目錄}。生產者 SHOULD 遵循 這些規則，讓僅消費工作階段摘要的用戶端（例如工作階段清單）仍能看到 有意義的狀態：

• status：當 {@link SessionState.defaultChat | 預設聊天}存在時取其活動 位元（Idle / InProgress / InputNeeded / Error — 位元 0–4）， 否則取最近修改的聊天。當工作階段中任何聊天需要輸入時提升為 InputNeeded，且當任何聊天處於錯誤狀態時提升為 Error — 兩者皆 覆寫預設聊天位元。正交旗標位元（IsRead、IsArchived）保持工作 階段範圍。
• activity：鏡射預設聊天的活動字串，或當非預設聊天勝出時（例如 引發 InputNeeded 的聊天）鏡射目前驅動已提升狀態位元之聊天的活動 字串。
• modifiedAt：所有聊天 modifiedAt 的最大值。
• workingDirectories：工作階段層級集合。個別聊天 MAY 透過 {@link ChatSummary.workingDirectories} 限制為子集；將這些向上彙總毫無 意義，且 SHOULD NOT 嘗試。
• changes：跨所有聊天的選用彙總。生產者 MAY 對每個聊天的變更集 統計加總，或回報最昂貴聊天的統計 — 視何者對主機計算更便宜而定。

具有單一聊天的工作階段會簡單滿足上述所有條件（聊天的值原樣通過）。 這些規則僅在工作階段帶有多個聊天時才有意義。

欄位	類型	必要	說明
resource	URI	是	工作階段 URI
createdAt	string	是	建立時間戳記（ISO 8601，例如 "2025-03-10T18:42:03.123Z"）
modifiedAt	string	是	上次修改時間戳記（ISO 8601，例如 "2025-03-10T18:42:03.123Z"）
changes	ChangesSummary	否	與此工作階段關聯之檔案變更的彙總摘要。伺服器 MAY 填入此欄位以 提供用戶端工作階段足跡的快速一覽檢視（例如用於清單呈現），而 無需用戶端訂閱變更集。
_meta	Record<string, unknown>	否	伺服器定義的輕量級中繼資料，用戶端可用於工作階段呈現。協定不 解譯這些值；生產者 SHOULD 保持有效負載小巧，因為摘要出現於 工作階段清單與工作階段通知中。

ChangesSummary

描述與工作階段關聯之檔案變更的彙總計數。

所有欄位皆為選用，讓伺服器能僅填入其成本低廉可得的指標。

欄位	類型	必要	說明
additions	number	否	跨所有變更檔案的新增行總數。
deletions	number	否	跨所有變更檔案的刪除行總數。
files	number	否	有變更的檔案數。

AgentSelection

工作階段的已選自訂代理程式。

uri 識別特定的自訂代理程式（與透過工作階段有效自訂公開的 {@link AgentCustomization.uri | AgentCustomization.uri} 相符）。消費者 透過在工作階段的自訂樹中查找 uri 來解析代理程式的顯示名稱。

未選取 agent 的訊息使用提供者的預設行為。

欄位	類型	說明
uri	URI	穩定的代理程式 URI（與 {@link AgentCustomization.uri} 相符）。

SessionConfigPropertySchema

工作階段設定屬性描述器。

以工作階段特定的顯示延伸擴充通用的 {@link ConfigPropertySchema}。

欄位	類型	必要	說明
enumDynamic	boolean	否	顯示延伸：為 true 時，完整允許值集合過大而無法靜態列舉。用戶端 SHOULD 使用 sessionConfigCompletions 根據使用者輸入取得相符值。 enum 中的任何值為初始顯示用的種子/近期值。
sessionMutable	boolean	否	為 true 時，使用者可在工作階段建立後變更此屬性

SessionConfigSchema

描述可用工作階段設定中繼資料的 JSON Schema 物件。

欄位	類型	必要	說明
type	'object'	是	JSON Schema：永遠為 'object'
properties	Record<string, SessionConfigPropertySchema>	是	JSON Schema：以屬性 id 為鍵的屬性描述器
required	string[]	否	JSON Schema：必要屬性 id 的清單

SessionConfigState

即時工作階段設定中繼資料。

綱要描述可用設定屬性，而 values 包含每個已解析屬性的目前值。

欄位	類型	說明
schema	SessionConfigSchema	描述可用設定屬性的 JSON Schema
values	Record<string, unknown>	目前設定值

ToolDefinition

描述工作階段中可用的工具，由伺服器或作用中用戶端提供。

欄位	類型	必要	說明
name	string	是	唯一工具識別碼
title	string	否	人類可讀的顯示名稱
description	string	否	工具功能描述
inputSchema	{ type: 'object'; properties?: Record<string, object>; required?: string[]; }	否	定義預期輸入參數的 JSON Schema。 選用，因為用戶端提供的工具可能沒有正式綱要。鏡射 MCP Tool.inputSchema。
outputSchema	{ type: 'object'; properties?: Record<string, object>; required?: string[]; }	否	定義工具輸出結構的 JSON Schema。 鏡射 MCP Tool.outputSchema。
annotations	ToolAnnotations	否	關於工具的行為提示。所有屬性皆為建議性。
_meta	Record<string, unknown>	否	額外的提供者特定中繼資料。 鏡射 MCP _meta 慣例。

ToolAnnotations

關於工具的行為提示。所有屬性皆為建議性，且不保證能如實描述工具 行為。

鏡射 Model Context Protocol 規範中的 MCP ToolAnnotations。

欄位	類型	必要	說明
title	string	否	替代的人類可讀標題
readOnlyHint	boolean	否	工具不修改其環境（預設：false）
destructiveHint	boolean	否	工具可能執行破壞性更新（預設：true）
idempotentHint	boolean	否	以相同引數重複呼叫沒有額外效果（預設：false）
openWorldHint	boolean	否	工具可能與外部實體互動（預設：true）

CustomizationType

自訂種類的判別欄位。

{@link SessionState.customizations} 與 {@link AgentInfo.customizations} 中的頂層項目不是容器自訂（{@link CustomizationType.Plugin | Plugin} 或 {@link CustomizationType.Directory | Directory}），就是主機直接 公開的 {@link CustomizationType.McpServer | McpServer} 項目。其餘 種類僅作為容器的子項出現。

成員	值
Plugin	'plugin'
Directory	'directory'
Agent	'agent'
Skill	'skill'
Prompt	'prompt'
Rule	'rule'
Hook	'hook'
McpServer	'mcpServer'

ChildCustomizationType

作為 {@link PluginCustomization} 或 {@link DirectoryCustomization} 子項 出現的自訂類型。

CustomizationType.Agent | CustomizationType.Skill | CustomizationType.Prompt | CustomizationType.Rule | CustomizationType.Hook | CustomizationType.McpServer

CustomizationLoadStatus

{@link CustomizationLoadState} 的判別值。

成員	值
Loading	'loading'
Loaded	'loaded'
Degraded	'degraded'
Error	'error'

CustomizationLoadingState

容器正由主機載入。

欄位	類型	說明
kind	CustomizationLoadStatus.Loading

CustomizationLoadedState

容器載入成功。

欄位	類型	說明
kind	CustomizationLoadStatus.Loaded

CustomizationDegradedState

容器部分載入但有警告。

欄位	類型	說明
kind	CustomizationLoadStatus.Degraded
message	string	警告的人類可讀描述。

CustomizationErrorState

容器載入失敗。

欄位	類型	說明
kind	CustomizationLoadStatus.Error
message	string	人類可讀的錯誤訊息。

CustomizationLoadState

容器自訂（{@link PluginCustomization} 或 {@link DirectoryCustomization}）的判別聯集載入狀態。

CustomizationLoadingState | CustomizationLoadedState | CustomizationDegradedState | CustomizationErrorState

PluginCustomization

一個 Open Plugins 外掛。

欄位	類型	必要	說明
type	CustomizationType.Plugin	是
version	string	否	外掛版本，取自 Open Plugins 資訊清單的 選用 version 欄位（semver，例如 "1.2.0"）。當資訊清單未宣告版本 — 該欄位在那裡為選用 — 或來源沒有版本概念時不存在。僅供出處/ 顯示之用：主機既不解析也不強制執行它。

ClientPluginCustomization

由用戶端發布的 {@link PluginCustomization}。以不透明的 nonce 擴充 伺服器面向的形狀，讓主機能偵測用戶端的外掛檢視何時變更，並僅在 需要時重新解析。

用戶端 SHOULD 包含 nonce。發布時通常省略 {@link ContainerCustomizationBase.children | children} 與 {@link ContainerCustomizationBase.load | load} 等伺服器端欄位， 並在解析後的外掛出現於 {@link SessionState.customizations} 時由主機 填入。

欄位	類型	必要	說明
nonce	string	否	主機用來偵測變更的不透明版本權杖。

DirectoryCustomization

主機為此工作階段監視的目錄。

其存在於自訂清單中表示主機可從此目錄發現自訂。當 writable 為 true 時，用戶端 MAY 使用 resourceWrite 將新自訂持久化至 該目錄；主機接著會透過自訂操作公開產生的子項。

該目錄在磁碟上可能尚未存在。

欄位	類型	說明
type	CustomizationType.Directory
contents	ChildCustomizationType	此目錄持有的子自訂類型。
writable	boolean	用戶端是否可寫入此目錄。

AgentCustomization

由外掛或目錄貢獻的自訂代理程式。

鏡射 Open Plugins agent 格式：一個帶有 YAML frontmatter 的 markdown 檔案，其中本文為代理 程式的系統提示。

欄位	類型	必要	說明
type	CustomizationType.Agent	是
description	string	否	代理程式專精於什麼以及何時叫用它的簡短描述。取自代理程式檔案 frontmatter 的 description。
model	string	否	代理程式釘選的模型，取自代理程式檔案 frontmatter 的 model。 不存在表示代理程式繼承工作階段的預設模型。
tools	string[]	否	代理程式範圍限制的工具名稱允許清單，取自代理程式檔案 frontmatter 的 tools。非空清單將代理程式限制為確切那些工具。不存在 — 或 空清單 — 不施加工作階段預設之外的任何限制：代理程式可使用任何 可用工具。生產者透過省略該欄位而非傳送空陣列來表示「無限制」， 因此空清單不承載與不存在不同的意義。
disableModelInvocation	boolean	否	為 true 時，代理程式不會自動委派至此自訂代理程式作為子代理程式； 它只能由使用者選取。不存在或 false 表示代理程式 MAY 委派給它。
disableUserInvocation	boolean	否	為 true 時，使用者無法選取此自訂代理程式（例如在選擇器中）； 它仍可供代理程式自動委派。不存在或 false 表示使用者 MAY 選取 它。

SkillCustomization

由外掛或目錄貢獻的技能。

涵蓋兩種 Open Plugins skill 格式 — skills/ 目錄佈局（每個技能一個子目錄，各含一個 SKILL.md）與較扁平的 commands/ 斜線指令技能目錄。

欄位	類型	必要	說明
type	CustomizationType.Skill	是
description	string	否	用於說明文字與自動叫用比對的簡短描述。取自技能 frontmatter 的 description。
disableModelInvocation	boolean	否	為 true 時，僅使用者可叫用此技能 — 代理程式不會自動叫用它。 取自指令技能 frontmatter 的 disable-model-invocation 旗標。
disableUserInvocation	boolean	否	為 true 時，使用者無法直接叫用此技能（例如作為斜線指令）； 它仍可供代理程式自動叫用。不存在或 false 表示使用者 MAY 叫用 它。

PromptCustomization

由外掛或目錄貢獻的提示。

欄位	類型	必要	說明
type	CustomizationType.Prompt	是
description	string	否	提示功能的簡短描述。

RuleCustomization

由外掛或目錄貢獻的規則。

鏡射 Open Plugins rule 格式：一個 markdown 檔案（例如 .mdc），其本文在規則作用時注入至 上下文。此類型也涵蓋工具特定的「instruction」格式（例如 VS Code Copilot 的 .github/instructions/*.md），其僅在命名上不同 — 它們 共用 description、選用的常駐啟用與選用的 glob 範圍限制的相同語意。

欄位	類型	必要	說明
type	CustomizationType.Rule	是
description	string	否	規則所強制執行之內容的描述。
alwaysApply	boolean	否	為 true 時，規則永遠作用（受 globs 約束，若有）。為 false 或 不存在時，由代理程式或使用者決定是否套用該規則。
globs	string[]	否	規則適用的 glob 模式。存在時，規則僅對相符檔案作用。

HookCustomization

由外掛或目錄貢獻的掛鉤資訊清單。

欄位	類型	說明
type	CustomizationType.Hook

McpServerCustomization

由外掛或目錄貢獻的 MCP 伺服器。

當伺服器內嵌宣告於包含的外掛資訊清單時，uri 指向資訊清單檔案， 而 {@link CustomizationBase.range | range} 將其縮窄至宣告的跨度。

MCP 伺服器自訂也反映其目前狀態。

欄位	類型	必要	說明
type	CustomizationType.McpServer	是
enabled	boolean	是	此 MCP 伺服器目前是否啟用。
state	McpServerState	是	MCP 伺服器的目前生命週期狀態。
channel	URI	否	用戶端用來將流量側通道傳入上游 MCP 伺服器本身的 mcp:// 協定 通道。該通道並非全新的原始 MCP 連線：它搭載於 AHP 傳輸上並跳過 MCP initialize 序列。 代理主機 MAY 僅在此通道上提供 MCP 的子集；所提供的子集由 領域特定能力描述，例如 {@link McpServerCustomizationApps.capabilities} 中的那些。 通道 URI SHOULD 在伺服器生命週期內穩定，但代理主機 MAY 變更它 （例如跨重新啟動），且 MAY 僅在伺服器處於 {@link McpServerStatus.Ready | Ready} 時公開它。不存在表示目前 沒有可用的側通道。
mcpApp	McpServerCustomizationApps	否	MCP App 支援。對支援 apps 的 MCP 伺服器，SHOULD 公開此屬性。

McpServerCustomizationApps

代理主機為呈現由此 MCP 伺服器提供之 MCP Apps 所需的資訊。

欄位	類型	說明
capabilities	AhpMcpUiHostCapabilities	AHP 主機能為由此伺服器支援的 Views 滿足的 MCP App HostCapabilities 子集。用戶端將其直接送入傳遞給 View 的 ui/initialize 回應的 hostCapabilities 中。

AhpMcpUiHostCapabilities

AHP 主機可從上游 MCP 伺服器（及 AHP 自身的轉送管線）推導出的 MCP App HostCapabilities 子集。公開於 {@link McpServerCustomizationApps.capabilities}，讓用戶端 能將其直接送入傳遞給 MCP App View 的 ui/initialize 回應的 hostCapabilities 中。

欄位名稱與 MCP Apps 規範完全一致，讓 AHP 端生產者能將其直接送入 傳遞給 View 的 ui/initialize 回應的 hostCapabilities 中。

此集合之外的能力（openLinks、downloadFile、sandbox、 experimental）由呈現 View 的 AHP 用戶端在本機決定，且不屬於此 AHP 層級通告的一部分 — 僅有伺服器推導的子集屬於。

代理主機 MUST 僅在其確實於 mcp:// 通道上接受對應方法/通知時通告 某項能力：

• {@link serverTools}：主機代理 tools/list 與 tools/call 至 MCP 伺服器。當 listChanged 為 true 時，主機也轉送 notifications/tools/list_changed。
• {@link serverResources}：主機代理 resources/read、 resources/list 與 resources/templates/list 至 MCP 伺服器。當 listChanged 為 true 時，主機也轉送 notifications/resources/list_changed。
• {@link logging}：主機接受來自 App 的 notifications/message 日誌 項目並透過 mcpNotification 轉送（並將 logging/setLevel 呼叫 轉送至伺服器）。
• {@link sampling}：主機透過 mcpMethodCall 提供 sampling/createMessage。當 sampling.tools 存在時，主機也接受 CreateMessageRequest 內的 SEP-1577 tools / toolChoice / tool_use 內容區塊。

欄位	類型	必要	說明
serverTools	{ listChanged?: boolean; }	否	生產者將 MCP tools/* 方法代理至上游伺服器。
serverResources	{ listChanged?: boolean; }	否	生產者將 MCP resources/* 方法代理至上游伺服器。
logging	Record<string, never>	否	生產者透過 mcpNotification 接受來自 App 的 notifications/message 日誌項目。
sampling	{ tools?: Record<string, never>; }	否	生產者透過 mcpMethodCall 提供 sampling/createMessage。

ChildCustomization

存在於 {@link PluginCustomization} 或 {@link DirectoryCustomization} 內的子自訂。

AgentCustomization | SkillCustomization | PromptCustomization | RuleCustomization | HookCustomization | McpServerCustomization

Customization

工作階段中作用中的頂層自訂。可以是容器（{@link PluginCustomization} 或 {@link DirectoryCustomization}），其葉自訂存在於其 {@link ContainerCustomizationBase.children | children} 陣列中，或是 主機直接公開的單獨 {@link McpServerCustomization}。

PluginCustomization | DirectoryCustomization | McpServerCustomization

McpServerStatus

{@link McpServerState} 聯集的判別欄位。

成員	值	說明
Starting	'starting'	伺服器已註冊但尚未執行。
Ready	'ready'	伺服器執行中並提供請求服務。
AuthRequired	'authRequired'	伺服器可連線，但在啟動前或服務特定請求前需要額外驗證。承載用戶端 取得權杖所需的 RFC 9728 Protected Resource Metadata；用戶端接著 透過現有的 authenticate 指令推送權杖。
Error	'error'	伺服器啟動失敗、崩潰或以其他方式轉換至致命錯誤。
Stopped	'stopped'	伺服器已關閉。

McpAuthRequiredReason

MCP 伺服器目前為何處於 {@link McpServerStatus.AuthRequired} 狀態。 鏡射 MCP authorization 規範 定義的三種失敗模式。

成員	值	說明
Required	'required'	尚未提供權杖（HTTP 401，無先前權杖）。
Expired	'expired'	先前有效的權杖已過期或被撤銷（HTTP 401）。
InsufficientScope	'insufficientScope'	提升授權：權杖存在但其範圍對所請求的操作不足（HTTP 403，含 WWW-Authenticate: Bearer error="insufficient_scope"）。 與 {@link Required} 和 {@link Expired} — 兩者通常在任何工具工作進行前 出現 — 不同，InsufficientScope 幾乎總是由回合中途發出的 MCP 請求 （tools/call、resources/read 等）觸發。主機 SHOULD 將 {@link McpServerAuthRequiredState} 轉換與 {@link SessionSummary.status | 工作階段}上的 {@link SessionStatus.InputNeeded} 配對，讓活動在工作階段摘要層級 可見，且用戶端 SHOULD 監看任何支援執行中工具呼叫的 {@link McpServerCustomization | MCP 伺服器}上的此種類，以便能呈現 與受阻工具呼叫繫結的明確「授予更多存取權」介面。

McpServerStartingState

伺服器已向主機註冊但尚未啟動。

欄位	類型	說明
kind	McpServerStatus.Starting

McpServerReadyState

伺服器執行中並提供請求服務。

欄位	類型	說明
kind	McpServerStatus.Ready

McpOAuthClient

預先註冊的 OAuth 用戶端，用戶端在解決 MCP 驗證挑戰時使用它，而非 動態用戶端註冊。

欄位	類型	必要	說明
clientId	string	是	向授權伺服器註冊的 OAuth 用戶端識別碼。
clientSecret	string	否	機密用戶端的 OAuth 用戶端密碼。不存在表示用戶端為公開用戶端，並 使用如授權碼搭配 PKCE 的無密碼流程。

McpAuthRequirement

可重複使用的 MCP 驗證挑戰 — 用戶端取得權杖並透過 authenticate 指令 推送所需的 RFC 9728 探索資訊。刻意不承載權杖：此處描述的是所 請求的內容，從不包含 ****** 本身。

由兩個描述同一 OAuth 挑戰不同觀點的獨立狀態機共用：

• {@link McpServerAuthRequiredState} — MCP 伺服器本身在用戶端驗證前 無法服務任何請求。
• {@link ToolCallAuthRequiredState} — 特定的進行中工具呼叫因等待 驗證而暫停（通常為 {@link McpAuthRequiredReason.InsufficientScope} 執行中途的提升 授權）。伺服器狀態與工具呼叫狀態刻意保持分離：伺服器說「我需要 驗證」與工具呼叫說「我正在等待該驗證」是可獨立為真的不同事實。

欄位	類型	必要	說明
reason	McpAuthRequiredReason	是	為何需要驗證。
oauthClient	McpOAuthClient	否	用於授權的預先註冊 OAuth 用戶端。存在時，用戶端 MUST 使用這些 憑證而非動態用戶端註冊。
resource	ProtectedResourceMetadata	是	RFC 9728 Protected Resource Metadata。resource 欄位為依 RFC 8707 的標準 MCP 伺服器 URI，用作 OAuth resource 指示器。 authorization_servers 為 MCP authorization 規範所 REQUIRED。
requiredScopes	string[]	否	目前挑戰所需的範圍，解析自 WWW-Authenticate: ******"…" 標頭（或 scopes_supported 回退值）。對下次授權請求具權威性 — 用戶端 MUST NOT 假設與 resource.scopes_supported 有任何子集/超集關係。
description	string	否	人類可讀的提示，通常來自 OAuth error_description。

McpServerAuthRequiredState

伺服器可連線但在用戶端驗證前無法服務請求。鏡射 RFC 9728 （Protected Resource Metadata）定義的探索流程，以及 MCP authorization 規範所需的 OAuth 2.1 / RFC 6750 挑戰語意。

用戶端透過以現有的 authenticate 指令呼叫，並帶上此處承載的 {@link ProtectedResourceMetadata.resource | resource} 來回應此狀態。 MCP 伺服器沒有 notify/authRequired 通知 — 操作串流是唯一 真相來源。

當轉換是由回合期間發出的請求觸發 — 最常見為 {@link McpAuthRequiredReason.InsufficientScope | InsufficientScope} 在工具呼叫中途出現 — 主機 SHOULD 一併在工作階段上引發 {@link SessionStatus.InputNeeded}，讓阻塞在摘要層級可見。用戶端 SHOULD 監看任何支援執行中工具呼叫之 MCP 伺服器上的此狀態，並呈現 與該工具呼叫繫結的明確介面（例如「授予額外存取權」提示），而非 仰賴使用者注意到自訂的狀態徽章。

欄位	類型	說明
kind	McpServerStatus.AuthRequired

McpServerErrorState

伺服器啟動失敗、崩潰或以其他方式轉換至無法恢復的錯誤。驗證失敗 請使用 {@link McpServerStatus.AuthRequired}。

欄位	類型	說明
kind	McpServerStatus.Error
error	ErrorInfo	錯誤詳細資訊。

McpServerStoppedState

伺服器已關閉。主機 MAY 在此狀態後不久將伺服器從工作階段中完全 移除。

欄位	類型	說明
kind	McpServerStatus.Stopped

McpServerState

所有 MCP 伺服器生命週期狀態的判別聯集。 以 kind（一個 {@link McpServerStatus} 值）作為判別。

McpServerStartingState | McpServerReadyState | McpServerAuthRequiredState | McpServerErrorState | McpServerStoppedState

操作

變動 SessionState。透過外層的 ActionEnvelope.channel 限定於某個工作階段 URI。

JSON Schema: actions.schema.json

session/ready

工作階段後端初始化成功。

欄位	類型	說明
type	ActionType.SessionReady

session/creationFailed

工作階段後端初始化失敗。

欄位	類型	說明
type	ActionType.SessionCreationFailed
error	ErrorInfo	錯誤詳細資訊

session/chatAdded

聊天已加入此工作階段的目錄。Upsert 語意：若已存在具有相同 summary.resource 的聊天，則取代現有項目。

鏡射根通道的 root/sessionAdded 通知。

欄位	類型	說明
type	ActionType.SessionChatAdded
summary	ChatSummary	新增（或 upsert）之聊天的完整摘要。

session/chatRemoved

聊天已從此工作階段的目錄中移除。無相符項目時為 no-op。

鏡射根通道的 root/sessionRemoved 通知。

欄位	類型	說明
type	ActionType.SessionChatRemoved
chat	URI	要移除的聊天 URI。

session/chatUpdated

一個現有聊天的摘要欄位已變更。

部分更新語意：僅寫入 changes 中出現的欄位；省略的欄位會被保留。 識別欄位（resource）MUST NOT 隨附於 changes。無相符 chat 項目時 為 no-op — 用戶端 SHOULD 接著等待 {@link SessionChatAddedAction | session/chatAdded}。

鏡射根通道的 root/sessionSummaryChanged 通知。

欄位	類型	說明
type	ActionType.SessionChatUpdated
chat	URI	摘要已變更的聊天 URI。
changes	Partial<ChatSummary>	已變動的可變摘要欄位；省略的欄位保持不變。 識別欄位（resource）永不變更，且傳送端 MUST 省略；接收端若收到 則 SHOULD 忽略。

session/defaultChatChanged

此工作階段的預設聊天輸入路由提示已變更。

欄位	類型	必要	說明
type	ActionType.SessionDefaultChatChanged	是
defaultChat	URI	否	新的預設聊天 URI，或 undefined 以清除提示。

session/titleChanged

工作階段標題已更新。當標題從對話自動產生時由伺服器引發，或由 用戶端分派以重新命名工作階段。

欄位	類型	說明
type	ActionType.SessionTitleChanged
title	string	新標題

session/isReadChanged

工作階段的已讀狀態已變更。

由用戶端分派以將工作階段標記為已讀（例如檢視後）或未讀（例如自 用戶端上次檢視後有新活動）。

欄位	類型	說明
type	ActionType.SessionIsReadChanged
isRead	boolean	工作階段是否已讀

session/isArchivedChanged

工作階段的封存狀態已變更。

由用戶端分派以封存工作階段（例如工作完成）或解除封存。

欄位	類型	說明
type	ActionType.SessionIsArchivedChanged
isArchived	boolean	工作階段是否已封存

session/activityChanged

工作階段的活動描述已變更。

由伺服器分派以指出工作階段目前正在做什麼（例如執行工具、 思考）。設為 undefined 以清除活動。

欄位	類型	說明
type	ActionType.SessionActivityChanged
activity	string | undefined	目前活動的人類可讀描述，或 undefined 以清除

session/changesetsChanged

代理主機為此工作階段所通告的 {@link Changeset | 變更集目錄}已變更。 完全取代 {@link SessionState.changesets | state.changesets} （完全取代語意）— 設為 undefined 以清除目錄。

生產者在新增或移除項目時分派此操作。展發透過此操作進行，讓 觀察者能在其已追蹤的檔案層級更新所用的同一個 {@link ChangesetAction | 每個變更集} 操作串流中看到目錄變動。

欄位	類型	說明
type	ActionType.SessionChangesetsChanged
changesets	Changeset[] | undefined	新目錄，或 undefined 以清除

session/serverToolsChanged

此工作階段的伺服器工具已變更。

完全取代語意：tools 陣列完全取代先前的 serverTools。

欄位	類型	說明
type	ActionType.SessionServerToolsChanged
tools	ToolDefinition[]	已更新的伺服器工具清單（完全取代）

session/activeClientSet

此工作階段的作用中用戶端已新增或更新。

以 {@link SessionActiveClient.clientId | clientId} 為鍵的 Upsert 語意：用戶端以自己的 SessionActiveClient 分派此操作以加入工作 階段的作用中用戶端或重新整理其項目，取代任何具有相同 clientId 的現有項目。多個用戶端可同時作用中。這也是用戶端更新 其已發布工具或自訂的方式 — 以完整、已更新的項目重新分派。使用 {@link SessionActiveClientRemovedAction | session/activeClientRemoved} 來離開。當作用中用戶端斷線時，伺服器 SHOULD 自動分派該移除操作。

欄位	類型	說明
type	ActionType.SessionActiveClientSet
activeClient	SessionActiveClient	要新增或更新的作用中用戶端，以 clientId 比對。

session/activeClientRemoved

此工作階段的作用中用戶端已移除。

從 {@link SessionState.activeClients} 移除以 clientId 識別的用戶端 項目；無相符項目時為 no-op。

當用戶端停止參與工作階段時，主機 SHOULD 自動分派此操作 — 例如 當其取消訂閱工作階段通道、斷線且未在主機定義的寬限期內重新連線， 或 reconnect 指令的 subscriptions 省略了用戶端仍在作用中的工作 階段時。移除用戶端時，主機 SHOULD 一併取消該用戶端的進行中工具 呼叫 — 即工具呼叫狀態承載具有相符 clientId 之用戶端 ToolCallContributor 的那些呼叫 — 作法是分派 chat/toolCallComplete 並設定 result.success = false。（沒有每個工具呼叫的伺服器取消； 失敗的補全即為取消機制，呼叫以失敗結果結束於 completed 狀態。）

欄位	類型	說明
type	ActionType.SessionActiveClientRemoved
clientId	string	要移除的作用中用戶端之 clientId。

session/workingDirectorySet

工作目錄已加入工作階段的 {@link SessionState.workingDirectories} 集合。

以目錄 URI 為鍵的成員資格語意：當集合尚不包含 directory 時 reducer 會附加它（若集合不存在則建立），且已存在時為 no-op。 僅在代理程式通告 {@link AgentCapabilities.multipleWorkingDirectories} 時有效。

欄位	類型	說明
type	ActionType.SessionWorkingDirectorySet
directory	URI	要授予工作階段代理程式工具存取權的工作目錄。

session/workingDirectoryRemoved

工作目錄已從工作階段的 {@link SessionState.workingDirectories} 集合中移除。

從集合中移除 directory；不存在時為 no-op。沒有原子的後端「移除 一個」基本操作 — 主機將其代理程式重新設定為縮減後的集合 — 因此 此操作可安全地建模為冪等。主機 MAY 拒絕套用移除（例如某個目錄 仍被指定為某個聊天的 {@link ChatState.primaryWorkingDirectory | 主要目錄}）；此時它會保持 集合不變。

欄位	類型	說明
type	ActionType.SessionWorkingDirectoryRemoved
directory	URI	要撤銷工作階段代理程式工具存取權的工作目錄。

session/inputNeededSet

工作階段層級的輸入請求已新增或更新。

以 {@link SessionInputRequest.id | request.id} 為鍵的 Upsert 語意： 主機以完整的 {@link SessionInputRequest} 分派此操作以將新項目附加至 {@link SessionState.inputNeeded} 或取代具有相同 id 的現有項目。

伺服器發起：主機將聊天層級的請求（引出、工具確認、用戶端工具 執行）鏡射至工作階段彙總中，讓僅訂閱工作階段通道的用戶端能發現 它們。用戶端透過將普通的 chat/* 操作分派至項目的 chat 通道來 回應 — 見 {@link SessionInputRequest}。

欄位	類型	說明
type	ActionType.SessionInputNeededSet
request	SessionInputRequest	要新增或更新的輸入請求，以 id 比對。

session/inputNeededRemoved

工作階段層級的輸入請求已移除。

從 {@link SessionState.inputNeeded} 移除以 id 識別的項目；無相符 項目時為 no-op。

伺服器發起：主機在底層請求解決後（使用者回答、工具呼叫確認、或 用戶端回報結果）分派此操作。

欄位	類型	說明
type	ActionType.SessionInputNeededRemoved
id	string	要移除之輸入請求的 id。

session/customizationsChanged

工作階段的自訂已變更。

完全取代語意：customizations 陣列完全取代先前的 customizations。

欄位	類型	說明
type	ActionType.SessionCustomizationsChanged
customizations	Customization[]	已更新的自訂清單（完全取代）。

session/customizationToggled

用戶端將某個自訂啟用或停用。

先以 id 比對每個頂層自訂 — 外掛或目錄容器，或單獨的頂層 MCP 伺服器 — 再比對每個容器內的子項（技能、代理程式或其他項目）， 並設定相符項目的 enabled 旗標。停用容器仍會停用其所有子項 — 子項的有效狀態為 container.enabled && (child.enabled ?? true) — 因此切換子項僅在其容器啟用時才有意義。沒有自訂具有給定 id 時 為 no-op。

欄位	類型	說明
type	ActionType.SessionCustomizationToggled
id	string	要切換的容器或子項之 id。
enabled	boolean	要啟用或停用目標自訂。

session/customizationUpdated

Upsert 頂層自訂（外掛或目錄）。

reducer 以 customization.id 定位現有項目：

• 若找到，項目會完全以 customization 取代，包含其 children 陣列。要保留現有子項，主機必須在有效負載中包含它們。
• 若未找到，則附加該項目。

欄位	類型	說明
type	ActionType.SessionCustomizationUpdated
customization	Customization	要 upsert 的自訂（以 customization.id 比對）。

session/customizationRemoved

以 id 移除自訂。

在每個容器及其子項中搜尋該項目。若項目是容器，其子項會一併移除。 沒有相符 id 時為 no-op。

欄位	類型	說明
type	ActionType.SessionCustomizationRemoved
id	string	要移除的自訂之 id。

session/mcpServerStateChanged

更新現有 {@link McpServerCustomization} 的執行時期欄位 — 針對高頻率的 starting ↔ ready ↔ authRequired 轉換，是 {@link SessionCustomizationUpdatedAction} 的窄替代方案。

以 id 定位目標項目，搜尋頂層自訂清單與每個容器的 children 陣列。取代項目的 {@link McpServerCustomization.state | state} 與 {@link McpServerCustomization.channel | channel} （完全取代語意：省略 channel 以清除現有通道 URI）。自訂的其他 欄位會被保留。

找不到相符的 McpServerCustomization 時為 no-op。要更新任何其他 欄位（名稱、圖示、mcpApp 能力等），請改用 {@link SessionCustomizationUpdatedAction}。

當轉換至 {@link McpServerStatus.AuthRequired} 是因回合中途發出的 請求所致時，主機 SHOULD 一併在工作階段上引發 {@link SessionStatus.InputNeeded} — 見 {@link McpServerAuthRequiredState} 的理由說明。

欄位	類型	必要	說明
type	ActionType.SessionMcpServerStateChanged	是
id	string	是	要更新的 {@link McpServerCustomization} 之 id。
state	McpServerState	是	新的生命週期狀態。
channel	URI	否	已更新的 mcp:// 側通道 URI。完全取代：省略以清除現有通道 （離開 {@link McpServerStatus.Ready | Ready} 時的典型做法）。

session/mcpServerStartRequested

請求主機啟動或重新啟動現有的 {@link McpServerCustomization}。

以 id 定位目標項目，搜尋頂層自訂清單與每個容器的 children 陣列。reducer 樂觀地將伺服器移至 {@link McpServerStatus.Starting | starting} 並清除任何先前的 {@link McpServerCustomization.channel | channel}；主機仍具權威性， SHOULD 在伺服器就緒、需要驗證、失敗或被拒絕後，接著分派 {@link SessionMcpServerStateChangedAction | session/mcpServerStateChanged}。 找不到相符的 McpServerCustomization 時為 no-op。

欄位	類型	說明
type	ActionType.SessionMcpServerStartRequested
id	string	要啟動的 {@link McpServerCustomization} 之 id。

session/mcpServerStopRequested

請求主機停止現有的 {@link McpServerCustomization}。

以 id 定位目標項目，搜尋頂層自訂清單與每個容器的 children 陣列。reducer 樂觀地將伺服器移至 {@link McpServerStatus.Stopped | stopped} 並清除任何先前的 {@link McpServerCustomization.channel | channel}。以 stopped 取代 {@link McpServerStatus.AuthRequired | authRequired} 生命週期 狀態會解除伺服器等待驗證的阻塞。若主機僅為該 MCP 伺服器引發了 工作階段層級的待處理輸入狀態，則在接受停止時 SHOULD 移除該待處理 輸入項目。

主機仍具權威性，且 MAY 拒絕該操作，或在最終生命週期狀態不同時接著 分派 {@link SessionMcpServerStateChangedAction | session/mcpServerStateChanged}。 找不到相符的 McpServerCustomization 時為 no-op。

欄位	類型	說明
type	ActionType.SessionMcpServerStopRequested
id	string	要停止的 {@link McpServerCustomization} 之 id。

session/configChanged

用戶端在工作階段中途變更了可變的設定值。

只有設定綱要中具有 sessionMutable: true 的屬性可被變更。伺服器驗證 並廣播此操作；reducer 將新值合併至 state.config.values。

欄位	類型	必要	說明
type	ActionType.SessionConfigChanged	是
config	Record<string, unknown>	是	已更新的設定值
replace	boolean	否	為 true 時，取代所有設定值而非合併

session/metaChanged

工作階段的 _meta 側通道已變更。完全取代 state._meta （完全取代語意）。生產者 SHOULD 在分派前將任何想保留的鍵合併至 新值中。

欄位	類型	說明
type	ActionType.SessionMetaChanged
_meta	Record<string, unknown> | undefined	新的 _meta 有效負載，或 undefined 以清除

指令

JSON Schema: commands.schema.json

createSession

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	必要	說明
channel	URI	是	工作階段 URI（由用戶端選擇，例如 ahp-session:/<uuid>）
provider	string	否	代理程式提供者 ID
workingDirectories	URI[]	否	工作階段代理程式被授予工具存取權的工作目錄。一個工作階段可跨越多個 目錄；它們是平等的同儕，除非代理程式通告了 {@link MultipleWorkingDirectoriesCapability.requiresPrimary}，此時 應透過 {@link primaryWorkingDirectory} 將其中之一指定為主要目錄。 除非代理程式通告了 {@link AgentCapabilities.multipleWorkingDirectories}，否則用戶端 MUST NOT 提供多個項目；不具此能力的伺服器僅將第一個項目視為工作階段的工作 目錄，並忽略其餘項目。在工作階段啟動後，分派 session/workingDirectorySet / session/workingDirectoryRemoved 來 變更此集合。 分叉的工作階段會忽略此欄位 — 分叉會從 fork 所識別的來源工作階段 繼承其工作目錄。
primaryWorkingDirectory	URI	否	工作階段預設聊天的主要工作目錄。 工作階段本身沒有主要目錄 — 主要目錄是每個聊天的概念（見 {@link ChatState.primaryWorkingDirectory}）。但 createSession 會隱含 建立工作階段的預設聊天，且沒有獨立的 createChat 呼叫可承載該聊天的 建立時間欄位。因此，此欄位是用戶端唯一能在誕生時指定預設聊天 主要目錄之處；它會被複製到該聊天唯讀的 primaryWorkingDirectory。對任何非預設聊天，請改為傳遞 {@link CreateChatParams.primaryWorkingDirectory}。 設定時，它 MUST 是 {@link workingDirectories} 之一。當代理程式通告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時，用戶端 SHOULD 提供此欄位；主機 MAY 拒絕省略它的建立請求，或退回使用 workingDirectories 的第一個項目。分叉的工作階段會忽略此欄位 （分叉會繼承來源工作階段的聊天及其主要目錄）。
fork	SessionForkSource	否	從現有工作階段分叉。新工作階段會以來源工作階段的內容填入，範圍至 並包含指定回合的回應為止。
config	Record<string, unknown>	否	透過 resolveSessionConfig 收集的代理程式特定設定值。鍵與值對應於 伺服器回傳的綱要。
activeClient	SessionActiveClient	否	為新工作階段主動認領作用中用戶端角色。 提供時，伺服器會以此用戶端作為作用中用戶端初始化工作階段，等同於 在建立後立即分派 session/activeClientSet 操作。clientId MUST 與建立用戶端在 initialize 中提供的 clientId 相符。
progressToken	string	否	選擇加入的進度權杖。設定時，用戶端表示願意接收伺服器為帶起此工作 階段所做任何長時間執行工作的 progress 通知（見 ProgressParams） — 最顯著的是提供者原生 SDK 的延遲首次使用下載。伺服器會在每個 progress 框架上回應此確切權杖，讓用戶端能將其與此 createSession 呼叫（及等待它的 UI）關聯。 權杖 MUST 在用戶端的作用中請求間是唯一的。伺服器 MAY 忽略它 （例如當不需要任何長時間執行的工作時），此情況下不會發出任何 progress 通知。

結果： 成功時為 null。

---

disposeSession

處置工作階段並清理伺服器端資源。

伺服器會向所有用戶端廣播 root/sessionRemoved 通知。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

無參數。

結果： 成功時為 null。

---

fetchTurns

請求主機將較舊的歷史回合載入聊天狀態。

指令結果不承載回合。相反地，在回應前，主機 MUST 分派 chat/turnsLoaded，將任何已載入的回合插入聊天通道的 turns 狀態，置於已載入視窗之前，並更新或清除 turnsNextCursor。

在套用任何參照目前載入視窗外回合的操作前，主機 MUST 主動將足夠的 舊回合載入狀態，讓該操作能對有效狀態進行歸約。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	必要	說明
channel	URI	是	聊天 URI
cursor	string	否	來自 ChatState.turnsNextCursor 的不透明游標。 主機 MUST 以 InvalidParams 拒絕無法辨識的游標。僅在要求主機為 聊天（若有的話）順勢載入其下一個較舊分頁時才省略。

結果：

（空物件）

範例：

// Client → Server (load the next page indicated by ChatState.turnsNextCursor)
{ "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
  "params": { "channel": "ahp-chat:/<uuid>", "cursor": "opaque-cursor" } }

// Server updates chat state, then responds
{ "jsonrpc": "2.0", "id": 8, "result": {} }

---

completions

為部分輸入的內容請求補全項目（例如使用者目前正在撰寫的使用者 訊息）。用於驅動 @ 提及選擇器、檔案/符號參照，以及類似的內嵌 補全體驗。

伺服器 SHOULD 將此指令視為盡力而為並迅速回傳。用戶端 SHOULD 對呼叫 進行去抖動，以避免在每次按鍵時用請求淹沒伺服器。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	說明
kind	CompletionItemKind	所請求的補全種類。
channel	URI	請求補全的聊天 URI。
text	string	正在補全之輸入的完整文字（例如目前為止輸入的完整使用者訊息文字）。
offset	number	在 text 中請求補全的字元偏移量，以 UTF-16 碼單位測量。MUST 滿足 0 <= offset <= text.length。

結果：

欄位	類型	說明
items	CompletionItem[]	補全項目，按伺服器建議顯示的順序排列。

範例：

// User has typed "look at

---