Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(modes): the assistant can switch and author its own character by voice

rubenluetke10-beep96acaa0f5ee6
diff --git a/docs/adr/0011-router-pure-dispatcher.md b/docs/adr/0011-router-pure-dispatcher.md
index ffb6c3c094..243a6be23a 100644
--- a/docs/adr/0011-router-pure-dispatcher.md
+++ b/docs/adr/0011-router-pure-dispatcher.md
@@ -1054,3 +1054,44 @@ queries via hybrid search.
- `tests/unit/plugins/tool/test_ultrawiki_search_tool.py`
- `tests/unit/brain/test_routing.py` (ROUTER_TOOLS exact set)
+
+## Amendment: Assistant-Mode Tools (2026-08-13)
+
+`list-modes`, `switch-mode` and `save-mode` join `ROUTER_TOOLS`: the assistant
+can now read, switch and author its own *mode* — the character it answers in
+(`jarvis/brain/modes.py`, `jarvis/plugins/tool/assistant_mode.py`).
+
+The precedent is `switch-provider`, not `open_app`. These tools reconfigure the
+assistant itself; they run in-process, touch no external system, and their
+result is deterministic. Nothing here is a direct action on the user's machine,
+so nothing here belongs behind the Jarvis-Agent bridge. Direct gated actions,
+never spawns, never in a worker tool set (AP-5/AP-14).
+
+Tiers are set by what each one can actually cost:
+
+- `list-modes` — safe. A property read over the mode directory.
+- `switch-mode` — monitor. It changes tone and nothing else, the app-wide mode
+ indicator shows it the moment it happens, and undoing it is one sentence.
+ Confirming a change of character the user just asked for out loud would be
+ paperwork, not safety.
+- `save-mode` — ask, echo-confirmed. It writes a file that every future turn
+ reads, under a name the model chose from a conversation. The confirmation is
+ the natural last beat of the mode-builder interview and is what stops a
+ half-heard sentence from becoming a permanent character.
+
+A mode is layered onto the base persona, never substituted for it
+(`persona_loader.load_effective_persona_prompt`), so no mode — including one the
+model wrote itself — can drop the standing rules about honesty and about what is
+safe to say aloud. `save_mode` is told not to restate those rules, because a
+mode that appears to own them invites a later one to relax them.
+
+The Agentic IDE's coding mode is applied as an in-memory *section override*
+rather than a persisted choice, so a mode a screen switched on cannot outlive
+the process.
+
+### Regression guards
+
+- `tests/unit/plugins/test_assistant_mode_tool.py`
+- `tests/unit/brain/test_modes.py`
+- `tests/integration/test_modes_routes.py`
+- `tests/unit/brain/test_routing.py` (ROUTER_TOOLS exact set)
diff --git a/jarvis/brain/factory.py b/jarvis/brain/factory.py
index 723d873c4c..ef79fd3c32 100644
--- a/jarvis/brain/factory.py
+++ b/jarvis/brain/factory.py
@@ -94,6 +94,14 @@ ROUTER_TOOLS = frozenset({
# (two-turn voice confirm). Direct gated action, never a spawn — never in
# a worker set (AP-5/AP-14). See ADR-0011 amendment "app-command tool".
"app-command",
+ # Assistant modes (2026-08-13): the assistant's own character. Reading the
+ # list is a property read; switching changes tone and is visible on screen
+ # the moment it happens; saving is ask-tier because it writes a file every
+ # future turn will read. All three are direct gated actions, never a spawn
+ # — never in a worker set (AP-5/AP-14).
+ "list-modes",
+ "switch-mode",
+ "save-mode",
# Phase A1: synchronous state read on the AwarenessManager (Plan §5).
# NO brain call, NO IO — property read only.
"awareness-snapshot",
diff --git a/jarvis/plugins/tool/assistant_mode.py b/jarvis/plugins/tool/assistant_mode.py
new file mode 100644
index 0000000000..b10643086c
--- /dev/null
+++ b/jarvis/plugins/tool/assistant_mode.py
@@ -0,0 +1,232 @@
+"""``switch_mode`` / ``save_mode`` — the assistant changes its own character.
+
+Two tools, one feature. ``switch_mode`` is how "be my friend for a bit" or
+"back to normal" works by voice. ``save_mode`` is the end of the mode-builder
+interview: the assistant has asked what kind of company the user wants, and
+this is where it writes the answer down.
+
+They live here rather than as bespoke realtime declarations because the
+realtime bridge builds its tool list from this same registry
+(``jarvis/realtime/tools.py``). One tool file therefore reaches the speaking
+brain, the typing brain and the CLI at once — a mode built by voice is
+immediately visible on the modes screen, with no second code path to keep in
+step.
+
+Risk tiers, and why they differ:
+
+* ``switch_mode`` is ``monitor``. It changes tone, nothing else, it is visible
+ on screen the moment it happens, and undoing it is one sentence. Making the
+ user confirm a change of voice they just asked for out loud would be
+ paperwork.
+* ``save_mode`` is ``ask``. It writes a file the assistant will read on every
+ future turn, and the name is one the model chose from a conversation. The
+ confirmation is not friction here — it is the natural last beat of the
+ interview ("shall I save this as Night Owl?"), and it is what stops a
+ half-heard sentence from becoming a permanent character.
+
+Neither tool is a spawn vehicle and neither belongs in a worker set
+(AP-5/AP-14): both are direct, gated, in-process actions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jarvis.core.protocols import ExecutionContext, ToolResult
+
+
+class SwitchModeTool:
+ """Switch the active assistant mode. Applies from the next turn."""
+
+ name: str = "switch_mode"
+ risk_tier: str = "monitor"
+ description: str = (
+ "Switch how you behave by selecting one of the user's assistant modes "
+ "(for example assistant, friend, coach, focus, coding, or one they "
+ "created). Use this when the user asks you to be different — warmer, "
+ "shorter, tougher, back to normal. Call list_modes first if you are "
+ "not sure which modes exist. The change applies from the next turn."
+ )
+ schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": (
+ "The mode id to switch to, e.g. 'friend'. Must be one that "
+ "already exists."
+ ),
+ },
+ },
+ "required": ["slug"],
+ }
+
+ async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
+ del ctx
+ from jarvis.brain import modes
+
+ slug = str(args.get("slug", "")).strip()
+ if not slug:
+ return ToolResult(success=False, output=None, error="No mode id given.")
+ try:
+ mode = modes.set_active(slug)
+ except modes.ModeError as exc:
+ available = ", ".join(m.slug for m in modes.list_modes())
+ return ToolResult(
+ success=False,
+ output=None,
+ # The model gets the real list back rather than a bare refusal,
+ # so a near-miss ("friendly") is recoverable in the same turn
+ # instead of becoming an apology to the user.
+ error=f"{exc} Available modes: {available}.",
+ )
+
+ override = modes.section_override()
+ if override and override != mode.slug:
+ # Honest rather than convenient: the switch was stored, but it is
+ # not what the user will hear until they leave the section that is
+ # holding the override.
+ return ToolResult(
+ success=True,
+ output=(
+ f"Saved {mode.name} as the chosen mode, but the {override} mode "
+ "is in force while that section is open."
+ ),
+ error=None,
+ )
+ return ToolResult(success=True, output=f"Now in {mode.name} mode.", error=None)
+
+
+class SaveModeTool:
+ """Write a new assistant mode from what the user described."""
+
+ name: str = "save_mode"
+ risk_tier: str = "ask"
+ description: str = (
+ "Save a new assistant mode the user has described, or replace one they "
+ "already have. Use this at the end of a conversation about how they "
+ "want you to behave. Write 'character' in the second person, addressed "
+ "to yourself ('You are talking to a friend, not serving a client'), and "
+ "make it concrete: how to greet them, whether to have opinions, how "
+ "long answers should be, what to never do. Do not restate rules about "
+ "honesty or safety — those always apply and are not part of a mode."
+ )
+ schema: dict[str, Any] = {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Short display name, e.g. 'Night Owl'.",
+ },
+ "character": {
+ "type": "string",
+ "description": (
+ "How you should behave in this mode, in the second person. "
+ "A few short paragraphs."
+ ),
+ },
+ "description": {
+ "type": "string",
+ "description": "One line describing the mode, shown on its card.",
+ },
+ "emoji": {"type": "string", "description": "A single emoji for the card."},
+ "verbosity": {
+ "type": "string",
+ "enum": ["brief", "normal", "rich"],
+ "description": "How long the answers should be.",
+ },
+ "proactivity": {
+ "type": "string",
+ "enum": ["reactive", "normal", "forward"],
+ "description": (
+ "How much to volunteer: 'reactive' answers only what was "
+ "asked, 'forward' thinks a step ahead."
+ ),
+ },
+ "activate": {
+ "type": "boolean",
+ "description": "Switch to the mode straight after saving it.",
+ },
+ },
+ "required": ["name", "character"],
+ }
+
+ async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
+ del ctx
+ from jarvis.brain import modes
+
+ name = str(args.get("name", "")).strip()
+ character = str(args.get("character", "")).strip()
+ if not name or not character:
+ return ToolResult(
+ success=False,
+ output=None,
+ error="A mode needs both a name and a description of how to behave.",
+ )
+
+ try:
+ mode = modes.save_mode(
+ slug=modes.normalize_slug(name),
+ name=name,
+ character=character,
+ emoji=str(args.get("emoji", "") or ""),
+ description=str(args.get("description", "") or ""),
+ verbosity=str(args.get("verbosity") or modes.VERBOSITY_NORMAL),
+ proactivity=str(args.get("proactivity") or modes.PROACTIVITY_NORMAL),
+ )
+ except modes.ModeError as exc:
+ return ToolResult(success=False, output=None, error=str(exc))
+ except OSError as exc:
+ return ToolResult(
+ success=False, output=None, error=f"Could not save the mode: {exc}"
+ )
+
+ if not bool(args.get("activate")):
+ return ToolResult(
+ success=True, output=f"Saved the {mode.name} mode.", error=None
+ )
+ try:
+ modes.set_active(mode.slug)
+ except modes.ModeError as exc:
+ # The mode IS saved; only the switch failed. Reporting success
+ # here would promise a character the user is not going to get.
+ return ToolResult(
+ success=True,
+ output=f"Saved the {mode.name} mode, but could not switch to it: {exc}",
+ error=None,
+ )
+ return ToolResult(
+ success=True, output=f"Saved the {mode.name} mode and switched to it.", error=None
+ )
+
+
+class ListModesTool:
+ """Read-only: which modes exist and which one is active."""
+
+ name: str = "list_modes"
+ risk_tier: str = "safe"
+ description: str = (
+ "List the user's assistant modes and which one is currently active. "
+ "Use it before switching modes, or when the user asks what modes they "
+ "have."
+ )
+ schema: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+
+ async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
+ del args, ctx
+ from jarvis.brain import modes
+
+ active = modes.active_slug()
+ listing = [
+ {
+ "slug": m.slug,
+ "name": m.name,
+ "description": m.description,
+ "active": m.slug == active,
+ }
+ for m in modes.list_modes()
+ ]
+ return ToolResult(success=True, output={"modes": listing, "active": active}, error=None)
+
+
+__all__ = ["ListModesTool", "SaveModeTool", "SwitchModeTool"]
diff --git a/pyproject.toml b/pyproject.toml
index 0ab955a431..5b62c815b1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -631,6 +631,13 @@ click-element = "jarvis.plugins.tool.click_element:ClickElementTool"
scroll = "jarvis.plugins.tool.scroll:ScrollTool"
wait-for-element = "jarvis.plugins.tool.wait_for_element:WaitForElementTool"
remember = "jarvis.plugins.tool.remember:RememberTool"
+# Assistant modes (2026-08-13): the assistant's own character, switchable by
+# voice and buildable through an interview. Direct gated actions, never a spawn
+# (AP-5/AP-14). save_mode is ask-tier because it writes a file every future
+# turn reads.
+list-modes = "jarvis.plugins.tool.assistant_mode:ListModesTool"
+switch-mode = "jarvis.plugins.tool.assistant_mode:SwitchModeTool"
+save-mode = "jarvis.plugins.tool.assistant_mode:SaveModeTool"
dispatch-to-harness = "jarvis.plugins.tool.dispatch_to_harness:DispatchToHarnessTool"
# Computer-Use (Wave 1, 2026-05-29) — first-class router tool to drive the live
# desktop via the in-process computer-use harness. Router-tier only (in
diff --git a/tests/unit/brain/test_routing.py b/tests/unit/brain/test_routing.py
index 920a5b39fe..ee3a141df1 100644
--- a/tests/unit/brain/test_routing.py
+++ b/tests/unit/brain/test_routing.py
@@ -1978,6 +1978,18 @@ def test_router_tools_is_pure_dispatcher_set() -> None:
# jarvis/brain/visualize_gate.py), because the mandate is that a
# visualisation is asked for, never volunteered.
"visualize",
+ # Assistant modes (2026-08-13, maintainer mandate): the assistant's
+ # own character. list-modes (safe, property read), switch-mode
+ # (monitor, changes tone only and is visible on screen the moment it
+ # happens), save-mode (ask, echo-confirm — it writes a file every
+ # future turn reads). Deterministic, in-process, touching no
+ # external system: the same shape as switch-provider, which is the
+ # standing precedent for the assistant reconfiguring itself by
+ # voice. Direct gated actions, never spawns (AP-5/AP-14). See
+ # ADR-0011 amendment "Assistant-Mode Tools".
+ "list-modes",
+ "switch-mode",
+ "save-mode",
}
)
assert ROUTER_TOOLS == expected, (
diff --git a/tests/unit/plugins/test_assistant_mode_tool.py b/tests/unit/plugins/test_assistant_mode_tool.py
new file mode 100644
index 0000000000..d027e0b228
--- /dev/null
+++ b/tests/unit/plugins/test_assistant_mode_tool.py
@@ -0,0 +1,108 @@
+"""The three mode tools the assistant can call itself.
+
+``switch_mode`` is how "be my friend for a bit" works by voice; ``save_mode``
+is the last beat of the mode-builder interview. They live in the normal tool
+registry rather than as bespoke realtime declarations, so the speaking brain
+and the typing brain get the same behaviour from one file — these tests lock
+that they are registered, gated at the right tiers, and honest when they fail.
+"""
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+
+import pytest
+
+import jarvis.core.config as core_config
+from jarvis.brain import modes, persona_loader
+from jarvis.plugins.tool.assistant_mode import ListModesTool, SaveModeTool, SwitchModeTool
+
+
[email protected](autouse=True)
+def _isolate(tmp_path, monkeypatch: pytest.MonkeyPatch):
+ """Never touch the real data dir or the real jarvis.toml."""
+ monkeypatch.setattr(core_config, "DATA_DIR", tmp_path)
+ stored: dict[str, str] = {}
+ monkeypatch.setattr(modes, "_configured_slug", lambda: stored.get("slug", modes.DEFAULT_MODE))
+ monkeypatch.setattr(
+ "jarvis.core.config_writer.set_active_mode",
+ lambda slug, **_kw: stored.__setitem__("slug", slug),
+ )
+ modes.set_section_override(None)
+ yield
+ modes.set_section_override(None)
+
+
+def test_all_three_tools_are_registered_entry_points() -> None:
+ """Unregistered, they exist but the model can never reach them."""
+ names = {e.name for e in entry_points(group="jarvis.tool")}
+ assert {"list-modes", "switch-mode", "save-mode"} <= names
+
+
+def test_risk_tiers_match_what_each_tool_actually_does() -> None:
+ assert ListModesTool.risk_tier == "safe" # a property read
+ assert SwitchModeTool.risk_tier == "monitor" # visible, reversible in one sentence
+ assert SaveModeTool.risk_tier == "ask" # writes a file every future turn reads
+
+
+async def test_list_modes_reports_the_shelf_and_the_active_one() -> None:
+ result = await ListModesTool().execute({}, None)
+ assert result.success
+ assert [m["slug"] for m in result.output["modes"]][:5] == list(modes.BUILTIN_SLUGS)
+ assert result.output["active"] == modes.DEFAULT_MODE
+
+
+async def test_switching_reaches_the_persona_layer() -> None:
+ """The point of the whole feature: one call changes what the brain is told."""
+ base = persona_loader.base_persona_prompt()
+ result = await SwitchModeTool().execute({"slug": "friend"}, None)
+ assert result.success
+ assert "Friend" in persona_loader.load_effective_persona_prompt()[len(base) :]
+
+
+async def test_an_unknown_mode_comes_back_with_the_real_list() -> None:
+ """A near-miss must be recoverable in the same turn, not an apology."""
+ result = await SwitchModeTool().execute({"slug": "friendly"}, None)
+ assert not result.success
+ assert "friend" in result.error
+ assert "coach" in result.error
+
+
+async def test_switching_under_a_section_override_says_so() -> None:
+ """Reporting a mode the user will not actually hear is the lie to avoid."""
+ modes.set_section_override(modes.MODE_CODING)
+ result = await SwitchModeTool().execute({"slug": "friend"}, None)
+ assert result.success
+ assert "coding" in result.output
+ assert modes.active_slug() == modes.MODE_CODING
+
+
+async def test_save_mode_writes_and_can_activate() -> None:
+ result = await SaveModeTool().execute(
+ {
+ "name": "Night Owl",
+ "character": "Speak quietly. It is late.",
+ "emoji": "🦉",
+ "verbosity": "brief",
+ "activate": True,
+ },
+ None,
+ )
+ assert result.success
+ saved = modes.get_mode("night-owl")
+ assert saved is not None and saved.verbosity == modes.VERBOSITY_BRIEF
+ assert modes.active_slug() == "night-owl"
+
+
+async def test_save_mode_does_not_activate_unless_asked() -> None:
+ await SaveModeTool().execute({"name": "Night Owl", "character": "Quietly."}, None)
+ assert modes.active_slug() == modes.DEFAULT_MODE
+
+
+async def test_save_mode_needs_both_a_name_and_a_character() -> None:
+ result = await SaveModeTool().execute({"name": "Half", "character": " "}, None)
+ assert not result.success
+
+
+async def test_save_mode_refuses_a_path_shaped_name() -> None:
+ result = await SaveModeTool().execute({"name": "../escape", "character": "x"}, None)
+ assert not result.success