@maudecode/talaria-web 1.21.0 → 1.23.2

package/sidecar/talaria_sidecar/methods/agent_imports.py

@@ -0,0 +1,346 @@
+"""Profile import adapter. Native planning runs on private snapshots; publication uses anchored descriptors."""
+from __future__ import annotations
+
+from contextlib import contextmanager, nullcontext
+import hashlib
+import json
+from itertools import islice
+import os
+from pathlib import Path
+import re
+import secrets
+import stat
+import tempfile
+import time
+
+from .. import home as homes
+from ..errors import InvalidParams, RpcError
+from . import config, memory, plugin_catalog
+
+_SOURCES = {'claude-code': ('.claude', 'Claude Code'), 'codex': ('.codex', 'Codex CLI'), 'cursor': ('.cursor', 'Cursor')}
+_CREDENTIALS = {'.credentials.json', 'auth.json', 'credentials.json', 'cli-config.json', '.env'}
+_TARGETS = ('config.yaml', 'memories', 'skills', 'import-sync.json')
+_MEMORY_FILES = {'memories/MEMORY.md', 'memories/USER.md'}
+_PREVIEWS = {}
+_MAX_FILES = 2048
+_MAX_BYTES = 16 * 1024 * 1024
+_LEDGER = '.talaria-agent-imports'
+
+
+def _result(status, *, items=None, stripped=None, receipt=None, sources=None, message=None, can_apply=False, catalog_required=False):
+    return dict(status=status, items=items or [], stripped_secrets=stripped or [], receipt=receipt,
+                sources=sources or [], message=message, can_apply=can_apply, catalog_required=catalog_required)
+
+
+@contextmanager
+def _directory(path):
+    """Open every ancestor without following links; the held descriptor owns all subsequent IO."""
+    path = Path(path)
+    if not path.is_absolute():
+        raise OSError('An absolute directory is required')
+    fd = os.open(path.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for part in path.parts[1:]:
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        yield fd
+    finally:
+        os.close(fd)
+
+
+def _read(fd, name):
+    child = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=fd)
+    try:
+        info = os.fstat(child)
+        if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_size > _MAX_BYTES:
+            raise OSError('Unsafe or oversized import file')
+        with os.fdopen(os.dup(child), 'rb') as stream:
+            body = stream.read(_MAX_BYTES + 1)
+        after = os.fstat(child)
+        if (info.st_size, info.st_mtime_ns, info.st_ctime_ns) != (after.st_size, after.st_mtime_ns, after.st_ctime_ns):
+            raise OSError('Import input changed during read')
+        return body, (info.st_dev, info.st_ino, info.st_mode, info.st_mtime_ns, info.st_ctime_ns)
+    finally:
+        os.close(child)
+
+
+def _snapshot(path, names):
+    """Bounded snapshot of only importer inputs. Credential stores are never read."""
+    files, identities = {}, {}
+    def walk(fd, name, rel):
+        try:
+            info = os.stat(name, dir_fd=fd, follow_symlinks=False)
+        except FileNotFoundError:
+            return
+        if rel.endswith('.lock') and rel[:-5] in _MEMORY_FILES:
+            if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+                raise OSError('Unsafe memory lock')
+            return
+        if stat.S_ISDIR(info.st_mode):
+            child = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            try:
+                identities[rel] = (info.st_dev, info.st_ino, info.st_mode)
+                if len(identities) > _MAX_FILES:
+                    raise OSError('Import tree too large')
+                with os.scandir(child) as entries:
+                    names = [entry.name for entry in islice(entries, _MAX_FILES + 1)]
+                if len(names) > _MAX_FILES:
+                    raise OSError('Import directory too large')
+                for entry in sorted(names):
+                    if entry not in _CREDENTIALS and entry not in {'.git', '__pycache__'}:
+                        walk(child, entry, rel + '/' + entry)
+            finally:
+                os.close(child)
+        else:
+            body, identity = _read(fd, name)
+            files[rel], identities[rel] = body, identity
+            if len(identities) > _MAX_FILES or sum(map(len, files.values())) > _MAX_BYTES:
+                raise OSError('Import tree too large')
+    with _directory(path) as fd:
+        info = os.fstat(fd)
+        identities['.'] = (info.st_dev, info.st_ino, info.st_mode)
+        for name in names:
+            walk(fd, name, name)
+    return files, identities
+
+
+def _source(agent):
+    os_home = Path.home()
+    source = os_home / _SOURCES[agent][0]
+    names = {'claude-code': ['CLAUDE.md', 'settings.json', 'skills', 'commands'],
+             'codex': ['AGENTS.md', 'config.toml', 'memories', 'skills'],
+             'cursor': ['AGENTS.md', 'mcp.json', 'rules', 'skills']}[agent]
+    files, identity = _snapshot(source, names)
+    if agent == 'claude-code':
+        extra, extra_identity = _snapshot(os_home, ['.claude.json'])
+        files.update({'../' + k: v for k, v in extra.items()})
+        identity.update({'../' + k: v for k, v in extra_identity.items()})
+    return source, files, identity
+
+
+def _stamp(snapshot):
+    files, identities = snapshot
+    return hashlib.sha256(json.dumps([identities, {k: hashlib.sha256(v).hexdigest() for k, v in files.items()}], sort_keys=True).encode()).hexdigest()
+
+
+def _materialize(root, files, identities):
+    root.mkdir()
+    for name, info in identities.items():
+        if name != '.' and stat.S_ISDIR(info[2]):
+            (root / name).mkdir(parents=True, exist_ok=True)
+    for name, body in files.items():
+        path = root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(body)
+        path.chmod(stat.S_IMODE(identities[name][2]))
+
+
+def _project(report):
+    # No native reason, path, command, content or arbitrary detail crosses the boundary.
+    kinds = {'source': 'Source', 'settings': 'Settings', 'claude-md': 'Claude Code instructions',
+             'agents-md': 'Instructions', 'command-allowlist': 'Allowed commands', 'command-denylist': 'Denied commands',
+             'mcp-servers': 'MCP servers', 'skills': 'Skills', 'skill': 'Skill', 'memories': 'Memories',
+             'rules': 'Cursor rules', 'config': 'Configuration', 'slash-commands': 'Slash commands'}
+    statuses = {'imported', 'skipped', 'conflict', 'error'}
+    items = report.get('items')
+    if not isinstance(items, list) or len(items) > _MAX_FILES:
+        raise ValueError('Invalid native report')
+    projected = []
+    for item in items:
+        if not isinstance(item, dict) or item.get('kind') not in kinds or item.get('status') not in statuses:
+            raise ValueError('Invalid native disposition')
+        projected.append(dict(kind=item['kind'], status=item['status'], label=kinds[item['kind']]))
+    stripped = report.get('stripped_secrets', [])
+    if not isinstance(stripped, list) or len(stripped) > _MAX_FILES:
+        raise ValueError('Invalid stripped-secret names')
+    return projected, [name for name in stripped if isinstance(name, str) and len(name) <= 200
+                       and re.fullmatch(r'[A-Za-z0-9_.-]+', name)]
+
+
+@contextmanager
+def _parent(root_fd, rel, create=False):
+    parts = Path(rel).parts
+    if not parts or any(p in ('.', '..') for p in parts) or Path(rel).is_absolute():
+        raise OSError('Unsafe output path')
+    fd = os.dup(root_fd)
+    try:
+        for part in parts[:-1]:
+            if create:
+                try:
+                    os.mkdir(part, 0o700, dir_fd=fd)
+                    os.fsync(fd)
+                except FileExistsError:
+                    pass
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        yield fd, parts[-1]
+    finally:
+        os.close(fd)
+
+
+def _write(root_fd, rel, body, *, exclusive=False, mode=0o600, expected=None):
+    with _parent(root_fd, rel, create=True) as (fd, name):
+        tmp = '.import-' + secrets.token_hex(16)
+        child = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+        try:
+            with os.fdopen(child, 'wb') as stream:
+                os.fchmod(stream.fileno(), stat.S_IMODE(mode) & 0o777)
+                stream.write(body)
+                stream.flush()
+                os.fsync(stream.fileno())
+            guard = memory.file_lock(Path(name), parent_fd=fd) if rel in _MEMORY_FILES else nullcontext()
+            with guard:
+                if expected is not None and _read(fd, name) != expected:
+                    raise OSError('Import destination changed during publication')
+                if exclusive:
+                    os.link(tmp, name, src_dir_fd=fd, dst_dir_fd=fd, follow_symlinks=False)
+                else:
+                    # Replacing a link cannot follow it. Never mutate the old inode in place.
+                    os.rename(tmp, name, src_dir_fd=fd, dst_dir_fd=fd)
+                os.fsync(fd)
+        finally:
+            try:
+                os.unlink(tmp, dir_fd=fd)
+            except FileNotFoundError:
+                pass
+
+
+def _ledger(root_fd, token, result=None):
+    name = _LEDGER + '/' + hashlib.sha256(token.encode()).hexdigest() + '.json'
+    if result is not None:
+        _write(root_fd, name, json.dumps(result).encode())
+        return result
+    try:
+        with _parent(root_fd, name) as (fd, leaf):
+            return json.loads(_read(fd, leaf)[0])
+    except FileNotFoundError:
+        return None
+
+
+def _refresh_runtime(home):
+    from .commands import _reload_mcp, _reload_skills
+    try:
+        with homes.scoped_home(home, load_plugins=False):
+            _reload_skills()
+            _reload_mcp(log_errors=False)
+        return True
+    except Exception:
+        return False
+
+
+def run(ctx, params):
+    action, agent, token = params.get('action'), params.get('agent'), params.get('receipt')
+    if action not in ('discover', 'preview', 'apply', 'result') or action == 'preview' and agent not in _SOURCES or action in ('apply', 'result') and (not isinstance(token, str) or not 0 < len(token) <= 128):
+        raise InvalidParams('Invalid profile import request')
+    home = homes.profile_home_param(params)
+    with homes.scoped_home(home, load_plugins=False, read_only=True), plugin_catalog._lock:
+        try:
+            with _directory(home) as root_fd:
+                # Read the durable consumption record before plugin/source checks. A retry is readback only.
+                if action in ('apply', 'result'):
+                    previous = _ledger(root_fd, token)
+                    if previous is not None:
+                        if 'expected' in previous:
+                            files, _ = _snapshot(home, _TARGETS)
+                            if all(name in files and hashlib.sha256(files[name]).hexdigest() == digest for name, digest in previous['expected'].items()):
+                                return _ledger(root_fd, token, previous['confirmed'])
+                            return previous['result']
+                        return previous
+                    if action == 'result':
+                        # Fence a late apply that never reached the consumption record.
+                        _PREVIEWS.pop(token, None)
+                        return _result('changed', message='No import was confirmed. Preview again.')
+                try:
+                    config.assert_config_writable(home)
+                except RpcError:
+                    return _result('unavailable', message='Profile configuration is managed or its write policy cannot be verified. Import is unavailable.')
+                native = plugin_catalog.reviewed_importer(home)
+                if native is None:
+                    return _result('unavailable', message='Install and enable Agent Importers from the plugin catalog.', catalog_required=True)
+                importer, sync, plugin = native
+                if action == 'discover':
+                    sources = []
+                    for name, (_, label) in _SOURCES.items():
+                        try:
+                            _source(name)
+                            sources.append(dict(agent=name, label=label))
+                        except OSError:
+                            pass
+                    return _result('available', sources=sources)
+                now = time.monotonic()
+                for old in list(_PREVIEWS):
+                    if _PREVIEWS[old]['expires'] <= now:
+                        del _PREVIEWS[old]
+                receipt = _PREVIEWS.get(token) if action == 'apply' else None
+                if action == 'apply' and (receipt is None or receipt['home'] != str(home)):
+                    return _result('changed', message='Preview expired or belongs to another profile. Preview again.')
+                agent = receipt['agent'] if receipt else agent
+                source, source_files, source_identity = _source(agent)
+                if home == source or home in source.parents or source in home.parents:
+                    raise OSError('Source overlaps the active profile')
+                target = _snapshot(home, _TARGETS)
+                identity = [str(home), str(source), plugin, _stamp((source_files, source_identity)), _stamp(target)]
+                if receipt and receipt['identity'] != identity:
+                    return _result('changed', message='Source, profile or plugin changed. Preview again.')
+                if ctx is not None:
+                    ctx.check_cancelled()
+                # Private temporary copies isolate the native path-based API from hostile path replacement.
+                with tempfile.TemporaryDirectory(prefix='talaria-import-') as temp:
+                    stage_source, stage_target = Path(temp).resolve() / 'source', Path(temp).resolve() / 'target'
+                    _materialize(stage_source, source_files, source_identity)
+                    _materialize(stage_target, *target)
+                    report = importer(agent, stage_source, stage_target, execute=False, overwrite=False).run()
+                    items, stripped = _project(report)
+                    plan = json.dumps([items, stripped], sort_keys=True)
+                    if receipt and plan != receipt['plan']:
+                        return _result('changed', message='Import plan changed. Preview again.')
+                    if action == 'preview':
+                        if not any(i['status'] == 'imported' for i in items):
+                            return _result('preview', items=items, stripped=stripped)
+                        token = secrets.token_urlsafe(32)
+                        if len(_PREVIEWS) >= 64:
+                            del _PREVIEWS[next(iter(_PREVIEWS))]
+                        _PREVIEWS[token] = dict(home=str(home), agent=agent, identity=identity, plan=plan, expires=now + 300)
+                        return _result('preview', items=items, stripped=stripped, receipt=token,
+                                       can_apply=any(i['status'] == 'imported' for i in items))
+                    del _PREVIEWS[token]
+                    unknown = _result('unknown', message='Import outcome is unknown. Check the profile before starting a new preview.')
+                    # Fsync the consumed record before any native write. Restart or cancellation cannot replay it.
+                    _ledger(root_fd, token, unknown)
+                    try:
+                        report = importer(agent, stage_source, stage_target, execute=True, overwrite=False).run()
+                        items, stripped = _project(report)
+                        sync.update_sync_manifest(agent, stage_source, stage_target, False, report,
+                                                  refresh_digest=not any(i['status'] == 'error' for i in items))
+                        manifest_path = stage_target / 'import-sync.json'
+                        manifest = json.loads(manifest_path.read_text())
+                        manifest['agents'][agent]['source'] = str(source)
+                        manifest_path.write_text(json.dumps(manifest))
+                        config.assert_config_writable(home)
+                        output, output_identity = _snapshot(stage_target, _TARGETS)
+                        # Check original objects again before publication; no write resolves a client/native path.
+                        fresh_source = _source(agent)
+                        if (plugin_catalog.reviewed_importer(home)[2] != plugin
+                                or _stamp(fresh_source[1:]) != identity[3] or _stamp(_snapshot(home, _TARGETS)) != identity[4]):
+                            return _ledger(root_fd, token, _result('changed', message='Import inputs changed before publication. Preview again.'))
+                        result = _result('partial' if any(i['status'] == 'error' for i in items) else 'applied', items=items, stripped=stripped)
+                        result['message'] = 'Files imported. Reload Skills and MCP before using the imported setup.'
+                        _ledger(root_fd, token, dict(result=unknown, expected={k: hashlib.sha256(v).hexdigest() for k, v in output.items()}, confirmed=result))
+                        for rel, body in output.items():
+                            if target[0].get(rel) != body:
+                                _write(root_fd, rel, body, exclusive=rel not in target[0], mode=output_identity[rel][2], expected=(target[0][rel], target[1][rel]) if rel in target[0] else None)
+                        result = _result('partial' if any(i['status'] == 'error' for i in items) else 'applied', items=items, stripped=stripped)
+                        if not _refresh_runtime(home):
+                            result['message'] = 'Files imported. Reload Skills and MCP before using the imported setup.'
+                        return _ledger(root_fd, token, result)
+                    except Exception:
+                        # Exceptions may include secret values. The durable unknown record is the only public result.
+                        return unknown
+        except (OSError, ValueError, TypeError, KeyError):
+            return _result('unknown' if action == 'result' else 'changed' if action == 'apply' else 'unavailable', message='Import paths or state are unsafe, unavailable or changed. Check the profile before continuing.')
+
+
+def register(registry):
+    registry.method('profiles.import')(run)

package/sidecar/talaria_sidecar/methods/chat.py

@@ -18,6 +18,7 @@ import importlib.util
 import inspect
 import json
 import logging
+import math
 import os
 import queue
 import re
@@ -34,7 +35,7 @@ from ..errors import InvalidParams, RpcError
 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 .providers import require_runtime_ownership, runtime_failure
 from .state_db import release_all, release_home, release_session_db
 from .toolsets import disabled_toolsets
 
@@ -69,6 +70,12 @@ class _Run:
         self.session_ended = False
         self.home = None  # the profile home its agent runs under, set by ``start``
         self.mcp_discovery_outcome = "ok"
+        self.deadline: float | None = None
+
+    def prompt_cancelled(self, data: dict) -> bool:
+        # Vault answers racing a clear retain their existing unlock-then-release cleanup at turn end.
+        ended = self.session_ended and not str(data.get("kind") or "").startswith("vault_")
+        return self.ctx.cancelled or self.cancel.is_set() or self.finished.is_set() or ended
 
 
 class _ClarifyEntry:
@@ -80,7 +87,77 @@ class _ClarifyEntry:
         self.deadline: float | None = None
 
 
+def _ask_clarify(run: _Run, data: dict, timeout: int, emit=None) -> 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."""
+    emit = emit or run.ctx.emit
+    entry = _ClarifyEntry(data)
+    entry.data["clarify_id"] = entry.clarify_id
+    entry.deadline = None if timeout <= 0 else time.monotonic() + float(timeout)
+    if run.deadline is not None:
+        entry.deadline = min(entry.deadline, run.deadline) if entry.deadline is not None else run.deadline
+    with run.lock:
+        if run.prompt_cancelled(data) or (entry.deadline is not None and entry.deadline <= time.monotonic()):
+            return None
+        run.clarify_entries[entry.clarify_id] = entry
+    try:
+        emit("clarify", dict(entry.data))
+        while not entry.event.is_set():
+            if run.prompt_cancelled(data):
+                break
+            if entry.deadline is None:
+                entry.event.wait(0.1)
+                continue
+            remaining = entry.deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            entry.event.wait(min(0.1, remaining))
+    finally:
+        with run.lock:
+            run.clarify_entries.pop(entry.clarify_id, None)
+        emit("clarify_resolved", {"clarify_id": entry.clarify_id, "session_id": run.session_id})
+    return None if run.prompt_cancelled(data) else entry.result
+
+
+def _clarify_callback(run: _Run, params: dict, emit=None):
+    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)
+        if run.deadline is not None:
+            remaining = max(1, math.ceil(run.deadline - time.monotonic()))
+            timeout = min(timeout, remaining) if timeout > 0 else remaining
+        data = {"question": str(question or ""), "choices_offered": choices_list, "session_id": run.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_clarify(run, data, timeout, emit)
+        if answer is not None:
+            if structured:
+                return {"answers": json.loads(answer)["answers"], "outcome": "submitted"}
+            return answer
+        cancelled = run.prompt_cancelled(data)
+        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 ""
+
+    return clarify_callback
+
+
 _RUNS: dict[str, _Run] = {}
+_COMMAND_RUNS: dict[str, _Run] = {}
 _RUNS_BY_SESSION: dict[str, str] = {}
 # Which run owns the Agent's gateway approval callback per session; register/unregister happen under one lock so a
 # stale run can never remove a successor's callback, and a successor can never leak a predecessor's.
@@ -108,6 +185,43 @@ _MCP_REDISCOVERY_WAIT = 2.0
 _MCP_PENDING_KEY = "mcp_discovery_pending"
 
 
+def cancel_command_choices(session_id: str | None = None, home=None) -> None:
+    with _RUNS_LOCK:
+        for run in _COMMAND_RUNS.values():
+            if (session_id is None or run.session_id == session_id) and (home is None or run.home == os.path.realpath(home)):
+                run.session_ended = True
+                run.cancel.set()
+
+
+@contextlib.contextmanager
+def command_choices(ctx: CallContext, params: dict):
+    session_id = str(params.get("session_id") or "").strip()
+    try:
+        from hermes_cli.plugin_choices import bind_asker, clarify_asker
+    except ImportError:
+        yield
+        return
+    if not session_id:
+        yield
+        return
+    run = _Run(uuid.uuid4().hex, session_id, ctx)
+    # The server's commands.exec budget includes every question and the handler's final output.
+    run.deadline = time.monotonic() + 120
+    run.home = os.path.realpath(profile_home_param(params))
+    with _MCP_DISCOVERY_LOCK, _RUNS_LOCK:
+        ctx.check_cancelled()
+        if _DRAINING.is_set() or run.home in _MCP_CLOSING_HOMES:
+            raise RpcError("Command profile is unavailable", condition="profile_unavailable")
+        _COMMAND_RUNS[run.stream_id] = run
+    try:
+        with bind_asker(clarify_asker(_clarify_callback(run, params))):
+            yield
+    finally:
+        run.finished.set()
+        with _RUNS_LOCK:
+            _COMMAND_RUNS.pop(run.stream_id, None)
+
+
 def _snippet(raw: Any, limit: int = _TOOL_RESULT_SNIPPET_MAX) -> str:
     """Predecessor ``_tool_result_snippet``: the ``output``/``result``/``error`` of a dict (or JSON) result, hard-cut."""
     if limit <= 0:
@@ -313,8 +427,14 @@ def _usage(agent: Any) -> dict:
         value = getattr(agent, name, None)
         return value if isinstance(value, (int, float)) else 0
 
+    try:
+        from gateway.session_usage import plan_gauge
+        gauge = plan_gauge(agent)
+    except Exception:  # noqa: BLE001 - older Agent capability omission clears a complete snapshot
+        gauge = None
     cost = getattr(agent, "session_estimated_cost_usd", None)
     return {
+        **({"plan_gauge": gauge} if gauge is not None else {}),
         "prompt_tokens": int(_num("session_prompt_tokens")),
         "completion_tokens": int(_num("session_completion_tokens")),
         "cache_read_tokens": int(_num("session_cache_read_tokens")),
@@ -695,6 +815,7 @@ def _cancel_checkpoint(run: _Run) -> list | None:
 
 
 def _resolve_runtime(provider: str | None, model: str) -> dict:
+    require_runtime_ownership(provider)
     try:
         from hermes_cli.runtime_provider import resolve_runtime_provider
     except Exception as exc:  # noqa: BLE001
@@ -1363,6 +1484,7 @@ def _cancel_background_reviews(entries, message: str) -> list[threading.Thread]:
 
 def evict_all_agents() -> int:
     """Drop every cached agent (credentials or environment changed underneath them)."""
+    cancel_command_choices()
     with _AGENT_CACHE_LOCK:
         entries = list(_AGENT_CACHE.values())
         _AGENT_CACHE.clear()
@@ -1387,7 +1509,7 @@ def drain_agents(timeout: float = _AGENT_RELEASE_TIMEOUT) -> None:
         run.cancel.set()
     while time.monotonic() < deadline:
         with _AGENT_CACHE_LOCK, _RUNS_LOCK:
-            if not _COMMITTING and not any(_RUNS.get(run.stream_id) is run for run in runs):
+            if not _COMMITTING and not _COMMAND_RUNS and not any(_RUNS.get(run.stream_id) is run for run in runs):
                 break
         time.sleep(0.05)
     # A turn may have cached its agent after the first eviction.
@@ -1440,6 +1562,7 @@ def release_profile_agents(home):
             raise RpcError("The profile is already being deleted.", condition="profile_unavailable")
         _MCP_CLOSING_HOMES.add(target)
     try:
+        cancel_command_choices(home=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]
             started = _release_agents_locked(entries)
@@ -1470,8 +1593,8 @@ def release_profile_agents(home):
 
 
 def _holding_home(target: str) -> bool:
-    with _AGENT_CACHE_LOCK:
-        return any(os.path.realpath(home) == target for _agent, home in _COMMITTING)
+    with _AGENT_CACHE_LOCK, _RUNS_LOCK:
+        return any(os.path.realpath(home) == target for _agent, home in _COMMITTING) or any(run.home == target for run in _COMMAND_RUNS.values())
 
 
 def _acquire_session_db(home):
@@ -1889,28 +2012,7 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
                 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))
-            while not entry.event.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 entry.deadline is None:
-                    entry.event.wait(1.0)
-                    continue
-                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
+            return _ask_clarify(run, data, timeout, emit)
 
         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."""
@@ -1966,35 +2068,7 @@ def start(ctx: CallContext, params: dict) -> dict:  # noqa: PLR0915 - one turn,
             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 ""
+        clarify_callback = _clarify_callback(run, params, emit)
 
         # 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``.
@@ -2465,10 +2539,18 @@ def refine(params: dict) -> str:
     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:
+def _run_for(params: dict, *, include_commands: bool = False) -> _Run | None:
     stream_id = str(params.get("stream_id") or "").strip()
     session_id = str(params.get("session_id") or "").strip()
     with _RUNS_LOCK:
+        clarify_id = str(params.get("clarify_id") or "")
+        home = params.get("profile_home")
+        if include_commands and clarify_id and session_id and home:
+            for run in _COMMAND_RUNS.values():
+                if run.session_id == session_id and run.home == os.path.realpath(home):
+                    with run.lock:
+                        if clarify_id in run.clarify_entries:
+                            return run
         if stream_id:
             return _RUNS.get(stream_id)
         if session_id:
@@ -2619,6 +2701,7 @@ def register(registry) -> None:
         in place."""
         session_id = str(params.get("session_id") or "").strip()
         end_session = params.get("clear_session") is True
+        cancel_command_choices(session_id)
         with _AGENT_CACHE_LOCK:
             with _RUNS_LOCK:
                 run = _RUNS.get(_RUNS_BY_SESSION.get(session_id) or "")
@@ -2775,7 +2858,7 @@ def register(registry) -> None:
     def clarify_respond_(ctx: CallContext, params: dict) -> dict:
         response = str(params.get("response") or "")
         clarify_id = str(params.get("clarify_id") or "").strip()
-        run = _run_for(params)
+        run = _run_for(params, include_commands=True)
         if run is None:
             return {"ok": False}
         if params.get("session_id") and str(params["session_id"]) != run.session_id:
@@ -2786,7 +2869,7 @@ def register(registry) -> 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):
+            if ctx.cancelled or run.prompt_cancelled(target.data) or (skill_secret and not clarify_id):
                 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