Skip to main content

muse_code_sdk/msp/view/
approval.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::error::ApprovalRequirementRef;
4use crate::msp::view::SourceRange;
5pub use decision::ApprovalAmendment;
6pub use decision::ApprovalAmendmentDurability;
7pub use decision::ApprovalChange;
8pub use decision::ApprovalChoice;
9pub use decision::ApprovalChoiceScope;
10pub use decision::ApprovalDecision;
11pub use decision::ApprovalPersistenceStatus;
12pub use decision::ApprovalPolicyResult;
13pub use decision::ApprovalResolvedBy;
14pub use decision::ApprovalStageEvidence;
15use serde::Deserialize;
16use serde::Serialize;
17
18pub(crate) mod decision;
19
20/// Full params shared by `approval/request` and `approval/requested`.
21#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(rename_all = "camelCase")]
23#[non_exhaustive]
24pub struct ApprovalRequestParams {
25    /// The owning session. For a subagent's approval shown on the parent, this
26    /// is the parent session.
27    pub session_id: String,
28    /// The approval's stable id. Match `approval/decide`, `approval/updated`
29    /// and `approval/resolved` by it, never by the JSON-RPC request id, which
30    /// belongs to one connection.
31    pub approval_id: String,
32    /// The turn whose tool call is waiting on this approval.
33    pub turn_id: String,
34    /// The id of the task running the tool call.
35    pub task_id: String,
36    /// The `toolCall` view item waiting on this approval.
37    pub item_id: String,
38    /// The model provider's id for this tool call.
39    pub tool_call_id: String,
40    /// The name of the tool being called.
41    pub tool_name: String,
42    /// The tool call's arguments as a string, usually JSON. With `toolName`, it
43    /// lets a client show a subject whose `kind` it does not recognize.
44    pub raw_args: String,
45    /// The cursor of the `approval/requested` event that opened this request.
46    /// A re-send for a later stage keeps this cursor, so `view/page` at it
47    /// returns the opening stage, which may be older than this payload.
48    pub view_cursor: String,
49    /// The stored records this event was folded from: an opaque token clients
50    /// must not interpret.
51    pub source_range: SourceRange,
52    /// What the approval is for. Show a `kind` you do not recognize
53    /// generically, and never auto-approve it.
54    pub subject: ApprovalSubject,
55    /// The requirement the next decision must target; send it unchanged as
56    /// `requirementId` in `approval/decide`. For `shell` it names the first
57    /// stage still needing a decision; for other kinds its `sourceIndex` is 0.
58    pub current_requirement_id: ApprovalRequirementRef,
59    /// The choices the server offers for the current requirement. Send the
60    /// chosen one's `choiceId` in `approval/decide`; clients never build their
61    /// own.
62    pub available_choices: Vec<ApprovalChoice>,
63    /// `true` when this approval guards a write to a protected file. Only
64    /// allow-once and reject choices are offered, and a decision is accepted
65    /// only while at least one client is subscribed to the session.
66    pub protected_write: bool,
67    /// `true` when the automated LLM judge saw this request first and handed it
68    /// to a person without deciding. A display hint only. The host sends it
69    /// as `false` when it re-issues the request after a restart or on
70    /// `session/resume`; a re-send for a later stage keeps it.
71    pub judge_escalated: bool,
72    /// Present only for a child (native subagent) approval projected onto the
73    /// parent session's plane; parent-own approvals omit it.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub subagent_origin: Option<ApprovalSubagentOrigin>,
76    /// A Computer Use card's facts: the page, the window and each step that
77    /// may have an effect, in the host's words; absent on every other
78    /// approval.
79    #[serde(default, skip_serializing_if = "Option::is_none")]
80    pub cua_card_facts: Option<crate::msp::view::approval_card_facts::ApprovalCuaCardFacts>,
81}
82
83/// `approval/updated` params: the refreshed pending view plus one change.
84#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
85#[serde(rename_all = "camelCase")]
86#[non_exhaustive]
87pub struct ApprovalUpdatedParams {
88    /// The owning session.
89    pub session_id: String,
90    /// This event's view cursor: opaque, and strictly increasing within the
91    /// session.
92    pub view_cursor: String,
93    /// The stored records this event was folded from: an opaque token clients
94    /// must not interpret.
95    pub source_range: SourceRange,
96    /// The approval that changed.
97    pub approval_id: String,
98    /// The requirement the next decision must target after this change; send it
99    /// as `requirementId` in `approval/decide`.
100    pub current_requirement_id: ApprovalRequirementRef,
101    /// The approval's subject, with `stages` refreshed for this change.
102    pub subject: ApprovalSubject,
103    /// The refreshed choices for the current requirement.
104    pub available_choices: Vec<ApprovalChoice>,
105    /// What changed; `change.kind` names the kind of change.
106    pub change: ApprovalChange,
107    /// Present only for a child (native subagent) approval projected onto the
108    /// parent session's plane; parent-own approvals omit it.
109    #[serde(default, skip_serializing_if = "Option::is_none")]
110    pub subagent_origin: Option<ApprovalSubagentOrigin>,
111}
112
113/// `approval/resolved` params: the first durable terminal decision.
114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
115#[serde(rename_all = "camelCase")]
116#[non_exhaustive]
117pub struct ApprovalResolvedParams {
118    /// The owning session.
119    pub session_id: String,
120    /// This event's view cursor: opaque, and strictly increasing within the
121    /// session.
122    pub view_cursor: String,
123    /// The stored records this event was folded from: an opaque token clients
124    /// must not interpret.
125    pub source_range: SourceRange,
126    /// The approval that was decided.
127    pub approval_id: String,
128    /// The `toolCall` view item this approval was holding.
129    pub item_id: String,
130    /// The turn whose tool call this approval was holding.
131    pub turn_id: String,
132    /// The final decision.
133    pub decision: ApprovalDecision,
134    /// Whether the final decision lets the action run (`allow`) or blocks it
135    /// (`deny`).
136    pub policy_result: ApprovalPolicyResult,
137    /// The policy rule the decision created. Present only when the decision
138    /// created one.
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub amendment: Option<ApprovalAmendment>,
141    /// Who or what made the decision: `user`, `policy` or `llmJudge`.
142    pub resolved_by: ApprovalResolvedBy,
143    /// The `commandId` of the `approval/decide` command that won. Absent when
144    /// no such command made the decision, for example a policy or LLM judge
145    /// decision.
146    #[serde(skip_serializing_if = "Option::is_none")]
147    pub decided_by_command_id: Option<String>,
148    /// The decision time as RFC3339, projected from the durable
149    /// `DecisionApplied` record's own stamp: optional on the wire so decoders
150    /// tolerate its absence, always populated by current hosts.
151    #[serde(default, skip_serializing_if = "Option::is_none")]
152    pub decided_at: Option<String>,
153    /// For a `shell` approval, how each stage was resolved when the decision
154    /// became final. Empty for other subject kinds, and it can be empty for
155    /// `shell` too.
156    pub stage_evidence: Vec<ApprovalStageEvidence>,
157    /// Present only for a child (native subagent) approval projected onto the
158    /// parent session's plane; parent-own approvals omit it.
159    #[serde(default, skip_serializing_if = "Option::is_none")]
160    pub subagent_origin: Option<ApprovalSubagentOrigin>,
161}
162
163/// Child (native subagent) provenance for an approval projected onto the PARENT
164/// session's approval plane: identifies the originating child run/agent so a
165/// client can attribute the prompt. Omitted (`skip_serializing_if`) on the
166/// parent's own approvals, so pre-existing parent frames stay byte-identical.
167#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
168#[serde(rename_all = "camelCase")]
169#[non_exhaustive]
170pub struct ApprovalSubagentOrigin {
171    /// The originating child's subagent id, from the parent session's
172    /// durable subagent control records.
173    pub subagent_id: String,
174    /// The child session stream id whose records carry this approval.
175    pub child_session_id: String,
176    /// The child run that parked on this approval.
177    pub child_run_id: String,
178}
179
180/// Open approval subject union. Unknown kinds are rendered generically and
181/// never auto-approved by clients.
182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "camelCase")]
184#[non_exhaustive]
185pub struct ApprovalSubject {
186    /// Open discriminator: `shell | fileAccess | network | unixSocket | process | tool`.
187    pub kind: String,
188    /// The full raw shell command. Present when `kind` is `shell`.
189    #[serde(skip_serializing_if = "Option::is_none")]
190    pub command: Option<String>,
191    /// The canonical workspace root the shell command runs in, present on
192    /// `shell` subjects when the host knows it. Saved command-prefix rules
193    /// apply only within this root.
194    #[serde(skip_serializing_if = "Option::is_none")]
195    pub workspace_root: Option<String>,
196    /// The shell command split into stages that are approved separately (the
197    /// commands of a pipeline or command list), in order. Present on `shell`
198    /// subjects; it may be empty.
199    #[serde(skip_serializing_if = "Option::is_none")]
200    pub stages: Option<Vec<ApprovalStage>>,
201    /// The tool asking for the action. Present for every kind except `shell`.
202    #[serde(skip_serializing_if = "Option::is_none")]
203    pub tool_name: Option<String>,
204    /// For `fileAccess`, the path the tool asked to access, normalized by the
205    /// host (workspace-relative inside the workspace); for
206    /// `unixSocket`, the exact resolved socket path, sent unescaped, so escape
207    /// it before display.
208    #[serde(skip_serializing_if = "Option::is_none")]
209    pub path: Option<String>,
210    /// The access asked for: `read` or `write` for `fileAccess`, `control` for
211    /// `process`. Absent for other kinds.
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub access: Option<String>,
214    /// The network host the tool wants to reach. Present when `kind` is
215    /// `network`.
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub host: Option<String>,
218    /// The network port, present only on `network` subjects that name one. A
219    /// session grant made from a subject without a port covers every port.
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub port: Option<u16>,
222    /// The network protocol, for example `https`. Present only on `network`
223    /// subjects that name one.
224    #[serde(skip_serializing_if = "Option::is_none")]
225    pub protocol: Option<String>,
226    /// Display text naming the process the tool wants to control. Present when
227    /// `kind` is `process`.
228    #[serde(skip_serializing_if = "Option::is_none")]
229    pub target: Option<String>,
230    /// What triggered the action (a shell command or a URL), for display only
231    /// and untrusted. It is not sent on `shell` subjects, and policy rules
232    /// never match on it.
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub origin: Option<ApprovalOrigin>,
235}
236
237/// The `ApprovalSubject.kind` wire words — one source for the session-view fold
238/// that writes them and every client that inverts them.
239impl ApprovalSubject {
240    /// `shell`: run a shell command. See `command`, `workspaceRoot` and
241    /// `stages`.
242    pub const KIND_SHELL: &'static str = "shell";
243    /// `fileAccess`: a tool wants to read or write a path. This grants access
244    /// to the path; it is not a review of file contents. See `path` and
245    /// `access`.
246    pub const KIND_FILE_ACCESS: &'static str = "fileAccess";
247    /// `network`: a tool wants network access. See `host`, `port` and
248    /// `protocol`.
249    pub const KIND_NETWORK: &'static str = "network";
250    /// `unixSocket`: a command wants to connect to the local Unix socket at
251    /// `path`. Only one-time choices are offered, and no rule is ever saved.
252    pub const KIND_UNIX_SOCKET: &'static str = "unixSocket";
253    /// `process`: a tool wants to control another process. See `target` and
254    /// `access`.
255    pub const KIND_PROCESS: &'static str = "process";
256    /// `tool`: any other tool action, such as an MCP tool call. Show it using
257    /// `toolName` and the request's `rawArgs`.
258    pub const KIND_TOOL: &'static str = "tool";
259    /// `read`: read access to a `fileAccess` path.
260    pub const ACCESS_READ: &'static str = "read";
261    /// `write`: write access to a `fileAccess` path. It does not include read
262    /// access.
263    pub const ACCESS_WRITE: &'static str = "write";
264    /// `control`: control of a `process` target.
265    pub const ACCESS_CONTROL: &'static str = "control";
266}
267
268/// What triggered a tool action, shown so the user can judge it. It is
269/// display-only and untrusted, and policy rules never match on it.
270#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
271#[serde(rename_all = "camelCase")]
272#[non_exhaustive]
273pub struct ApprovalOrigin {
274    /// Which kind of origin this is: `shellCommand` or `url`.
275    pub kind: String,
276    /// The shell command whose process asked for the action. Present when
277    /// `kind` is `shellCommand`.
278    #[serde(skip_serializing_if = "Option::is_none")]
279    pub command: Option<String>,
280    /// The full URL a fetch tool is requesting. Present when `kind` is `url`.
281    #[serde(skip_serializing_if = "Option::is_none")]
282    pub url: Option<String>,
283}
284
285/// One stage of a `shell` approval: a single command from the pipeline or
286/// command list, approved separately from the others.
287#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
288#[serde(rename_all = "camelCase")]
289#[non_exhaustive]
290pub struct ApprovalStage {
291    /// This stage's requirement id. When it equals the approval's
292    /// `currentRequirementId`, send it as `requirementId` in `approval/decide`.
293    pub requirement_id: ApprovalRequirementRef,
294    /// This stage's 1-based position in the command; it equals
295    /// `requirementId.sourceIndex + 1`.
296    pub position: usize,
297    /// The total number of stages in the command.
298    pub total_stages: usize,
299    /// The stage's command words as parsed. When `argvComplete` is `false`,
300    /// this can be a single unparsed piece of the command.
301    pub argv: Vec<String>,
302    /// `true` when `argv` is the stage's complete command, known before it
303    /// runs; `false` when part of it cannot be resolved ahead of time (for
304    /// example a command substitution). A stage with `false` never has a
305    /// `suggestedPrefix`.
306    pub argv_complete: bool,
307    /// Whether this stage still needs a decision or, if not, how it was
308    /// satisfied.
309    pub resolution: ApprovalStageResolution,
310    /// A command prefix the host suggests always allowing in this workspace,
311    /// present only when one can be taken from a fully parsed stage.
312    /// `availableChoices` shows whether that grant is offered.
313    #[serde(skip_serializing_if = "Option::is_none")]
314    pub suggested_prefix: Option<ApprovalSuggestedPrefix>,
315}
316
317/// The `ApprovalOrigin.kind` wire words (same single-source rule).
318impl ApprovalOrigin {
319    /// `shellCommand`: the action came from a shell command's process. See
320    /// `command`.
321    pub const KIND_SHELL_COMMAND: &'static str = "shellCommand";
322    /// `url`: the action fetches a URL. See `url`.
323    pub const KIND_URL: &'static str = "url";
324}
325
326/// Whether a shell stage still needs a decision, or how it was satisfied.
327/// Satisfied stages are included so a client can show progress.
328#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
329#[serde(rename_all = "camelCase")]
330#[non_exhaustive]
331pub struct ApprovalStageResolution {
332    /// One of `unresolved`, `knownSafe`, `policyAllow`, `allowOnce` or
333    /// `policyAmendment`. The set is open, so newer hosts may add values.
334    pub kind: String,
335    /// Free-form text naming the rule or mode that allowed the stage, for
336    /// display or troubleshooting. Present only when `kind` is `policyAllow`.
337    #[serde(skip_serializing_if = "Option::is_none")]
338    pub diagnostic: Option<String>,
339    /// The command prefix saved as an always-allow rule when this stage was
340    /// approved. Present only when `kind` is `policyAmendment`.
341    #[serde(skip_serializing_if = "Option::is_none")]
342    pub argv_prefix: Option<Vec<String>>,
343}
344
345/// The `ApprovalStageResolution.kind` wire words (same single-source rule).
346impl ApprovalStageResolution {
347    /// `unresolved`: the stage still needs a decision.
348    pub const KIND_UNRESOLVED: &'static str = "unresolved";
349    /// `knownSafe`: the stage's command is recognized as safe to run without
350    /// asking.
351    pub const KIND_KNOWN_SAFE: &'static str = "knownSafe";
352    /// `policyAllow`: an existing rule or the session's approval mode already
353    /// allows the stage. See `diagnostic`.
354    pub const KIND_POLICY_ALLOW: &'static str = "policyAllow";
355    /// `allowOnce`: a decision allowed this stage for this request only,
356    /// without saving a rule.
357    pub const KIND_ALLOW_ONCE: &'static str = "allowOnce";
358    /// `policyAmendment`: a decision allowed this stage and saved a
359    /// command-prefix rule. See `argvPrefix`.
360    pub const KIND_POLICY_AMENDMENT: &'static str = "policyAmendment";
361}
362
363/// A suggested always-allow rule for a shell stage: commands starting with
364/// `argvPrefix` would run in this workspace without asking.
365#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
366#[serde(rename_all = "camelCase")]
367#[non_exhaustive]
368pub struct ApprovalSuggestedPrefix {
369    /// The leading command words the rule would allow, for example `["cargo",
370    /// "test"]`.
371    pub argv_prefix: Vec<String>,
372    /// A human-readable label for the suggestion, ready to show as is.
373    pub label: String,
374}