claude-code-tools 1.11.2__tar.gz → 1.12.0__tar.gz

{claude_code_tools-1.11.2 → claude_code_tools-1.12.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: claude-code-tools
-Version: 1.11.2
+Version: 1.12.0
 Summary: Collection of tools for working with Claude Code
 License-File: LICENSE
 Requires-Python: >=3.11
 Requires-Dist: claude-agent-sdk>=0.1.6
 Requires-Dist: click>=8.0.0
 Requires-Dist: commitizen>=4.8.3
+Requires-Dist: discord-py>=2.4.0
 Requires-Dist: fire>=0.5.0
 Requires-Dist: mcp>=1.13.0
 Requires-Dist: pytest>=9.0.1
@@ -25,14 +26,14 @@ Description-Content-Type: text/markdown
 <div align="center">
 
 <a href="https://pchalasani.github.io/claude-code-tools/">
-<img src="assets/logo-nyc-subway.png" alt="CLAUDE CODE TOOLS"
+<img src="assets/title-blade-runner-theme.png" alt="CLAUDE CODE TOOLS"
      width="500"/>
 </a>
 
 CLI tools, skills, agents, hooks, and plugins for enhancing productivity with Claude Code and other coding agents.
 
 [![Documentation](https://img.shields.io/badge/%F0%9F%93%96-documentation-blue)](https://pchalasani.github.io/claude-code-tools/)
-[![aichat-search](https://img.shields.io/github/v/release/pchalasani/claude-code-tools?filter=rust-v*&label=aichat-search&color=orange)](https://github.com/pchalasani/claude-code-tools/releases?q=rust)
+[![aichat-search](https://img.shields.io/crates/v/aichat-search?label=aichat-search&color=orange)](https://crates.io/crates/aichat-search)
 [![Mentioned in Awesome Codex CLI](https://awesome.re/mentioned-badge.svg)](https://github.com/RoggeOhta/awesome-codex-cli)
 
 </div>
@@ -105,13 +106,18 @@ Click a card to jump to that feature, or
 </a>
 </td>
 <td align="center">
-<a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
-<img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
+<a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
+<img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
 </a>
 </td>
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
+<img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/vault/">
 <img src="assets/card-vault.svg" alt="vault" width="200"/>
 </a>
@@ -121,13 +127,13 @@ Click a card to jump to that feature, or
 <img src="assets/card-env-safe.svg" alt="env-safe" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/safety-hooks/">
 <img src="assets/card-safety.svg" alt="safety" width="200"/>
 </a>
 </td>
-</tr>
-<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/statusline/">
 <img src="assets/card-statusline.svg" alt="statusline" width="200"/>
@@ -138,13 +144,13 @@ Click a card to jump to that feature, or
 <img src="assets/card-gdocs.svg" alt="gdocs" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-sheets/">
 <img src="assets/card-gsheets.svg" alt="gsheets" width="200"/>
 </a>
 </td>
-</tr>
-<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/integrations/alt-llm-providers/">
 <img src="assets/card-alt.svg" alt="alt" width="200"/>
@@ -155,6 +161,8 @@ Click a card to jump to that feature, or
 <img src="assets/card-voice.svg" alt="voice" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/fix-session/">
 <img src="assets/card-session-repair.svg" alt="session repair" width="200"/>

{claude_code_tools-1.11.2 → claude_code_tools-1.12.0}/README.md

@@ -1,14 +1,14 @@
 <div align="center">
 
 <a href="https://pchalasani.github.io/claude-code-tools/">
-<img src="assets/logo-nyc-subway.png" alt="CLAUDE CODE TOOLS"
+<img src="assets/title-blade-runner-theme.png" alt="CLAUDE CODE TOOLS"
      width="500"/>
 </a>
 
 CLI tools, skills, agents, hooks, and plugins for enhancing productivity with Claude Code and other coding agents.
 
 [![Documentation](https://img.shields.io/badge/%F0%9F%93%96-documentation-blue)](https://pchalasani.github.io/claude-code-tools/)
-[![aichat-search](https://img.shields.io/github/v/release/pchalasani/claude-code-tools?filter=rust-v*&label=aichat-search&color=orange)](https://github.com/pchalasani/claude-code-tools/releases?q=rust)
+[![aichat-search](https://img.shields.io/crates/v/aichat-search?label=aichat-search&color=orange)](https://crates.io/crates/aichat-search)
 [![Mentioned in Awesome Codex CLI](https://awesome.re/mentioned-badge.svg)](https://github.com/RoggeOhta/awesome-codex-cli)
 
 </div>
@@ -81,13 +81,18 @@ Click a card to jump to that feature, or
 </a>
 </td>
 <td align="center">
-<a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
-<img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
+<a href="https://pchalasani.github.io/claude-code-tools/tools/agent-tunnel/">
+<img src="assets/card-agent-tunnel.svg" alt="agent-tunnel" width="200"/>
 </a>
 </td>
 </tr>
 <tr>
 <td align="center">
+<a href="https://pchalasani.github.io/claude-code-tools/tools/lmsh/">
+<img src="assets/card-lmsh.svg" alt="lmsh" width="200"/>
+</a>
+</td>
+<td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/vault/">
 <img src="assets/card-vault.svg" alt="vault" width="200"/>
 </a>
@@ -97,13 +102,13 @@ Click a card to jump to that feature, or
 <img src="assets/card-env-safe.svg" alt="env-safe" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/plugins-detail/safety-hooks/">
 <img src="assets/card-safety.svg" alt="safety" width="200"/>
 </a>
 </td>
-</tr>
-<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/statusline/">
 <img src="assets/card-statusline.svg" alt="statusline" width="200"/>
@@ -114,13 +119,13 @@ Click a card to jump to that feature, or
 <img src="assets/card-gdocs.svg" alt="gdocs" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/integrations/google-sheets/">
 <img src="assets/card-gsheets.svg" alt="gsheets" width="200"/>
 </a>
 </td>
-</tr>
-<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/integrations/alt-llm-providers/">
 <img src="assets/card-alt.svg" alt="alt" width="200"/>
@@ -131,6 +136,8 @@ Click a card to jump to that feature, or
 <img src="assets/card-voice.svg" alt="voice" width="200"/>
 </a>
 </td>
+</tr>
+<tr>
 <td align="center">
 <a href="https://pchalasani.github.io/claude-code-tools/tools/fix-session/">
 <img src="assets/card-session-repair.svg" alt="session repair" width="200"/>

{claude_code_tools-1.11.2 → claude_code_tools-1.12.0}/claude_code_tools/__init__.py

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

claude_code_tools-1.12.0/claude_code_tools/agent_tunnel/__init__.py

@@ -0,0 +1,6 @@
+"""agent-tunnel: expose a local Claude Code session to teammates.
+
+A small daemon that answers questions (Discord v1) against forks of a
+long-lived "expert" Claude Code session, with hard read-only tool
+restrictions. See docs/agent-tunnel-spec.md for the design.
+"""

claude_code_tools-1.12.0/claude_code_tools/agent_tunnel/backends.py

@@ -0,0 +1,447 @@
+"""Execution backends: answer a question against a forked Claude session.
+
+Each external conversation thread is *bound* in the store to an expert
+session (handle -> session_id + project dir) before any question runs, so a
+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>`).
+
+Two interchangeable strategies (see docs/agent-tunnel-spec.md):
+
+- HeadlessBackend: `claude -p` per question (clean JSON I/O; Agent SDK
+  metering on subscription plans from 2026-06-15).
+- TmuxBackend: a real interactive `claude` per thread in a window of a
+  dedicated tmux session; question pasted in, answer read from the fork's
+  JSONL transcript (interactive subscription metering).
+
+Both apply the same hard read-only tool restrictions per turn.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Protocol
+
+from .config import TunnelConfig, resolve_tools
+from .session import (
+    extract_answer,
+    list_session_files,
+    make_marker,
+    wait_for_new_session_file,
+)
+from .store import ThreadRecord, TunnelStore
+from .tmux import TmuxSession
+from .trust import (
+    default_trust_config_path,
+    ensure_folder_trusted,
+    trust_config_path_for,
+)
+
+
+class BackendError(RuntimeError):
+    """Answering a question failed; message is user-presentable."""
+
+
+@dataclass
+class Answer:
+    """A completed answer from a fork."""
+
+    text: str
+    fork_session_id: str
+    new_thread: bool
+
+
+class Backend(Protocol):
+    """Common interface for execution backends."""
+
+    def ask(self, thread_key: str, question: str) -> Answer:
+        """Answer `question` in the (already-bound) thread's fork."""
+        ...
+
+    def forget(self, thread_key: str) -> None:
+        """Drop a thread mapping and any live resources."""
+        ...
+
+    def reap_idle(self) -> int:
+        """Release idle resources; returns how many were released."""
+        ...
+
+
+def build_claude_flags(
+    cfg: TunnelConfig, resume_id: str, fork: bool, access: str = "read"
+) -> list[str]:
+    """Common claude CLI flags for a fork invocation/launch.
+
+    Args:
+        cfg: Tunnel configuration (tool restrictions, model, persona).
+        resume_id: Session id to resume (expert id when forking, else the
+            fork's own id).
+        fork: Whether to create a new fork of `resume_id`.
+        access: Per-handle access level ("read"/"write") set via >share.
+
+    Returns:
+        Argument list (excluding the binary, -p, and the prompt).
+    """
+    claude = cfg.claude
+    allowed, disallowed = resolve_tools(claude, access)
+    flags = ["--resume", resume_id]
+    if fork:
+        flags.append("--fork-session")
+    if allowed:
+        flags += ["--allowedTools", ",".join(allowed)]
+    if disallowed:
+        flags += ["--disallowedTools", ",".join(disallowed)]
+    if claude.permission_mode:
+        flags += ["--permission-mode", claude.permission_mode]
+    if claude.model:
+        flags += ["--model", claude.model]
+    if claude.persona:
+        flags += ["--append-system-prompt", claude.persona]
+    return 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.
+    """
+    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"
+    return f"{base}-{suffix}"
+
+
+class _BaseBackend:
+    """Shared store handling and binding lookup."""
+
+    name = "base"
+
+    def __init__(self, cfg: TunnelConfig, store: TunnelStore) -> None:
+        """Keep config and store references."""
+        self.cfg = cfg
+        self.store = store
+
+    def _require_binding(self, thread_key: str) -> ThreadRecord:
+        rec = self.store.get(thread_key)
+        if rec is None:
+            raise BackendError(
+                f"Thread {thread_key} is not bound to any published session."
+            )
+        if not rec.expert_session_id or not rec.project_dir:
+            raise BackendError(
+                f"Thread {thread_key} has an incomplete binding."
+            )
+        return rec
+
+    def _home(self, rec: ThreadRecord) -> Optional[Path]:
+        """Claude config dir the session lives under (for transcript lookup)."""
+        return Path(rec.config_dir) if rec.config_dir else self.cfg.claude_home
+
+    def _env(self, rec: ThreadRecord) -> dict[str, str]:
+        """Subprocess env with CLAUDE_CONFIG_DIR pinned to the session's dir."""
+        env = dict(os.environ)
+        if rec.config_dir:
+            env["CLAUDE_CONFIG_DIR"] = rec.config_dir
+        return env
+
+    def reap_idle(self) -> int:
+        """Default: nothing to reap."""
+        return 0
+
+
+class HeadlessBackend(_BaseBackend):
+    """`claude -p` per question; prompt on stdin, JSON result on stdout.
+
+    Note: `--bare` is NOT added automatically — on subscription-auth setups
+    it can break login ("Not logged in"), since it skips loading user
+    configuration. Add it via [claude] headless_extra_args if your setup
+    supports it.
+    """
+
+    name = "headless"
+
+    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."""
+        rec = self._require_binding(thread_key)
+        fork = not rec.fork_session_id
+        resume_id = rec.expert_session_id if fork else rec.fork_session_id
+
+        argv = [
+            self.cfg.claude.binary,
+            "-p",
+            "--output-format",
+            "json",
+            *build_claude_flags(self.cfg, resume_id, fork, rec.access),
+            *self.cfg.claude.headless_extra_args,
+        ]
+        try:
+            result = subprocess.run(
+                argv,
+                input=question,
+                capture_output=True,
+                text=True,
+                cwd=rec.project_dir,
+                env=self._env(rec),
+                timeout=self.cfg.limits.answer_timeout_s,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise BackendError(
+                f"Timed out after {self.cfg.limits.answer_timeout_s:.0f}s"
+            ) from exc
+        except OSError as exc:
+            raise BackendError(f"Could not run claude: {exc}") from exc
+
+        if result.returncode != 0:
+            tail = (result.stderr or result.stdout or "").strip()[-500:]
+            raise BackendError(f"claude exited {result.returncode}: {tail}")
+        try:
+            data = json.loads(result.stdout)
+        except json.JSONDecodeError as exc:
+            raise BackendError(
+                f"Unparseable claude output: {result.stdout[:300]}"
+            ) from exc
+        if data.get("is_error"):
+            raise BackendError(str(data.get("result", "unknown error"))[:500])
+
+        fork_id = data.get("session_id") or resume_id
+        rec.fork_session_id = fork_id
+        self.store.upsert(rec)
+        text = str(data.get("result", "")).strip()
+        if not text:
+            raise BackendError("Empty answer from claude")
+        return Answer(text=text, fork_session_id=fork_id, new_thread=fork)
+
+    def forget(self, thread_key: str) -> None:
+        """Drop the thread mapping."""
+        self.store.remove(thread_key)
+
+
+class TmuxBackend(_BaseBackend):
+    """Interactive forked sessions, one tmux window per thread."""
+
+    name = "tmux"
+
+    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 _launch(
+        self,
+        window: str,
+        project_dir: str,
+        resume_id: str,
+        fork: bool,
+        config_dir: str = "",
+        access: str = "read",
+        initial_prompt: Optional[str] = None,
+    ) -> None:
+        """Launch an interactive fork in `window`.
+
+        `config_dir` pins the fork to the session's Claude config dir (via
+        `CLAUDE_CONFIG_DIR`) so it finds the transcript and the folder's trust
+        — essential when the daemon runs under a different config dir than the
+        shared session (e.g. work vs personal).
+
+        With `initial_prompt`, the question is passed as claude's positional
+        prompt argument, so claude auto-submits it once it is ready — no
+        keystroke simulation, which sidesteps the slow-to-accept-input window
+        right after a cold launch. Without it, we wait for the prompt to go
+        idle (used only for warm reuse paths).
+        """
+        argv = [
+            self.cfg.claude.binary,
+            *build_claude_flags(self.cfg, resume_id, fork, access),
+            *self.cfg.claude.tmux_extra_args,
+        ]
+        if initial_prompt is not None:
+            argv.append(initial_prompt)
+        if config_dir:
+            argv = ["env", f"CLAUDE_CONFIG_DIR={config_dir}", *argv]
+        if self.cfg.claude.auto_trust:
+            self._pretrust(project_dir, config_dir)
+        self.tmux.kill_window(window)
+        self.tmux.new_window(window, shlex.join(argv), cwd=project_dir)
+        if initial_prompt is None:
+            ready = self.tmux.wait_for_idle(
+                window, idle_s=2.5, timeout_s=self.cfg.limits.launch_timeout_s
+            )
+        else:
+            ready = True
+            time.sleep(2.0)  # let claude spin up; it auto-submits the prompt
+        screen = self.tmux.capture(window, lines=40).lower()
+        if "trust the files" in screen or "do you trust" in screen:
+            self.tmux.kill_window(window)
+            raise BackendError(
+                "Project folder is not trusted and auto-trust did not take. "
+                "Open it once in Claude and accept the prompt, or check "
+                "[claude] auto_trust / trust_config_path."
+            )
+        if self.tmux.pane_dead(window):
+            tail = self.tmux.capture(window, lines=30).strip()[-500:]
+            self.tmux.kill_window(window)
+            raise BackendError(f"claude exited at launch:\n{tail}")
+        if not ready:
+            raise BackendError(
+                "Forked session did not become ready within "
+                f"{self.cfg.limits.launch_timeout_s:.0f}s"
+            )
+
+    def _pretrust(self, project_dir: str, config_dir: str = "") -> None:
+        """Best-effort: mark the project folder trusted before launching,
+        in the same config dir the fork will use."""
+        try:
+            if self.cfg.claude.trust_config_path:
+                path = Path(self.cfg.claude.trust_config_path).expanduser()
+            elif config_dir:
+                path = trust_config_path_for(config_dir)
+            else:
+                path = default_trust_config_path()
+            ensure_folder_trusted(Path(project_dir).resolve(), path)
+        except Exception:
+            pass  # if it fails, the trust-dialog check below reports it
+
+    def _fork_file(
+        self, project_dir: Path, fork_id: str, claude_home: Optional[Path]
+    ) -> Optional[Path]:
+        """Locate a fork's transcript by session id."""
+        for path in list_session_files(project_dir, claude_home):
+            if path.stem == fork_id:
+                return path
+        return None
+
+    def ask(self, thread_key: str, question: str) -> Answer:
+        """Answer a question in the thread's fork.
+
+        Cold paths (a new fork, or a follow-up whose window was reaped) launch
+        with the question as claude's initial prompt — claude auto-submits it
+        once ready, sidestepping the slow-startup keystroke problem. A warm
+        follow-up window is reused by pasting + Enter. The answer is read from
+        the fork's JSONL transcript either way.
+        """
+        rec = self._require_binding(thread_key)
+        window = _window_name(rec.handle, thread_key)
+        project_dir = Path(rec.project_dir)
+        home = self._home(rec)
+        marker = make_marker(question)
+        fork = not rec.fork_session_id
+
+        if fork:
+            before = {
+                p.stem for p in list_session_files(project_dir, home)
+            }
+            self._launch(
+                window,
+                rec.project_dir,
+                rec.expert_session_id,
+                fork=True,
+                config_dir=rec.config_dir,
+                access=rec.access,
+                initial_prompt=question,
+            )
+            fork_file = wait_for_new_session_file(
+                project_dir,
+                before=before,
+                exclude=self.store.known_fork_ids(),
+                deadline=time.time() + 90,
+                claude_home=home,
+            )
+            if fork_file is None:
+                raise BackendError(
+                    "Fork transcript did not appear — did the fork launch?"
+                )
+        else:
+            fork_file = self._fork_file(project_dir, rec.fork_session_id, home)
+            if fork_file is None:
+                raise BackendError(
+                    f"Fork transcript {rec.fork_session_id} not found"
+                )
+            if self.tmux.window_alive(window) and not self.tmux.pane_dead(
+                window
+            ):
+                # Warm session: paste + Enter (no startup delay when warm).
+                if not self.tmux.submit_text(window, question):
+                    raise BackendError(
+                        "Question pasted but never submitted (Enter not "
+                        "accepted)."
+                    )
+            else:
+                # Window was reaped — relaunch cold with the prompt arg.
+                self._launch(
+                    window,
+                    rec.project_dir,
+                    rec.fork_session_id,
+                    fork=False,
+                    config_dir=rec.config_dir,
+                    access=rec.access,
+                    initial_prompt=question,
+                )
+
+        deadline = time.time() + self.cfg.limits.answer_timeout_s
+        while True:
+            if time.time() > deadline:
+                raise BackendError(
+                    "Timed out waiting for the answer "
+                    f"({self.cfg.limits.answer_timeout_s:.0f}s)"
+                )
+            if self.tmux.pane_dead(window):
+                tail = self.tmux.capture(window, lines=30).strip()[-500:]
+                raise BackendError(f"Forked session died:\n{tail}")
+            complete, text = extract_answer(fork_file, marker)
+            if complete and text:
+                break
+            time.sleep(2.0)
+
+        rec.fork_session_id = fork_file.stem
+        rec.tmux_window = window
+        self.store.upsert(rec)
+        return Answer(
+            text=text.strip(),
+            fork_session_id=fork_file.stem,
+            new_thread=fork,
+        )
+
+    def forget(self, thread_key: str) -> None:
+        """Drop the mapping and kill its window."""
+        rec = self.store.remove(thread_key)
+        if rec is not None and rec.tmux_window:
+            self.tmux.kill_window(rec.tmux_window)
+
+    def reap_idle(self) -> int:
+        """Kill windows idle longer than the configured TTL (backstop).
+
+        A TTL of 0 (or less) disables reaping entirely — threads then live
+        until closed with !done, ``forget``, or a server kill.
+        """
+        ttl_s = self.cfg.limits.pane_idle_ttl_min * 60
+        if ttl_s <= 0:
+            return 0
+        reaped = 0
+        for rec in self.store.all_records():
+            if not rec.tmux_window or rec.backend != self.name:
+                continue
+            if time.time() - rec.last_used < ttl_s:
+                continue
+            if self.tmux.window_alive(rec.tmux_window):
+                self.tmux.kill_window(rec.tmux_window)
+                reaped += 1
+            rec.tmux_window = ""
+            self.store.upsert(rec)
+        return reaped
+
+
+def make_backend(cfg: TunnelConfig, store: TunnelStore) -> Backend:
+    """Instantiate the configured backend."""
+    if cfg.backend == "headless":
+        return HeadlessBackend(cfg, store)
+    return TmuxBackend(cfg, store)