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

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

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

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

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

{claude_code_tools-1.28.0 → claude_code_tools-1.29.1}/claude_code_tools/agent_tunnel/config.py

@@ -176,6 +176,10 @@ class HttpConfig:
     token_file: str = ""
     # Name used in the fork's persona for questions arriving this way.
     platform: str = "the web"
+    # Append-only JSON-lines log of answered turns, readable at GET /turns.
+    # Empty = off. Relative paths sit beside the state file. The sender is
+    # never written to it.
+    turn_log: str = ""
 
 
 @dataclass
@@ -423,6 +427,7 @@ unset_api_key = true
 # port = 8766
 # token_file = "~/.config/agent-tunnel/http-token"
 # platform = "the web"
+# turn_log = "http-turns.jsonl"   # answered turns, no sender; GET /turns reads it
 
 [limits]
 max_concurrent = 2

{claude_code_tools-1.28.0 → claude_code_tools-1.29.1}/claude_code_tools/agent_tunnel/http_frontend.py

@@ -9,7 +9,9 @@ refresh and logging are shared with Discord and Mattermost.
 Routes (``[http]`` in the config; off unless ``port`` is set):
 
     GET  /health
-    POST /ask   {"handle": ..., "question": ..., "thread": ..., "sender": ...}
+    POST /ask   {"handle": ..., "question": ..., "thread": ..., "sender": ...,
+                 "metadata": {...}}
+    GET  /turns ?handle=...&limit=...&meta.<key>=<value>
 
 Every route requires ``X-Ask-Token: <contents of http.token_file>``.
 ``thread`` is any caller-chosen id; questions with the same handle and
@@ -20,6 +22,11 @@ whatever access the handle was shared with, because the caller picks the
 handle. The response says whether a turn ran (``ran``) separately from what
 it produced, and a failed turn is an HTTP 502 carrying the relay's own
 error text, never an empty answer.
+
+With ``[http] turn_log`` set, each answered turn is appended to that file
+with the caller's flat ``metadata`` (a docs site sends page and heading) and
+without the sender, and ``GET /turns`` returns the matching turns newest
+first. See :mod:`.turn_log`.
 """
 
 from __future__ import annotations
@@ -37,6 +44,7 @@ from aiohttp import web
 from .readonly import HTTP_THREAD_PREFIX
 from .config import TunnelConfig
 from .relay import QUEUE_NOTICE, Relay
+from .turn_log import MAX_LIMIT, TurnLog, resolve_log_path, validate_metadata
 
 logger = logging.getLogger("agent_tunnel.http")
 
@@ -148,6 +156,8 @@ async def _turn(
     thread: str,
     question: str,
     sender: str,
+    metadata: dict[str, str],
+    turn_log: Optional[TurnLog],
 ) -> web.Response:
     """Bind if new, run one relay turn, and shape the JSON reply.
 
@@ -166,6 +176,16 @@ async def _turn(
         error = problem or "the turn produced no answer"
         return _json(502, {"ran": False, "error": error, "thread": thread})
     record = relay.store.get(thread_key)
+    logged = False
+    if turn_log is not None:
+        try:
+            await turn_log.append(handle, thread, question, dest.text, metadata)
+            logged = True
+        except (OSError, ValueError):
+            # The reader still gets the answer; the response says it was not
+            # logged, and the daemon log says why.
+            logger.exception("Could not append to turn log %s", turn_log.path)
+            dest.notices.append("this turn could not be written to the turn log")
     return _json(
         200,
         {
@@ -176,6 +196,7 @@ async def _turn(
             "fork_session_id": record.fork_session_id if record else "",
             "files": [p.name for p in dest.files],
             "notices": dest.notices,
+            "logged": logged,
         },
     )
 
@@ -183,6 +204,8 @@ async def _turn(
 def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
     """The aiohttp application; separated from serving so tests can drive it."""
     token = resolve_http_token(cfg).encode("utf-8")
+    log_path = resolve_log_path(cfg.http.turn_log, cfg.state_path)
+    turn_log = TurnLog(log_path) if log_path else None
 
     @web.middleware
     async def require_token(request: web.Request, handler: Any) -> web.Response:
@@ -225,6 +248,10 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
             return _json(
                 400, {"ran": False, "error": "thread must match [A-Za-z0-9_.:-]{1,80}"}
             )
+        metadata, err = validate_metadata(body.get("metadata"))
+        if err:
+            status = 413 if "longer" in err else 400
+            return _json(status, {"ran": False, "error": err})
         # The same per-user cooldown the chat front-ends apply, keyed by the
         # sender the caller vouches for, else by the caller's address.
         caller = sender or (request.remote or "unknown")
@@ -236,7 +263,17 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
             )
         thread_key = f"{HTTP_THREAD_PREFIX}{handle}:{thread}"
         try:
-            return await _turn(cfg, relay, thread_key, handle, thread, question, sender)
+            return await _turn(
+                cfg,
+                relay,
+                thread_key,
+                handle,
+                thread,
+                question,
+                sender,
+                metadata,
+                turn_log,
+            )
         except Exception:  # noqa: BLE001 - keep the JSON contract on any failure
             logger.exception("HTTP turn failed [%s]", thread_key)
             return _json(
@@ -248,9 +285,39 @@ def make_app(cfg: TunnelConfig, relay: Relay) -> web.Application:
                 },
             )
 
+    async def turns(request: web.Request) -> web.Response:
+        if turn_log is None:
+            return _json(404, {"ran": False, "error": "no [http] turn_log configured"})
+        query = request.query
+        handle = query.get("handle", "").strip().lower()
+        if not handle:
+            return _json(400, {"ran": False, "error": "handle is required"})
+        try:
+            limit = int(query.get("limit", "50"))
+        except ValueError:
+            return _json(400, {"ran": False, "error": "limit must be an integer"})
+        if not 1 <= limit <= MAX_LIMIT:
+            return _json(
+                400, {"ran": False, "error": f"limit must be 1 to {MAX_LIMIT}"}
+            )
+        filters = {
+            key[len("meta.") :]: value
+            for key, value in query.items()
+            if key.startswith("meta.")
+        }
+        try:
+            found, skipped = await asyncio.to_thread(
+                turn_log.read, handle, filters, limit
+            )
+        except OSError:
+            logger.exception("Could not read turn log %s", turn_log.path)
+            return _json(502, {"ran": False, "error": "could not read the turn log"})
+        return _json(200, {"ran": True, "turns": found, "skipped": skipped})
+
     app = web.Application(client_max_size=256 * 1024, middlewares=[require_token])
     app.router.add_get("/health", health)
     app.router.add_post("/ask", ask)
+    app.router.add_get("/turns", turns)
     return app
 
 

claude_code_tools-1.29.1/claude_code_tools/agent_tunnel/turn_log.py

@@ -0,0 +1,164 @@
+"""An append-only log of HTTP turns, and the reader behind ``GET /turns``.
+
+The daemon's thread store keeps only a trimmed recap of each conversation,
+so it cannot answer "what was asked about this page last month". When
+``[http] turn_log`` names a file, every answered HTTP turn is appended to it
+as one JSON line: when, which handle and thread, the question, the answer,
+and whatever flat ``metadata`` the caller attached (a docs site sends the
+page and heading). The sender is never written. The fork is still told who
+is asking and may repeat it in its answer, so a caller that shows the log to
+other people sends a pseudonym as the sender rather than a name or email.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+logger = logging.getLogger("agent_tunnel.turn_log")
+
+META_KEY_RE = re.compile(r"^[A-Za-z0-9_.-]{1,40}$")
+MAX_META_KEYS = 20
+MAX_META_VALUE = 4000
+MAX_LIMIT = 500
+
+
+def validate_metadata(value: Any) -> tuple[dict[str, str], str]:
+    """A caller's ``metadata`` as a flat string map, or why it is not one.
+
+    Args:
+        value: The request's ``metadata`` field; absent or null is empty.
+
+    Returns:
+        ``(metadata, "")`` on success, else ``({}, error)``. An error that
+        mentions "longer" is an over-limit value (the caller answers 413).
+    """
+    if value is None:
+        return {}, ""
+    if not isinstance(value, dict):
+        return {}, "metadata must be a JSON object"
+    if len(value) > MAX_META_KEYS:
+        return {}, f"metadata has more than {MAX_META_KEYS} keys"
+    meta: dict[str, str] = {}
+    for key, item in value.items():
+        if not META_KEY_RE.match(key):
+            return {}, "metadata keys must match [A-Za-z0-9_.-]{1,40}"
+        if not isinstance(item, str):
+            return {}, f"metadata.{key} must be a string"
+        if len(item) > MAX_META_VALUE:
+            return {}, f"metadata.{key} is longer than {MAX_META_VALUE} characters"
+        meta[key] = item
+    return meta, ""
+
+
+def resolve_log_path(configured: str, state_path: Path) -> Optional[Path]:
+    """The turn log's path, or None when logging is off.
+
+    A relative path sits beside the daemon's state file, like its other
+    runtime files.
+    """
+    if not configured:
+        return None
+    path = Path(configured).expanduser()
+    return path if path.is_absolute() else state_path.parent / path
+
+
+@dataclass
+class TurnLog:
+    """Append answered turns to a JSON-lines file and read them back."""
+
+    path: Path
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+    async def append(
+        self,
+        handle: str,
+        thread: str,
+        question: str,
+        answer: str,
+        metadata: Mapping[str, str],
+    ) -> None:
+        """Write one turn durably; raises OSError if it could not be written."""
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "handle": handle,
+            "thread": thread,
+            "question": question,
+            "answer": answer,
+            "metadata": dict(metadata),
+        }
+        # ASCII escapes: a lone surrogate from JSON input is a valid str but
+        # cannot be encoded as UTF-8, and must not cost the reader an answer.
+        line = json.dumps(record) + "\n"
+        async with self._lock:
+            await asyncio.to_thread(self._write, line)
+
+    def _write(self, line: str) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # Owner-only, like the thread store: the log holds every question
+        # and answer.
+        fd = os.open(self.path, os.O_RDWR | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a+b") as fh:
+            if hasattr(os, "fchmod"):  # POSIX only; also narrows an older file
+                os.fchmod(fh.fileno(), 0o600)
+            # A failed earlier write can leave a record without its newline;
+            # end it first so this record stays on a line of its own.
+            end = fh.seek(0, os.SEEK_END)
+            if end:
+                fh.seek(end - 1)
+                if fh.read(1) != b"\n":
+                    fh.write(b"\n")
+            fh.write(line.encode("utf-8"))
+            fh.flush()
+            os.fsync(fh.fileno())
+
+    def read(
+        self, handle: str, meta_filters: Mapping[str, str], limit: int
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Matching turns, newest first, and how many lines were unreadable.
+
+        Args:
+            handle: Only turns of this handle.
+            meta_filters: Each key must be present in a turn's metadata with
+                exactly this value.
+            limit: At most this many turns, the most recent ones.
+
+        Returns:
+            ``(turns, skipped)``; a missing file is no turns, not an error.
+        """
+        if not self.path.exists():
+            return [], 0
+        # Only the latest `limit` matches are kept while scanning, so memory
+        # stays bounded however long the log grows.
+        matches: deque[dict[str, Any]] = deque(maxlen=limit)
+        skipped = 0
+        # Bytes, decoded line by line, so one damaged line is skipped and
+        # counted rather than hiding every record after it.
+        with self.path.open("rb") as fh:
+            for raw in fh:
+                if not raw.strip():
+                    continue
+                try:
+                    turn = json.loads(raw.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    skipped += 1
+                    continue
+                meta = turn.get("metadata", {}) if isinstance(turn, dict) else None
+                if not isinstance(meta, dict):
+                    skipped += 1  # valid JSON, but not a turn record
+                    continue
+                if turn.get("handle") != handle:
+                    continue
+                if all(meta.get(k) == v for k, v in meta_filters.items()):
+                    matches.append(turn)
+        if skipped:
+            logger.warning("Turn log %s: %d unreadable line(s)", self.path, skipped)
+        return list(reversed(matches)), skipped

{claude_code_tools-1.28.0 → claude_code_tools-1.29.1}/claude_code_tools/tmux_cli_controller.py

@@ -914,11 +914,8 @@ class CLI:
                 print(str(e))
         else:
             # Remote mode - kill window
-            try:
-                self.controller.kill_window(window_id=pane)
-                print("Window killed")
-            except ValueError as e:
-                print(str(e))
+            self.controller.kill_window(window_id=pane)
+            print("Window killed")
     
     def wait_idle(self, pane: Optional[str] = None, idle_time: float = 2.0, 
                   timeout: Optional[int] = None):

{claude_code_tools-1.28.0 → claude_code_tools-1.29.1}/claude_code_tools/tmux_remote_controller.py

@@ -3,7 +3,7 @@
 Remote Tmux Controller
 
 Enables tmux-cli to work when run outside of tmux by:
-- Auto-creating a detached tmux session on first use
+- Creating a detached tmux session when launching a managed window
 - Managing commands in separate tmux windows (not panes)
 - Providing an API compatible with the local (pane) controller
 """
@@ -16,65 +16,141 @@ from typing import Optional, List, Dict, Tuple, Union, Any
 
 class RemoteTmuxController:
     """Remote controller that manages a dedicated tmux session and windows."""
+
+    _ready_option = '@tmux_cli_ready'
     
     def __init__(self, session_name: str = "remote-cli-session"):
-        """Initialize with session name and ensure the session exists."""
+        """Initialize with a managed session name without creating it."""
         self.session_name = session_name
-        self.target_window: Optional[str] = None  # e.g., "session:0" (active pane in that window)
+        self.target_window: Optional[str] = None  # Stable window ID, e.g., "@1"
         print(f"Note: tmux-cli is running outside tmux. Managing windows in session '{session_name}'.")
         print("For better integration, consider running from inside a tmux session.")
         print("Use 'tmux-cli attach' to view the remote session.")
-        self._ensure_session()
     
     # ----------------------------
     # Internal utilities
     # ----------------------------
-    def _run_tmux(self, args: List[str]) -> Tuple[str, int]:
-        result = subprocess.run(
-            ['tmux'] + args,
-            capture_output=True,
-            text=True
+    def _run_tmux(self, args: List[str], include_stderr: bool = False) -> Tuple[str, int]:
+        try:
+            result = subprocess.run(
+                ['tmux'] + args,
+                capture_output=True,
+                text=True
+            )
+        except OSError as exc:
+            raise RuntimeError(f"Could not run tmux {args[0]}: {exc}") from exc
+        output = result.stdout.strip()
+        if include_stderr and result.returncode != 0:
+            output = "\n".join(part for part in (output, result.stderr.strip()) if part)
+        return output, result.returncode
+
+    @staticmethod
+    def _session_is_missing(error: str) -> bool:
+        """Recognize tmux's absent-session and absent-server diagnostics only."""
+        return (
+            "can't find session:" in error
+            or error.startswith("no server running on ")
+            or (error.startswith("error connecting to ") and "(No such file or directory)" in error)
         )
-        return result.stdout.strip(), result.returncode
+
+    @staticmethod
+    def _tmux_failure(action: str, output: str, code: int) -> RuntimeError:
+        detail = f": {output}" if output else ""
+        return RuntimeError(f"tmux {action} failed (exit {code}){detail}")
+
+    @staticmethod
+    def _window_is_missing(error: str, window_id: str) -> bool:
+        """Only classify a diagnostic for this exact stable ID as a vanished window."""
+        return error.strip() in (
+            f"no such window: {window_id}",
+            f"can't find window: {window_id}",
+        )
+
+    def _managed_session_exists(self) -> bool:
+        output, code = self._run_tmux(['has-session', '-t', f'={self.session_name}'], include_stderr=True)
+        if code == 0:
+            return True
+        if self._session_is_missing(output):
+            return False
+        raise self._tmux_failure('has-session', output, code)
     
     def _ensure_session(self) -> None:
-        """Create the session if it doesn't exist (detached)."""
-        _, code = self._run_tmux(['has-session', '-t', self.session_name])
-        if code != 0:
+        """Create the managed session if needed for a new window."""
+        if not self._managed_session_exists():
             # Create a detached session using user's default shell
             # Return the session name just to force creation
-            self._run_tmux([
+            output, code = self._run_tmux([
                 'new-session', '-d', '-s', self.session_name, '-P', '-F', '#{session_name}'
-            ])
-            # Remember first window as default target
-            self.target_window = f"{self.session_name}:0"
-        else:
-            # If already exists and we don't have a target, set to active window
-            if not self.target_window:
-                win, code2 = self._run_tmux(['display-message', '-p', '-t', self.session_name, '#{session_name}:#{window_index}'])
-                if code2 == 0 and win:
-                    self.target_window = win
+            ], include_stderr=True)
+            if code != 0:
+                # Another launcher may have won the check/create race.
+                if output != f'duplicate session: {self.session_name}' or not self._managed_session_exists():
+                    raise self._tmux_failure('new-session', output, code)
+            elif not output:
+                raise self._tmux_failure('new-session', output, code)
     
     def _window_target(self, pane: Optional[str]) -> str:
         """Resolve user-provided pane/window hint to a tmux target.
         Accepts:
-        - None -> use last target window if set else active window in session
+        - None -> use last target window if set else a ready active window in session
         - digits (e.g., "1") -> session:index
         - full tmux target (e.g., "name:1" or "name:1.0" or "%12") -> pass-through
         """
-        self._ensure_session()
         if pane is None:
             if self.target_window:
-                return self.target_window
-            # Fallback to active window in session
-            win, code = self._run_tmux(['display-message', '-p', '-t', self.session_name, '#{session_name}:#{window_index}'])
-            if code == 0 and win:
-                self.target_window = win
-                return win
-            # Final fallback: session:0
-            return f"{self.session_name}:0"
+                # Window IDs can be reused after a server restart. Check both
+                # membership and readiness before trusting a cached default.
+                windows, code = self._run_tmux(
+                    ['list-windows', '-t', f'={self.session_name}',
+                     '-F', '#{window_id}|#{@tmux_cli_ready}'],
+                    include_stderr=True,
+                )
+                if code != 0 and not self._session_is_missing(windows):
+                    raise self._tmux_failure('list-windows', windows, code)
+                expected = f'{self.target_window}|{self.target_window}'
+                if code == 0 and expected in windows.splitlines():
+                    return self.target_window
+                self.target_window = None
+                if code != 0:
+                    raise ValueError(
+                        "No target pane/window specified; managed session "
+                        f"'{self.session_name}' does not exist. "
+                        "Launch a window or pass --pane."
+                    )
+            # An existing managed session may have been created by an earlier CLI call.
+            win, code = self._run_tmux(
+                ['display-message', '-p', '-t', f'={self.session_name}:',
+                 '#{window_id}|#{@tmux_cli_ready}'],
+                include_stderr=True,
+            )
+            if code == 0:
+                if not win:
+                    raise self._tmux_failure('display-message', win, code)
+                window_id, separator, ready = win.partition('|')
+                if not separator or not window_id.startswith('@'):
+                    raise self._tmux_failure('display-message', win, code)
+                if ready == window_id:
+                    self.target_window = window_id
+                    return window_id
+                raise ValueError(
+                    f"No target pane/window specified; managed session '{self.session_name}' "
+                    "has no successfully launched active window. Launch a window or pass --pane."
+                )
+            if code != 0 and not (self._session_is_missing(win) or "can't find window:" in win):
+                raise self._tmux_failure('display-message', win, code)
+            raise ValueError(
+                f"No target pane/window specified; managed session '{self.session_name}' "
+                "does not exist or has no active window. Launch a window or pass --pane."
+            )
         # If user supplied a simple index
-        if isinstance(pane, str) and pane.isdigit():
+        if isinstance(pane, bool):
+            raise ValueError("Boolean --pane is not a window index")
+        if type(pane) is int or (isinstance(pane, str) and pane.isdigit()):
+            if not self._managed_session_exists():
+                raise ValueError(
+                    f"Managed session '{self.session_name}' does not exist; "
+                    "launch a window or pass a full --pane target."
+                )
             return f"{self.session_name}:{pane}"
         # Otherwise assume user provided a pane/window target or pane id
         return pane
@@ -92,7 +168,6 @@ class RemoteTmuxController:
         Returns a list shaped similarly to local list_panes, with keys:
         id (window target), index, title (window name), active (bool), size (N/A)
         """
-        self._ensure_session()
         out, code = self._run_tmux([
             'list-windows', '-t', self.session_name,
             '-F', '#{window_index}|#{window_name}|#{window_active}|#{window_width}x#{window_height}'
@@ -117,17 +192,49 @@ class RemoteTmuxController:
         """Launch a command in a new window within the managed session.
         Returns the window target (e.g., "session:1").
         """
-        self._ensure_session()
-        args = ['new-window', '-t', self.session_name, '-P', '-F', '#{session_name}:#{window_index}']
-        if name:
-            args.extend(['-n', name])
-        if command:
-            args.append(command)
-        out, code = self._run_tmux(args)
-        if code == 0 and out:
-            self.target_window = out
-            return out
-        return None
+        previous_target = self.target_window
+        try:
+            self._ensure_session()
+            args = ['new-window', '-t', f'={self.session_name}:', '-P', '-F',
+                    '#{session_name}:#{window_index}|#{window_id}']
+            if name:
+                args.extend(['-n', name])
+            if command:
+                args.append(command)
+            out, code = self._run_tmux(args, include_stderr=True)
+            if code != 0 or not out:
+                raise self._tmux_failure('new-window', out, code)
+            target, separator, window_id = out.partition('|')
+            if not separator or not target or not window_id.startswith('@'):
+                raise self._tmux_failure('new-window', out, code)
+            try:
+                marked, mark_code = self._run_tmux(
+                    ['set-option', '-w', '-t', window_id, self._ready_option, window_id],
+                    include_stderr=True,
+                )
+            except RuntimeError as exc:
+                raise RuntimeError(
+                    f"Ready mark for created window {window_id} could not be set; "
+                    f"command may have started. {exc}"
+                ) from exc
+            if mark_code != 0:
+                if self._window_is_missing(marked, window_id):
+                    raise RuntimeError(
+                        f"Command was launched in window {window_id}, but that window "
+                        f"disappeared before its ready mark; no live target is available "
+                        f"(tmux set-option exit {mark_code}: {marked}). "
+                        "The command may have run; do not retry automatically."
+                    )
+                raise RuntimeError(
+                    f"{self._tmux_failure('set-option', marked, mark_code)}; "
+                    f"created window {window_id}; command may have started. "
+                    "Inspect the window before retrying."
+                )
+            self.target_window = window_id
+            return target
+        except Exception:
+            self.target_window = previous_target
+            raise
     
     def send_keys(self, text: str, pane_id: Optional[str] = None, enter: bool = True,
                   delay_enter: Union[bool, float] = True, verify_enter: bool = True,
@@ -272,14 +379,25 @@ class RemoteTmuxController:
 
     def kill_window(self, window_id: Optional[str] = None):
         target = self._window_target(window_id)
+        cached_target = target
+        if self.target_window and target != self.target_window:
+            resolved, code = self._run_tmux(
+                ['display-message', '-p', '-t', target, '#{window_id}']
+            )
+            if code == 0 and resolved:
+                cached_target = resolved
         # Ensure the target refers to a window (not a %pane id)
         # If user passed a pane id like %12, tmux can still resolve to its window
         self._run_tmux(['kill-window', '-t', target])
-        if self.target_window == target:
+        if self.target_window == cached_target:
             self.target_window = None
     
     def attach_session(self):
-        self._ensure_session()
+        if not self._managed_session_exists():
+            raise ValueError(
+                f"Managed session '{self.session_name}' does not exist; "
+                "launch a window before attaching."
+            )
         # Attach will replace the current terminal view until the user detaches
         subprocess.run(['tmux', 'attach-session', '-t', self.session_name])
     
@@ -289,7 +407,6 @@ class RemoteTmuxController:
     
     def list_windows(self) -> List[Dict[str, str]]:
         """List all windows in the managed session with basic info."""
-        self._ensure_session()
         out, code = self._run_tmux(['list-windows', '-t', self.session_name, '-F', '#{window_index}|#{window_name}|#{window_active}'])
         if code != 0 or not out:
             return []

{claude_code_tools-1.28.0 → claude_code_tools-1.29.1}/docs/agent-tunnel-spec.md

@@ -58,7 +58,9 @@ safe.
   forks are read-only whatever the handle's access, the configured tool
   lists, the backends' extra args, the configured permission mode, the
   settings' MCP servers, or `allow_skip_permissions`, since the caller picks
-  the handle.
+  the handle. With `[http] turn_log` set, each answered turn is appended to
+  a JSON-lines log with the caller's flat `metadata` and never the sender;
+  `GET /turns` reads it back newest first, filtered by `meta.<key>=<value>`.
   Fields must be strings within their limits (over-limit is a 413); the
   per-user cooldown applies per `sender` (a 429 inside it). The
   response separates whether a turn ran from what it produced: a failed