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