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}