claude-smart 0.2.30 → 0.2.32

package/plugin/src/claude_smart/context_format.py

@@ -2,9 +2,18 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable
+import os
+from collections.abc import Iterable
+from typing import Any
+from urllib.parse import quote, urlparse
 
-from claude_smart import cs_cite
+from claude_smart import cs_cite, env_config
+
+_DASHBOARD_URL_ENV = "CLAUDE_SMART_DASHBOARD_URL"
+_CITATION_LINK_STYLE_ENV = "CLAUDE_SMART_CITATION_LINK_STYLE"
+_DEFAULT_DASHBOARD_URL = "http://localhost:3001"
+_REFLEXIO_URL_ENV = "REFLEXIO_URL"
+_LOCAL_REFLEXIO_HOSTS = {"localhost", "127.0.0.1", "0.0.0.0", "::1"}
 
 
 def _first_nonempty(*values: Any) -> str:
@@ -93,7 +102,17 @@ def render_with_registry(
     if profile_lines:
         sections.append("### Project preferences")
         sections.extend(profile_lines)
-    sections.append(cs_cite.CITATION_INSTRUCTION)
+    instruction = _citation_instruction(
+        os.environ.get("CLAUDE_SMART_CITATIONS", "on"),
+        os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown"),
+    )
+    if instruction:
+        sections.append(instruction)
+    exact_osc8_marker = _exact_osc8_marker_instruction(
+        playbook_entries + profile_entries
+    )
+    if exact_osc8_marker:
+        sections.append(exact_osc8_marker)
     return "\n".join(sections) + "\n", playbook_entries + profile_entries
 
 
@@ -164,16 +183,159 @@ def render_inline_with_registry(
     if profile_lines:
         sections.append("### Relevant project preferences")
         sections.extend(profile_lines)
-    sections.append(cs_cite.CITATION_INSTRUCTION)
+    instruction = _citation_instruction(
+        os.environ.get("CLAUDE_SMART_CITATIONS", "on"),
+        os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown"),
+    )
+    if instruction:
+        sections.append(instruction)
+    exact_osc8_marker = _exact_osc8_marker_instruction(
+        playbook_entries + profile_entries
+    )
+    if exact_osc8_marker:
+        sections.append(exact_osc8_marker)
     return "\n".join(sections) + "\n", playbook_entries + profile_entries
 
 
+def render_inline_compact_with_registry(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> tuple[str, list[dict[str, Any]]]:
+    """Render mid-session context as one compact logical line.
+
+    Codex currently displays ``UserPromptSubmit.additionalContext`` in the TUI.
+    This renderer preserves the model-visible ids and rule URLs needed for
+    citation tracking while avoiding the multi-line markdown block used by
+    hosts that can hide hook context.
+    """
+    del project_id  # kept for symmetry with ``render_inline_with_registry``.
+    _, playbook_entries = _format_combined_playbooks(
+        agent_playbooks=agent_playbooks, user_playbooks=user_playbooks
+    )
+    _, profile_entries = _format_profiles(profiles)
+    entries = playbook_entries + profile_entries
+    if not entries:
+        return "", []
+
+    skill_parts = []
+    preference_parts = []
+    marker_parts = []
+    link_style = os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown")
+    for entry in entries:
+        title = _one_line(str(entry.get("title") or entry["content"]))
+        content = _one_line(str(entry["content"]))
+        rule_url = str(entry.get("rule_url") or "")
+        if link_style == "osc8" and rule_url:
+            linked_title = _osc8_link(
+                rule_url, _strip_trailing_sentence_punctuation(title)
+            )
+            item = _osc8_link(rule_url, _strip_trailing_sentence_punctuation(content))
+            marker_parts.append(linked_title)
+        else:
+            item = f"{content} (title: {title}"
+            if rule_url:
+                item += f"; open: {rule_url}"
+            item += ")"
+        if entry.get("kind") == "profile":
+            preference_parts.append(item)
+        else:
+            skill_parts.append(item)
+
+    memory_sections = []
+    if skill_parts:
+        label = "Skill" if len(skill_parts) == 1 else "Skills"
+        memory_sections.append(f"{label}: {'; '.join(skill_parts)}")
+    if preference_parts:
+        label = "Preference" if len(preference_parts) == 1 else "Preferences"
+        memory_sections.append(f"{label}: {'; '.join(preference_parts)}")
+    sections = [f"claude-smart: using relevant memory. {'. '.join(memory_sections)}."]
+    instruction = _compact_citation_instruction(marker_parts)
+    if instruction:
+        sections.append(instruction)
+    return " ".join(sections) + "\n", entries
+
+
+def _compact_citation_instruction(marker_parts: list[str] | None = None) -> str:
+    if os.environ.get("CLAUDE_SMART_CITATIONS", "on") == "off":
+        return ""
+    link_style = os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown")
+    if link_style == "osc8" and marker_parts:
+        marker = f"✨ claude-smart rule applied: {' | '.join(marker_parts)}"
+        separator_instruction = (
+            " Separate multiple linked memories with the visible ` | ` separator."
+            if len(marker_parts) > 1
+            else ""
+        )
+        return _remoteize_citation_instruction(
+            f"If used, copy this final marker exactly, preserving its hidden "
+            f"OSC 8 terminal link: `{marker}`.{separator_instruction} "
+            f"Skip when unrelated."
+        )
+    if link_style == "osc8":
+        return _remoteize_citation_instruction(
+            "If used, end with `✨ claude-smart rule applied:` followed by "
+            "the same linked memory text; keep the link, but do not show the "
+            "URL. Skip when unrelated."
+        )
+    return _remoteize_citation_instruction(
+        "Only if a listed [cs:...] item materially changes your answer, end "
+        "with one final marker like `✨ claude-smart rule applied: "
+        "[verify process state](http://localhost:3001/rules/s1-123)` using "
+        "the shown rule URL; skip the marker when unrelated."
+    )
+
+
+def _citation_instruction(mode: str, link_style: str) -> str:
+    return _remoteize_citation_instruction(
+        cs_cite.citation_instruction(mode, link_style)
+    )
+
+
+def _remoteize_citation_instruction(text: str) -> str:
+    playbooks_url = _remote_reflexio_page_url("playbook")
+    profiles_url = _remote_reflexio_page_url("profile")
+    if not text or not playbooks_url or not profiles_url:
+        return text
+    return text.replace("http://localhost:3001/rules/s1-123", playbooks_url).replace(
+        "http://localhost:3001/rules/p1-pref", profiles_url
+    )
+
+
+def _exact_osc8_marker_instruction(entries: list[dict[str, Any]]) -> str:
+    if os.environ.get("CLAUDE_SMART_CITATIONS", "on") == "off":
+        return ""
+    if os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown") != "osc8":
+        return ""
+
+    marker_parts = []
+    for entry in entries:
+        rule_url = str(entry.get("rule_url") or "")
+        if not rule_url:
+            continue
+        title = _one_line(str(entry.get("title") or entry["content"]))
+        marker_parts.append(
+            _osc8_link(rule_url, _strip_trailing_sentence_punctuation(title))
+        )
+    if not marker_parts:
+        return ""
+
+    marker = f"✨ claude-smart rule applied: {' | '.join(marker_parts)}"
+    return (
+        "If any listed memory above was used, copy this exact final marker, "
+        f"preserving its hidden OSC 8 terminal links: `{marker}`. "
+        "Do not rename, summarize, or regroup the linked titles."
+    )
+
+
 def _format_combined_playbooks(
     *,
     agent_playbooks: Iterable[Any],
     user_playbooks: Iterable[Any],
 ) -> tuple[list[str], list[dict[str, Any]]]:
-    """Render agent playbooks first, then user playbooks, with one shared rank counter."""
+    """Render agent then user playbooks with one shared rank counter."""
     lines: list[str] = []
     entries: list[dict[str, Any]] = []
     rank = 0
@@ -205,11 +367,15 @@ def _append_playbook_bullet(
     real_id = _field(pb, id_field)
     item_id = cs_cite.rank_id("playbook", rank, real_id)
     title = _title_from_content(content)
+    dashboard_url = _dashboard_url("playbook", real_id, source_kind)
+    rule_url = _rule_url(item_id, "playbook")
     bullet = f"- [cs:{item_id}] {content}"
     if trigger:
         bullet += f" _(when: {trigger})_"
     if rationale:
         bullet += f" — *why:* {rationale}"
+    if rule_url:
+        bullet += f" _(open: {rule_url})_"
     lines.append(bullet)
     entries.append(
         {
@@ -219,6 +385,8 @@ def _append_playbook_bullet(
             "content": content,
             "real_id": str(real_id) if real_id is not None else None,
             "source_kind": source_kind,
+            "dashboard_url": dashboard_url,
+            "rule_url": rule_url,
         }
     )
     return rank
@@ -238,7 +406,12 @@ def _format_profiles(
         real_id = _field(p, "profile_id")
         item_id = cs_cite.rank_id("profile", rank, real_id)
         title = _title_from_content(content)
-        lines.append(f"- [cs:{item_id}] {content}")
+        dashboard_url = _dashboard_url("profile", real_id)
+        rule_url = _rule_url(item_id, "profile")
+        bullet = f"- [cs:{item_id}] {content}"
+        if rule_url:
+            bullet += f" _(open: {rule_url})_"
+        lines.append(bullet)
         entries.append(
             {
                 "id": item_id,
@@ -246,11 +419,64 @@ def _format_profiles(
                 "title": title,
                 "content": content,
                 "real_id": str(real_id) if real_id is not None else None,
+                "dashboard_url": dashboard_url,
+                "rule_url": rule_url,
             }
         )
     return lines, entries
 
 
+def _dashboard_url(kind: str, real_id: Any, source_kind: str | None = None) -> str:
+    remote_url = _remote_reflexio_page_url(kind)
+    if remote_url:
+        return remote_url
+    if real_id is None:
+        return ""
+    encoded_id = quote(str(real_id), safe="")
+    base = os.environ.get(_DASHBOARD_URL_ENV, _DEFAULT_DASHBOARD_URL).rstrip("/")
+    if kind == "profile":
+        return f"{base}/preferences/project/{encoded_id}"
+    if kind == "playbook":
+        skill_kind = "shared" if source_kind == "agent_playbook" else "project"
+        return f"{base}/skills/{skill_kind}/{encoded_id}"
+    return ""
+
+
+def _rule_url(item_id: str, kind: str) -> str:
+    remote_url = _remote_reflexio_page_url(kind)
+    if remote_url:
+        return remote_url
+    if not item_id:
+        return ""
+    encoded_id = quote(item_id, safe="")
+    base = os.environ.get(_DASHBOARD_URL_ENV, _DEFAULT_DASHBOARD_URL).rstrip("/")
+    return f"{base}/rules/{encoded_id}"
+
+
+def _remote_reflexio_page_url(kind: str) -> str:
+    origin = _remote_reflexio_origin()
+    if not origin:
+        return ""
+    if kind == "profile":
+        return f"{origin}/profiles"
+    if kind == "playbook":
+        return f"{origin}/playbooks"
+    return ""
+
+
+def _remote_reflexio_origin() -> str:
+    env_config.load_reflexio_env()
+    raw = os.environ.get(_REFLEXIO_URL_ENV, "").strip()
+    if not raw:
+        return ""
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return ""
+    if (parsed.hostname or "").lower() in _LOCAL_REFLEXIO_HOSTS:
+        return ""
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
 def _title_from_content(content: str, limit: int = 80) -> str:
     """Derive a compact human-readable title from a bullet's content.
 
@@ -270,6 +496,18 @@ def _title_from_content(content: str, limit: int = 80) -> str:
     return text[: limit - 1].rstrip() + "…"
 
 
+def _one_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _osc8_link(url: str, label: str) -> str:
+    return f"\x1b]8;;{url}\x1b\\{label}\x1b]8;;\x1b\\"
+
+
+def _strip_trailing_sentence_punctuation(text: str) -> str:
+    return text.rstrip().rstrip(".!?")
+
+
 def _field(obj: Any, name: str) -> Any:
     """Read ``name`` from either an attribute or a dict key."""
     if isinstance(obj, dict):

package/plugin/src/claude_smart/context_inject.py

@@ -17,6 +17,7 @@ turn) — see the two call sites for the small policy differences.
 from __future__ import annotations
 
 import json
+import os
 import sys
 import time
 
@@ -59,7 +60,13 @@ def emit_context(
         query=query,
         top_k=top_k,
     )
-    markdown, registry = context_format.render_inline_with_registry(
+    renderer = (
+        context_format.render_inline_compact_with_registry
+        if hook_event_name == "UserPromptSubmit"
+        and os.environ.get("CLAUDE_SMART_HOST") == "codex"
+        else context_format.render_inline_with_registry
+    )
+    markdown, registry = renderer(
         project_id=project_id,
         user_playbooks=user_playbooks,
         agent_playbooks=agent_playbooks,

package/plugin/src/claude_smart/cs_cite.py

@@ -7,7 +7,7 @@ real id (``[cs:s1-1a2b]`` for the first skill whose
 second preference). The injected instruction asks the assistant to end
 impactful replies with a marker like::
 
-    ✨ 1 claude-smart learning applied [cs:s1-1a2b]
+    ✨ claude-smart rule applied: [git safety](http://localhost:3001/rules/s1-123)
 
 The Stop hook later scans the assistant text for those markers and resolves
 the ids against a per-session registry persisted at
@@ -26,18 +26,24 @@ This module holds:
 - ``rank_id``: ``p{n}-{fp}`` / ``s{n}-{fp}`` tag for a given
   (kind, rank, real_id) tuple. Fingerprint is omitted when no real id
   is available. ``p`` is preference, ``s`` is skill.
-- ``CITATION_INSTRUCTION``: the trailer text appended to injected context
-  so the assistant knows when and how to emit the citation marker.
+- ``citation_instruction(mode)``: the trailer text appended to injected
+  context so the assistant knows when and how to emit the citation marker.
+  ``mode`` is read from the ``CLAUDE_SMART_CITATIONS`` env var by the
+  caller; ``"off"`` disables the instruction, while all other values enable
+  the compact marker instruction for backward compatibility.
+- ``CITATION_INSTRUCTION``: the compact enabled instruction string, kept as
+  a module-level constant for backward-compatible imports.
 """
 
 from __future__ import annotations
 
 import re
 from typing import Any
+from urllib.parse import unquote, urlparse
 
 _FINGERPRINT_LEN = 4
 
-_ID_TOKEN = r"(?i:cs:)?(?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?"
+_ID_TOKEN = r"(?i:cs:)?(?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?"  # noqa: S105
 _ID_SEP = r"[,\s]+"
 _CLEAN_ID_RE = re.compile(r"^(?i:cs:)?((?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?)$")
 _SPLIT_RE = re.compile(_ID_SEP)
@@ -45,28 +51,97 @@ _TEXT_CITATION_LINE_RE = re.compile(
     r"(?im)^\s*✨\s+\d+\s+claude-smart learning(?:s)? applied\s+"
     r"\[cs:(?P<ids>[^\]]+)\]\s*$"
 )
+_APPLIED_LINK_LINE_RE = re.compile(
+    r"(?im)^\s*✨\s+(?:Applied|claude-smart rules? applied):\s+(?P<body>.+?)\s*$"
+)
+_MARKDOWN_LINK_RE = re.compile(r"\[[^\]]+\]\((?P<url>[^)]+)\)")
+_OSC8_URL_RE = re.compile(
+    r"\x1b\]8;[^\x07\x1b]*;(?P<url>[^\x07\x1b]+)(?:\x07|\x1b\\)"
+)
+_RAW_DASHBOARD_URL_RE = re.compile(
+    r"(?P<url>(?:https?://[^\s),\x1b\\]+)?/"
+    r"(?:skills/(?:project|shared)/[^\s),\x1b\\]+|"
+    r"preferences/(?:project/)?[^\s),\x1b\\]+|"
+    r"rules/[^\s),\x1b\\]+))"
+)
+
+_COMPACT_INTRO = (
+    "_If you use any listed `[cs:…]` item to answer and it materially changes "
+    "your answer, you must end with one final marker line. Skip the marker "
+    "only when no listed item affected the answer."
+)
 
-CITATION_INSTRUCTION = (
-    "_First, fully answer the user — citation does not change what or how "
-    "you reply. Then, as a final step, consider whether to cite: if — and "
-    "only if — an injected `[cs:…]` item materially changed your reply "
-    "(different wording, action, or conclusion than you would have produced "
-    "without it), append exactly one final citation line after your answer. "
-    "Do not call a shell command or any other tool for citations. Ids come verbatim "
-    "from the `[cs:…]` tags — keep the leading `p` (preference) or `s` "
-    "(skill) and the `-<fp>` suffix. Use this exact format for one id: "
-    "`✨ 1 claude-smart learning applied [cs:s1-ab12]`. Use this exact format "
-    "for multiple ids: `✨ 2 claude-smart learnings applied [cs:s1-ab12,p2-cd34]`, "
-    "where the number is the count of ids in the brackets. "
-    "Never emit a standalone wrapper like `✨s1-ab12✨` or `✨abc123✨`; "
-    "those are not claude-smart citations and cannot be resolved. "
-    "Default is to skip. If an item is merely on-topic, confirms what you "
-    "already planned, or your reply would read the same without it, do not "
-    "cite — end the turn normally with your reply. When unsure, skip. Do "
-    "not add any other text, tool calls, or role markers after the final "
-    "citation line._"
+_MARKDOWN_MARKER_PARAGRAPH = (
+    "Use human-readable linked titles, not raw ids. Format for one item: "
+    "`✨ claude-smart rule applied: "
+    "[verify process state](http://localhost:3001/rules/s1-123)`. "
+    "For multiple items: "
+    "`✨ claude-smart rule applied: "
+    "[git safety](http://localhost:3001/rules/s1-123) | "
+    "[brief answer preference](http://localhost:3001/rules/p1-pref)`. "
+    "Separate multiple linked memories with the visible ` | ` separator. "
+    "Use the dashboard URL shown beside each cited item; do not invent URLs. "
+    "Do not include `[cs:…]` ids in the marker line. Never use the old "
+    "`✨ 1 claude-smart learning applied [cs:...]` marker format._"
 )
 
+_OSC8_EXAMPLE_ONE = (
+    "✨ claude-smart rule applied: "
+    "\x1b]8;;http://localhost:3001/rules/s1-123\x1b\\"
+    "verify process state"
+    "\x1b]8;;\x1b\\"
+)
+_OSC8_EXAMPLE_MULTI = (
+    "✨ claude-smart rule applied: "
+    "\x1b]8;;http://localhost:3001/rules/s1-123\x1b\\"
+    "git safety"
+    "\x1b]8;;\x1b\\"
+    " | "
+    "\x1b]8;;http://localhost:3001/rules/p1-pref\x1b\\"
+    "brief answer preference"
+    "\x1b]8;;\x1b\\"
+)
+_OSC8_MARKER_PARAGRAPH = (
+    "Use human-readable OSC 8 terminal hyperlinks, not raw ids or visible "
+    "URLs. Format for one item: "
+    f"`{_OSC8_EXAMPLE_ONE}`. For multiple items: "
+    f"`{_OSC8_EXAMPLE_MULTI}`. Use the dashboard URL shown beside each cited "
+    "item; do not invent URLs. Separate multiple linked memories with the "
+    "visible ` | ` separator. If OSC 8 is unavailable, use markdown links. "
+    "Do not include `[cs:…]` ids in the marker line. Do not omit the marker "
+    "after using listed memory._"
+)
+
+CITATION_MODES = ("on", "auto", "marker-only", "off")
+LINK_STYLES = ("markdown", "osc8")
+
+
+def citation_instruction(mode: str, link_style: str = "markdown") -> str:
+    """Return the citation prompt for ``mode``.
+
+    Args:
+        mode: ``"off"`` returns an empty string so no instruction is
+            injected. Any other value, including legacy ``"auto"`` and
+            ``"marker-only"``, returns the compact enabled instruction.
+            Unknown values stay enabled — env-var typos must not break
+            injection.
+        link_style: ``"markdown"`` for ordinary markdown links, or ``"osc8"``
+            for terminal-native hyperlinks. Unknown values fall back to
+            ``"markdown"``.
+
+    Returns:
+        str: The instruction text, or ``""`` for ``"off"``.
+    """
+    if mode == "off":
+        return ""
+    marker_paragraph = (
+        _OSC8_MARKER_PARAGRAPH if link_style == "osc8" else _MARKDOWN_MARKER_PARAGRAPH
+    )
+    return f"{_COMPACT_INTRO}\n\n{marker_paragraph}"
+
+
+CITATION_INSTRUCTION = citation_instruction("on")
+
 
 def _fingerprint(real_id: Any) -> str:
     """Return the first ``_FINGERPRINT_LEN`` alphanumeric chars of ``real_id``.
@@ -128,21 +203,98 @@ def rank_id(kind: str, rank: int, real_id: Any = None) -> str:
 def parse_text_citations(text: str) -> list[str]:
     """Extract Codex text-only citation ids from a final learning marker line.
 
-    The parser intentionally only accepts lines containing the visual
-    ``claude-smart learning(s) applied`` marker, so ordinary references to
-    injected ``[cs:...]`` ids inside an answer do not count as citations.
-    When multiple matching lines exist, the last one wins because the
+    Supports the legacy id marker::
+
+        ✨ 1 claude-smart learning applied [cs:s1-ab12]
+
+    and the newer human-readable dashboard-link marker::
+
+        ✨ claude-smart rule applied: [git safety](http://localhost:3001/rules/s1-123)
+
+    Ordinary references to injected ``[cs:...]`` ids or dashboard URLs inside
+    the answer do not count as citations; they must appear on a final marker
+    line. When multiple matching lines exist, the last one wins because the
     instruction requires the citation marker to be final.
     """
-    matches = list(_TEXT_CITATION_LINE_RE.finditer(text or ""))
+    old_matches = [
+        (m.start(), "ids", m.group("ids"))
+        for m in _TEXT_CITATION_LINE_RE.finditer(text or "")
+    ]
+    new_matches = [
+        (m.start(), "links", m.group("body"))
+        for m in _APPLIED_LINK_LINE_RE.finditer(text or "")
+    ]
+    matches = old_matches + new_matches
     if not matches:
         return []
-    return _parse_id_tokens(matches[-1].group("ids"))
+    _, kind, value = max(matches, key=lambda item: item[0])
+    if kind == "ids":
+        return _parse_id_tokens(value)
+    return _parse_dashboard_link_tokens(value)
+
+
+def strip_marker_lines(text: str) -> str:
+    """Remove any ``✨ N claude-smart learning(s) applied [cs:…]`` lines.
+
+    Used by the Stop hook when ``CLAUDE_SMART_CITATIONS=off`` to scrub
+    any marker the assistant emitted from a cached prompt fragment that
+    still contained the citation instruction. Returns ``text`` unchanged
+    when no marker line is present.
+
+    Args:
+        text: Assistant message text.
+
+    Returns:
+        str: ``text`` with marker lines removed, trailing blank lines
+            trimmed. ``""`` when ``text`` is falsy.
+    """
+    if not text:
+        return text or ""
+    cleaned = _TEXT_CITATION_LINE_RE.sub("", text)
+    cleaned = _APPLIED_LINK_LINE_RE.sub("", cleaned)
+    return cleaned.rstrip("\n")
 
 
 def _parse_id_tokens(raw_ids: str) -> list[str]:
-    ids: list[str] = []
-    for tok in _SPLIT_RE.split(raw_ids.strip()):
-        if clean := _CLEAN_ID_RE.match(tok):
-            ids.append(clean.group(1).lower())
-    return ids
+    return [
+        clean.group(1).lower()
+        for tok in _SPLIT_RE.split(raw_ids.strip())
+        if (clean := _CLEAN_ID_RE.match(tok))
+    ]
+
+
+def _parse_dashboard_link_tokens(raw: str) -> list[str]:
+    tokens: list[str] = []
+    seen: set[str] = set()
+    matches = [
+        (m.start(), m.group("url"))
+        for regex in (_OSC8_URL_RE, _MARKDOWN_LINK_RE, _RAW_DASHBOARD_URL_RE)
+        for m in regex.finditer(raw)
+    ]
+    for _, url in sorted(matches, key=lambda item: item[0]):
+        if (token := dashboard_url_token(url)) and token not in seen:
+            seen.add(token)
+            tokens.append(token)
+    return tokens
+
+
+def dashboard_url_token(url: str) -> str:
+    """Return an internal resolver token for a dashboard detail URL.
+
+    The token is consumed by ``events.stop._resolve_cited_items``. It is not
+    shown to users.
+    """
+    parsed = urlparse(url)
+    path = parsed.path if parsed.scheme else url.split("?", 1)[0].split("#", 1)[0]
+    parts = [unquote(part) for part in path.strip("/").split("/") if part]
+    if len(parts) == 3 and parts[0] == "skills" and parts[1] in {"project", "shared"}:
+        source_kind = "user_playbook" if parts[1] == "project" else "agent_playbook"
+        return f"route:playbook:{source_kind}:{parts[2]}"
+    if len(parts) == 2 and parts[0] == "preferences":
+        return f"route:profile:profile:{parts[1]}"
+    if len(parts) == 3 and parts[0] == "preferences" and parts[1] == "project":
+        return f"route:profile:profile:{parts[2]}"
+    if len(parts) == 2 and parts[0] == "rules":
+        clean = _CLEAN_ID_RE.match(parts[1])
+        return clean.group(1).lower() if clean else ""
+    return ""