feat: Add support for action modifier keys like ctrl,shift,alt.

docs/DESIGN.md

@@ -48,6 +48,43 @@ metadata that came in, plus selection context:
 {"label": "beach_sunset.jpg", "sublabel": "/home/maple/walls/nature/", "meta": {"size": "2.4MB"}, "action": "select", "index": 3}
 ```
 
+When `--structured` is used, the output JSON includes a
+`modifiers` field if any modifier keys (shift, ctrl, alt)
+were held during confirmation. The value is an array of
+strings:
+
+```jsonl
+{"label": "firefox", "action": "select", "index": 0, "modifiers": ["shift"]}
+{"label": "alacritty", "action": "select", "index": 2, "modifiers": ["ctrl", "alt"]}
+```
+
+When no modifiers are held, the field is omitted entirely.
+Plain text output is unchanged: modifiers only appear in
+structured JSON.
+
+### Working with Structured Output
+
+Check for shift modifier with jq:
+
+```sh
+pikl --structured | jq 'if (.modifiers // [] | contains(["shift"])) then "alternate" else "default" end'
+```
+
+Extract a field:
+
+```sh
+pikl --structured | jq -r '.label'
+```
+
+Branch on modifiers in a script:
+
+```sh
+result=$(echo -e "a\nb\nc" | pikl --structured)
+if echo "$result" | jq -e '.modifiers // [] | contains(["shift"])' > /dev/null 2>&1; then
+    echo "shift was held"
+fi
+```
+
 ### Streaming
 
 Input can arrive over time. The list populates progressively
@@ -96,6 +133,12 @@ There are two ways to respond to them: **exec hooks** and
 | `on-filter` | Filter text changes | Dynamic item reloading |
 | `on-toggle` | User toggles an item's selection | Visual feedback (deferred) |
 
+Hook event JSON includes a `modifiers` field on `select`,
+`cancel`, `filter`, `hover`, and `quicklist` events when
+modifier keys were held. Same format as structured output:
+an array of strings like `["shift"]` or `["ctrl", "alt"]`.
+Omitted when no modifiers are active.
+
 ### Exec Hooks (fire-and-forget)
 
 `--on-<event>-exec` spawns a subprocess for each event.
@@ -770,6 +813,18 @@ Available actions:
 | `show-tui` | (none) | Hand off to TUI specifically |
 | `show-gui` | (none) | Hand off to GUI specifically |
 
+Actions can include modifier key prefixes with `+`:
+
+```
++shift confirm
++ctrl+alt move-down 3
+```
+
+Valid modifiers: `shift`, `ctrl`, `alt`. Multiple modifiers
+chain with `+`. Lines without a `+` prefix work exactly as
+before. This lets scripts signal intent to hooks and
+structured output the same way a user holding Shift would.
+
 `show-ui` auto-detects the appropriate interactive frontend
 (Wayland: GUI, X11: GUI, otherwise: TUI). `show-tui` and
 `show-gui` are explicit overrides. All three must be the