@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/tools/schema_sanitizer.py

@@ -21,6 +21,12 @@ The failure modes we've seen in the wild:
   optional fields (common Pydantic/MCP shape). Anthropic rejects these at
   the top of ``input_schema``; collapse them to the non-null branch.
 * Unconstrained ``additionalProperties`` on objects with empty properties.
+* ``default`` (and other annotation keywords) alongside ``$ref`` — strict
+  backends (Fireworks-hosted Kimi, JSON Schema draft-07 validators) reject
+  sibling keywords at the same level as ``$ref``.  Common MCP/Pydantic shape
+  after nullable-union collapse::
+
+      {"$ref": "#/$defs/Foo", "default": null}
 
 This module walks the final tool schema tree (after MCP-level normalization
 and any per-tool dynamic rebuilds) and fixes the known-hostile constructs
@@ -90,6 +96,35 @@ def _sanitize_single_tool(tool: dict) -> dict:
     fn["parameters"] = _strip_top_level_combinators(
         fn["parameters"], path=fn.get("name", "<tool>")
     )
+    fn["parameters"] = _strip_ref_siblings(fn["parameters"])
+    return out
+
+
+# Sibling keywords strict JSON Schema validators reject alongside ``$ref``.
+_REF_FORBIDDEN_SIBLINGS = frozenset({"default"})
+
+
+def _strip_ref_siblings(node: Any) -> Any:
+    """Drop forbidden sibling keywords from nodes that carry ``$ref``.
+
+    Fireworks (and other draft-07-strict backends) fail tool requests with::
+
+        JSON Schema not supported: keyword(s) ['default'] not allowed at
+        the same level as $ref.
+
+    Nullable-union collapse and MCP ingestion can leave ``default`` on a
+    ``$ref`` node; strip it recursively.
+    """
+    if isinstance(node, list):
+        return [_strip_ref_siblings(item) for item in node]
+    if not isinstance(node, dict):
+        return node
+
+    out = {key: _strip_ref_siblings(value) for key, value in node.items()}
+    if "$ref" in out:
+        for key in _REF_FORBIDDEN_SIBLINGS:
+            if key in out:
+                out.pop(key, None)
     return out
 
 
@@ -185,6 +220,9 @@ def strip_nullable_unions(
                 replacement.setdefault("nullable", True)
             for meta_key in ("title", "description", "default", "examples"):
                 if meta_key in stripped and meta_key not in replacement:
+                    # ``default`` is illegal alongside ``$ref`` on strict backends.
+                    if meta_key == "default" and "$ref" in replacement:
+                        continue
                     replacement[meta_key] = stripped[meta_key]
             return strip_nullable_unions(replacement, keep_nullable_hint=keep_nullable_hint)
     return stripped

package/agent/tools/send_message_tool.py

@@ -38,8 +38,16 @@ _NUMERIC_TOPIC_RE = _TELEGRAM_TOPIC_TARGET_RE
 # below and falls through to channel-name resolution, which has no way to
 # resolve a raw phone number. Keeping the '+' preserves the E.164 form that
 # downstream adapters (signal, etc.) expect.
-_PHONE_PLATFORMS = frozenset({"signal", "sms", "whatsapp"})
+_PHONE_PLATFORMS = frozenset({"photon", "signal", "sms", "whatsapp"})
 _E164_TARGET_RE = re.compile(r"^\s*\+(\d{7,15})\s*$")
+# WhatsApp JIDs: group chats (<digits>@g.us), individual users
+# (<phone>@s.whatsapp.net), linked identities (<id>@lid), and broadcast /
+# newsletter chats. These are explicit native targets the bridge accepts
+# verbatim — they must NOT fall through to home-channel resolution.
+_WHATSAPP_JID_RE = re.compile(
+    r"^\s*[\w-]+@(?:g\.us|s\.whatsapp\.net|lid|broadcast|newsletter)\s*$",
+    re.IGNORECASE,
+)
 # Email addresses — a valid email like "user@domain.com" should be treated as
 # an explicit target for the email platform, not fall through to channel-name
 # resolution which has no way to resolve a raw address.
@@ -138,16 +146,24 @@ SEND_MESSAGE_SCHEMA = {
         "properties": {
             "action": {
                 "type": "string",
-                "enum": ["send", "list"],
-                "description": "Action to perform. 'send' (default) sends a message. 'list' returns all available channels/contacts across connected platforms."
+                "enum": ["send", "list", "react", "unreact"],
+                "description": "Action to perform. 'send' (default) sends a message. 'list' returns all available channels/contacts across connected platforms. 'react' attaches an emoji reaction to a message (platforms that support it, e.g. photon/iMessage tapbacks). 'unreact' retracts a previously-added reaction."
             },
             "target": {
                 "type": "string",
-                "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', 'platform:chat_id', or 'platform:chat_id:thread_id' for Telegram topics and Discord threads. Examples: 'telegram', 'telegram:-1001234567890:17585', 'discord:999888777:555444333', 'discord:#bot-home', 'slack:#engineering', 'signal:+155****4567', 'matrix:!roomid:server.org', 'matrix:@user:server.org', 'yuanbao:direct:<account_id>' (DM), 'yuanbao:group:<group_code>' (group chat)"
+                "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', 'platform:chat_id', or 'platform:chat_id:thread_id' for Telegram topics and Discord threads. Examples: 'telegram', 'telegram:-1001234567890:17585', 'discord:999888777:555444333', 'discord:#bot-home', 'slack:#engineering', 'signal:+155****4567', 'matrix:!roomid:server.org', 'matrix:@user:server.org', 'ntfy:alerts-channel' (explicit ntfy topic), 'yuanbao:direct:<account_id>' (DM), 'yuanbao:group:<group_code>' (group chat)"
             },
             "message": {
                 "type": "string",
                 "description": "The message text to send. To send an image or file, include MEDIA:<local_path> (e.g. 'MEDIA:/tmp/report.pdf') in the message — the platform will deliver it as a native media attachment."
+            },
+            "emoji": {
+                "type": "string",
+                "description": "For action='react': the emoji to react with (e.g. '❤️'). On iMessage, ❤️👍👎😂‼️❓ render as native tapbacks; other emoji use custom-emoji reactions."
+            },
+            "message_id": {
+                "type": "string",
+                "description": "For action='react'/'unreact': id of the message to react to. Omit to target the most recent message received in that chat (usually the one being replied to)."
             }
         },
         "required": []
@@ -162,6 +178,12 @@ def send_message_tool(args, **kw):
     if action == "list":
         return _handle_list()
 
+    if action == "react":
+        return _handle_react(args)
+
+    if action == "unreact":
+        return _handle_react(args, remove=True)
+
     return _handle_send(args)
 
 
@@ -174,6 +196,98 @@ def _handle_list():
         return json.dumps(_error(f"Failed to load channel directory: {e}"))
 
 
+def _handle_react(args, remove=False):
+    """Attach (or with ``remove=True`` retract) an emoji reaction on a message
+    via a live gateway adapter.
+
+    Only adapters that expose ``add_reaction(chat_id, emoji, message_id)`` /
+    ``remove_reaction(chat_id, message_id)`` coroutines support this (e.g.
+    photon/iMessage tapbacks). Requires the gateway to be running in this
+    process — there is no standalone fallback, since reacting needs the
+    adapter's live message-id state.
+    """
+    target = args.get("target", "")
+    emoji = (args.get("emoji") or "").strip()
+    message_id = (args.get("message_id") or "").strip() or None
+    if not target or (not remove and not emoji):
+        return tool_error(
+            "Both 'target' and 'emoji' are required when action='react'"
+            if not remove
+            else "'target' is required when action='unreact'"
+        )
+
+    parts = target.split(":", 1)
+    platform_name = parts[0].strip().lower()
+    target_ref = parts[1].strip() if len(parts) > 1 else None
+    chat_id = None
+    if target_ref:
+        chat_id, _thread_id, _ = _parse_target_ref(platform_name, target_ref)
+        if not chat_id:
+            try:
+                from gateway.channel_directory import resolve_channel_name
+                resolved = resolve_channel_name(platform_name, target_ref)
+            except Exception:
+                resolved = None
+            # Opaque platform-native ids (e.g. photon space GUIDs like
+            # 'any;-;+1555...') match no parser pattern and no directory
+            # entry — pass them through verbatim; the adapter validates.
+            chat_id = resolved or target_ref
+
+    try:
+        from gateway.config import Platform, load_gateway_config
+        platform = Platform(platform_name)
+    except (ValueError, KeyError):
+        return tool_error(f"Unknown platform: {platform_name}")
+
+    if not chat_id:
+        try:
+            config = load_gateway_config()
+            home = config.get_home_channel(platform)
+        except Exception:
+            home = None
+        if not home:
+            return tool_error(
+                f"No chat specified and no home channel set for {platform_name}. "
+                f"Use '{platform_name}:chat_id'."
+            )
+        chat_id = home.chat_id
+
+    runner = None
+    try:
+        from gateway.run import _gateway_runner_ref
+        runner = _gateway_runner_ref()
+    except Exception:
+        runner = None
+    adapter = runner.adapters.get(platform) if runner is not None else None
+    if adapter is None:
+        return tool_error(
+            f"Reactions require a live {platform_name} adapter in the running "
+            "gateway (not available from cron/standalone contexts)."
+        )
+    fn_name = "remove_reaction" if remove else "add_reaction"
+    react_fn = getattr(adapter, fn_name, None)
+    if not callable(react_fn):
+        return tool_error(
+            f"Platform '{platform_name}' does not support message reactions."
+        )
+
+    try:
+        from model_tools import _run_async
+        if remove:
+            result = _run_async(
+                react_fn(chat_id=chat_id, message_id=message_id)
+            )
+        else:
+            result = _run_async(
+                react_fn(chat_id=chat_id, emoji=emoji, message_id=message_id)
+            )
+    except Exception as e:
+        return json.dumps(_error(f"Reaction failed: {e}"))
+    if isinstance(result, dict):
+        return json.dumps(result)
+    return json.dumps({"success": bool(result)})
+
+
 def _handle_send(args):
     """Send a message to a platform target."""
     target = args.get("target", "")
@@ -395,10 +509,20 @@ def _parse_target_ref(platform_name: str, target_ref: str):
         if target_ref.strip().isdigit():
             return f"group:{target_ref.strip()}", None, True
         return None, None, False
+    if platform_name == "ntfy":
+        topic = target_ref.strip()
+        if topic:
+            return topic, None, True
     if platform_name == "email":
         match = _EMAIL_TARGET_RE.fullmatch(target_ref)
         if match:
             return target_ref.strip(), None, True
+    if platform_name == "whatsapp":
+        # Native WhatsApp JIDs (group @g.us, user @s.whatsapp.net, @lid, etc.)
+        # are explicit targets — pass through verbatim. E.164 '+' numbers fall
+        # through to the _PHONE_PLATFORMS handler below.
+        if _WHATSAPP_JID_RE.fullmatch(target_ref):
+            return target_ref.strip(), None, True
     if platform_name in _PHONE_PLATFORMS:
         match = _E164_TARGET_RE.fullmatch(target_ref)
         if match:
@@ -502,6 +626,7 @@ async def _send_via_adapter(
          the runner weakref is ``None``).
       3. A descriptive error explaining both options.
     """
+    platform_name = platform.value if hasattr(platform, "value") else str(platform)
     runner = None
     try:
         from gateway.run import _gateway_runner_ref
@@ -516,7 +641,13 @@ async def _send_via_adapter(
             adapter = None
         if adapter is not None:
             try:
-                metadata = {"thread_id": thread_id} if thread_id else None
+                metadata = {}
+                if thread_id:
+                    metadata["thread_id"] = thread_id
+                if platform_name == "ntfy" and chat_id:
+                    metadata["publish_topic"] = chat_id
+                if not metadata:
+                    metadata = None
                 result = await adapter.send(chat_id=chat_id, content=chunk, metadata=metadata)
             except asyncio.CancelledError:
                 raise
@@ -526,7 +657,6 @@ async def _send_via_adapter(
                 return {"success": True, "message_id": result.message_id}
             return {"error": f"Adapter send failed: {result.error}"}
 
-    platform_name = platform.value if hasattr(platform, "value") else str(platform)
     entry = None
     try:
         from gateway.platform_registry import platform_registry
@@ -578,6 +708,16 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
     (preserves code-block boundaries, adds part indicators).
     """
     from gateway.config import Platform
+
+    media_files = media_files or []
+
+    # Weixin handles text/media delivery inside its native helper and does not
+    # need the optional platform adapter imports below. Keep this branch early
+    # so a Weixin send is not blocked by unrelated optional dependencies (for
+    # example lark-oapi's heavy Feishu import path).
+    if platform == Platform.WEIXIN:
+        return await _send_weixin(pconfig, chat_id, message, media_files=media_files)
+
     from gateway.platforms.base import BasePlatformAdapter, utf16_len
     from gateway.platforms.slack import SlackAdapter
 
@@ -595,8 +735,6 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
     except ImportError:
         _feishu_available = False
 
-    media_files = media_files or []
-
     if platform == Platform.SLACK and message:
         try:
             slack_adapter = SlackAdapter.__new__(SlackAdapter)
@@ -653,10 +791,6 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
             last_result = result
         return last_result
 
-    # --- Weixin: use the native one-shot adapter helper for text + media ---
-    if platform == Platform.WEIXIN:
-        return await _send_weixin(pconfig, chat_id, message, media_files=media_files)
-
     # --- Discord: chunked delivery via the registry's standalone_sender_fn.
     # The plugin's ``_standalone_send`` (registered in
     # plugins/platforms/discord/adapter.py) handles forum channels, threads,
@@ -767,7 +901,7 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
     last_result = None
     for chunk in chunks:
         if platform == Platform.SLACK:
-            result = await _send_slack(pconfig.token, chat_id, chunk)
+            result = await _send_slack(pconfig.token, chat_id, chunk, thread_ts=thread_id)
         elif platform == Platform.WHATSAPP:
             result = await _send_whatsapp(pconfig.extra, chat_id, chunk)
         elif platform == Platform.SIGNAL:
@@ -778,8 +912,6 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
             result = await _send_sms(pconfig.api_key, chat_id, chunk)
         elif platform == Platform.MATRIX:
             result = await _send_matrix(pconfig.token, pconfig.extra, chat_id, chunk)
-        elif platform == Platform.HOMEASSISTANT:
-            result = await _send_homeassistant(pconfig.token, pconfig.extra, chat_id, chunk)
         elif platform == Platform.DINGTALK:
             result = await _send_dingtalk(pconfig.extra, chat_id, chunk)
         elif platform == Platform.FEISHU:
@@ -1049,7 +1181,7 @@ async def _send_telegram(token, chat_id, message, media_files=None, thread_id=No
         return _error(f"Telegram send failed: {e}")
 
 
-async def _send_slack(token, chat_id, message):
+async def _send_slack(token, chat_id, message, thread_ts=None):
     """Send via Slack Web API."""
     try:
         import aiohttp
@@ -1063,6 +1195,8 @@ async def _send_slack(token, chat_id, message):
         headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
         async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30), **_sess_kw) as session:
             payload = {"channel": chat_id, "text": message, "mrkdwn": True}
+            if thread_ts:
+                payload["thread_ts"] = thread_ts
             async with session.post(url, headers=headers, json=payload, **_req_kw) as resp:
                 data = await resp.json()
                 if data.get("ok"):
@@ -1474,29 +1608,6 @@ async def _send_matrix_via_adapter(pconfig, chat_id, message, media_files=None,
             pass
 
 
-async def _send_homeassistant(token, extra, chat_id, message):
-    """Send via Home Assistant notify service."""
-    try:
-        import aiohttp
-    except ImportError:
-        return {"error": "aiohttp not installed. Run: pip install aiohttp"}
-    try:
-        hass_url = (extra.get("url") or os.getenv("HASS_URL", "")).rstrip("/")
-        token = token or os.getenv("HASS_TOKEN", "")
-        if not hass_url or not token:
-            return {"error": "Home Assistant not configured (HASS_URL, HASS_TOKEN required)"}
-        url = f"{hass_url}/api/services/notify/notify"
-        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
-        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session:
-            async with session.post(url, headers=headers, json={"message": message, "target": chat_id}) as resp:
-                if resp.status not in {200, 201}:
-                    body = await resp.text()
-                    return _error(f"Home Assistant API error ({resp.status}): {body}")
-        return {"success": True, "platform": "homeassistant", "chat_id": chat_id}
-    except Exception as e:
-        return _error(f"Home Assistant send failed: {e}")
-
-
 async def _send_dingtalk(extra, chat_id, message):
     """Send via DingTalk robot webhook.
 
@@ -1788,13 +1899,16 @@ async def _send_yuanbao(chat_id, message, media_files=None):
 
 
 # --- Registry ---
-from tools.registry import registry, tool_error
-
-registry.register(
-    name="send_message",
-    toolset="messaging",
-    schema=SEND_MESSAGE_SCHEMA,
-    handler=send_message_tool,
-    check_fn=_check_send_message,
-    emoji="📨",
-)
+from tools.registry import tool_error
+
+# NOTE: ``send_message`` is intentionally NOT registered as an agent-callable
+# model tool. The agent should not decide on its own to fire off cross-platform
+# messages or reactions. The send engine in this module (``_send_to_platform``,
+# ``_send_via_adapter``, ``_parse_target_ref``, the per-platform ``_send_*``
+# helpers) remains the shared transport used by:
+#   - cron delivery (cron/scheduler.py)
+#   - the ``hermes send`` CLI command (hermes_cli/send_cmd.py)
+#   - the gateway kanban notifier (dashboard-toggled, outside agent control)
+#   - the standalone MCP server (mcp_serve.py), which is an opt-in surface
+# Those callers import the helpers directly; none of them need the registry
+# entry.

package/agent/tools/session_search_tool.py

@@ -34,9 +34,10 @@ import logging
 from typing import Any, Dict, List, Optional, Union
 
 # Sources that are excluded from session browsing/searching by default.
-# Third-party integrations tag their sessions with HERMES_SESSION_SOURCE=tool
-# so they don't clutter the user's session history.
-_HIDDEN_SESSION_SOURCES = ("tool",)
+# Third-party integrations tag their sessions with HERMES_SESSION_SOURCE=tool;
+# delegate subagent runs are tagged "subagent" — neither belongs in the
+# user's session history.
+_HIDDEN_SESSION_SOURCES = ("subagent", "tool")
 
 
 def _format_timestamp(ts: Union[int, float, str, None]) -> str:
@@ -107,6 +108,122 @@ def _shape_message(m: Dict[str, Any], anchor_id: Optional[int] = None) -> Dict[s
     return {k: v for k, v in entry.items() if v is not None or k in ("content",)}
 
 
+def _resolve_profile_db(profile: str):
+    """Open another profile's ``state.db`` read-only, or None for the current one.
+
+    The desktop's ``@session:<profile>/<id>`` links always carry the source
+    profile, so a linked session from profile B can be read while the agent
+    runs in profile A. ``read_only=True`` (mode=ro) takes no write lock — safe
+    to point at a live profile's DB, including our own. Returns None when no
+    profile is given (use the caller's default db).
+    """
+    if profile is None or not str(profile).strip():
+        return None
+
+    from hermes_cli import profiles as profiles_mod
+    from hermes_state import SessionDB
+
+    canon = profiles_mod.normalize_profile_name(profile)
+    profiles_mod.validate_profile_name(canon)
+    if not profiles_mod.profile_exists(canon):
+        raise ValueError(f"profile '{canon}' does not exist")
+
+    return SessionDB(db_path=profiles_mod.get_profile_dir(canon) / "state.db", read_only=True)
+
+
+def _locate_session_db(session_id: str):
+    """Scan every profile's ``state.db`` (read-only) for a session id.
+
+    Returns ``(db, profile_name)`` for the first profile that owns the id, or
+    ``(None, None)``. Session ids are globally unique (timestamp + random hex),
+    so the first hit is authoritative. This is the safety net for linked-session
+    reads where the model dropped the owning profile from the link and passed a
+    bare id — we find it wherever it actually lives instead of failing.
+    """
+    from pathlib import Path
+
+    try:
+        from hermes_cli import profiles as profiles_mod
+        from hermes_state import SessionDB
+    except Exception:
+        return None, None
+
+    targets = [("default", profiles_mod.get_profile_dir("default"))]
+    try:
+        targets += [(info.name, info.path) for info in profiles_mod.list_profiles()]
+    except Exception:
+        logging.debug("list_profiles failed during session locate", exc_info=True)
+
+    seen: set = set()
+    for name, home in targets:
+        db_path = Path(home) / "state.db"
+        key = str(db_path)
+        if key in seen or not db_path.exists():
+            continue
+        seen.add(key)
+        try:
+            pdb = SessionDB(db_path=db_path, read_only=True)
+        except Exception:
+            continue
+        try:
+            if pdb.get_session(session_id):
+                return pdb, name
+        except Exception:
+            logging.debug("get_session probe failed for %s in %s", session_id, name, exc_info=True)
+        pdb.close()
+
+    return None, None
+
+
+def _read_session(db, session_id: str, head: int = 20, tail: int = 10) -> str:
+    """Read shape: dump a whole session by id (head + tail when large).
+
+    Serves the linked-session case — the user dropped an @session reference and
+    the agent wants the transcript. Bounded payload: small sessions return in
+    full, large ones return the first ``head`` and last ``tail`` messages with a
+    pointer to scroll the middle.
+    """
+    try:
+        meta = db.get_session(session_id) or {}
+    except Exception as e:
+        logging.debug("get_session failed for %s: %s", session_id, e, exc_info=True)
+        meta = {}
+    if not meta:
+        return tool_error(f"session_id not found: {session_id}", success=False)
+
+    try:
+        rows = db.get_messages(session_id)
+    except Exception as e:
+        logging.error("get_messages failed for %s: %s", session_id, e, exc_info=True)
+        return tool_error(f"failed to load session: {e}", success=False)
+
+    shaped = [_shape_message(m) for m in rows]
+    total = len(shaped)
+    truncated = total > head + tail
+    window = shaped[:head] + shaped[-tail:] if truncated else shaped
+
+    response = {
+        "success": True,
+        "mode": "read",
+        "session_id": session_id,
+        "session_meta": {
+            "when": _format_timestamp(meta.get("started_at")),
+            "source": meta.get("source"),
+            "model": meta.get("model"),
+            "title": meta.get("title"),
+        },
+        "message_count": total,
+        "truncated": truncated,
+        "messages": window,
+    }
+    if truncated:
+        response["message"] = (
+            f"Session has {total} messages; showing first {head} + last {tail}. "
+            "Pass around_message_id (any id above) to scroll the middle."
+        )
+    return json.dumps(response, ensure_ascii=False)
+
+
 def _list_recent_sessions(db, limit: int, current_session_id: str = None) -> str:
     """Return metadata for the most recent sessions (no LLM calls, no FTS5)."""
     try:
@@ -387,15 +504,19 @@ def session_search(
     window: int = 5,
     # Discovery shape
     sort: str = None,
+    # Cross-profile (any shape)
+    profile: str = None,
 ) -> str:
     """Single-shape tool. Mode inferred from which args are set.
 
     Discovery: pass ``query``.
     Scroll:    pass ``session_id`` + ``around_message_id``.
+    Read:      pass ``session_id`` (no anchor) — dumps the whole session.
     Browse:    pass nothing.
 
-    Scroll wins over discovery when both are set — the agent has explicitly
-    asked for a slice of a known session.
+    Pass ``profile`` to read another profile's sessions (e.g. resolving an
+    ``@session:<profile>/<id>`` link). Scroll wins over read/discovery when an
+    anchor is set — the agent has asked for a specific slice.
     """
     if db is None:
         try:
@@ -406,6 +527,30 @@ def session_search(
             from hermes_state import format_session_db_unavailable
             return tool_error(format_session_db_unavailable(), success=False)
 
+    # Normalise a raw `@session:<profile>/<id>` link value passed as session_id.
+    # Session ids never contain "/", so a slash unambiguously means profile/id —
+    # always strip the prefix off the id, and adopt the embedded profile only
+    # when one wasn't passed explicitly. Handles every permutation the model
+    # might send (full value as id, with or without a separate profile=).
+    if isinstance(session_id, str) and "/" in session_id:
+        emb_profile, _, emb_id = session_id.partition("/")
+        if emb_id:
+            session_id = emb_id
+            if emb_profile and (profile is None or not str(profile).strip()):
+                profile = emb_profile
+
+    # Cross-profile read: swap in the named profile's DB (read-only) for every
+    # shape below. The current-session-lineage guards no longer apply across
+    # profiles, but they key off ids that won't collide, so they stay inert.
+    if profile is not None and str(profile).strip():
+        try:
+            profile_db = _resolve_profile_db(profile)
+        except Exception as e:
+            return tool_error(f"profile '{profile}': {e}", success=False)
+        if profile_db is not None:
+            db = profile_db
+            current_session_id = None
+
     # Scroll shape takes precedence — explicit anchor beats any query.
     if (isinstance(session_id, str) and session_id.strip()) and around_message_id is not None:
         return _scroll(
@@ -416,6 +561,27 @@ def session_search(
             current_session_id=current_session_id,
         )
 
+    # Read shape: a session_id with no anchor → dump the whole session.
+    if isinstance(session_id, str) and session_id.strip():
+        sid = session_id.strip()
+        result = _read_session(db, sid)
+        if json.loads(result).get("success"):
+            return result
+
+        # Miss in the target profile — the model may have dropped the owning
+        # profile from the link. Scan every profile and read it from wherever
+        # it lives, tagging the profile it was found in.
+        located, owner = _locate_session_db(sid)
+        if located is not None:
+            try:
+                found = json.loads(_read_session(located, sid))
+            finally:
+                located.close()
+            if found.get("success"):
+                found["profile"] = owner
+                return json.dumps(found, ensure_ascii=False)
+        return result
+
     # Limit clamp [1, 10]
     if not isinstance(limit, int):
         try:
@@ -465,7 +631,7 @@ SESSION_SEARCH_SCHEMA = {
         "Search past sessions stored in the local session DB, or scroll inside one. "
         "FTS5-backed retrieval over the SQLite message store. No LLM calls — every "
         "shape returns actual messages from the DB.\n\n"
-        "THREE CALLING SHAPES\n\n"
+        "FOUR CALLING SHAPES\n\n"
         "  1) DISCOVERY — pass `query`:\n"
         "     session_search(query=\"auth refactor\", limit=3)\n"
         "     Runs FTS5, dedupes hits by session lineage, returns the top N sessions. "
@@ -491,7 +657,13 @@ SESSION_SEARCH_SCHEMA = {
         "       - The boundary message appears in both windows — orientation marker.\n"
         "       - When messages_before or messages_after is < window, you're at the "
         "start or end of the session.\n\n"
-        "  3) BROWSE — no args:\n"
+        "  3) READ — pass `session_id` only (no around_message_id):\n"
+        "     session_search(session_id=\"...\", profile=\"work\")\n"
+        "     Dumps the whole session by id (first 20 + last 10 messages when "
+        "large). This is how you resolve an `@session:<profile>/<id>` link the "
+        "user dropped into the chat: split the value on `/` into profile + id "
+        "and call session_search(session_id=id, profile=profile).\n\n"
+        "  4) BROWSE — no args:\n"
         "     session_search()\n"
         "     Returns recent sessions chronologically: titles, previews, timestamps. "
         "Use when the user asks \"what was I working on\" without naming a topic.\n\n"
@@ -573,6 +745,15 @@ SESSION_SEARCH_SCHEMA = {
                     "behaviour) or 'tool' to search tool output only."
                 ),
             },
+            "profile": {
+                "type": "string",
+                "description": (
+                    "Optional. Read sessions from another Hermes profile's database "
+                    "(read-only). Use when resolving an `@session:<profile>/<id>` link: "
+                    "pass the profile segment here with session_id as the id segment. "
+                    "Omit to use the current profile."
+                ),
+            },
         },
         "required": [],
     },
@@ -594,6 +775,7 @@ registry.register(
         around_message_id=args.get("around_message_id"),
         window=args.get("window", 5),
         sort=args.get("sort"),
+        profile=args.get("profile"),
         db=kw.get("db"),
         current_session_id=kw.get("current_session_id"),
     ),