/ha-settings

name: ha-settings
description: "Manage Hope Agent application settings through conversation. Use when the user wants to view or change any app configuration: theme, language, enhanced focus indicators, proxy, temperature, notifications, tool timeout, context compaction, automatic session titles, web search, GitHub issue reporting, memory, embedding, multimodal embedding, dreaming (offline memory consolidation), recap, behavior awareness, smart-mode approvals, plan mode, ask-user-question timeout, tool-result disk spill threshold, embedded server, ACP control plane, MCP subsystem (kill switch / concurrency / backoff), per-skill env vars, or any other setting visible in the Settings UI. Trigger phrases: 'change settings', 'configure proxy', 'set theme to dark', 'turn on enhanced focus indicators', 'turn off notifications', 'adjust temperature', 'show my settings', 'bind the server to all interfaces', 'enable smart mode', 'tune dreaming', 'disable mcp', 'show my channels'. Trigger even when the user doesn't explicitly say 'settings' — any intent to adjust app behavior qualifies."
always: true

Settings — Application Configuration Management

Use `get_settings` and `update_settings` to read and modify settings. **Never edit config files directly.** Coverage matches the desktop Settings UI one-to-one for everything that doesn't carry secrets. The GUI-only zones — Providers / API Keys, IM Channel accounts (`channels`), MCP server configs (`mcp_servers`), the active model selection (`active_model` / `fallback_models`), the embedding model selection for both memory and knowledge-base vector search (`memory_embedding` / `knowledge_embedding` — model choice carries a background reembed side effect, like `active_model`), the knowledge-base chunking parameters (`knowledge_chunk` — changing chunk size/overlap re-chunks and re-embeds every space, same heavy reindex side effect; tuned under Settings → Knowledge → Advanced), the credential/model-selection parts of Speech-to-Text (`stt_providers` / `active_stt_model` / `stt_fallback_models`; the non-secret `stt_language` remains writable), and the Hooks system (`hooks`) — are configured only in the Settings UI (memory vector search under Settings → Memory; knowledge vector search under Settings → Knowledge) so credentials stay out of conversation logs and the model can't grant itself command execution.

Risk Levels & Dual-Confirmation

Every response from `get_settings` / `update_settings` includes a `riskLevel` field. **Follow this workflow strictly**:

| Risk | Required before calling `update_settings` | |------|-------------------------------------------| | `low` | One-line summary of what you'll change is enough | | `medium` | Show current value → new value, then proceed if the user has asked for it | | `high` | **MUST** explicitly ask the user to confirm (e.g. "Are you sure you want to change X from A to B? This affects …"). Wait for explicit yes before writing. |

`get_settings({ category: "all" })` returns a `riskLevels` map grouping every category.

If the response includes `sideEffect`, surface it to the user (e.g. "this requires an app restart").

Workflow

1. **Understand intent** — what does the user want to view or change? 2. **Read current** — `get_settings(category)`. Note `riskLevel` and `sideEffect`. 3. **Confirm** — low: brief summary. medium: diff. **high: explicit yes/no prompt.** 4. **Apply** — `update_settings(category, values)` with partial JSON. 5. **Report** — show the updated values and any side-effect note (e.g. restart needed).

Tool Usage

get_settings

{ "category": "theme" }        // Read one category
{ "category": "all" }          // Overview + riskLevels map

update_settings

{ "category": "theme", "values": { "theme": "dark" } }

`values` uses partial merge — only include fields you want to change.

Full Category Reference

LOW risk — cosmetic / preference, trivially reversible

| Category | Fields | |----------|--------| | `user` | `name`, `avatar`, `gender`, `birthday`, `role`, `timezone`, `language`, `aiExperience`, `responseStyle`, `customInfo`, `autoSendPending`, `autoExpandThinking`, `autoCollapseCompletedTurns`, `chatDisplayMode`, `serverMode`, `remoteServerUrl`, `weatherEnabled`, `weatherCity`, `weatherLatitude`, `weatherLongitude`. `remoteApiKey` is credential-bearing, read-only/redacted here, and must be changed in Settings → Server | | `theme` | `theme` (`auto`/`light`/`dark`) | | `language` | `language` (`auto`/`zh`/`en`/…) | | `focus_indicator` | `enhancedFocusIndicators` (bool, default `false`). Enables the stronger 2px focus outline for all input methods. When disabled, pointer/touch focus stays visually quiet while keyboard navigation keeps the lightweight focus indicator. System `prefers-contrast: more` and forced-colors modes still take precedence automatically. | | `ui_effects` | `uiEffectsEnabled` | | `prevent_sleep` | `preventSleep` (bool, default `false`). When `true`, the primary process keeps the host awake by holding an OS sleep assertion (macOS `caffeinate -i` / Linux logind inhibitor / Windows `ES_SYSTEM_REQUIRED`) so long-running tasks, downloads, and background work aren't interrupted by idle sleep. The display may still turn off; takes effect immediately, no restart needed. | | `sidebar_ui` | `sidebarUiMode` (`compact` / `detailed`; invalid values normalize to `detailed`) | | `notification` | `enabled`, `showChatContent` (include assistant reply previews in chat-completion notices), `notifyOnBackgroundJobComplete` (bool, default `true`; R4: fire a desktop notification when a background job finishes, gated by `enabled` + only when the window is in the background) | | `startup_notification` | `enabled` (default `true`), `windowSecs` (lookback for "active" chats, default 259200 = 72h), `globalMax` (cap on the number of chats **actually notified** per boot — applied after silencing / cooldown filters so they can't starve fresh chats; def