better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/hooks.md

@@ -0,0 +1,257 @@
+<!--
+source: https://omp.sh/docs/hooks
+fetched: 2026-09-06
+-->
+
+# Hooks
+
+> Run trusted TypeScript at well-defined points in an omp session: prevent risky actions, transform context or tool results, and react to lifecycle events.
+
+## Start with a force-push guard
+
+Hooks let you apply a local policy every time omp works: stop a dangerous command before it runs, redact output before it reaches the model, add context to a turn, or record session activity. A hook is a trusted TypeScript or JavaScript module that subscribes to public events.
+
+This project hook blocks `git push --force` while still allowing `--force-with-lease`:
+
+```ts
+// .omp/hooks/pre/force-push.ts
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+} from "@oh-my-pi/pi-coding-agent";
+
+const FORCE_PUSH = /\bgit\s+push\b[^\n]*(?:--force(?:\s|$)|(?:^|\s)-f(?:\s|$))/;
+
+export default function forcePushGuard(pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.notify("Force-push guard active", "info");
+  });
+
+  pi.on("tool_call", (event) => {
+    if (!isToolCallEventType("bash", event)) return;
+    if (!FORCE_PUSH.test(event.input.command)) return;
+
+    return {
+      block: true,
+      reason: "Blocked git push --force; use --force-with-lease after reviewing the remote branch.",
+    };
+  });
+}
+```
+
+Create the directory, save the file, and start a new `omp` session from that project. The startup notification confirms the handler ran. Open `/extensions` to see the resolved file and its source.
+
+To test a loose file without installing it, pass it explicitly:
+
+```sh
+omp --hook /absolute/path/to/force-push.ts
+```
+
+Then ask:
+
+> Run `git push --force` in this throwaway repository.
+
+The command must not run. omp shows the hook's reason as the tool error, and the agent can choose a safer next step. Use a throwaway repository for policy tests in case the hook contains a mistake.
+
+> Hooks execute as your user and can inspect prompts, tool inputs, results, credentials metadata, and session state. Only load code you trust.
+
+## Install a loose hook
+
+omp automatically discovers direct `.ts` and `.js` files in these directories:
+
+| Scope | Directory |
+| --- | --- |
+| Current project | `.omp/hooks/pre/` and `.omp/hooks/post/` under the session's working directory |
+| Current user profile | `~/.omp/profiles/<name>/agent/hooks/pre/` and `post/` for a named profile; `~/.omp/agent/hooks/pre/` and `post/` for the default profile |
+
+Discovery is not recursive. A file such as `.omp/hooks/pre/team/guard.ts` is ignored. Start a new session after adding or changing a hook.
+
+`pre` and `post` are organization and discovery namespaces; they do not automatically select an event or tool. A file in `pre/` may subscribe to any event, and a filename such as `bash.ts` does not automatically filter calls. Register the event and perform any `toolName` check in code. Conventionally, put gates and input transforms in `pre/`, and observers or result transforms in `post/`.
+
+For a one-session load, use either `--hook <path>` or `--extension <path>`; the flags feed the same module-loading surface. A relative path resolves from the session working directory. To keep an explicit hook enabled, add its absolute path to `extensions` in `~/.omp/agent/config.yml`:
+
+```yaml
+extensions:
+  - /absolute/path/to/force-push.ts
+```
+
+Check the effective set with `/extensions` interactively or `omp -p '/extensions'` from the shell.
+
+## The module contract
+
+A current hook module default-exports a synchronous or asynchronous factory that receives `ExtensionAPI`. Register handlers while the factory loads:
+
+```ts
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function myHook(pi: ExtensionAPI) {
+  pi.on("turn_end", async (event, ctx) => {
+    pi.logger.debug("turn completed", {
+      cwd: ctx.cwd,
+      turn: event.turnIndex,
+    });
+  });
+}
+```
+
+The handler receives `(event, ctx)`. `event` is the typed payload in the tables below. Frequently useful context members are:
+
+| Member | Meaning |
+| --- | --- |
+| `ctx.cwd` | Current session working directory. |
+| `ctx.mode` | `"tui"`, `"rpc"`, `"json"`, or `"print"`. |
+| `ctx.hasUI`, `ctx.ui` | Whether interactive UI is available, plus notifications, prompts, status, widgets, and other UI methods. Guard interactive calls with `hasUI` or `mode === "tui"`. |
+| `ctx.model`, `ctx.models` | Current model and the read-only model query surface. |
+| `ctx.sessionManager` | Read-only session access. Use `pi.sendMessage()` or `pi.appendEntry()` for supported writes. |
+| `ctx.isIdle()`, `ctx.hasPendingMessages()`, `ctx.abort()` | Current run state and cancellation control. |
+| `ctx.getContextUsage()`, `ctx.getSystemPrompt()` | Current context usage and effective system-prompt lines. |
+| `ctx.setTimeout()`, `ctx.setInterval()`, `ctx.clearTimer()` | Session-owned timers whose errors are contained and which are cleared at shutdown. |
+
+Use the exported TypeScript types rather than copying nested payload types into your hook. In particular, tool inputs and details are discriminated unions; `isToolCallEventType("bash", event)` narrows a built-in tool safely.
+
+## Events that can change behavior
+
+Payload columns list the public top-level fields in addition to `type`. A bare return leaves behavior unchanged.
+
+| Event | Payload | Handler return and combination behavior |
+| --- | --- | --- |
+| `resources_discover` | `cwd`, `reason: "startup" \| "reload"` | `{ skillPaths?, promptPaths?, themePaths? }`. Paths from every handler are accumulated. |
+| `input` | `text`, `images?`, `source: "interactive" \| "rpc" \| "extension"` | `{ text?, images?, handled? }`. Transforms chain; `handled: true` stops normal input processing and later handlers. |
+| `user_bash` | `command`, `excludeFromContext`, `cwd` | `{ result }` to replace execution. The first handler that returns a result wins. This observes user-entered `!`/`!!` commands, not model tool calls. |
+| `user_python` | `code`, `excludeFromContext`, `cwd` | `{ result }` to replace execution. The first handler that returns a result wins. This observes user-entered `$`/`$$` code. |
+| `tool_call` | `toolName`, `toolCallId`, typed `input` | `{ block?, reason?, input? }`. The first block stops dispatch. Otherwise the last returned result wins; all handlers see the original event input. Replacement `input` on a model-issued call is revalidated and becomes what omp displays, approves, persists, and executes. It is ignored for blocked calls and not applied to `computer` calls. |
+| `tool_result` | `toolName`, `toolCallId`, `input`, `content`, `details`, `isError` | `{ content?, details?, isError? }`. Changes chain field by field, and later handlers see earlier changes. A hook may rewrite success or failure output and may change the final error state. |
+| `context` | `messages` about to be sent to the model | `{ messages }`. Replacements chain. This changes only that model call, not stored session messages. |
+| `before_provider_request` | opaque `payload` | Return the replacement provider payload directly. Replacements chain. This is an advanced provider-specific seam; a malformed payload can break the request. |
+| `before_agent_start` | `prompt`, `images?`, current `systemPrompt` lines | `{ message?, systemPrompt? }`. Every returned message is added; system-prompt replacements chain. The custom message is persisted and visible according to its `display` field. |
+| `session_before_switch` | `reason: "new" \| "resume" \| "fork"`, `targetSessionFile?` | `{ cancel: true }` stops the switch. First cancellation wins. |
+| `session_before_branch` | `entryId` | `{ cancel?, skipConversationRestore? }`. First cancellation wins; otherwise the latest returned result applies. |
+| `session_before_compact` | `preparation`, `branchEntries`, `customInstructions?`, `signal` | `{ cancel?, compaction? }`. Cancel or provide a complete custom compaction result; first cancellation wins, otherwise the latest result applies. |
+| `session.compacting` | `sessionId`, `messages` | `{ context?, prompt?, preserveData? }`. The latest returned result replaces earlier results. Use this to customize normal compaction without constructing a complete compaction result. |
+| `session_before_tree` | `preparation`, `signal` | `{ cancel?, summary? }`. First cancellation wins; otherwise the latest result applies. A custom summary is used only when `preparation.userWantsSummary` is true. |
+| `session_stop` | `messages`, `turn_id`, `last_assistant_message?`, `session_id`, `session_file?`, `stop_hook_active`, `signal` | `{ continue: true, additionalContext }` or `{ decision: "block", reason }` requests one model-visible continuation. The first actionable continuation with non-empty context/reason wins. |
+
+### Tool interception details
+
+`tool_call` is the pre-execution policy seam. Its `event.input` is a normalized view intended for inspection; an `input` returned by the handler must instead be the complete raw argument object the tool executes. Do not copy normalized, gate-only fields into a replacement. If you only need to deny an action, return `block` and avoid rewriting input.
+
+A revised call still goes through the normal tool schema and approval policy. The user therefore approves the arguments that will actually run. Hooks supplement omp's approval settings; they do not bypass them.
+
+`tool_result` runs after both successful and failed executions. Text and image blocks live in `content`; tool-specific metadata lives in `details`. Prefer returning new content objects rather than mutating the event in place.
+
+## Notification events
+
+Returns from these events are ignored. The payload is still typed, so a hook can log, update UI, persist its own state, or enqueue a supported message.
+
+### Session and agent lifecycle
+
+| Event | Payload and timing |
+| --- | --- |
+| `session_start` | No additional fields; initial session load. |
+| `session_switch` | `reason`, `previousSessionFile`; after a new, resumed, or forked session becomes active. |
+| `session_branch` | `previousSessionFile`; after branching. |
+| `session_compact` | `compactionEntry`, `fromExtension`; after compaction. |
+| `session_tree` | `newLeafId`, `oldLeafId`, `summaryEntry?`, `fromExtension?`; after tree navigation. |
+| `session_shutdown` | No additional fields; process shutdown. Use it for short cleanup only. |
+| `agent_start` | No additional fields; once per submitted prompt when an agent loop begins. |
+| `agent_end` | `messages`, `willContinue?`; loop end. `willContinue` means an automatic continuation is already scheduled. |
+| `turn_start` | `turnIndex`, `timestamp`; start of one model/tool turn. |
+| `turn_end` | `turnIndex`, final `message`, `toolResults`; end of one turn. |
+| `message_start` | `message`; a user, assistant, or tool-result message started. |
+| `message_update` | current `message`, `assistantMessageEvent`; streaming assistant updates. This can be high-volume. |
+| `message_end` | detached `message` snapshot; notification only. Mutating it does not rewrite model or session context. |
+
+### Tool execution and approvals
+
+| Event | Payload and timing |
+| --- | --- |
+| `tool_execution_start` | `toolCallId`, `toolName`, `args`, `intent?`; execution begins after pre-call processing. |
+| `tool_execution_update` | `toolCallId`, `toolName`, `args`, `partialResult`; streaming progress. This can be high-volume. |
+| `tool_execution_end` | `toolCallId`, `toolName`, `result`, `isError`; execution completed. Use `tool_result`, not this event, to rewrite what the model receives. |
+| `tool_approval_requested` | `sessionId`, `toolCallId`, `toolName`, `reason?`, `approvalMode`; omp is about to ask for approval. |
+| `tool_approval_resolved` | `sessionId`, `toolCallId`, `toolName`, `approved`, `reason?`; approval was accepted or denied. |
+
+### Maintenance, retry, and integrations
+
+| Event | Payload and timing |
+| --- | --- |
+| `auto_compaction_start` | `reason`, `action`; automatic compaction began. |
+| `auto_compaction_end` | `action`, `result`, `aborted`, `willRetry`, `errorMessage?`, `skipped?`; automatic compaction settled. |
+| `auto_retry_start` | `attempt`, `maxAttempts`, `delayMs`, `errorMessage`, `errorId?`; a retry wait began. |
+| `auto_retry_end` | `success`, `attempt`, `finalError?`, `retryErrors?`; retry sequence settled. |
+| `retry_fallback_applied` | `from`, `to`, `role`; retry switched model/provider. |
+| `retry_fallback_succeeded` | `model`, `role`; a request succeeded on the fallback. |
+| `ttsr_triggered` | matched `rules`; generation was interrupted by a TTSR rule. |
+| `todo_reminder` | `todos`, `attempt`, `maxAttempts`; unfinished-todo reminder logic ran. |
+| `goal_updated` | `goal` or `null`, `state?`; goal-mode state changed. |
+| `credential_disabled` | `provider`, `disabledCause`; omp automatically soft-disabled a failing credential. It is not emitted for a user removal or credential deduplication. |
+| `mcp_notification` | raw configured `server` name, JSON-RPC `method`, opaque `params`; emitted after omp handles known MCP notifications and also for server-specific methods. |
+| `after_provider_response` | `status`, `headers`, `requestId?`, `metadata?`; response metadata is available before the stream body is consumed. There is no response body in this event. |
+
+## Ordering, timeouts, and errors
+
+Within one module, handlers run in registration order. Except for `session_shutdown`, event handlers are awaited one at a time. Across modules, handlers follow the resolved load order, but directory enumeration and capability deduplication are not a public priority mechanism. Do not use filename prefixes such as `00-` and `99-` to build correctness dependencies across hook files; combine dependent handlers in one module instead.
+
+A duplicate discovered hook key can shadow a lower-priority provider's hook. Use distinctive filenames in packages. An explicitly listed path is deduplicated by its resolved absolute path, so the same module is not intentionally loaded twice.
+
+Most handlers have a 30-second active-work budget. `tool_call` uses the configurable `extensionHandlers.toolCallTimeoutMs` setting, also 30 seconds by default:
+
+```yaml
+extensionHandlers:
+  toolCallTimeoutMs: 10000
+```
+
+A `tool_call` exception or timeout fails closed: omp blocks the call and reports which extension failed or timed out. Other event exceptions and timeouts are reported as extension errors, that handler contributes no result, and later handlers continue. `session_shutdown` handlers run concurrently with a two-second budget so cleanup cannot hold the process open.
+
+At load time, a syntax/import error, a thrown factory, or a missing default factory prevents that module from loading; omp continues loading other modules. Use `/extensions` to identify the missing path, then restart with `--log-level debug` for the load error.
+
+## Package and share hooks
+
+For a reusable hook-only package, keep the conventional directory and declare the hook as a package entry. This makes direct directory loading work while installed-plugin discovery can also find the `hooks/` surface:
+
+```text
+force-push-guard/
+  package.json
+  hooks/
+    pre/
+      force-push.ts
+```
+
+```json
+{
+  "name": "@acme/force-push-guard",
+  "version": "1.0.0",
+  "omp": {
+    "extensions": ["./hooks/pre/force-push.ts"]
+  }
+}
+```
+
+Test the directory before publishing:
+
+```sh
+omp --hook ./force-push-guard
+```
+
+For regular local use, install it as a plugin:
+
+```sh
+omp install ./force-push-guard
+# Project scope instead of user scope:
+omp install -l ./force-push-guard
+```
+
+`omp install` accepts local paths, npm packages, Git repositories, and marketplace entries. Package imports must be resolvable from the installed package, and every runtime file must be included in the published artifact. Keep secrets and machine-specific policy in user or project configuration rather than committing them into a public package.
+
+See [Authoring extensions](/docs/extension-authoring) for multi-entry packages and [Plugins](/docs/plugins) for installation, scope, updates, and publishing.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Hook missing from `/extensions` | The file must be a direct `.ts` or `.js` child of `hooks/pre` or `hooks/post`, or be passed explicitly. Project discovery uses the session's working directory; user discovery uses the active profile. |
+| Hook appears but a handler never runs | Directory and filename do not select events. Confirm the exact `pi.on("event_name", ...)` registration and any `toolName` filter. |
+| Startup reports an invalid extension | Export one default factory function and fix its import/syntax error. Run with `--log-level debug` to see the failing path. |
+| UI calls disappear in print or RPC mode | Check `ctx.hasUI` or `ctx.mode` before prompting or rendering. Use logging or persisted state for headless modes. |
+| A tool is blocked with an extension failure | A `tool_call` handler threw or exceeded its timeout. Fix the hook rather than raising the timeout first; gates fail closed by design. |
+| Two hooks disagree | Put ordering-dependent logic in one module. For independent modules, remember: first block wins, result/context transforms chain as documented above, and many session result events use the latest returned result. |

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/keybindings.md

@@ -0,0 +1,204 @@
+<!--
+source: https://omp.sh/docs/keybindings
+fetched: 2026-09-06
+-->
+
+# Keybindings
+
+> The shortcuts that control an omp session, where they apply, and how to remap them.
+
+Keybindings let you send or queue prompts, interrupt work, navigate the editor, and open common session controls without leaving the keyboard. Start with the small set below; use `/hotkeys` when you forget a chord.
+
+## First-session shortcuts
+
+| Key | What it does |
+| --- | --- |
+| <kbd>Enter</kbd> | Send the prompt. While omp is working, this sends a steering message to the active turn. |
+| <kbd>Shift</kbd>+<kbd>Enter</kbd>, <kbd>Ctrl</kbd>+<kbd>J</kbd>, or <kbd>Alt</kbd>+<kbd>Enter</kbd> | Insert a newline instead of sending. |
+| <kbd>Ctrl</kbd>+<kbd>Q</kbd> or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> | Queue a follow-up for after the current turn finishes. |
+| <kbd>Escape</kbd> | Dismiss autocomplete or interrupt the active operation. |
+| <kbd>Ctrl</kbd>+<kbd>O</kbd> | Expand or collapse tool output. |
+| <kbd>Ctrl</kbd>+<kbd>R</kbd> | Search prompt history. |
+| <kbd>Ctrl</kbd>+<kbd>C</kbd> | Clear the editor. Press it again within half a second to exit. |
+| <kbd>Ctrl</kbd>+<kbd>D</kbd> | Exit immediately; a non-empty prompt is saved as a resumable draft. |
+| <kbd>Alt</kbd>+<kbd>A</kbd> | Open the Agent Hub. |
+
+## Discover the active shortcuts
+
+Enter this in any interactive session:
+
+```text
+/hotkeys
+```
+
+The resulting table uses your platform's key names and resolves application remaps from the active `keybindings.yml`. For example, macOS displays `Option` and `Cmd` where the configuration syntax uses `alt` and `super`.
+
+`/hotkeys` is a quick everyday list, not the complete configuration registry. Its editor navigation rows describe the standard defaults, and extension-added shortcuts are not appended to it. Use the action tables below when remapping editor or selection controls.
+
+## Where a shortcut applies
+
+The focused surface decides what a key means. Reusing a key in separate contexts is normal: <kbd>Ctrl</kbd>+<kbd>O</kbd> expands tool output in the transcript but cycles filters inside `/tree`, for example.
+
+| Context | Controls |
+| --- | --- |
+| Main prompt editor | Application actions (`app.*`) plus editor actions (`tui.editor.*` and `tui.input.*`). |
+| Autocomplete, history, and most pickers | Selection actions (`tui.select.*`): arrows move, <kbd>PageUp</kbd>/<kbd>PageDown</kbd> page, <kbd>Enter</kbd> confirms, and <kbd>Escape</kbd> cancels. |
+| `@` file picker | Type to fuzzy-filter project files, use <kbd>Up</kbd>/<kbd>Down</kbd>, accept with <kbd>Tab</kbd>, and dismiss with <kbd>Escape</kbd>. |
+| Plan approval | <kbd>Escape</kbd> cancels approval and returns to [plan-mode iteration](/docs/plan). |
+
+### Full-screen surfaces
+
+These pages add controls specific to the surface. Their fixed controls are not separate action IDs in `keybindings.yml`; remappable selection and interrupt actions still apply where shown.
+
+| Surface | Controls |
+| --- | --- |
+| `/tree` | <kbd>Up</kbd>/<kbd>Down</kbd> move; <kbd>Alt</kbd>+<kbd>Up</kbd>/<kbd>Down</kbd> jump between user or assistant turns; <kbd>Left</kbd>/<kbd>Right</kbd> or <kbd>PageUp</kbd>/<kbd>PageDown</kbd> page; <kbd>Home</kbd>/<kbd>End</kbd> jump to the first/last visible item; <kbd>Enter</kbd> selects; <kbd>Shift</kbd>+<kbd>Enter</kbd> summarizes and switches directly; <kbd>Ctrl</kbd>+<kbd>O</kbd>/<kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>O</kbd> cycle filters; <kbd>Escape</kbd> clears search, then closes. |
+| `/extensions` | <kbd>Tab</kbd>/<kbd>Shift</kbd>+<kbd>Tab</kbd> or <kbd>Left</kbd>/<kbd>Right</kbd> switch provider tabs; arrows or <kbd>j</kbd>/<kbd>k</kbd> move; <kbd>Space</kbd> or <kbd>Enter</kbd> toggles the selected row; typing filters; <kbd>Escape</kbd> clears the filter, then closes; <kbd>Ctrl</kbd>+<kbd>C</kbd> closes immediately. |
+| `/agents` | <kbd>Tab</kbd>/<kbd>Shift</kbd>+<kbd>Tab</kbd> or <kbd>Left</kbd>/<kbd>Right</kbd> switch between scope and list; arrows move; <kbd>Enter</kbd> opens or activates; <kbd>Space</kbd> toggles the selected agent when the search is empty; typing filters; <kbd>Ctrl</kbd>+<kbd>R</kbd> reloads; <kbd>Escape</kbd> clears the filter, then closes. |
+| Agent Hub | Arrows or <kbd>j</kbd>/<kbd>k</kbd> select; <kbd>Enter</kbd> opens an agent; <kbd>t</kbd> toggles flat/tree views; <kbd>Tab</kbd> shows the inspector on narrow terminals; <kbd>r</kbd> revives a parked agent; <kbd>x</kbd> kills and releases an agent; <kbd>Escape</kbd> closes the inspector, then the Hub. |
+
+## Complete application defaults
+
+These action IDs control the main omp session. An **Unbound** action works once you assign it a chord.
+
+| Action ID | Default | User-visible action |
+| --- | --- | --- |
+| `app.interrupt` | `escape` | Cancel autocomplete or interrupt active work. |
+| `app.clear` | `ctrl+c` | Clear the editor; a second press within 500 ms exits. |
+| `app.exit` | `ctrl+d` | Exit and save the current prompt as a draft. |
+| `app.suspend` | `ctrl+z` | Suspend omp on POSIX systems; resume with `fg`. |
+| `app.display.reset` | `alt+l` | Reset and repaint the terminal display. |
+| `app.thinking.cycle` | `shift+tab` | Cycle the thinking level. |
+| `app.thinking.toggle` | `ctrl+t` | Show or hide thinking blocks. |
+| `app.model.cycleForward` | `ctrl+p` | Cycle role models forward: slow, default, smol. |
+| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle role models backward. |
+| `app.model.selectTemporary` | `alt+p` | Choose a temporary model for this session. |
+| `app.model.select` | `alt+m` | Open the model selector and set model roles. |
+| `app.tools.expand` | `ctrl+o` | Expand or collapse tool output. |
+| `app.tools.toggleVisibility` | `ctrl+shift+o` | Show or hide tool activity. |
+| `app.editor.external` | `ctrl+g` | Edit the draft with `$VISUAL`, falling back to `$EDITOR`. |
+| `app.message.followUp` | `ctrl+q`, `ctrl+enter` | Queue a follow-up message. |
+| `app.retry` | `alt+r` | Retry the last failed assistant turn. |
+| `app.message.dequeue` | `alt+up`, `shift+up` | Move the most recently queued message back into the editor. |
+| `app.clipboard.pasteImage` | Linux: `ctrl+v`; macOS: `ctrl+v`, `super+v`; Windows: `ctrl+v`, `alt+v` | Paste an image from the clipboard, or text when no image is present. |
+| `app.clipboard.pasteTextRaw` | `ctrl+shift+v`, `alt+shift+v` | Paste text without collapsing a large paste. |
+| `app.clipboard.copyLine` | `alt+shift+l` | Copy the current prompt line. |
+| `app.clipboard.copyPrompt` | `alt+shift+c` | Copy the whole prompt. |
+| `app.agents.hub` | `alt+a` | Open or close the Agent Hub. |
+| `app.session.observe` | `ctrl+s` | Open or close the Agent Hub using the legacy session-observe chord. |
+| `app.session.new` | Unbound | Start a new session, like `/new`. |
+| `app.session.tree` | Unbound | Open the session tree. |
+| `app.session.fork` | Unbound | Open the message picker used to fork the session. |
+| `app.session.resume` | Unbound | Open the session resume picker. |
+| `app.plan.toggle` | `alt+shift+p` | Toggle plan mode. |
+| `app.history.search` | `ctrl+r` | Search prompt history. |
+| `app.stt.toggle` | Unbound | Toggle speech-to-text recording. By default, hold <kbd>Space</kbd> to record and release it to transcribe when speech-to-text is enabled. |
+| `app.live.toggle` | `ctrl+l` | Start or stop live voice mode, like `/live`. |
+
+Double-tapping <kbd>Left</kbd> in an empty editor also opens the Agent Hub when there is an agent to show. That gesture is fixed rather than a remappable action.
+
+## Complete editor and picker defaults
+
+### Editor navigation and editing
+
+| Action ID | Default | Action |
+| --- | --- | --- |
+| `tui.editor.cursorUp` | `up` | Move the cursor up; in an empty main editor, browse older prompt history. |
+| `tui.editor.cursorDown` | `down` | Move the cursor down or browse newer prompt history. |
+| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move left one character. |
+| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move right one character. |
+| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move left one word. |
+| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move right one word. |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+a` | Move to the start of the line. |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+e` | Move to the end of the line. |
+| `tui.editor.jumpForward` | `ctrl+]` | Read a character, then jump forward to it. |
+| `tui.editor.jumpBackward` | `ctrl+alt+]` | Read a character, then jump backward to it. |
+| `tui.editor.pageUp` | `pageUp` | Move up one editor page. |
+| `tui.editor.pageDown` | `pageDown` | Move down one editor page. |
+| `tui.editor.deleteCharBackward` | `backspace` | Delete the character before the cursor. |
+| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete the character after the cursor. In the main omp editor, `app.exit` takes `ctrl+d`, so use <kbd>Delete</kbd>. |
+| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace`, `ctrl+backspace`, `super+alt+backspace` | Delete the previous word. |
+| `tui.editor.deleteWordForward` | `alt+delete`, `alt+d`, `super+alt+delete`, `super+alt+d` | Delete the next word. |
+| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to the start of the line. |
+| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to the end of the line. |
+| `tui.editor.yank` | `ctrl+y` | Insert the most recently deleted text. |
+| `tui.editor.yankPop` | `alt+y` | Replace the last yank with the previous deleted-text entry. |
+| `tui.editor.undo` | `ctrl+-`, `ctrl+_` | Undo the last edit. |
+| `tui.editor.spellingSuggestions` | `ctrl+.` | Show spelling replacements. |
+
+### Generic input and selection
+
+| Action ID | Default | Action |
+| --- | --- | --- |
+| `tui.input.newLine` | `shift+enter`, `ctrl+j` | Insert a newline. <kbd>Alt</kbd>+<kbd>Enter</kbd> is also a built-in newline fallback. |
+| `tui.input.submit` | `enter` | Submit the input. |
+| `tui.input.tab` | `tab` | Tab or accept autocomplete. |
+| `tui.input.copy` | `ctrl+c` | Copy a selection in inputs that support selection. |
+| `tui.select.up` | `up` | Move a picker selection up. |
+| `tui.select.down` | `down` | Move a picker selection down. |
+| `tui.select.pageUp` | `pageUp` | Move a picker selection up one page. |
+| `tui.select.pageDown` | `pageDown` | Move a picker selection down one page. |
+| `tui.select.confirm` | `enter` | Confirm a picker selection. |
+| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel a picker. |
+
+## Remap shortcuts
+
+Keybindings are separate from the main settings file:
+
+- Default profile: `~/.omp/agent/keybindings.yml`
+- Named profile: `~/.omp/profiles/<name>/agent/keybindings.yml`
+- Custom default-profile agent directory: `$PI_CODING_AGENT_DIR/keybindings.yml`
+
+A named profile inherits the default profile's bindings, then overrides them action by action. See [Settings](/docs/settings) for profile and directory configuration.
+
+Create the file if it does not exist. It is a YAML mapping from an exact action ID to one chord, an array of chords, or an empty array:
+
+```yaml
+# ~/.omp/agent/keybindings.yml
+app.model.cycleForward: f6
+app.plan.toggle: f7
+tui.editor.undo: [ctrl+-, ctrl+_]
+app.history.search: []
+```
+
+A remap **replaces** that action's complete default list; it does not add to it. Repeat any defaults you want to retain. An empty array disables the action.
+
+Restart `omp` after saving the file. Run `/hotkeys` to verify application actions such as `app.model.cycleForward`; exercise the key directly to verify editor and picker actions, whose `/hotkeys` rows remain a compact defaults guide.
+
+### Chord syntax
+
+- Chords are simultaneous keys joined by `+`, such as `ctrl+p`, `alt+shift+p`, or `ctrl+backspace`. Multi-step sequences are not supported.
+- Names are case-insensitive. Lowercase is recommended in authored files.
+- Modifiers are `ctrl`, `shift`, `alt`, and `super`. On macOS, `alt` means Option and `super` means Command.
+- Base keys include letters, digits, punctuation, arrows, `home`, `end`, `pageUp`, `pageDown`, `backspace`, `delete`, `insert`, `enter`, `escape`, `tab`, `space`, and `f1` through `f12`.
+- `esc` is accepted as an alias for `escape`; `return` is accepted as an alias for `enter`.
+- Avoid assigning the same chord to multiple actions in the same context. Which one wins can depend on the focused surface.
+
+Legacy unqualified action names are migrated when loaded. A legacy `keybindings.json` is migrated to `keybindings.yml`; `keybindings.yaml` is also accepted. New configuration should use `keybindings.yml` and the namespaced IDs in this page.
+
+## Platform and terminal notes
+
+- **macOS:** write `alt` and `super` in YAML even though omp displays Option and Cmd. Some terminal profiles use Option for character composition and do not deliver <kbd>Option</kbd>+<kbd>Up</kbd>; use the <kbd>Shift</kbd>+<kbd>Up</kbd> dequeue fallback.
+- **Windows:**<kbd>Ctrl</kbd>+<kbd>Z</kbd> cannot suspend omp. Windows Terminal does not deliver a distinct <kbd>Ctrl</kbd>+<kbd>Enter</kbd>, so use <kbd>Ctrl</kbd>+<kbd>Q</kbd> for follow-ups. If it captures <kbd>Ctrl</kbd>+<kbd>V</kbd>, use <kbd>Alt</kbd>+<kbd>V</kbd> for clipboard images.
+- **Newlines:** if a terminal cannot distinguish <kbd>Shift</kbd>+<kbd>Enter</kbd> from <kbd>Enter</kbd>, use <kbd>Ctrl</kbd>+<kbd>J</kbd> or <kbd>Alt</kbd>+<kbd>Enter</kbd>.
+- **Terminal-owned keys:** your terminal, multiplexer, desktop, or shell may intercept a chord before omp receives it. Change that terminal binding or choose another omp chord.
+
+## Troubleshooting
+
+### A remap does not take effect
+
+1. Confirm you edited `keybindings.yml` in the active profile's agent directory, not `config.yml`.
+2. Confirm the action ID exactly matches a table entry; action IDs are case-sensitive.
+3. Restart `omp`. Keybindings are loaded when the interactive session starts.
+4. Check that the YAML value is a string, array of strings, or `[]`.
+5. Run `/hotkeys` for an application action, or exercise an editor/picker action directly.
+
+### A chord still does nothing
+
+Try one of the documented fallback chords. If the fallback works, the terminal is probably consuming or normalizing the original chord. This is common for <kbd>Ctrl</kbd>+<kbd>Enter</kbd>, <kbd>Shift</kbd>+<kbd>Enter</kbd>, Option combinations, and clipboard keys.
+
+Also check the rest of `keybindings.yml` for the same chord. Assigning it to two actions in one context creates an ambiguous remap.
+
+### The key does something different
+
+Check the focused surface. Editor, picker, `/tree`, `/extensions`, `/agents`, and Agent Hub controls are context-sensitive. Press <kbd>Escape</kbd> to close the current overlay, then retry the shortcut in the main prompt editor. See [Slash commands](/docs/slash) for command alternatives to common shortcuts.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/magic-keywords.md

@@ -0,0 +1,135 @@
+<!--
+source: https://omp.sh/docs/magic-keywords
+fetched: 2026-09-06
+-->
+
+# Magic keywords
+
+> Steer one prompt toward deeper reasoning or coordinated parallel work with an exact standalone word.
+
+Magic keywords are optional, one-turn shortcuts. Put a recognized standalone word in a normal prompt when you want omp to change how it approaches **that prompt** without switching on a persistent mode.
+
+Start with the behavior you need:
+
+```text
+ultrathink about the failure modes before changing this public API
+
+orchestrate the migration across the server, client, and tests
+
+workflowz perform an adversarial review of authentication, authorization, and session handling
+```
+
+The word remains part of your visible message. In the terminal editor, omp paints a recognized occurrence with a moving gradient while the editor is focused; the sent message uses a static gradient. This is a recognition aid, not confirmation that the keyword's behavior is enabled or that its required tools are available.
+
+## Choose a keyword
+
+| Keyword | Use it when… | What to expect |
+| --- | --- | --- |
+| `ultrathink` | A decision, diagnosis, or risky change deserves especially careful reasoning. | omp asks for a careful multi-step approach. If automatic thinking is active, this turn also uses the highest reasoning effort supported by the current model. |
+| `orchestrate` | A substantial task has independent work that can profitably run in parallel. | omp scopes the task, delegates suitable independent parts to subagents, integrates the results, and verifies the work. |
+| `workflowz` | Broad research, a review, migration, or adversarial analysis benefits from an explicit, deterministic multi-agent workflow. | omp builds a structured workflow with parallel and staged subagent work, then synthesizes the results. |
+
+These words steer execution; they do not guarantee a particular answer or a fixed number of workers. A small or tightly coupled request may have little useful parallel work. `workflowz` is the more explicit workflow-building choice; `orchestrate` is the general-purpose delegation choice.
+
+## Scope: one submitted prompt
+
+A keyword affects only the turn whose submitted user message contains it. It does not become session state and does not carry into the next prompt.
+
+```text
+orchestrate inspect the three independent packages and fix their failing builds
+```
+
+The orchestration request applies to that turn, including the work omp performs to finish it. A later prompt such as “Now update the release notes” is normal unless you include a keyword again. Multiple enabled keywords in one prompt can all apply, although combining them may add cost without improving the result; usually choose the single best fit.
+
+## Exact matching rules
+
+Matching is case-sensitive and deliberately excludes code-like contexts. Use the exact lowercase spelling as standalone prose.
+
+**Matches:**
+
+```text
+Please ultrathink before choosing a migration strategy.
+"orchestrate" the independent investigations.
+Can you workflowz, then summarize the strongest evidence?
+```
+
+Sentence punctuation and quotation marks may touch the word.
+
+**Does not match:**
+
+```text
+Ultrathink about this                 # wrong case
+orchestrated this migration           # part of another word
+my_orchestrate_helper                 # identifier
+orchestrate.ts                         # file name
+foo::orchestrate                      # symbol reference
+orchestrate()                          # call syntax
+plans/orchestrate/checklist            # path
+`workflowz` this review                # inline code
+```
+
+Letters, digits, underscores, slashes, backslashes, hyphens, file-extension suffixes, `::`, and immediate call parentheses bind the word into a code-like token. Occurrences inside inline code, fenced code blocks, and HTML/XML comments, tags, or elements are ignored. This lets you discuss a symbol or paste code without accidentally steering the turn.
+
+If you need to mention the word without activating it, put it in inline code or a fenced block, change its case, or disable that keyword before submitting.
+
+## Prerequisites and fallback behavior
+
+- `ultrathink` needs no subagent tool. Its automatic-thinking override matters only when thinking is set to automatic; otherwise the current thinking selection remains in force. Models differ in the reasoning efforts they support, so “highest” means the highest supported by the active model.
+- `orchestrate` requires the subagent task capability to be active. Without it, no orchestration behavior is added; the visible prompt is still submitted normally.
+- `workflowz` requires both the subagent task capability and the persistent evaluation capability to be active. If either is unavailable, no workflow behavior is added; the visible prompt is still submitted normally.
+
+Plan mode, tool configuration, or other session controls can make capabilities unavailable. Check `/tools` when `orchestrate` or `workflowz` appears to have had no effect. The colored word can still appear because highlighting recognizes text independently of capability checks.
+
+## Enable or disable keywords
+
+All four settings below default to `true`. In the terminal UI, open `/settings`, then go to **Interaction → Magic Keywords**. The main **Magic Keywords** switch gates every keyword; the three keyword switches control them individually.
+
+You can make the same changes from the shell:
+
+```sh
+# Disable all keyword behavior
+omp config set magicKeywords.enabled false
+
+# Disable one behavior while leaving the others available
+omp config set magicKeywords.ultrathink false
+omp config set magicKeywords.orchestrate false
+omp config set magicKeywords.workflow false
+
+# Re-enable them
+omp config set magicKeywords.enabled true
+omp config set magicKeywords.ultrathink true
+omp config set magicKeywords.orchestrate true
+omp config set magicKeywords.workflow true
+```
+
+The setting name is `magicKeywords.workflow`, even though the prompt word is `workflowz`. Run `omp config list` and inspect the `magicKeywords.*` values to verify the effective configuration. Configuration scopes and precedence are covered in [Settings](/docs/settings).
+
+Disabling the global switch stops the editor's animation, but recognized words can remain statically colored in the editor and sent messages. Per-keyword switches do not control highlighting. Therefore, verify enablement through `/settings` or `omp config list`, not color alone.
+
+## Cost and parallelism
+
+Magic keywords do not create a separate billing mode, but they can increase usage:
+
+- `ultrathink` can spend more reasoning tokens when automatic thinking selects the model's maximum supported effort.
+- `orchestrate` and `workflowz` may run several subagents concurrently. Parallel execution can reduce elapsed time, but each worker consumes model and tool capacity, so total usage can be materially higher than a single-agent turn.
+- More workers are not automatically better. Give independent deliverables, boundaries, and a concrete acceptance check so parallel work is useful rather than duplicated.
+
+Use `/usage` or `omp stats` to inspect usage instead of assuming that faster wall-clock completion costs less.
+
+## Troubleshooting
+
+### The word is not highlighted
+
+Check the lowercase spelling and the boundaries around it. Remove code formatting, a path or extension, identifier characters, `::`, or immediate parentheses. Highlighting is a terminal UI affordance; do not rely on it in one-shot or protocol output.
+
+### The word is highlighted but behavior did not change
+
+Check **Interaction → Magic Keywords** or `omp config list`. The global and matching per-keyword switches must both be on. For `orchestrate`, confirm the task capability in `/tools`; for `workflowz`, confirm both task and evaluation capabilities. Highlighting alone does not prove that behavior was injected.
+
+### `ultrathink` did not change the displayed thinking level
+
+Its maximum-effort override applies when automatic thinking is active and is limited to levels supported by the current model. With a manually selected thinking level, it still steers the turn toward care but does not replace that selection.
+
+### Too many agents ran or usage was higher than expected
+
+Use a narrower prompt, name the genuinely independent slices, or omit the keyword for work that is sequential or small. Disable the individual keyword if you want mentions to remain ordinary prose while keeping the other shortcuts available.