@maudecode/talaria-web 1.18.0 → 1.19.0

package/sidecar/talaria_sidecar/methods/chat.py

@@ -14,21 +14,26 @@ import contextlib
 import contextvars
 import copy
 import hashlib
+import importlib.util
 import inspect
 import json
 import logging
 import os
+import re
 import threading
 import time
 import uuid
 from collections import OrderedDict
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
 from ..errors import InvalidParams, RpcError
-from ..home import profile_home_param, scoped_home
+from ..home import profile_home_param, scoped_home, session_workspace
 from ..rpc import CallContext
 from .checkpoints import checkpoint_kwargs
+from .providers import runtime_failure
+from .toolsets import disabled_toolsets
 
 log = logging.getLogger("talaria_sidecar.chat")
 
@@ -37,10 +42,10 @@ _AGENT_CACHE_MAX = 32
 _AGENT_RELEASE_TIMEOUT = 4.0
 # Profile deletion waits this long for the profile's memory flushes, under the server's 120 s call timeout.
 _PROFILE_RELEASE_TIMEOUT = 60.0
+_SESSION_FINALIZE_TIMEOUT = 10.0
 _TOOL_RESULT_SNIPPET_MAX = 4000
 # Predecessor ``_TOOL_ARG_CONTENT_KEYS`` (#4928): card content / diff-reconstruction inputs keep the long cap.
 _TOOL_ARG_CONTENT_KEYS = frozenset({"command", "cmd", "script", "code", "patch", "diff", "old_string", "new_string", "content", "path", "file_path"})
-_CLARIFY_FALLBACK = "The user did not provide a response within the time limit. Use your best judgement to make the choice and proceed."
 
 
 class _Run:
@@ -56,6 +61,10 @@ class _Run:
         self.lock = threading.Lock()
         # The Agent's transcript list from before this turn: a Stop while the Agent still holds it has no checkpoint.
         self.prior_messages = None
+        # TAL-897: the session ended (clear/delete) or the sidecar is draining, set under both cache and run locks; an
+        # agent this run binds afterwards forks no review and stays out of the cache.
+        self.session_ended = False
+        self.home = None  # the profile home its agent runs under, set by ``start``
 
 
 class _ClarifyEntry:
@@ -64,6 +73,7 @@ class _ClarifyEntry:
         self.data = data
         self.event = threading.Event()
         self.result: str | None = None
+        self.deadline: float | None = None
 
 
 _RUNS: dict[str, _Run] = {}
@@ -79,7 +89,7 @@ _AGENT_CACHE_LOCK = threading.Lock()
 # Running release thread -> the profile home it runs under.
 _RELEASES: dict[threading.Thread, Any] = {}
 _RELEASES_LOCK = threading.Lock()
-# Agents inside ``chat.commit_memory`` (guarded by ``_AGENT_CACHE_LOCK``): like a turn, a commit defers their release.
+# Agents inside ``chat.commit_memory`` or ``chat.refine`` (guarded by ``_AGENT_CACHE_LOCK``): like a turn, each defers their release.
 _COMMITTING: list = []
 # Set (under ``_RUNS_LOCK``) when shutdown drains: no turn is admitted after the drain's snapshot of ``_RUNS``.
 _DRAINING = threading.Event()
@@ -114,6 +124,31 @@ def _result_diff(raw: Any) -> str | None:
     return diff if isinstance(diff, str) else None
 
 
+def _edit_snapshot(name: str, args: Any, task_id: str) -> Any:
+    """TAL-909: the Agent's before-state of a file edit, through the task's terminal; None for a remote backend (the
+    Agent never diffs an unrelated local file), a non-edit tool, or any failure."""
+    try:
+        from agent.display import capture_local_edit_snapshot
+
+        return capture_local_edit_snapshot(name, args, task_id=task_id)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _edit_metadata(name: str, args: Any, result: Any, snapshot: Any) -> dict:
+    """TAL-909: a tool-result row's ``display_metadata``: an edit's unified ``diff`` from its snapshot, which the server
+    turns into ``edit_diff``. Empty when the result carries its own ``diff`` (``patch``), which the server already reads."""
+    if snapshot is None or _result_diff(result) is not None:
+        return {}
+    try:
+        from agent.display import extract_edit_diff
+
+        diff = extract_edit_diff(name, result, function_args=args, snapshot=snapshot)
+    except Exception:  # noqa: BLE001
+        return {}
+    return {"diff": diff} if diff else {}
+
+
 def _raw_result(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> Any:
     """The tool result as the server's outcome rule reads it, bounded: a dict (or JSON-object text) keeps its first
     ``_RAW_RESULT_MAX_KEYS`` top-level fields plus its outcome fields, scalars as they are, text and non-empty nested
@@ -138,6 +173,18 @@ def _raw_result(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> Any:
     return out
 
 
+_TODO_TOOL_NAMES = frozenset({"todo", "todo_list"})
+
+
+def _is_todo_tool(name: Any) -> bool:
+    """TAL-889: the Agent's own todo-tool predicate (canonical ``todo_list`` and legacy aliases); older Agents lack it."""
+    try:
+        from tools.todo_tool import is_todo_tool_name
+    except Exception:  # noqa: BLE001 - older Agent without the predicate
+        return isinstance(name, str) and name in _TODO_TOOL_NAMES
+    return bool(is_todo_tool_name(name))
+
+
 def _delegation_cost_usd(name: Any, raw: Any):
     """Predecessor ``_delegation_cost_usd``: total spend a ``delegate_task`` result reports, or None."""
     if str(name or "") != "delegate_task":
@@ -255,9 +302,29 @@ def _context_length(agent: Any) -> dict:
         value = getattr(cc, key, None)
         if isinstance(value, (int, float)):
             out[key] = int(value)
+    threshold = _next_turn_threshold(agent, cc)
+    if threshold:
+        out["next_turn_threshold_tokens"] = threshold
     return out
 
 
+def _next_turn_threshold(agent: Any, cc: Any) -> int | None:
+    """TAL-1005: the compression threshold the next turn runs under. A turn that ended on a fallback leaves the
+    fallback's threshold on the compressor, but the Agent restores the primary runtime at the next turn's start
+    (``restore_primary_runtime``), so this is the trigger the compressor installs for that runtime's snapshot."""
+    value = getattr(cc, "threshold_tokens", None)
+    primary = getattr(agent, "_primary_runtime", None)
+    if getattr(agent, "_fallback_activated", False) is True and isinstance(primary, dict):
+        value = primary.get("compressor_threshold_tokens")
+        preview = getattr(cc, "preview_threshold_tokens", None)
+        if callable(preview) and isinstance(primary.get("compressor_context_length"), int):
+            try:
+                value = preview(str(primary.get("compressor_model") or ""), primary["compressor_context_length"], str(primary.get("compressor_provider") or ""))
+            except Exception:  # noqa: BLE001
+                log.debug("primary threshold preview failed", exc_info=True)
+    return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0 else None
+
+
 # TAL-539: the hard cap on raw tool output kept in a compressed context (predecessor ``_hard_prune_post_compression_*``).
 _TAIL_TOOL_BUDGET_TOKENS = 4096
 _TAIL_TOOL_MIN_SNIPPET_TOKENS = 256
@@ -280,25 +347,111 @@ def _rough_tokens(text: str) -> int:
         return -(-len(text) // _ROUGH_TOKEN_CHARS)
 
 
+def _tool_failure_outcome(text: str) -> str:
+    """`` FAILED: <error>`` for a JSON tool payload with a top-level ``error`` / ``success: false``, `` FAILED: exit N`` for
+    a non-zero ``exit_code`` / ``exitCode`` the agent did not kill itself, else ``""``: the Agent's compression-stub rule
+    (``_payload_failure_suffix``, ``_sum_process_manage``). Payloads put these fields after ``output``, so a cut drops them."""
+    try:
+        payload = json.loads(text)
+    except (ValueError, RecursionError):
+        return ""
+    if not isinstance(payload, dict):
+        return ""
+    error = payload.get("error")
+    if not error and payload.get("success") is not False:
+        code = payload.get("exit_code")
+        code = payload.get("exitCode") if code is None else code
+        if not isinstance(code, int) or isinstance(code, bool) or code == 0 or payload.get("completion_reason") == "killed":
+            return ""
+        error = f"exit {code}"
+    preview = " ".join(str(error).split())[:80] if error else ""
+    return f" FAILED: {preview}" if preview else " FAILED"
+
+
 def _capped_tool_result(text: str, tokens: int, keep_tokens: int) -> str:
-    """The kept head of an over-budget tool result plus a note on what the model no longer sees."""
-    prefix = "[Talaria context budget: omitted "
-    suffix = f" (~{tokens} rough tokens) from this tool result; the full output remains in the visible transcript.]"
+    """The kept head of an over-budget tool result plus a note on what the model no longer sees, ending on the outcome.
+    TAL-827: the Agent's elision marker marks the cut, so its dispatch guard rejects a model that copies the marker
+    into a durable write; Talaria's note follows on its own line."""
+    outcome = _tool_failure_outcome(text)
+    try:
+        from agent.compression_marker import elide_middle
+    except ImportError:  # An Agent without the shared marker keeps Talaria's own.
+        prefix = "[Talaria context budget: omitted "
+        suffix = f" (~{tokens} rough tokens) from this tool result; the full output remains in the visible transcript.{outcome}]"
+        note_only, widest = f"{prefix}{len(text)} chars{suffix}", f"{prefix}{len(text)} of {len(text)} chars{suffix}"
+
+        def cut(snippet: str) -> str:
+            return f"{snippet}\n\n{prefix}{len(text) - len(snippet)} of {len(text)} chars{suffix}"
+    else:
+        note = f"\n[Talaria context budget: this tool result is ~{tokens} rough tokens; the full output remains in the visible transcript.{outcome}]"
+        # With nothing kept the marker counts every char, its widest form for this text.
+        note_only = widest = elide_middle(text, 0, 0) + note
+
+        def cut(snippet: str) -> str:
+            return elide_middle(text, len(snippet), 0) + note
     if keep_tokens < _TAIL_TOOL_MIN_SNIPPET_TOKENS:
-        return f"{prefix}{len(text)} chars{suffix}"
-    room = keep_tokens - _rough_tokens(f"{prefix}{len(text)} of {len(text)} chars{suffix}") - 1
+        return note_only
+    room = keep_tokens - _rough_tokens(widest) - 1
     snippet = text[: len(text) * room // tokens]
     # Density varies along the text: shrink until the kept head fits the remaining tokens.
     while snippet and _rough_tokens(snippet) > room:
         snippet = snippet[: len(snippet) * 3 // 4]
     snippet = snippet.rstrip()
-    if not snippet:
-        return f"{prefix}{len(text)} chars{suffix}"
-    return f"{snippet}\n\n{prefix}{len(text) - len(snippet)} of {len(text)} chars{suffix}"
+    return cut(snippet) if snippet else note_only
 
 
-def _cap_tool_results(messages: list, compressor: Any) -> list:
-    """Newest tool results spend one shared budget; the first one over it is cut to the remainder, older ones to a note."""
+def _skill_result_stubs(messages: list) -> dict[int, str]:
+    """Recovery metadata for paired skill loads, captured before the Agent can prune their success/failure payloads.
+    Extends the Agent's call-id and marker helpers; its older summaries omit small-skill markers and failure verdicts."""
+    try:
+        from agent.context_compressor import _tool_calls_by_id
+    except ImportError:
+        return {}
+    try:
+        from agent.context_compressor import _skill_pruned_marker
+    except ImportError:
+        def _skill_pruned_marker(name: str) -> str:
+            return f"[SKILL_PRUNED: content lost in compression; reload with skill_view(name='{name}')]"
+
+    calls = _tool_calls_by_id(messages)
+    stubs = {}
+    for i, msg in enumerate(messages):
+        if msg.get("role") != "tool" or not msg.get("tool_call_id"):
+            continue
+        tool, raw_args = calls.get(msg["tool_call_id"], (None, None))
+        if tool != "skill_view":
+            continue
+        try:
+            args = json.loads(raw_args)
+        except (TypeError, ValueError, RecursionError):
+            continue
+        name = args.get("name") if isinstance(args, dict) else None
+        if not isinstance(name, str) or not name or args.get("file_path"):
+            continue
+        text = _content_text(msg.get("content"))
+        outcome = _tool_failure_outcome(text)
+        if text.startswith("[skill_view] ") and " FAILED" in text.split(" (", 1)[0]:
+            outcome = " FAILED"
+        if outcome:
+            stubs[i] = f"[skill_view] name={name}{outcome}"
+            continue
+        try:
+            payload = json.loads(text)
+        except (ValueError, RecursionError):
+            payload = None
+        successful = isinstance(payload, dict) and payload.get("success") is True and isinstance(payload.get("content"), str)
+        marker = _skill_pruned_marker(name)
+        # Lean-tail stubs predate the current cap and may have been persisted by a different supported Agent.
+        demoted = text.startswith(("[skill_view output demoted at compaction ", "[tool output demoted at compaction ")) and text.endswith("] " + marker)
+        if successful or text.startswith(f"[skill_view] name={name} (") or text == marker or demoted:
+            stubs[i] = marker
+    return stubs
+
+
+def _cap_tool_results(messages: list, compressor: Any, original_messages: list | None = None) -> list:
+    """Newest bodies spend one shared budget. Skill reload/failure stubs, like omission notes, survive exhaustion."""
+    originals = messages if original_messages is None else original_messages
+    skill_stubs = _skill_result_stubs(originals)
     budget = getattr(compressor, "tail_token_budget", None)
     budget = budget if isinstance(budget, int) and budget > 0 else _TAIL_TOOL_BUDGET_TOKENS
     threshold = getattr(compressor, "threshold_tokens", None)
@@ -312,13 +465,17 @@ def _cap_tool_results(messages: list, compressor: Any) -> list:
         if msg.get("role") != "tool":
             continue
         text = _content_text(msg.get("content"))
+        stub = skill_stubs.get(i)
+        if stub and text != _content_text(originals[i].get("content")):
+            text = stub
+            out[i] = {**msg, "content": text}
         if not text.strip():
             continue
         tokens = _rough_tokens(text)
         if tokens <= budget - spent:
             spent += tokens
             continue
-        out[i] = {**msg, "content": _capped_tool_result(text, tokens, budget - spent)}
+        out[i] = {**msg, "content": stub or _capped_tool_result(text, tokens, budget - spent)}
         spent = budget
     return out
 
@@ -337,7 +494,7 @@ def _post_compression_context(agent: Any, messages: list, system_message: Any) -
                 context = pruned
         except Exception:  # noqa: BLE001 - the hard cap below still bounds the context
             log.debug("post-compression tool-result pruning failed", exc_info=True)
-    context = _cap_tool_results(context, compressor)
+    context = _cap_tool_results(context, compressor, messages)
     estimate = None
     try:
         from agent.model_metadata import estimate_request_tokens_rough
@@ -350,6 +507,40 @@ def _post_compression_context(agent: Any, messages: list, system_message: Any) -
     return context, estimate if isinstance(estimate, int) and estimate > 0 else None
 
 
+# TAL-887: the Agent's password-manager prompts, answered like a clarify; the waits are the Agent's own surfaces' (its TUI).
+_VAULT_PROMPT_TIMEOUTS = {"vault_unlock": 120, "vault_save_login": 180, "vault_code": 180, "skill_secret": 120}
+
+
+def _set_vault_session(session_id) -> None:
+    """Bind the session an unlock made on this thread belongs to (released with it)."""
+    try:
+        from agent.vault_backends import unlock
+    except Exception:  # noqa: BLE001 - an Agent without the credential vault
+        return
+    unlock.set_current_session_id(session_id)
+
+
+def _release_vault_session(session_id) -> None:
+    """Lock the password managers ``session_id`` unlocked; other sessions keep theirs."""
+    try:
+        from agent.vault_backends.unlock import release_session
+    except Exception:  # noqa: BLE001 - an Agent without the credential vault
+        return
+    release_session(session_id)
+
+
+def _set_vault_prompts(session_id, unlock_cb, save_login_cb, code_cb) -> None:
+    """Bind (or with ``None``s clear) the Agent's per-thread vault prompts and the session an unlock belongs to."""
+    try:
+        from agent.vault_backends import unlock
+    except Exception:  # noqa: BLE001 - an Agent without the credential vault
+        return
+    _set_vault_session(session_id)
+    unlock.set_unlock_prompt_callback(unlock_cb)
+    unlock.set_save_login_prompt_callback(save_login_cb)
+    unlock.set_code_prompt_callback(code_cb)
+
+
 def _clarify_timeout(params: dict) -> int:
     """Predecessor ``_clarify_timeout_seconds``: an explicit request value wins, else the Agent's resolver over config."""
     explicit = params.get("clarify_timeout_seconds")
@@ -481,7 +672,7 @@ def _resolve_runtime(provider: str | None, model: str) -> dict:
     try:
         runtime = resolve_runtime_provider(requested=provider or None, target_model=model or None)
     except Exception as exc:  # noqa: BLE001
-        raise RpcError(str(exc), condition="credential_missing", data={"error_type": type(exc).__name__}) from exc
+        raise runtime_failure(exc, provider) from exc
     if not isinstance(runtime, dict):
         runtime = dict(vars(runtime)) if hasattr(runtime, "__dict__") else {}
     return runtime
@@ -520,14 +711,8 @@ def _turn_identity(session_id: str, workspace: str):
     except Exception:  # noqa: BLE001
         log.debug("per-turn session context bind failed", exc_info=True)
     try:
-        from agent.runtime_cwd import _SESSION_CWD
-
-        tok = _SESSION_CWD.set(str(workspace))
-        resets.append(lambda: _SESSION_CWD.reset(tok))
-    except Exception:  # noqa: BLE001
-        log.debug("per-turn session cwd bind failed", exc_info=True)
-    try:
-        yield
+        with session_workspace(workspace):
+            yield
     finally:
         for reset in reversed(resets):
             try:
@@ -562,16 +747,13 @@ def _discover_mcp_tools(run: _Run) -> None:
     The Agent keys connections by profile scope and skips live ones, so later turns are cheap. Runs under the call's
     ``scoped_home``; a failure leaves the turn without MCP tools rather than failing it. A Stop does not wait for a slow
     server: the turn moves on to its cancelled end while the connect finishes in the background."""
-    from .commands import retire_unscoped_launch_mcp_servers
+    from .commands import discover_profile_mcp_tools
 
     done = threading.Event()
 
     def discover() -> None:
         try:
-            from tools.mcp_tool_discovery import discover_mcp_tools
-
-            retire_unscoped_launch_mcp_servers()
-            discover_mcp_tools()
+            discover_profile_mcp_tools()
         except Exception:  # noqa: BLE001
             log.warning("MCP discovery failed", exc_info=True)
         finally:
@@ -593,7 +775,18 @@ def _profile_fallback_chain() -> list[dict] | None:
     return get_fallback_chain(load_config() or {}) or None
 
 
-def _main_model_request_overrides(model: str, provider) -> dict | None:
+def _profile_prefill_messages() -> list[dict] | None:
+    """The profile's few-shot prefill (``HERMES_PREFILL_MESSAGES_FILE``, then ``prefill_messages_file``, then legacy
+    ``agent.prefill_messages_file``; relative to the profile) through the Agent's own loader, like the CLI, gateway and
+    Desktop. A missing or empty file is None. Runs under the call's ``scoped_home``."""
+    from hermes_cli.cli_config_load import _load_prefill_messages, _resolve_prefill_messages_file
+    from hermes_cli.config import load_config
+    from hermes_constants import get_hermes_home
+
+    return _load_prefill_messages(_resolve_prefill_messages_file(load_config() or {}), get_hermes_home()) or None
+
+
+def _main_model_request_overrides(model: str, provider, base_url: str = "") -> dict | None:
     """Predecessor ``_main_model_request_overrides``: the profile's ``model.service_tier`` and ``model.extra_body``
     (written by ``/api/model/set``) apply only to turns on that configured main model. Runs under ``scoped_home``."""
     from hermes_cli.config import load_config
@@ -606,17 +799,31 @@ def _main_model_request_overrides(model: str, provider) -> dict | None:
     if not main_model or main_model != model.strip():
         return None
     # An unset or ``auto`` main provider resolves at runtime, so the model id alone identifies the main model.
-    if main_provider not in ("", "auto") and main_provider != str(provider or "").strip().lower():
+    from hermes_cli.models import normalize_provider
+
+    if main_provider not in ("", "auto") and normalize_provider(main_provider) != normalize_provider(str(provider or "").strip().lower()):
         return None
-    overrides: dict = {}
-    if str(model_cfg.get("service_tier") or "").strip().lower() == "priority":
-        overrides["service_tier"] = "priority"
+    from ..speed import fast_overrides
+
+    overrides = fast_overrides(model, str(provider or ""), base_url, str(model_cfg.get("service_tier") or "").strip().lower()) or {}
     extra_body = model_cfg.get("extra_body")
     if isinstance(extra_body, dict) and extra_body:
         overrides["extra_body"] = extra_body
     return overrides or None
 
 
+def _request_overrides(model: str, provider, runtime: dict) -> dict | None:
+    """The resolver's ``request_overrides`` (a custom provider entry's ``extra_body``) under the main-model ones, whose
+    ``extra_body`` wins key by key, the Agent's own merge order. Runs under ``scoped_home``."""
+    merged = dict(runtime.get("request_overrides") or {})
+    main = _main_model_request_overrides(model, provider, str(runtime.get("base_url") or "")) or {}
+    extra_body = {**(merged.get("extra_body") or {}), **(main.get("extra_body") or {})}
+    merged.update(main)
+    if extra_body:
+        merged["extra_body"] = extra_body
+    return merged or None
+
+
 def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, kwargs: dict) -> str:
     """Cache identity of an ``AIAgent``: everything its constructor bound from the resolved runtime, so a rotated key,
     a different API mode, ACP command, or credential pool never reuses an agent built for the old bundle. The key
@@ -628,7 +835,8 @@ def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, k
     bundle = {
         "model": model, "provider": provider, "base_url": runtime.get("base_url"), "api_key": key_digest,
         "api_mode": runtime.get("api_mode"), "acp_command": runtime.get("acp_command"), "acp_args": runtime.get("acp_args"),
-        "credential_pool": pool_identity, "toolsets": toolsets, "home": home,
+        "credential_pool": pool_identity, "toolsets": toolsets, "home": home, "cwd": kwargs.get("cwd"),
+        "disabled_toolsets": kwargs.get("disabled_toolsets"),
         "max_iterations": kwargs.get("max_iterations"), "max_tokens": kwargs.get("max_tokens"),
         # Bound at construction too: a reasoning-effort change from the composer must build a fresh agent.
         "reasoning_config": kwargs.get("reasoning_config"),
@@ -636,10 +844,79 @@ def _agent_signature(model: str, provider, runtime: dict, toolsets, home: str, k
         "checkpoints": [kwargs.get(name) for name in ("checkpoints_enabled", "checkpoint_max_snapshots", "checkpoint_max_total_size_mb", "checkpoint_max_file_size_mb")],
         # Entries may carry their own ``api_key``.
         "fallback_model": hashlib.sha256(json.dumps(kwargs.get("fallback_model"), sort_keys=True, default=str).encode("utf-8")).hexdigest()[:16],
+        # Read each turn, so an edited prefill file builds a fresh agent.
+        "prefill_messages": hashlib.sha256(json.dumps(kwargs.get("prefill_messages"), sort_keys=True, default=str).encode("utf-8")).hexdigest()[:16],
     }
     return json.dumps(bundle, sort_keys=True, default=str)
 
 
+def _agent_kwargs(AIAgent, params: dict, session_id: str, model: str, provider, runtime: dict, toolsets) -> dict:
+    """The ``AIAgent`` arguments of a session's agent apart from a turn's callbacks: the resolved runtime, the session's
+    toolsets and budgets, and the profile's fallback chain, request overrides, prefill and checkpoints. Everything
+    ``_agent_signature`` reads is here, so an agent ``/refine`` builds (TAL-902) is the one the next turn reuses. Runs under
+    the call's ``scoped_home``."""
+    kwargs: dict = dict(
+        model=model,
+        provider=provider,
+        base_url=runtime.get("base_url"),
+        api_key=runtime.get("api_key"),
+        platform="webui",
+        quiet_mode=True,
+        enabled_toolsets=toolsets,
+        disabled_toolsets=disabled_toolsets(),
+        session_id=session_id,
+    )
+    for name, value in (
+        ("api_mode", runtime.get("api_mode")),
+        ("acp_command", runtime.get("acp_command")),
+        ("acp_args", runtime.get("acp_args")),
+        ("credential_pool", runtime.get("credential_pool")),
+        ("gateway_session_key", session_id),
+        # TAL-903: anchors subdirectory AGENTS.md discovery (and the memory provider) at the session workspace, when the
+        # server says it is a host path; a remote terminal backend's target-side path must never be read on the host.
+        ("cwd", params.get("workspace") if params.get("workspace_local") is True else None),
+    ):
+        if _supported(AIAgent, name) and value is not None:
+            kwargs[name] = value
+    if isinstance(params.get("max_iterations"), int) and params["max_iterations"] > 0 and _supported(AIAgent, "max_iterations"):
+        kwargs["max_iterations"] = params["max_iterations"]
+    if isinstance(params.get("max_tokens"), int) and params["max_tokens"] > 0 and _supported(AIAgent, "max_tokens"):
+        kwargs["max_tokens"] = params["max_tokens"]
+    # Predecessor: `agent.reasoning_effort` (already coerced for the model) → AIAgent ``reasoning_config``.
+    reasoning_config = params.get("reasoning_config")
+    if isinstance(reasoning_config, dict) and _supported(AIAgent, "reasoning_config"):
+        kwargs["reasoning_config"] = reasoning_config
+    fallback_chain = _profile_fallback_chain()
+    if fallback_chain and _supported(AIAgent, "fallback_model"):
+        kwargs["fallback_model"] = fallback_chain
+    request_overrides = _request_overrides(model, provider, runtime)
+    if request_overrides and _supported(AIAgent, "request_overrides"):
+        kwargs["request_overrides"] = request_overrides
+    prefill_messages = _profile_prefill_messages()
+    if prefill_messages and _supported(AIAgent, "prefill_messages"):
+        kwargs["prefill_messages"] = prefill_messages
+    # TAL-913: the profile's ``checkpoints`` section, as the Agent's own CLI and gateway turns read it.
+    for name, value in checkpoint_kwargs().items():
+        if _supported(AIAgent, name):
+            kwargs[name] = value
+    return kwargs
+
+
+def _build_agent(AIAgent, kwargs: dict, home, session_id: str, state_db: bool = True):
+    """A new session agent on the profile's ``state.db`` (unless ``state_db`` is false), which it releases with it."""
+    session_db = _acquire_session_db(home) if state_db and _supported(AIAgent, "session_db") else None
+    if session_db is not None:
+        kwargs["session_db"] = session_db
+        kwargs["session_id"] = _execution_session_id(session_db, session_id)
+    try:
+        agent = AIAgent(**kwargs)
+    except BaseException:
+        _release_session_db(session_db)
+        raise
+    agent._talaria_session_db = session_db  # released with the agent (``_release_agent``)
+    return agent
+
+
 def _evict_idle_agents_locked() -> None:
     """Trim the agent LRU (caller holds ``_AGENT_CACHE_LOCK``), never dropping a session whose turn is still running."""
     if len(_AGENT_CACHE) <= _AGENT_CACHE_MAX:
@@ -718,6 +995,73 @@ def _join(threads, deadline: float) -> None:
         thread.join(max(0.0, deadline - time.monotonic()))
 
 
+def _cancel_background_reviews(entries, message: str) -> list[threading.Thread]:
+    """TAL-897: stop the post-turn memory/skill review fork of each ``(agent, home)``, which no turn interrupt or release
+    reaches, so a deleted session or a stopping sidecar no longer pays for it. Each cancel then holds the agent's review
+    slot (a run token from the Agent's ``prepare_background_review_run``, never finished), so the Agent admits no later
+    review: not from a turn still running (a clear does not stop it), a spawn already under way, or a review deferred to
+    or requeued on the idle queue (managed local runtime). ``skip_background_review`` spares the turn finalizer queueing
+    one at all. Only a turn's start waits on a held slot, and an ended agent runs no further turn.
+
+    A cancel lasts until its fork acknowledges, which the Agent's own wait does not bound, and runs as a release under
+    ``home`` (``_RELEASES``): shutdown waits for it, and profile deletion, retries included, refuses while it runs or
+    once it failed."""
+    unique = {id(agent): (agent, home) for agent, home in entries if agent is not None}
+    for agent, _home in unique.values():
+        try:
+            agent.skip_background_review = True
+        except AttributeError:  # an object without instance attributes forks no reviews
+            pass
+    try:
+        from agent.background_review import cancel_background_review_for_live_turn, prepare_background_review_run
+    except ImportError:
+        return []
+
+    def cancel(agent) -> None:
+        thread = threading.current_thread()
+        try:
+            try:
+                # One cancel per agent at a time, so none mistakes another's freshly held slot for a review to cancel.
+                lock = vars(agent).setdefault("_talaria_review_cancel_lock", threading.Lock())
+            except TypeError:
+                return  # no instance attributes, so no review slot either
+            with lock:
+                # A spawn that slipped in between the cancel and the slot claim is cancelled on the next pass.
+                for _ in range(3):
+                    if getattr(agent, "_talaria_review_slot", None) is not None:
+                        return
+                    cancel_background_review_for_live_turn(agent, message=message, tool_reason="session ended")
+                    slot = prepare_background_review_run(agent)
+                    if slot is not None:
+                        agent._talaria_review_slot = slot
+                        return
+                    current = getattr(agent, "_background_review_run", None)
+                    if current is None:
+                        return  # not an Agent with a review slot
+                    if current.cancel_requested.is_set():
+                        # A cancelled fork past the Agent's wait may still write: wait for it to acknowledge, then claim
+                        # the slot before the Agent can requeue it.
+                        current.request_done.wait()
+            log.warning("a background review kept restarting after its session ended")
+            thread.failed = True
+        except Exception:  # noqa: BLE001 - teardown continues without it
+            log.warning("cancelling a background review failed", exc_info=True)
+            thread.failed = True
+        finally:
+            with _RELEASES_LOCK:
+                _RELEASES.pop(thread, None)
+
+    threads = []
+    for agent, home in unique.values():
+        thread = threading.Thread(target=cancel, args=(agent,), daemon=True, name="chat-review-cancel")
+        thread.failed = False  # type: ignore[attr-defined] - read by profile deletion
+        with _RELEASES_LOCK:
+            _RELEASES[thread] = home
+        thread.start()
+        threads.append(thread)
+    return threads
+
+
 def evict_all_agents() -> int:
     """Drop every cached agent (credentials or environment changed underneath them)."""
     with _AGENT_CACHE_LOCK:
@@ -731,10 +1075,15 @@ def drain_agents(timeout: float = _AGENT_RELEASE_TIMEOUT) -> None:
     """Shutdown: release every cached agent, stop running turns (like a Stop) so each releases the agent it holds, and
     wait, bounded, for those turns and every release still running."""
     deadline = time.monotonic() + timeout
-    evict_all_agents()
-    with _RUNS_LOCK:
+    with _AGENT_CACHE_LOCK, _RUNS_LOCK:
+        # Admission closes with the snapshot, so no later turn forks a review outside it.
         _DRAINING.set()
         runs = list(_RUNS.values())
+        owners = [(entry[0], entry[2]) for entry in _AGENT_CACHE.values()] + [(run.agent, run.home) for run in runs]
+        for run in runs:
+            run.session_ended = True
+    _cancel_background_reviews(owners, "sidecar shutting down")
+    evict_all_agents()
     for run in runs:
         run.cancel.set()
     while time.monotonic() < deadline:
@@ -749,15 +1098,39 @@ def drain_agents(timeout: float = _AGENT_RELEASE_TIMEOUT) -> None:
     _join(threads, deadline)
 
 
+def refresh_profile_agents_mcp_tools(home) -> None:
+    """MCP reload: republish the live registry's tools to the profile's cached agents, like the gateway's
+    ``_mcp_reload_refresh_cached_agents``. ``content_aware`` publishes a same-name schema change on every supported
+    Agent (0.22.0 implies it for an explicit reload, 0.21.x does not). Each agent keeps its build-time toolset
+    selection. An agent whose refresh fails leaves the cache, so its session's next turn builds one from the live
+    registry instead of keeping stale schemas; the rest still refresh."""
+    from tools.mcp_tool_agent import refresh_agent_mcp_tools
+
+    target = os.path.realpath(home)
+    with _AGENT_CACHE_LOCK:
+        failed = []
+        for session_id, entry in list(_AGENT_CACHE.items()):
+            if os.path.realpath(entry[2]) != target:
+                continue
+            try:
+                refresh_agent_mcp_tools(entry[0], quiet_mode=True, content_aware=True)
+            except Exception:  # noqa: BLE001
+                log.warning("Failed to refresh MCP tools for session %s; evicting its agent", session_id, exc_info=True)
+                failed.append(_AGENT_CACHE.pop(session_id))
+        _release_agents_locked(failed)
+
+
 def release_profile_agents(home) -> None:
-    """Profile deletion: release the profile's cached agents and wait for every release running under its home. Fails
-    rather than let the home go while a memory flush still runs under it."""
+    """Profile deletion: release the profile's cached agents, cancel their background reviews, and wait for both and
+    every release running under its home. Fails rather than let the home go while a memory flush still runs under it."""
     target = os.path.realpath(home)
     with _AGENT_CACHE_LOCK:
         entries = [_AGENT_CACHE.pop(sid) for sid, entry in list(_AGENT_CACHE.items()) if os.path.realpath(entry[2]) == target]
-        _release_agents_locked(entries)
+        started = _release_agents_locked(entries)
+    started += _cancel_background_reviews([(entry[0], entry[2]) for entry in entries], "profile deleted")
+    # The threads started here count even once they left ``_RELEASES``: a fast failure must still block the delete.
     with _RELEASES_LOCK:
-        threads = [thread for thread, owner in _RELEASES.items() if os.path.realpath(owner) == target]
+        threads = list(dict.fromkeys(started + [thread for thread, owner in _RELEASES.items() if owner is not None and os.path.realpath(owner) == target]))
     _join(threads, time.monotonic() + _PROFILE_RELEASE_TIMEOUT)
     if any(thread.is_alive() for thread in threads):
         raise RpcError("The profile is still saving memory from its chats. Retry in a moment.")
@@ -823,6 +1196,14 @@ def _max_iterations_summary_request() -> str:
     return str(MAX_ITERATIONS_SUMMARY_REQUEST)
 
 
+def _has_voice_turn_route() -> bool:
+    """Whether the Agent routes a marked turn to ``auxiliary.voice_chat`` (``agent.voice_turn_route``, v0.21.6)."""
+    try:
+        return importlib.util.find_spec("agent.voice_turn_route") is not None
+    except (ImportError, ValueError):
+        return False
+
+
 def _supported(cls, name: str) -> bool:
     """Whether ``cls.__init__`` accepts ``name`` (named, or through ``**kwargs``)."""
     try:
@@ -832,6 +1213,15 @@ def _supported(cls, name: str) -> bool:
     return name in parameters or any(p.kind is inspect.Parameter.VAR_KEYWORD for p in parameters.values())
 
 
+@lru_cache(maxsize=32)
+def _run_conversation_parameters(cls) -> frozenset[str]:
+    """Probe explicit turn capabilities once per Agent class; unknown signatures keep legacy arguments."""
+    try:
+        return frozenset(inspect.signature(cls.run_conversation).parameters)
+    except (TypeError, ValueError):
+        return frozenset()
+
+
 def _approval_notifier(session_id: str, emit):
     """The Agent's gateway notify callback for one turn: emits each parked approval, then ``approval_resolved``
     (id plus the Agent's reason) once its wait ends by any path, an ``approvals.timeout`` expiry included (TAL-514)."""
@@ -876,20 +1266,51 @@ def _is_compression_start(lower: str) -> bool:
 
 
 def _status_events(kind, text: str) -> list[str]:
-    """Events for one Agent status line: the compressing card, a fallback warning, and the turn's terminal error."""
+    """Events for one Agent status line: compression, provider diagnostics, and the turn's terminal error."""
     lower = text.lower()
     events = ["terminal_error"] if "non-retryable error" in lower else []
-    if str(kind or "").strip().lower() == "lifecycle":
+    kind = str(kind or "").strip().lower()
+    # TAL-1006: the Agent's one terminal edge of a started compaction (``_emit_compaction_done``); an aborted attempt
+    # sends none and ends with the turn.
+    if kind == "compacted":
+        return ["compression_finished"]
+    if kind == "lifecycle":
         if _is_compression_start(lower):
             return events + ["compressing"]
         # The Agent's own compression retries ("Compressed N → M messages, retrying...") are not provider fallbacks.
         if "compress" in lower or "context reduced to" in lower:
             return events
+        # Buffered diagnostics change wording across Agent releases; their severity glyph stays stable.
+        if not events and text.startswith(("⚠", "❌")):
+            return ["warning"]
     if "fallback" in lower or "rate limit" in lower or ("retry" in lower and "non-retryable" not in lower):
         events.append("warning")
     return events
 
 
+#: TAL-821: the Agent's live status line during a rate-limit backoff (``turn_recovery.compute_error_backoff``), e.g.
+#: "⏳ the free model is busy — resets in ~17m, retrying in 600s (attempt 1/3)". The Agent's other waits are not known
+#: rate limits: "waiting on provider" covers a 5xx retry as well as a 429 without a reset, and "provider overloaded" is a
+#: Z.AI overload. ``webui`` is not an attended source, so the Agent sits out a free-tier cooldown instead of ending.
+_RATE_LIMIT_WAIT_RE = re.compile(r"^⏳ (?:rate limited|the free model is busy) —.* retrying in (\d+)s\b", re.IGNORECASE)
+#: The line's reset window, in the Agent's ``format_duration_compact`` units ("45s", "17m", "1h 5m", "1.5d").
+_RESET_IN_RE = re.compile(r"resets in ~((?:\d+(?:\.\d+)?[dhms] ?)+)")
+_DURATION_UNITS = {"d": 86400, "h": 3600, "m": 60, "s": 1}
+
+
+def _rate_limit_wait(text: str) -> tuple[float, str] | None:
+    """``(seconds, "reset")`` until the provider's limit resets, else ``(seconds, "retry")`` until the Agent retries, for a
+    rate-limit wait line; None for any other line. The reset is the provider's own ``reset_at`` as the Agent read it from
+    the error; the credential pool's exhausted mark is no better, since without that field it is a fixed one-hour guess."""
+    wait = _RATE_LIMIT_WAIT_RE.match(text)
+    if not wait:
+        return None
+    reset = _RESET_IN_RE.search(text)
+    if not reset:
+        return float(wait.group(1)), "retry"
+    return sum(float(amount) * _DURATION_UNITS[unit] for amount, unit in re.findall(r"(\d+(?:\.\d+)?)([dhms])", reset.group(1))), "reset"
+
+
 def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn, one function
     session_id = str(params.get("session_id") or "").strip()
     stream_id = str(params.get("stream_id") or "").strip()
@@ -909,6 +1330,7 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
     system_message = params.get("system_message")
     home = profile_home_param(params)
     run = _Run(stream_id, session_id, ctx)
+    run.home = home
     with _RUNS_LOCK:
         if _DRAINING.is_set():
             raise RpcError("The sidecar is shutting down.", condition="sidecar_unavailable")
@@ -916,6 +1338,11 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
         # A previous turn for this session that never returned (a tool ignoring its interrupt) still owns the cached
         # agent; this turn must not share, rebind, or un-interrupt that live instance.
         session_busy = prior is not None and not prior.finished.is_set()
+        # TAL-829: a second agent beside a turn nobody stopped would wait on that turn's durable turn lease (up to 30
+        # minutes) and then write the same session. A stopped turn only lingers until the Agent abandons the wedged
+        # tool, which lets its lease go within seconds.
+        if session_busy and not (prior.cancel.is_set() or prior.ctx.cancelled):
+            raise RpcError("This chat is still answering the previous message. Stop it or wait for it to finish.", condition="session_busy")
         _RUNS[stream_id] = run
         _RUNS_BY_SESSION[session_id] = stream_id
     raw_emit = ctx.emit
@@ -945,6 +1372,8 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
         live_tool_calls: list[dict] = []
         started_ids: set[str] = set()
         completed_ids: set[str] = set()
+        edit_snapshots: dict[str, Any] = {}
+        prepared_metadata: dict[str, dict] = {}
         token_sent = [False]
 
         def on_token(text):
@@ -970,6 +1399,9 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 return
             if tid:
                 started_ids.add(tid)
+                snapshot = _edit_snapshot(name, args, session_id)
+                if snapshot is not None:
+                    edit_snapshots[tid] = snapshot
             live_tool_calls.append({"name": name, "args": args if isinstance(args, dict) else {}, "tid": tid, "done": False})
             emit("tool", {"event_type": "tool.started", "name": name, "preview": None, "args": _args_snapshot(args), "tid": tid})
 
@@ -988,8 +1420,12 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                     call["snippet"] = snippet
                     break
             payload = {"event_type": "tool.completed", "name": name, "preview": snippet, "args": _args_snapshot(args), "tid": tid, "raw_result": _raw_result(function_result)}
+            # TAL-909: the metadata the Agent persisted on the result row, or, from an Agent without the callback, live only.
+            metadata = prepared_metadata.pop(tid) if tid in prepared_metadata else _edit_metadata(name, args, function_result, edit_snapshots.pop(tid, None))
+            if metadata:
+                payload["display_metadata"] = metadata
             # TAL-397: ``raw_result`` caps nested values, so the todo tool's list travels whole for the server's ``todo_state``.
-            if name == "todo" and function_result is not None:
+            if function_result is not None and _is_todo_tool(name):
                 payload["todo_result"] = function_result if isinstance(function_result, str) else json.dumps(function_result, default=str)
             # TAL-448: likewise a result's unified ``diff``, so the server's ``edit_diff`` counts cover the whole change.
             diff = _result_diff(function_result)
@@ -1004,6 +1440,14 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                         break
             emit("tool_complete", payload)
 
+        def on_tool_result_metadata(tool_call_id, name, args, function_result):
+            """TAL-909: called before the Agent appends and flushes the tool-result row, which keeps the returned dict as
+            its ``display_metadata``; the completion frame that follows carries the same dict."""
+            tid = str(tool_call_id or "")
+            metadata = _edit_metadata(name, args, function_result, edit_snapshots.pop(tid, None))
+            prepared_metadata[tid] = metadata
+            return metadata
+
         def on_tool(*cb_args, **cb_kwargs):
             # Structured callbacks carry tool cards; the progress callback only feeds reasoning text on older builds.
             if len(cb_args) >= 3 and cb_args[0] in ("reasoning.available", "_thinking"):
@@ -1016,43 +1460,172 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             for event in _status_events(kind, text):
                 if event == "compressing":
                     emit("compressing", {"session_id": session_id, "message": "Compressing context"})
+                elif event == "compression_finished":
+                    emit("compression_finished", {"session_id": session_id})
                 elif event == "warning":
                     emit("warning", {"type": "fallback", "message": text})
                 else:
                     emit("status", {"kind": "terminal_error", "message": text})
 
-        def clarify_callback(question, choices, multi_select=False, questions=None):
-            choices_list = [str(c) for c in (choices or [])]
-            # Predecessor `_clarify_timeout_seconds`: the Agent's own resolver over this profile's config
-            # (``clarify.timeout`` else ``agent.clarify_timeout`` else 3600); ``<= 0`` waits until answered or cancelled.
-            # The advertised ``timeout_seconds`` is what the clients count down, so it is the same number.
-            timeout = _clarify_timeout(params)
-            data = {"question": str(question or ""), "choices_offered": choices_list, "session_id": session_id, "kind": "clarify", "requested_at": time.time(), "timeout_seconds": timeout}
-            if multi_select:
-                data["multi_select"] = True
-            # Batch prompts (the Agent's ``_run_batch``) carry no top-level question and expect the ``{"answers": {...}}`` reply.
-            if isinstance(questions, list) and questions:
-                data["questions"] = questions
+        wait_state = {"active": False, "prompt": False}
+
+        def on_thinking(text):
+            """Normalize provider waits and prompt-reading progress from the Agent's live status callback."""
+            line = str(text or "").strip()
+            progress = re.fullmatch(r"⚙ processing prompt(?: — (\d+(?:\.\d+)?)%)?", line)
+            if progress:
+                wait_state["prompt"] = True
+                emit("provider_phase", {"phase": {"phase": "prompt_reading", "progress_percent": min(100, float(progress[1])) if progress[1] else None}})
+            elif wait_state["prompt"]:
+                wait_state["prompt"] = False
+                emit("provider_phase", {"phase": None})
+            wait = _rate_limit_wait(line)
+            if wait is not None:
+                wait_state["active"] = True
+                emit("rate_limit_wait", {"provider": str(getattr(run.agent, "provider", None) or resolved_provider or "") or None,
+                                         "until": time.time() + wait[0], "until_kind": wait[1]})
+            elif wait_state["active"]:
+                wait_state["active"] = False
+                emit("rate_limit_wait", {"provider": None, "until": None})
+
+        # TAL-803: the Agent's sticky ``AgentNotice``s (a startup warning such as a memory provider that failed to load,
+        # credit and usage bands) and their clears; the server keeps the session's active set.
+        def on_notice(notice):
+            text = str(getattr(notice, "text", "") or "").strip()
+            if not text:
+                return
+            ttl_ms = getattr(notice, "ttl_ms", None)
+            key = getattr(notice, "key", None)
+            # The Agent raises a startup warning (memory provider unavailable) once per process, so a rebuilt agent never
+            # repeats it: it outlives the agent that raised it. Credit notices are per agent and re-raised by the next one.
+            emit("notice", {"id": getattr(notice, "id", None), "key": key, "level": str(getattr(notice, "level", "") or "info"),
+                            "kind": str(getattr(notice, "kind", "") or "sticky"), "ttl_ms": ttl_ms if isinstance(ttl_ms, int) else None, "text": text,
+                            "lapses_with_agent": not str(key or "").startswith("startup-warning.")})
+
+        def on_notice_clear(key):
+            if key:
+                emit("notice_clear", {"key": str(key)})
+
+        def ask(data: dict, timeout: int) -> str | None:
+            """Park on a prompt the server relays until it is answered, the turn is cancelled or ends, or ``timeout``
+            passes (``<= 0``: no limit). The answer, or None, goes back to the Agent and is never emitted."""
             entry = _ClarifyEntry(data)
             entry.data["clarify_id"] = entry.clarify_id
+            entry.deadline = None if timeout <= 0 else time.monotonic() + float(timeout)
             with run.lock:
                 run.clarify_entries[entry.clarify_id] = entry
             emit("clarify", dict(entry.data))
-            deadline = None if timeout <= 0 else time.monotonic() + float(timeout)
             while not entry.event.is_set():
-                if run.cancel.is_set() or run.finished.is_set():
+                if run.cancel.is_set() or run.finished.is_set() or (data.get("kind") == "skill_secret" and (ctx.cancelled or run.session_ended)):
                     break
-                if deadline is None:
+                if entry.deadline is None:
                     entry.event.wait(1.0)
                     continue
-                remaining = deadline - time.monotonic()
+                remaining = entry.deadline - time.monotonic()
                 if remaining <= 0:
                     break
                 entry.event.wait(min(1.0, remaining))
             with run.lock:
                 run.clarify_entries.pop(entry.clarify_id, None)
             emit("clarify_resolved", {"clarify_id": entry.clarify_id, "session_id": session_id})
-            return entry.result or _CLARIFY_FALLBACK
+            return entry.result
+
+        def ask_vault(kind: str, fields: dict) -> str:
+            """TAL-887: a password-manager prompt; an empty answer is the Agent's decline, as are expiry and cancel."""
+            timeout = _VAULT_PROMPT_TIMEOUTS[kind]
+            data = {"kind": kind, "session_id": session_id, "requested_at": time.time(), "timeout_seconds": timeout, **fields}
+            return ask(data, timeout) or ""
+
+        def vault_unlock_prompt(backend, display_name):
+            # The Agent stores the unlock right after this returns, on the thread that called it: a tool worker
+            # inherits this callback but not the turn's session, so bind it here too, or closing the session could
+            # not lock the manager again.
+            _set_vault_session(session_id)
+            return ask_vault("vault_unlock", {"backend": str(backend), "display_name": str(display_name)})
+
+        def vault_save_login_prompt(origin, site):
+            # The server sends ``{"identifier", "password"}``; the Agent stores it in its vault and fills the page.
+            raw = ask_vault("vault_save_login", {"origin": str(origin), "site": str(site)})
+            try:
+                answer = json.loads(raw) if raw else None
+            except ValueError:
+                return None
+            return answer if isinstance(answer, dict) and answer.get("password") else None
+
+        def vault_code_prompt(site, hint):
+            return ask_vault("vault_code", {"site": str(site), "hint": str(hint or "")})
+
+        def skill_secret_prompt(env_var, prompt, metadata=None):
+            skipped = {"success": True, "stored_as": env_var, "validated": False, "skipped": True}
+            if not isinstance(env_var, str) or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", env_var):
+                return skipped
+            metadata = metadata if isinstance(metadata, dict) else {}
+            fields = {"env_var": env_var, "prompt": str(prompt), **{key: str(metadata.get(key) or "") for key in ("skill_name", "help", "required_for")}}
+            value = ask_vault("skill_secret", fields)
+            if not value.strip():
+                return skipped
+            # The native writer strips these bytes, and reports non-ASCII characters to stderr. Refuse rather
+            # than change the credential or expose any of its characters in logs.
+            if not value.isascii() or any(char in value for char in ("\r", "\n", "\0")):
+                return {**skipped, "success": False}
+            try:
+                from hermes_cli.config import save_env_value_secure
+                from hermes_constants import get_hermes_home
+
+                # Keep the inherited secret scope so setup can use the value immediately. Fence the write against
+                # eviction/replacement under the same lock that changes the run's identity and session lifetime.
+                with _RUNS_LOCK:
+                    if (ctx.cancelled or run.cancel.is_set() or run.finished.is_set() or run.session_ended
+                            or _RUNS_BY_SESSION.get(session_id) != stream_id or _RUNS.get(stream_id) is not run
+                            or get_hermes_home() != home):
+                        return skipped
+                    saved = save_env_value_secure(env_var, value)
+                return {"success": saved.get("success") is True, "stored_as": env_var, "validated": saved.get("validated") is True, "skipped": False}
+            except Exception:  # noqa: BLE001 - never expose an exception that could include the submitted value
+                return {**skipped, "success": False}
+
+        def clarify_callback(question, choices=None, multi_select=False, questions=None):
+            # TAL-351: remove the legacy signature path when v0.21.6 is the oldest supported Agent.
+            structured = isinstance(question, list)
+            if structured:
+                questions, question = question, ""
+            choices_list = [str(c) for c in (choices or [])]
+            # Predecessor `_clarify_timeout_seconds`: the Agent's own resolver over this profile's config
+            # (``clarify.timeout`` else ``agent.clarify_timeout`` else 3600); ``<= 0`` waits until answered or cancelled.
+            # The advertised ``timeout_seconds`` is what the clients count down, so it is the same number.
+            timeout = _clarify_timeout(params)
+            data = {"question": str(question or ""), "choices_offered": choices_list, "session_id": session_id, "kind": "clarify", "requested_at": time.time(), "timeout_seconds": timeout}
+            if multi_select:
+                data["multi_select"] = True
+            # Batch prompts (the Agent's ``_run_batch``) carry no top-level question and expect the ``{"answers": {...}}`` reply.
+            if isinstance(questions, list) and questions:
+                data["questions"] = questions
+            answer = ask(data, timeout)
+            if answer is not None:
+                if structured:
+                    return {"answers": json.loads(answer)["answers"], "outcome": "submitted"}
+                return answer
+            cancelled = run.cancel.is_set() or run.finished.is_set()
+            if structured:
+                return {"answers": {}, "outcome": "cancelled" if cancelled else "timed_out",
+                        "notice": "The user cancelled the clarification." if cancelled else "The clarification timed out."}
+            # Older tools have no outcome field. A batch understands timed_out; a single needs an empty answer.
+            if questions:
+                return json.dumps({"answers": {}, "timed_out": not cancelled})
+            return ""
+
+        # TAL-818: a ``manage_connections`` card (a hosted connect, an MCP install) opened; the server turns the frame into
+        # the chat's connect card, which reads and answers the operation through ``connectors.operation`` / ``respond``.
+        # Only a client that draws the card asks for it: without the callback the Agent answers with plain links at once.
+        connect_card = params.get("connect_card") is True
+
+        def on_connection(payload):
+            from .connectors import remember_chat_operation
+
+            view = remember_chat_operation(home, payload)
+            if view is not None:
+                emit("connection", view)
+            return None
 
         # Approval bridge: the Agent parks dangerous commands in its gateway queue and calls back here.
         try:
@@ -1061,51 +1634,21 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             register_gateway_notify = unregister_gateway_notify = None
         approval_cb = _approval_notifier(session_id, emit) if register_gateway_notify is not None else None
 
-        kwargs: dict = dict(
-            model=resolved_model,
-            provider=resolved_provider,
-            base_url=runtime.get("base_url"),
-            api_key=runtime.get("api_key"),
-            platform="webui",
-            quiet_mode=True,
-            enabled_toolsets=toolsets,
-            session_id=session_id,
-            stream_delta_callback=on_token,
-            reasoning_callback=on_reasoning,
-            tool_progress_callback=on_tool,
-            clarify_callback=clarify_callback,
-        )
+        kwargs = _agent_kwargs(AIAgent, params, session_id, resolved_model, resolved_provider, runtime, toolsets)
+        kwargs.update(stream_delta_callback=on_token, reasoning_callback=on_reasoning, tool_progress_callback=on_tool, clarify_callback=clarify_callback)
         for name, value in (
             ("interim_assistant_callback", on_interim),
             ("tool_start_callback", on_tool_start),
             ("tool_complete_callback", on_tool_complete),
+            ("tool_result_metadata_callback", on_tool_result_metadata),
             ("status_callback", on_status),
-            ("api_mode", runtime.get("api_mode")),
-            ("acp_command", runtime.get("acp_command")),
-            ("acp_args", runtime.get("acp_args")),
-            ("credential_pool", runtime.get("credential_pool")),
-            ("gateway_session_key", session_id),
+            ("thinking_callback", on_thinking),
+            ("notice_callback", on_notice),
+            ("notice_clear_callback", on_notice_clear),
+            ("connection_callback", on_connection if connect_card else None),
         ):
             if _supported(AIAgent, name) and value is not None:
                 kwargs[name] = value
-        if isinstance(params.get("max_iterations"), int) and params["max_iterations"] > 0 and _supported(AIAgent, "max_iterations"):
-            kwargs["max_iterations"] = params["max_iterations"]
-        if isinstance(params.get("max_tokens"), int) and params["max_tokens"] > 0 and _supported(AIAgent, "max_tokens"):
-            kwargs["max_tokens"] = params["max_tokens"]
-        # Predecessor: `agent.reasoning_effort` (already coerced for the model) → AIAgent ``reasoning_config``.
-        reasoning_config = params.get("reasoning_config")
-        if isinstance(reasoning_config, dict) and _supported(AIAgent, "reasoning_config"):
-            kwargs["reasoning_config"] = reasoning_config
-        fallback_chain = _profile_fallback_chain()
-        if fallback_chain and _supported(AIAgent, "fallback_model"):
-            kwargs["fallback_model"] = fallback_chain
-        request_overrides = _main_model_request_overrides(resolved_model, resolved_provider)
-        if request_overrides and _supported(AIAgent, "request_overrides"):
-            kwargs["request_overrides"] = request_overrides
-        # TAL-913: the profile's ``checkpoints`` section, as the Agent's own CLI and gateway turns read it.
-        for name, value in checkpoint_kwargs().items():
-            if _supported(AIAgent, name):
-                kwargs[name] = value
         signature = _agent_signature(resolved_model, resolved_provider, runtime, toolsets, str(params.get("profile_home")), kwargs)
         agent = None
 
@@ -1113,6 +1656,8 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             """Claim the agent for this run under ``_AGENT_CACHE_LOCK``, so an eviction never releases it mid-turn."""
             run.prior_messages = getattr(bound, "_session_messages", None)
             run.agent = bound
+            if run.session_ended:
+                bound.skip_background_review = True
 
         if not session_busy:
             with _AGENT_CACHE_LOCK:
@@ -1122,27 +1667,31 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                     _AGENT_CACHE.move_to_end(session_id)
                     bind(agent)
         if agent is not None:
-            for name in ("stream_delta_callback", "reasoning_callback", "tool_progress_callback", "clarify_callback", "interim_assistant_callback", "tool_start_callback", "tool_complete_callback", "status_callback"):
+            for name in ("stream_delta_callback", "reasoning_callback", "tool_progress_callback", "clarify_callback", "interim_assistant_callback", "tool_start_callback", "tool_complete_callback", "tool_result_metadata_callback", "status_callback", "thinking_callback", "notice_callback", "notice_clear_callback"):
                 if name in kwargs and hasattr(agent, name):
                     setattr(agent, name, kwargs[name])
+            # A cached agent keeps the last turn's card callback; this turn's client decides afresh (TAL-818).
+            if hasattr(agent, "connection_callback"):
+                agent.connection_callback = on_connection if connect_card else None
+            # TAL-902: an agent ``/refine`` built runs its first turn here. Like a new one, it lapses the notices of the
+            # agent it replaced and raises the startup notices it parked while it had no callback.
+            if vars(agent).pop("_talaria_unannounced", False):
+                emit("notices_reset", {})
+                replay = getattr(agent, "_replay_startup_warnings", None)
+                if callable(replay):
+                    replay()
         else:
+            # TAL-803: the notices a replaced agent raised lapse with it (``lapses_with_agent``); this one raises its own.
+            emit("notices_reset", {})
             # A ``/btw`` side question's throwaway session stays out of state.db.
-            session_db = _acquire_session_db(home) if not params.get("ephemeral") and _supported(AIAgent, "session_db") else None
-            if session_db is not None:
-                kwargs["session_db"] = session_db
-                kwargs["session_id"] = _execution_session_id(session_db, session_id)
-            try:
-                agent = AIAgent(**kwargs)
-            except BaseException:
-                _release_session_db(session_db)
-                raise
-            agent._talaria_session_db = session_db  # released with the agent (``_release_agent``)
+            agent = _build_agent(AIAgent, kwargs, home, session_id, state_db=not params.get("ephemeral"))
             with _AGENT_CACHE_LOCK:
                 bind(agent)
-                replaced = _AGENT_CACHE.pop(session_id, None)
-                _AGENT_CACHE[session_id] = (agent, signature, home)
-                _release_agents_locked([replaced] if replaced else [])
-                _evict_idle_agents_locked()
+                if not run.session_ended:
+                    replaced = _AGENT_CACHE.pop(session_id, None)
+                    _AGENT_CACHE[session_id] = (agent, signature, home)
+                    _release_agents_locked([replaced] if replaced else [])
+                    _evict_idle_agents_locked()
         # Predecessor ``agent.ephemeral_system_prompt``: personality, surface context, progress guidance, and delivery
         # hints travel as runtime instructions that are never persisted to history.
         ephemeral = params.get("ephemeral_system_prompt")
@@ -1189,27 +1738,40 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
         watcher = threading.Thread(target=_watch_cancel, daemon=True, name=f"chat-cancel-{stream_id[:8]}")
         watcher.start()
         run_kwargs: dict = {"user_message": user_message, "conversation_history": history, "task_id": session_id}
-        try:
-            run_params = set(inspect.signature(agent.run_conversation).parameters)
-        except (TypeError, ValueError):
-            run_params = set()
+        run_params = _run_conversation_parameters(type(agent))
         if system_message and ("system_message" in run_params or not run_params):
             run_kwargs["system_message"] = system_message
+        # Talaria generates and syncs the title; suppress the Agent's duplicate auxiliary request.
+        if "title_user_message" in run_params:
+            run_kwargs["title_user_message"] = ""
         # The server's clean user text (no workspace prefix) is what state.db stores; the Agent keeps the sent bytes beside it.
         persist = params.get("persist_user_message")
         if not (isinstance(persist, str) and persist.strip()):
             persist = user_message if isinstance(user_message, str) else None
         if "persist_user_message" in run_params and persist is not None:
             run_kwargs["persist_user_message"] = persist
+        # TAL-801: a spoken turn runs on the profile's ``auxiliary.voice_chat`` slot; the Agent consumes the mark at turn
+        # setup. Every turn sets it, as the Agent's own surfaces do, so a mark a failed turn never consumed cannot leak.
+        if _has_voice_turn_route():
+            agent._voice_turn_pending = params.get("voice_turn") is True
         error: str | None = None
         result: dict = {}
+        # The Agent reads its vault prompts from the thread running the turn (and copies them onto tool workers).
+        _set_vault_prompts(session_id, vault_unlock_prompt, vault_save_login_prompt, vault_code_prompt)
         try:
-            raw = agent.run_conversation(**run_kwargs)
+            try:
+                from tools.skills_tool import bind_turn_secret_capture
+            except ImportError:  # Older Agents and v0.22.2 have only an unsafe process-global callback slot.
+                bind_turn_secret_capture = None
+                log.debug("Agent lacks turn-local skill secret capture; secure setup is unavailable")
+            with bind_turn_secret_capture(skill_secret_prompt) if bind_turn_secret_capture and params.get("skill_secret") is True else contextlib.nullcontext():
+                raw = agent.run_conversation(**run_kwargs)
             result = raw if isinstance(raw, dict) else {}
         except Exception as exc:  # noqa: BLE001
             log.warning("agent turn failed for %s: %s", session_id, exc)
             error = f"{type(exc).__name__}: {exc}"
         finally:
+            _set_vault_prompts(None, None, None, None)
             run.finished.set()
             watcher.join(timeout=2)
             # A successor turn for the same session (admitted past the cancel-unwind ceiling) may have registered
@@ -1255,7 +1817,8 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             "max_iterations_summary_request": _max_iterations_summary_request(),
             "usage": _usage(agent),
             "context": _context_length(agent),
-            "model": str(getattr(agent, "model", None) or resolved_model),
+            # TAL-801: the Agent's result names the model the turn ran on; a voice turn's route is undone by now.
+            "model": str(result.get("model") or getattr(agent, "model", None) or resolved_model),
             "provider": str(resolved_provider or ""),
             "compressed": compressed,
             "agent_session_id": str(getattr(agent, "session_id", None) or session_id),
@@ -1269,6 +1832,10 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 _RUNS.pop(stream_id, None)
                 if _RUNS_BY_SESSION.get(session_id) == stream_id:
                     _RUNS_BY_SESSION.pop(session_id, None)
+                # TAL-887: a session ended mid-turn (``chat.evict_agent`` marks the run under these locks) released its
+                # unlocks then; one the Agent stored after that is released now.
+                if run.session_ended:
+                    _release_vault_session(session_id)
             # An agent evicted or replaced while this turn held it is released now that the turn is over.
             _release_if_dropped_locked(run.agent, home)
 
@@ -1351,6 +1918,7 @@ def compress(ctx: CallContext, params: dict) -> dict:
         platform="webui",
         quiet_mode=True,
         enabled_toolsets=toolsets,
+        disabled_toolsets=disabled_toolsets(),
         session_id=session_id,
     )
     for name, value in (
@@ -1360,6 +1928,8 @@ def compress(ctx: CallContext, params: dict) -> dict:
         ("credential_pool", runtime.get("credential_pool")),
         ("gateway_session_key", session_id),
         ("skip_memory", not _checkpoint_required()),
+        ("request_overrides", _request_overrides(kwargs["model"], kwargs["provider"], runtime)),
+        ("prefill_messages", _profile_prefill_messages()),
     ):
         if _supported(AIAgent, name) and value is not None:
             kwargs[name] = value
@@ -1398,6 +1968,93 @@ def compress(ctx: CallContext, params: dict) -> dict:
             _release_compression(agent, committed=False)
 
 
+_REFINE_BUSY = "Agent is running — wait for the turn to finish, then /refine."
+
+
+def _session_running_locked(session_id: str) -> bool:
+    """Whether a turn for ``session_id`` has not returned yet, or no turn can start (caller holds ``_RUNS_LOCK``)."""
+    run = _RUNS.get(_RUNS_BY_SESSION.get(session_id) or "")
+    return _DRAINING.is_set() or (run is not None and not run.finished.is_set())
+
+
+def _refine_agent(params: dict, session_id: str, home):
+    """The session's cached agent, else one built the way its turn builds it and cached for that turn, held in
+    ``_COMMITTING`` until the caller lets go; None when a turn started meanwhile. Runs under the call's ``scoped_home``."""
+    with _AGENT_CACHE_LOCK:
+        with _RUNS_LOCK:
+            # Checked again with the claim: a turn admitted since ``refine``'s check holds the cached agent.
+            if _session_running_locked(session_id):
+                return None
+        cached = _AGENT_CACHE.get(session_id)
+        if cached is not None:
+            _COMMITTING.append(cached[0])
+            return cached[0]
+    model = str(params.get("model") or "").strip()
+    provider = str(params.get("model_provider") or "").strip() or None
+    toolsets = _turn_toolsets(params.get("enabled_toolsets"))
+    # Like a turn: the profile's MCP servers connect before the agent snapshots its tools, which its next turn keeps.
+    try:
+        from .commands import discover_profile_mcp_tools
+
+        discover_profile_mcp_tools()
+    except Exception:  # noqa: BLE001
+        log.warning("MCP discovery failed", exc_info=True)
+    runtime = _resolve_runtime(provider, model)
+    resolved_model = model or str(runtime.get("model") or "")
+    resolved_provider = provider or runtime.get("provider")
+    AIAgent = _agent_class()
+    kwargs = _agent_kwargs(AIAgent, params, session_id, resolved_model, resolved_provider, runtime, toolsets)
+    signature = _agent_signature(resolved_model, resolved_provider, runtime, toolsets, str(params.get("profile_home")), kwargs)
+    built = _build_agent(AIAgent, kwargs, home, session_id)
+    with _AGENT_CACHE_LOCK:
+        with _RUNS_LOCK:
+            running = _session_running_locked(session_id)
+        cached = _AGENT_CACHE.get(session_id)
+        agent = None if running else cached[0] if cached else built
+        if agent is not None:
+            _COMMITTING.append(agent)
+        if agent is built:
+            built._talaria_unannounced = True  # its first turn announces it (``start``)
+            _AGENT_CACHE[session_id] = (built, signature, home)
+            _evict_idle_agents_locked()
+        else:
+            _release_agents_locked([(built, None, home)])
+    return agent
+
+
+def refine(params: dict) -> str:
+    """TAL-902: ``/refine [focus]`` like the Agent's live-session handler (``_format_live_refine_output``): the memory/skill
+    review fork of ``messages`` (the server's model context for the session) on the session's agent, never while its turn
+    runs. The fork carries this call's ``scoped_home``, so its memory and skill writes land in the session's profile."""
+    session_id = str(params.get("session_id") or "").strip()
+    messages = params.get("messages")
+    if not session_id or not isinstance(messages, list):
+        raise InvalidParams("session_id and messages are required")
+    focus = str(params.get("focus") or "").strip()
+    with _RUNS_LOCK:
+        if _session_running_locked(session_id):
+            return _REFINE_BUSY
+    if not messages:
+        return "Nothing to refine yet — the conversation is empty."
+    home = profile_home_param(params)
+    agent = _refine_agent(params, session_id, home)
+    if agent is None:
+        return _REFINE_BUSY
+    try:
+        agent._spawn_background_review(messages_snapshot=list(messages), review_memory=True,
+                                       review_skills="skill_manage" in (getattr(agent, "valid_tool_names", None) or set()),
+                                       focus=focus or None, explicit=True)
+    except Exception as exc:  # noqa: BLE001 - the Agent's own wording for a fork that could not start
+        log.warning("/refine failed to start for session %s", session_id, exc_info=True)
+        return f"/refine failed to start: {exc}"
+    finally:
+        with _AGENT_CACHE_LOCK:
+            _COMMITTING.remove(agent)
+            _release_if_dropped_locked(agent, home)
+    tail = f" (focus: {focus})" if focus else ""
+    return f"⚗ Reviewing this conversation in the background{tail} — any memory/skill updates will be reported when done."
+
+
 def _run_for(params: dict) -> _Run | None:
     stream_id = str(params.get("stream_id") or "").strip()
     session_id = str(params.get("session_id") or "").strip()
@@ -1426,6 +2083,11 @@ def register(registry) -> None:
         with scoped_home(profile_home_param(params)):
             return compress(ctx, params)
 
+    @registry.method("chat.refine")
+    def refine_(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return {"output": refine(params)}
+
     @registry.method("chat.compress_finalize", requires_agent=False)
     def compress_finalize_(ctx: CallContext, params: dict) -> dict:
         token = str(params.get("commit_token") or "").strip()
@@ -1487,28 +2149,74 @@ def register(registry) -> None:
         pending, index = _steer_queue_params(params)
         run = _run_for(params)
         if run is None or run.agent is None:
-            return {"redirected": False, "withdrawn": False}
+            return {"redirected": False, "withdrawn": False, "reason": "not_running"}
         return steer_now(run.agent, pending, index)
 
+    @registry.method("chat.finalize_session", requires_agent=False)
+    def finalize_(ctx: CallContext, params: dict) -> dict:
+        session_id = str(params.get("session_id") or "").strip()
+        reason = params.get("reason")
+        if not session_id or reason not in ("clear", "delete"):
+            raise InvalidParams("session_id and reason (clear/delete) are required")
+        home = profile_home_param(params)
+        messages: list[str] = []
+
+        def finalize() -> None:
+            try:
+                # Scope inside the worker: a timed-out plugin keeps its own profile until it finishes.
+                with scoped_home(home):
+                    from hermes_cli import lifecycle
+
+                    callback = getattr(lifecycle, "finalize_session", None)
+                    if callback is None:
+                        return
+                    results = callback(session_id=session_id, platform="webui", reason=reason)
+                    extract = getattr(lifecycle, "session_end_messages", None)
+                    if extract is not None:
+                        messages.extend(extract(results))
+            except Exception:  # noqa: BLE001 - hooks must never block the boundary
+                log.warning("Session finalize failed for %s (%s)", session_id, reason, exc_info=True)
+            finally:
+                with _RELEASES_LOCK:
+                    _RELEASES.pop(worker, None)
+
+        worker = threading.Thread(target=finalize, name="session-finalize", daemon=True)
+        worker.failed = False  # type: ignore[attr-defined] - hook failures do not prevent profile deletion
+        with _RELEASES_LOCK:
+            _RELEASES[worker] = home
+        worker.start()
+        worker.join(_SESSION_FINALIZE_TIMEOUT)
+        if worker.is_alive():
+            log.warning("Session finalize exceeded %ss for %s (%s)", _SESSION_FINALIZE_TIMEOUT, session_id, reason)
+            return {"messages": []}
+        return {"messages": messages}
+
     @registry.method("chat.evict_agent", requires_agent=False)
     def evict_(ctx: CallContext, params: dict) -> dict:
         """Drop a session's cached agent. Only delete/clear (``clear_session``) end its approval grants, parked
-        approvals and kernels; a model switch, truncate or compress leaves a running turn's agent in place."""
+        approvals, kernels and background review; a model switch, truncate or compress leaves a running turn's agent
+        in place."""
         session_id = str(params.get("session_id") or "").strip()
         end_session = params.get("clear_session") is True
         with _AGENT_CACHE_LOCK:
             with _RUNS_LOCK:
                 run = _RUNS.get(_RUNS_BY_SESSION.get(session_id) or "")
+                if end_session and run is not None:
+                    run.session_ended = True
             if not end_session and run is not None and not run.finished.is_set():
                 return {"evicted": False}
             entry = _AGENT_CACHE.pop(session_id, None)
             _release_agents_locked([entry] if entry else [])
         if end_session:
+            # The server does not wait for an eviction; the cancels finish on their own.
+            _cancel_background_reviews(([(entry[0], entry[2])] if entry else []) + ([(run.agent, run.home)] if run else []), "session deleted or cleared")
             try:
                 from tools.approval import clear_session
                 clear_session(session_id)
             except Exception:  # noqa: BLE001
                 pass
+            # TAL-887: a password manager this session unlocked locks again with it; other sessions keep theirs.
+            _release_vault_session(session_id)
         return {"evicted": entry is not None}
 
     @registry.method("chat.commit_memory", requires_agent=False)
@@ -1600,22 +2308,27 @@ def register(registry) -> None:
 
     @registry.method("clarify.respond", requires_agent=False)
     def clarify_respond_(ctx: CallContext, params: dict) -> dict:
-        response = str(params.get("response") or "").strip()
+        response = str(params.get("response") or "")
         clarify_id = str(params.get("clarify_id") or "").strip()
-        if not response:
-            raise InvalidParams("response is required")
         run = _run_for(params)
         if run is None:
             return {"ok": False}
+        if params.get("session_id") and str(params["session_id"]) != run.session_id:
+            return {"ok": False}
         with run.lock:
             entries = list(run.clarify_entries.values())
-        target = None
-        if clarify_id:
-            target = next((e for e in entries if e.clarify_id == clarify_id), None)
-        elif entries:
-            target = entries[0]
-        if target is None:
-            return {"ok": False}
-        target.result = response
-        target.event.set()
-        return {"ok": True, "clarify_id": target.clarify_id}
+            target = next((e for e in entries if e.clarify_id == clarify_id), None) if clarify_id else (entries[0] if entries else None)
+            if target is None or target.event.is_set() or (target.deadline is not None and time.monotonic() >= target.deadline):
+                return {"ok": False}
+            skill_secret = target.data.get("kind") == "skill_secret"
+            if skill_secret and (not clarify_id or ctx.cancelled or run.ctx.cancelled or run.cancel.is_set() or run.finished.is_set() or run.session_ended):
+                return {"ok": False}
+            # Secure answers are as typed; an empty reply is their decline. Only the first answer releases a waiter.
+            secure = str(target.data.get("kind") or "").startswith("vault_") or skill_secret
+            if not secure:
+                response = response.strip()
+            if not response and not secure:
+                raise InvalidParams("response is required")
+            target.result = response
+            target.event.set()
+            return {"ok": True, "clarify_id": target.clarify_id}