# Desktop modes tool: design

Date: 2026-10-19. Status: implemented (2026-10-19).

## Goal

The quickshell settings window now controls most of the desktop. The
assistant should be able to set some of it too. This first step covers
the quick toggles only: the desktop modes in the status registry
(`~/bin/statusctl`, quickshell repo). Appearance, daemon configs and
lists are out of scope, each its own step later.

This is the first tool that changes something (phase 2 in
`2026-09-26-tools-and-config-design.md`). A mode is one bit and is undone
by asking again, so it applies at once with no confirmation step; the
canvas already shows the `tool` event. Tools that change more than a bit
still need the review step phase 2 describes.

## Tool

`examples/tools/mode.toml`, installed to `~/.config/desktop-assistant/tools/`
like the others. No change to `assistant.py`: the tool format already
passes parameters as argv, with no shell.

```toml
description = "Desktop modes: dnd (do not disturb), presentation (calls, screen sharing), nolock (screen does not lock), quiet (no notification sounds). Read one, or turn it on or off. Changes it immediately; say what changed."
command = ["mode.sh", "{mode}", "{on}"]
timeout = 5

[params.mode]
type = "string"
description = "dnd, presentation, nolock or quiet"

[params.on]
type = "string"
description = "1 to turn on, 0 to turn off. Empty to only read it."
```

`examples/tools/mode.sh`:

- `{on}` empty: read the mode. `0` or `1`: `statusctl <mode> set <on>`,
  then read it back. Anything else: an error naming the accepted values.
- Prints `<mode>: on` or `<mode>: off`, from the read-back, never from
  the request, so a set that did not land reports the real state.
- An unknown mode fails in statusctl, which names the valid ones; the
  model sees that error.
- `presentation` with `status.gaming` at 1: statusctl's own effective
  state is on whatever the manual half says, so the output adds
  `(held on by a running game)`. Setting it still writes the manual half,
  which applies when the game exits.

statusctl writes the registry files, not the shell, and the shell
reapplies each mode's effects from its own watch, so the tool works
whether or not quickshell is up.

## Check

Live, against the running model:

- 10 phrasings, Italian and English: on, off, and "is DND on?". Count
  right tool calls and arguments; after each, `statusctl <mode> get` must
  agree with what the reply said.
- The same set-then-ask sequence after unrelated history. Past tool
  results are placeholders, so the model must call the tool again rather
  than repeat an old state.
- presentation with a game running reports the hold.

## Not included

Night light (hyprsunset has no switch in the registry), the break and
snooze timers, and every settings page. Each can be a further tool file
when wanted.