ha-settings

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:

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

MEDIUM risk — behavioral changes (cost, context, output quality)

HIGH risk — require explicit user confirmation

Read-only (cannot be modified via this tool)

Model / Provider / API Key / Server authentication / IM Channel accounts / MCP server configs / STT providers / per-session configs require the Settings UI.

Special: teams Semantics

Unlike every other category, teams does not live in AppConfig — it targets rows in the team_templates SQLite table. The update_settings payload is CRUD-shaped:

// Create or overwrite a template
{
  "category": "teams",
  "values": {
    "action": "save",
    "template": {
      "templateId": "fullstack-py-react",
      "name": "Full-Stack (Py + React)",
      "description": "Frontend (React expert) + Backend (Python expert) + Tester",
      "members": [
        {
          "name": "Frontend",
          "role": "worker",
          "agentId": "react-expert",
          "color": "#3B82F6",
          "description": "You are the frontend specialist. Build React components with TS.",
          "modelOverride": null,
          "defaultTaskTemplate": "Implement the UI for the feature."
        }
      ]
    }
  }
}

// Delete a template by id
{
  "category": "teams",
  "values": { "action": "delete", "templateId": "fullstack-py-react" }
}

• read returns the full TeamTemplate[] — no values needed.
• templateId must be non-empty and unique. Each member's agentId must point to an existing Agent (check list_agents in the Agents panel).
• Deleting a template does not touch any teams that were created from it; teams.template_id is a historical reference only.
• EventBus broadcasts template_saved / template_deleted so the UI refreshes live.

Special: skill_env Update Modes

Because per-skill env vars are a nested map, update_settings("skill_env", …) accepts three patch forms:

// 1. Full replace
{ "skillEnv": { "my-skill": { "API_KEY": "xyz" } } }

// 2. Per-skill set (merge) — value null removes that var
{ "set": { "my-skill": { "API_KEY": "xyz", "OLD_VAR": null } } }

// 3. Remove an entire skill's env block
{ "remove": ["my-skill"] }

Prefer form 2 for targeted edits so you don't overwrite unrelated skills.

Rollback — Every Change Is Reversible

Every write to config.json / user.json — from this tool, the UI, or any other path — automatically snapshots the pre-change file under ~/.hope-agent/backups/autosave/. Last 50 snapshots retained.

list_settings_backups

{ "limit": 10 }              // latest 10 entries (default 20, max 200)
{ "kind": "config" }         // filter by "config" or "user"

Returns {id, timestamp, kind, category, source} newest first.

restore_settings_backup

{ "id": "2026-04-17T10-30-45-123__config__theme__skill" }

• Always HIGH risk — must confirm with the user before calling. Show them the entry's timestamp, kind, and category.
• Creates a fresh snapshot of the current state first, so the rollback itself is reversible — you can "undo the undo" by restoring the newly-created entry.
• Restoring a config entry reloads the in-memory cache immediately; server / shortcuts style side effects still apply and may need a restart.

When to proactively offer rollback

• User says "undo that", "revert", "go back", "you broke X" after a recent change.
• User complains about a specific behavior right after you changed a related setting.
• User asks "what did you change?" — list the last few entries to remind them.

Important Notes

• Read before write — always get_settings first so you can show a diff.
• Confirm before write — especially HIGH risk. Include the risk level in your confirmation prompt.
• Field names are camelCase (e.g. softRatio, toolTimeout, approvalTimeoutEnabled, askUserQuestionTimeoutEnabled, askUserQuestionTimeoutSecs).
• Security restrictions — cannot modify Providers or API Keys through this tool, including user.remoteApiKey; guide the user to the Settings UI.
• Surface side effects — if the response has sideEffect (e.g. "requires restart"), tell the user.
• Secrets in logs — never echo apiKey, remoteApiKey, or skill_env values back in chat unless the user explicitly asks. Note that get_settings for user / server / web_search / media_generation / acp_control / embedding already redacts the credential fields to "[REDACTED]" — if you see that marker, the field is set but the value is hidden from the model intentionally.
• Rollback is built-in — if a change goes wrong, offer restore_settings_backup instead of trying to reconstruct the old values manually.