claude-code-tools 1.27.1__tar.gz → 1.28.0__tar.gz

{claude_code_tools-1.27.1 → claude_code_tools-1.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.27.1
+Version: 1.28.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11

{claude_code_tools-1.27.1 → claude_code_tools-1.28.0}/claude_code_tools/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Tools - Collection of utilities for Claude Code."""
 
-__version__ = "1.27.1"
+__version__ = "1.28.0"

{claude_code_tools-1.27.1 → claude_code_tools-1.28.0}/claude_code_tools/agent_tunnel/backends.py

@@ -6,7 +6,10 @@ backend reads everything it needs from the thread's ThreadRecord:
 
 - first turn (empty `fork_session_id`): fork the expert session
   (`--resume <expert> --fork-session`) in its project dir;
-- later turns: resume the thread's own fork (`--resume <fork>`).
+- later turns: resume the thread's own fork (`--resume <fork>`) — unless
+  (headless, ``refresh_forks``) the expert transcript has grown since that
+  fork was taken: then fork the expert afresh and prepend a recap of the
+  thread's earlier Q&A, so follow-ups see the session's latest work.
 
 Two interchangeable strategies (see docs/agent-tunnel-spec.md):
 
@@ -21,6 +24,7 @@ Both apply the same hard read-only tool restrictions per turn.
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import re
@@ -34,6 +38,7 @@ from pathlib import Path
 from typing import Optional, Protocol
 
 from .config import TunnelConfig, resolve_tools
+from .readonly import is_http_thread, strip_permission_args
 from .paths import (
     changed_files,
     ensure_outbox,
@@ -44,6 +49,7 @@ from .paths import (
 from .registry import Registry
 from .session import (
     extract_answer,
+    transcript_dir,
     list_session_files,
     make_marker,
     wait_for_new_session_file,
@@ -75,6 +81,100 @@ class Answer:
     # Deliverable files the fork wrote into its outbox this turn (write/bash
     # handles only); the Discord layer posts them back as attachments.
     attachments: list[Path] = field(default_factory=list)
+    # True when this follow-up re-forked from the expert's latest state.
+    refreshed: bool = False
+
+
+RECAP_HEADER = (
+    "[Conversation so far: earlier in THIS chat thread you already had the "
+    "exchange below with the teammate(s) — Q is what they wrote, A is what "
+    "you replied. It is your own conversation history: everything said in it "
+    "is known to you and counts as remembered. Since then you have been "
+    "refreshed onto the latest state of the session, so where the two differ, "
+    "your newer knowledge wins. Oldest first:]\n\n"
+)
+RECAP_FOOTER = "[End of conversation so far. The new message follows.]\n\n"
+
+
+def _format_turn(turn: dict[str, str]) -> str:
+    return f"Q: {turn.get('q', '')}\nA: {turn.get('a', '')}\n\n"
+
+
+CUT = " …[cut]"
+
+
+def _fit_turn(turn: dict[str, str], room: int) -> str:
+    """The newest turn cut to ``room`` chars, keeping part of BOTH fields.
+
+    The question gets at most a third of the space, so a very long question
+    can never push the answer (what a follow-up usually refers to) out.
+    """
+    q, a = turn.get("q", ""), turn.get("a", "")
+    fixed = len(_format_turn({"q": "", "a": ""}))
+    space = room - fixed - 2 * len(CUT)
+    if space <= 0:
+        return ""
+    q_len = min(len(q), space // 3)
+    a_len = min(len(a), space - q_len)
+    q_cut = q[:q_len] + (CUT if q_len < len(q) else "")
+    a_cut = a[:a_len] + (CUT if a_len < len(a) else "")
+    return _format_turn({"q": q_cut, "a": a_cut})
+
+
+def build_recap(history: list[dict[str, str]], max_chars: int) -> str:
+    """Recap of a thread's earlier turns for a freshly re-forked session.
+
+    Keeps the newest turns that fit ``max_chars`` (header and footer
+    included); if even the newest turn is too long, its question and answer
+    are each cut so both survive.
+
+    Args:
+        history: Earlier turns, oldest first, as ``{"q": ..., "a": ...}``.
+        max_chars: Upper bound on the returned text's length.
+
+    Returns:
+        The recap text, or "" when there is no history or no room.
+    """
+    budget = max_chars - len(RECAP_HEADER) - len(RECAP_FOOTER)
+    if not history or budget <= 0:
+        return ""
+    kept: list[str] = []
+    used = 0
+    for turn in reversed(history):
+        text = _format_turn(turn)
+        if used + len(text) > budget:
+            if not kept:
+                fitted = _fit_turn(turn, budget)
+                if fitted:
+                    kept.append(fitted)
+            break
+        kept.append(text)
+        used += len(text)
+    if not kept:
+        return ""
+    return RECAP_HEADER + "".join(reversed(kept)) + RECAP_FOOTER
+
+
+def trim_history(
+    history: list[dict[str, str]], max_chars: int
+) -> list[dict[str, str]]:
+    """Bound a thread's stored history (it lives in the state file).
+
+    Each field is cut to ``max_chars`` and the oldest turns are dropped
+    while the total exceeds twice that, so the recap budget is always
+    covered without the state file growing without limit.
+    """
+    if max_chars <= 0:
+        return []  # no recap budget: keep nothing (else empty turns pile up)
+    turns = [
+        {"q": t.get("q", "")[:max_chars], "a": t.get("a", "")[:max_chars]}
+        for t in history
+    ]
+    while len(turns) > 1 and sum(
+        len(t["q"]) + len(t["a"]) for t in turns
+    ) > 2 * max_chars:
+        turns.pop(0)
+    return turns
 
 
 class Backend(Protocol):
@@ -100,6 +200,8 @@ def build_claude_flags(
     access: str = "read",
     add_dirs: tuple[str, ...] = (),
     extra_system: str = "",
+    platform: str = "",
+    force_read: bool = False,
 ) -> list[str]:
     """Common claude CLI flags for a fork invocation/launch.
 
@@ -109,10 +211,14 @@ def build_claude_flags(
             fork's own id).
         fork: Whether to create a new fork of `resume_id`.
         access: Per-handle access level ("read"/"write"/"bash") set via >share.
+        force_read: Use the read preset whatever ``access`` and the
+            operator's tool lists say (set for HTTP threads, which stay
+            read-only because their caller picks the handle).
         add_dirs: Extra directories the fork may access (``--add-dir``), e.g.
             the thread's inbound-attachment dir which lives outside the project.
         extra_system: Text appended to the persona system prompt (e.g. the
             per-thread outbox instruction for write/bash handles).
+        platform: Chat platform named in the persona; blank = the config's.
 
     Returns:
         Argument list (excluding the binary, -p, and the prompt).
@@ -121,7 +227,12 @@ def build_claude_flags(
     flags = ["--resume", resume_id]
     if fork:
         flags.append("--fork-session")
-    if access == "all" and claude.allow_skip_permissions:
+    if force_read:
+        # Only the MCP servers this invocation names, so a server configured
+        # in the project's or the user's settings cannot hand the fork a tool
+        # the read preset's deny list never names.
+        flags.append("--strict-mcp-config")
+    if access == "all" and claude.allow_skip_permissions and not force_read:
         # Full access: skip every permission prompt so the fork can use any
         # tool or MCP server the session has (web, browser, shell, edits). No
         # allow/deny lists — they would only restrict. The answer path refuses
@@ -130,20 +241,23 @@ def build_claude_flags(
         # would fall back to the restrictive read tools, never to "no limits".
         flags.append("--dangerously-skip-permissions")
     else:
-        allowed, disallowed = resolve_tools(claude, access)
+        allowed, disallowed = resolve_tools(claude, access, force_read)
         if allowed:
             flags += ["--allowedTools", ",".join(allowed)]
         if disallowed:
             flags += ["--disallowedTools", ",".join(disallowed)]
-        if claude.permission_mode:
-            flags += ["--permission-mode", claude.permission_mode]
+        mode = "dontAsk" if force_read else claude.permission_mode
+        if mode:
+            # A pinned fork never takes the configured mode, which could be
+            # bypassPermissions.
+            flags += ["--permission-mode", mode]
     if claude.model:
         flags += ["--model", claude.model]
     for directory in add_dirs:
         flags += ["--add-dir", directory]
     # Fill the persona's {platform} placeholder from config (a custom persona
     # without it is unaffected by str.replace).
-    system = claude.persona.replace("{platform}", cfg.platform)
+    system = claude.persona.replace("{platform}", platform or cfg.platform)
     if extra_system:
         system = f"{system}\n\n{extra_system}" if system else extra_system
     if system:
@@ -154,11 +268,15 @@ def build_claude_flags(
 def _window_name(handle: str, thread_key: str) -> str:
     """Readable, unique tmux window name: ``<handle>-<short>``.
 
-    The handle makes it recognizable when attached; the thread-key suffix
-    keeps it unique when the same handle opens more than one thread.
+    The handle makes it recognizable when attached; the suffix is a digest
+    of the whole thread key, so two threads of one handle never share a
+    window. Taking the key's last characters instead would collide, and
+    HTTP callers choose their own thread ids ("alice-1234", "bob-1234"),
+    which would put two conversations in one fork. The digest is wide
+    enough that a caller cannot search for a colliding id.
     """
     base = (re.sub(r"[^A-Za-z0-9-]", "", handle) or "s")[:24]
-    suffix = re.sub(r"[^A-Za-z0-9]", "", thread_key)[-4:] or "0"
+    suffix = hashlib.sha256(thread_key.encode("utf-8")).hexdigest()[:16]
     return f"{base}-{suffix}"
 
 
@@ -219,6 +337,8 @@ class _BaseBackend:
         # already-running thread (same fork, context kept). Persisting it means
         # the change fires `_on_access_changed` once, not on every later turn.
         cur = self._current_access(rec)
+        if is_http_thread(thread_key):
+            cur = "read"  # program callers never inherit write/bash/all
         if cur != rec.access:
             old = rec.access
             rec.access = cur
@@ -341,13 +461,43 @@ class HeadlessBackend(_BaseBackend):
 
     name = "headless"
 
+    def _expert_size(self, rec: ThreadRecord) -> int:
+        """Byte size of the expert's transcript, or -1 if it can't be read."""
+        path = (
+            transcript_dir(Path(rec.project_dir), self._home(rec))
+            / f"{rec.expert_session_id}.jsonl"
+        )
+        try:
+            return path.stat().st_size
+        except OSError:
+            return -1
+
     def ask(self, thread_key: str, question: str) -> Answer:
-        """Run one headless turn in the thread's fork (creating it on the
-        first turn) and return the result text."""
+        """Run one headless turn in the thread's fork and return the answer.
+
+        The first turn forks the expert. A follow-up resumes the thread's
+        fork, unless ``refresh_forks`` is on and the expert transcript has
+        grown since that fork was taken: then it forks the expert afresh and
+        prepends a recap of the thread's earlier Q&A.
+        """
         rec = self._require_binding(thread_key)
-        fork = not rec.fork_session_id
+        size = self._expert_size(rec)
+        refresh = bool(
+            rec.fork_session_id
+            and self.cfg.refresh_forks
+            and rec.fork_base_size > 0
+            and size > rec.fork_base_size
+        )
+        fork = not rec.fork_session_id or refresh
         resume_id = rec.expert_session_id if fork else rec.fork_session_id
+        prompt = question
+        if refresh:
+            prompt = (
+                build_recap(rec.history, self.cfg.limits.recap_max_chars)
+                + question
+            )
         add_dirs, extra_system, outbox, snapshot = self._begin_turn(rec)
+        pinned = is_http_thread(rec.thread_key)
 
         argv = [
             self.cfg.claude.binary,
@@ -355,14 +505,25 @@ class HeadlessBackend(_BaseBackend):
             "--output-format",
             "json",
             *build_claude_flags(
-                self.cfg, resume_id, fork, rec.access, add_dirs, extra_system
+                self.cfg,
+                resume_id,
+                fork,
+                rec.access,
+                add_dirs,
+                extra_system,
+                platform=rec.platform,
+                force_read=pinned,
+            ),
+            *(
+                strip_permission_args(self.cfg.claude.headless_extra_args)
+                if pinned
+                else self.cfg.claude.headless_extra_args
             ),
-            *self.cfg.claude.headless_extra_args,
         ]
         try:
             result = subprocess.run(
                 argv,
-                input=question,
+                input=prompt,
                 capture_output=True,
                 text=True,
                 cwd=rec.project_dir,
@@ -390,15 +551,26 @@ class HeadlessBackend(_BaseBackend):
 
         fork_id = data.get("session_id") or resume_id
         rec.fork_session_id = fork_id
-        self.store.upsert(rec)
+        # The size measured before this turn is the fork's base: the fork
+        # copied at least that much. A fork of an unknown base (a thread
+        # from before this was tracked) gets its baseline now.
+        if fork or rec.fork_base_size <= 0:
+            rec.fork_base_size = max(size, 0)
         text = str(data.get("result", "")).strip()
+        if text:
+            rec.history = trim_history(
+                [*rec.history, {"q": question, "a": text}],
+                self.cfg.limits.recap_max_chars,
+            )
+        self.store.upsert(rec)
         if not text:
             raise BackendError("Empty answer from claude")
         return Answer(
             text=text,
             fork_session_id=fork_id,
-            new_thread=fork,
+            new_thread=fork and not refresh,
             attachments=self._end_turn(outbox, snapshot),
+            refreshed=refresh,
         )
 
 
@@ -407,11 +579,58 @@ class TmuxBackend(_BaseBackend):
 
     name = "tmux"
 
+    # Windows this process launched under the HTTP read-only pin, shared by
+    # every instance because the relay builds a fresh backend for each turn.
+    # A warm window keeps the flags it launched with, and one left by an
+    # older build can hold wider tools while the thread's stored access
+    # already reads "read", so no access change fires to kill it. An HTTP
+    # window is reused only when it is in here.
+    _pinned_windows: set[str] = set()
+
     def __init__(self, cfg: TunnelConfig, store: TunnelStore) -> None:
         """Bind to the dedicated tmux session named in the config."""
         super().__init__(cfg, store)
         self.tmux = TmuxSession(cfg.tmux_session)
 
+    def _kill_stale_window(self, rec: ThreadRecord, window: str) -> bool:
+        """Kill a window this thread launched under an older naming scheme.
+
+        The turn overwrites ``rec.tmux_window``, so nothing would address
+        the old window afterwards and its fork would keep running.
+
+        Returns:
+            Whether a window was killed.
+        """
+        if not rec.tmux_window or rec.tmux_window == window:
+            return False
+        self.tmux.kill_window(rec.tmux_window)
+        return True
+
+    def _drop_unpinned_http_window(self, rec: ThreadRecord, window: str) -> bool:
+        """Kill a warm HTTP window this process did not launch read-only.
+
+        A warm window keeps the flags it launched with, and a window left by
+        an older build can hold wider tools while the thread's stored access
+        already reads ``read``, so no access change fires to kill it. Dropping
+        it sends the turn down the cold-relaunch path, which applies the pin.
+
+        Returns:
+            Whether a window was killed.
+
+        Raises:
+            BackendError: The window survived the kill, so reusing it would
+                answer with whatever tools it launched with.
+        """
+        if not is_http_thread(rec.thread_key) or window in self._pinned_windows:
+            return False
+        self.tmux.kill_window(window)
+        if self.tmux.window_alive(window):
+            raise BackendError(
+                f"Window {window} holds a fork this process did not launch "
+                "read-only, and it survived the kill. Close it by hand."
+            )
+        return True
+
     def _on_access_changed(self, rec: ThreadRecord, old: str, new: str) -> None:
         """Kill the warm window so the next turn cold-relaunches the fork.
 
@@ -421,7 +640,9 @@ class TmuxBackend(_BaseBackend):
         forces the next turn down the relaunch path, so the fork comes back
         with the new tools, same fork id, full context retained.
         """
-        self.tmux.kill_window(_window_name(rec.handle, rec.thread_key))
+        self.tmux.kill_window(
+            rec.tmux_window or _window_name(rec.handle, rec.thread_key)
+        )
 
     def _launch(
         self,
@@ -434,6 +655,8 @@ class TmuxBackend(_BaseBackend):
         initial_prompt: Optional[str] = None,
         add_dirs: tuple[str, ...] = (),
         extra_system: str = "",
+        platform: str = "",
+        force_read: bool = False,
     ) -> None:
         """Launch an interactive fork in `window`.
 
@@ -455,10 +678,25 @@ class TmuxBackend(_BaseBackend):
         argv = [
             self.cfg.claude.binary,
             *build_claude_flags(
-                self.cfg, resume_id, fork, access, add_dirs, extra_system
+                self.cfg,
+                resume_id,
+                fork,
+                access,
+                add_dirs,
+                extra_system,
+                platform=platform,
+                force_read=force_read,
+            ),
+            *(
+                strip_permission_args(self.cfg.claude.tmux_extra_args)
+                if force_read
+                else self.cfg.claude.tmux_extra_args
             ),
-            *self.cfg.claude.tmux_extra_args,
         ]
+        if force_read:
+            self._pinned_windows.add(window)
+        else:
+            self._pinned_windows.discard(window)
         if initial_prompt is not None:
             # `--` ends option parsing so a prompt beginning with "-" (e.g.
             # "- how are you?") is taken as the positional prompt, not a CLI
@@ -538,6 +776,7 @@ class TmuxBackend(_BaseBackend):
         """
         rec = self._require_binding(thread_key)
         window = _window_name(rec.handle, thread_key)
+        self._kill_stale_window(rec, window)
         # Resolve to the canonical path so the three things keyed on it agree
         # with the directory Claude actually runs in (its process.cwd() is
         # canonical): the launch cwd, the trust-config entry, and the
@@ -568,9 +807,11 @@ class TmuxBackend(_BaseBackend):
                 fork=True,
                 config_dir=rec.config_dir,
                 access=rec.access,
+                force_read=is_http_thread(rec.thread_key),
                 initial_prompt=prompt,
                 add_dirs=add_dirs,
                 extra_system=extra_system,
+                platform=rec.platform,
             )
             fork_file = wait_for_new_session_file(
                 project_dir,
@@ -589,6 +830,7 @@ class TmuxBackend(_BaseBackend):
                 raise BackendError(
                     f"Fork transcript {rec.fork_session_id} not found"
                 )
+            self._drop_unpinned_http_window(rec, window)
             if self.tmux.window_alive(window) and not self.tmux.pane_dead(
                 window
             ):
@@ -607,9 +849,11 @@ class TmuxBackend(_BaseBackend):
                     fork=False,
                     config_dir=rec.config_dir,
                     access=rec.access,
+                    force_read=is_http_thread(rec.thread_key),
                     initial_prompt=prompt,
                     add_dirs=add_dirs,
                     extra_system=extra_system,
+                    platform=rec.platform,
                 )
 
         deadline = time.time() + self.cfg.limits.answer_timeout_s

{claude_code_tools-1.27.1 → claude_code_tools-1.28.0}/claude_code_tools/agent_tunnel/cli.py

@@ -82,7 +82,7 @@ def serve(
     channels: tuple[int, ...],
     token_env: Optional[str],
 ) -> None:
-    """Run the Discord daemon (blocking).
+    """Run the chat daemon: Discord and/or Mattermost (blocking).
 
     Two server modes, set with --backend or [tunnel] backend (default
     headless):
@@ -102,17 +102,23 @@ def serve(
     store = TunnelStore(cfg.state_path)
     registry = Registry(cfg.registry_path)
     try:
-        from .discord_bot import run_bot
+        from .serve import plan_frontends, run_serve
     except ImportError as exc:
         raise click.ClickException(
             f"discord.py is required for serve: {exc}"
         ) from exc
+    try:
+        frontends = plan_frontends(cfg)
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
     click.echo(
         f"agent-tunnel: backend={cfg.backend} "
-        f"registry={cfg.registry_path} channels={cfg.discord.channel_ids}"
+        f"registry={cfg.registry_path} frontends={','.join(frontends)} "
+        f"discord_channels={cfg.discord.channel_ids} "
+        f"mattermost_channels={cfg.mattermost.channel_ids}"
     )
     try:
-        run_bot(cfg, store, registry)
+        run_serve(cfg, store, registry)
     except RuntimeError as exc:
         raise click.ClickException(str(exc)) from exc
 
@@ -192,11 +198,11 @@ def ask(
     except BackendError as exc:
         raise click.ClickException(str(exc)) from exc
     click.echo(answer.text)
-    click.echo(
-        f"\n[fork={answer.fork_session_id} "
-        f"{'new' if answer.new_thread else 'follow-up'}]",
-        err=True,
-    )
+    if answer.refreshed:
+        kind = "follow-up, re-forked from latest session"
+    else:
+        kind = "new" if answer.new_thread else "follow-up"
+    click.echo(f"\n[fork={answer.fork_session_id} {kind}]", err=True)
 
 
 def _resolve_target(
@@ -647,23 +653,65 @@ def doctor(config: Optional[str]) -> None:
     import shutil
 
     from .convert import detect_converter
-    from .discord_bot import resolve_token
+    from .discord_bot import discord_ready, resolve_token
+    from .mattermost_bot import mattermost_ready, resolve_mm_token
 
     cfg = _build(config)
-    checks: list[tuple[bool, str]] = [
-        (
-            bool(resolve_token(cfg)),
-            f"Discord token ({cfg.discord.token_env} or token_file)",
-        ),
-        (
-            bool(cfg.discord.channel_ids),
-            f"Watched channel(s): {cfg.discord.channel_ids or 'none set'}",
-        ),
+    checks: list[tuple[bool, str]] = []
+    # Checks shown but not failing: an incomplete Mattermost while Discord
+    # runs (serve skips it with a warning; doctor mirrors that).
+    warn_only: list[tuple[bool, str]] = []
+    from .http_frontend import http_ready
+
+    discord_token = bool(resolve_token(cfg))
+    mm = cfg.mattermost
+    http_runnable = bool(cfg.http.port) and http_ready(cfg) is None
+    # Discord is optional once another front-end is configured: check it only
+    # when serve would run it, or when it is the only front-end.
+    if discord_ready(cfg) is None or not (mm.url or cfg.http.port):
+        checks += [
+            (
+                discord_token,
+                f"Discord token ({cfg.discord.token_env} or token_file)",
+            ),
+            (
+                bool(cfg.discord.channel_ids or cfg.discord.respond_to_dms),
+                f"Watched channel(s): {cfg.discord.channel_ids or 'none set'}"
+                + (" (+ DMs)" if cfg.discord.respond_to_dms else ""),
+            ),
+        ]
+    if mm.url:
+        mm_warn_only = mattermost_ready(cfg) is not None and (
+            discord_ready(cfg) is None or http_runnable
+        )
+        (warn_only if mm_warn_only else checks).extend([
+            (
+                bool(resolve_mm_token(cfg)),
+                f"Mattermost token ({mm.token_env} or token_file)",
+            ),
+            (
+                bool(mm.channel_ids),
+                "Mattermost channel(s): "
+                f"{mm.channel_ids or 'none set'} @ {mm.url}",
+            ),
+        ])
+    if cfg.http.port:
+        other_runs = discord_ready(cfg) is None or (
+            bool(mm.url) and mattermost_ready(cfg) is None
+        )
+        (warn_only if not http_runnable and other_runs else checks).append(
+            (
+                http_runnable,
+                f"HTTP front-end: {cfg.http.bind}:{cfg.http.port}, token in "
+                f"{cfg.http.token_file or 'unset'}",
+            )
+        )
+    checks.append(
         (
             shutil.which(cfg.claude.binary) is not None,
             f"claude binary on PATH ({cfg.claude.binary})",
-        ),
-    ]
+        )
+    )
     if cfg.backend == "tmux":
         checks.append(
             (shutil.which("tmux") is not None, "tmux on PATH (tmux backend)")
@@ -672,6 +720,9 @@ def doctor(config: Optional[str]) -> None:
     for ok, label in checks:
         click.echo(f"  {'✓' if ok else '✗'} {label}")
         ok_all = ok_all and ok
+    for ok, label in warn_only:
+        suffix = "" if ok else "  (serve skips this front-end until fixed)"
+        click.echo(f"  {'✓' if ok else '!'} {label}{suffix}")
     n = len(Registry(cfg.registry_path).active())
     click.echo(f"  • {n} published session(s) live")
     if cfg.attachments.convert == "off":