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}