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