Control channel: a per-request param_check level, applied and confirmed by the app (#9184) (#9185)

* claim: #9184

* Control channel: a request's own param_check level, applied and confirmed by the app (#9184)

`engine.execute`, `engine.batch` and `engine.script` take an optional
`param_check: "off"|"warn"|"strict"` in their params. The app runs the
request at that level through the same `run_checked` path and batch
preflight a headless session uses, puts its own level back, and every
reply says the level it ran at as `param_check` beside `ok`. A command
that switches designs keeps the app's level; any other word is refused.
Readings and exports answered on a copy off the window thread keep the
level too.

`control.capabilities`, answered at once on the control-server thread,
lists what the channel does beyond the methods every version has:
`{"param_check": ["off", "warn", "strict"]}`. An older app answers
"unknown method".

The MCP bridge asks it once per connection. When the app lists the
level, every call and batch goes with it and the app checks against its
own commands; otherwise the bridge checks before sending, as #9073 does.
At strict, a reply that doesn't say the app checked the call is an error,
and the next calls are checked by the bridge. Also: `add_param_warnings`
takes the reply by `&mut`, and `with_param_check` sits beside
`Remote::new`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Control channel: a design-switching command is checked at the request's level

Review fixes for #9184. `component.edit_in_place`, `component.finish_edit`,
`view.next_tab` and `view.previous_tab` ran at the app's own level and
echoed `off`, so a misspelt call went through at strict. They now have
their parameters checked at the request's level before they run (and
still run at the app's own level, as each design keeps its own), and the
reply echoes the requested level. The MCP bridge at strict now requires
the echo to match its level, not just to be there. `param_check` is read
only by `engine.execute`, `engine.batch` and `engine.script`; other
methods ignore it. The off-thread test now shows the design change
computing off the window thread before it is refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Rick MorgansandClaude Opus 5.5 authored and GitHub committed 2026-10-30 07:24:41 +00:00
1 parent 5d6c5bab39
commit 92af4a21c8
10 files changed
+415 -34

No files matched your search

+20
View File
@@ -129,6 +129,12 @@ turn behind another. `command` is the command id of `engine.execute` (a known on
paths and expressions stay with the connection that sent them. `self` marks the asking
connection's own request. `{"running": []}` when the app is idle.
`control.capabilities` says what this app's control channel does beyond the methods every
version has, so a client can find out before it relies on it: `{"param_check": ["off", "warn",
"strict"]}`, the levels a request's own `param_check` takes (below). It is answered at once, like
`control.running`, also on a `busy` connection. An app older than it answers ``unknown method
`control.capabilities` ``; a feature added later is listed here too.
Any request's `params` may carry `allow_paths: ["/abs/folder", …]`: every file that request
reads, writes or deletes (command paths such as `file.export`'s `path` or `doc.recovery_*`'s
`dir`, `ui.render`, `ui.screenshot`) must then lie inside one of those folders after `..` and
@@ -140,6 +146,20 @@ or saved a design in; each counts on the open design folder's terms. The bridged
MCP server sends its folders this way on every request ([mcp.md](mcp.md)). Without
`allow_paths` file paths are not limited: a client holding the token can do what the user can.
`engine.execute`, `engine.batch` and `engine.script` may carry `param_check: "off" | "warn" |
"strict"` in their `params`: the commands of that request are checked against their typed
contracts at that level, whatever the app's own (which is `off`), as a headless session's
`--param-check` checks them (#9184). `warn` runs a call that breaks its contract and adds
`param_warnings` to its result; `strict` refuses it (a batch before its first step), and the
design is left as it was. Every reply to such a request says the level it was checked at as
`param_check`, beside `ok`. A command that switches to another design (`component.edit_in_place`,
`component.finish_edit`, `view.next_tab`, `view.previous_tab`) has its parameters checked at
that level before it runs, and then runs at the app's own level, as each design keeps its own.
Any other word is refused; other methods ignore the field. An app older than this ignores the field and its reply has no
`param_check`, so a client that needs the check asks `control.capabilities` first and treats a
reply without `param_check` as unchecked. The bridged MCP server asks once per connection
([mcp.md](mcp.md)).
## Engine
| Method | Params | Result |
+11 -5
View File
@@ -71,11 +71,17 @@ are converted; `describe_command` shows a command's schemas) can be checked as t
recipe given with `--in`, and for calls bridged to the app; the default is `off`, which changes
nothing. `warn` runs the call and adds `param_warnings` to its result, such as ``unknown key
`operaton`; did you mean `operation`?`` (a starting script's warnings go to stderr). `strict`
refuses the call, and the design is left as it was. Bridged, the server checks each call (and
each step of a `batch`) against its own commands' contracts before sending it: `strict` sends
nothing that breaks one, and a command the server has no contract for goes to the app unchecked.
Use the server from the same release as the app: an app newer than the server may take keys the
server's contracts don't know yet, and `strict` would refuse them.
refuses the call, and the design is left as it was. Bridged, the server asks the app once per
connection whether it checks a request's own level (`control.capabilities` and `param_check` in
[control-protocol.md](control-protocol.md)). If it does, every call and `batch` is sent with the
level and the app checks it against its own commands, so a newer app's keys are not refused. At
`strict`, a reply that doesn't say the app checked the call at that level is an error (it may
have run unchecked: inspect the design), and the server checks the next calls itself.
An older app is checked here instead, against the server's own commands' contracts, before
anything is sent: `strict` sends nothing that breaks one, and a command the server has no
contract for goes to the app unchecked. With such an app, use the server from the same release:
an app newer than the server may take keys the server's contracts don't know yet, and `strict`
would refuse them.
### Which files the agent can reach