ccgram 2.2.0__tar.gz → 2.2.2__tar.gz

{ccgram-2.2.0 → ccgram-2.2.2}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [2.2.2] - 2026-03-20
+
+### Fixed
+- Handle Telegram flood control during startup command registration
+
+## [2.2.1] - 2026-03-20
+
+### Added
+- Subagent context binding ([#32](https://github.com/alexei-led/ccgram/pull/32))
+
+
+### Documentation
+- Update CHANGELOG.md for v2.2.1
+
 ## [2.2.0] - 2026-03-20
 
 ### Added
@@ -12,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 - Update release process in CLAUDE.md [skip ci]
+- Update CHANGELOG.md for v2.2.0
 
 ## [2.1.2] - 2026-03-20
 

{ccgram-2.2.0 → ccgram-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccgram
-Version: 2.2.0
+Version: 2.2.2
 Summary: CCGram — manage AI coding agents from Telegram via tmux
 Project-URL: Homepage, https://github.com/alexei-led/ccgram
 Project-URL: Repository, https://github.com/alexei-led/ccgram

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '2.2.0'
-__version_tuple__ = version_tuple = (2, 2, 0)
+__version__ = version = '2.2.2'
+__version_tuple__ = version_tuple = (2, 2, 2)
 
 __commit_id__ = commit_id = None

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/bot.py

@@ -1649,7 +1649,10 @@ async def post_init(application: Application) -> None:
     global session_monitor, _status_poll_task, _global_provider_menu
 
     default_provider = get_provider()
-    await register_commands(application.bot, provider=default_provider)
+    try:
+        await register_commands(application.bot, provider=default_provider)
+    except TelegramError:
+        logger.warning("Failed to register bot commands at startup, will retry later")
     _global_provider_menu = default_provider.capabilities.name
 
     # Refresh bot command menu every 10 minutes.

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/cc_commands.py

@@ -286,10 +286,41 @@ async def register_commands(
         bot_commands.append(BotCommand(cmd.telegram_name, desc))
         cc_count += 1
 
-    if scope is None:
-        await bot.delete_my_commands()
-        await bot.set_my_commands(bot_commands)
-    else:
-        await bot.delete_my_commands(scope=scope)
-        await bot.set_my_commands(bot_commands, scope=scope)
+    import asyncio
+
+    from telegram.error import RetryAfter
+
+    max_attempts = 3
+    for attempt in range(1, max_attempts + 1):
+        try:
+            if scope is None:
+                await bot.delete_my_commands()
+                await bot.set_my_commands(bot_commands)
+            else:
+                await bot.delete_my_commands(scope=scope)
+                await bot.set_my_commands(bot_commands, scope=scope)
+            break
+        except RetryAfter as e:
+            retry_secs = min(
+                60,
+                (
+                    e.retry_after
+                    if isinstance(e.retry_after, int)
+                    else int(e.retry_after.total_seconds())
+                ),
+            )
+            if attempt < max_attempts:
+                logger.warning(
+                    "Telegram flood control registering commands, retry in %ds (attempt %d/%d)",
+                    retry_secs,
+                    attempt,
+                    max_attempts,
+                )
+                await asyncio.sleep(retry_secs)
+            else:
+                logger.warning(
+                    "Telegram flood control registering commands, giving up after %d attempts",
+                    max_attempts,
+                )
+                return
     logger.info("Registered %d bot commands (%d CC)", len(bot_commands), cc_count)

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/handlers/hook_events.py

@@ -133,13 +133,28 @@ async def _handle_stop(event: HookEvent, bot: Bot) -> None:
         await enqueue_status_update(bot, user_id, window_id, None, thread_id=thread_id)
 
 
-# Track active subagents per window: window_id -> set of subagent_ids
-_active_subagents: dict[str, set[str]] = {}
+# Track active subagents per window: window_id -> {subagent_id -> name}
+_active_subagents: dict[str, dict[str, str]] = {}
 
+_MAX_DISPLAYED_NAMES = 3
 
-def get_subagent_count(window_id: str) -> int:
-    """Return the number of active subagents for a window."""
-    return len(_active_subagents.get(window_id, set()))
+
+def get_subagent_names(window_id: str) -> list[str]:
+    """Return names of active subagents for a window."""
+    return list(_active_subagents.get(window_id, {}).values())
+
+
+def build_subagent_label(names: list[str]) -> str | None:
+    """Build a display label for active subagents.
+
+    Returns None if no subagents are active.
+    """
+    if not names:
+        return None
+    if len(names) == 1:
+        return f"\U0001f916 {names[0]}"
+    joined = ", ".join(names[:_MAX_DISPLAYED_NAMES])
+    return f"\U0001f916 {len(names)} subagents: {joined}"
 
 
 def clear_subagents(window_id: str) -> None:
@@ -147,28 +162,46 @@ def clear_subagents(window_id: str) -> None:
     _active_subagents.pop(window_id, None)
 
 
-async def _handle_subagent_start(event: HookEvent, bot: Bot) -> None:  # noqa: ARG001
-    """Handle SubagentStart — track active subagent."""
+async def _handle_subagent_start(event: HookEvent, bot: Bot) -> None:
+    """Handle SubagentStart — track active subagent and notify."""
+    from .message_queue import enqueue_status_update
+
     users = _resolve_users_for_window_key(event.window_key)
     if not users:
         return
 
     window_id = users[0][2]  # all users share the same window_id
     subagent_id = event.data.get("subagent_id", "")
+    name = (
+        (event.data.get("name") or "").strip()
+        or (event.data.get("description") or "").strip()
+        or subagent_id[:12]
+        or "subagent"
+    )
 
-    _active_subagents.setdefault(window_id, set()).add(subagent_id)
+    _active_subagents.setdefault(window_id, {})[subagent_id] = name
 
-    count = len(_active_subagents[window_id])
     logger.debug(
         "Subagent started: window=%s, count=%d, name=%s",
         window_id,
-        count,
-        event.data.get("name", ""),
+        len(_active_subagents[window_id]),
+        name,
     )
 
+    for user_id, thread_id, _ in users:
+        await enqueue_status_update(
+            bot,
+            user_id,
+            window_id,
+            f"\U0001f916 Subagent started: {name}",
+            thread_id=thread_id,
+        )
+
+
+async def _handle_subagent_stop(event: HookEvent, bot: Bot) -> None:
+    """Handle SubagentStop — remove subagent from tracking and notify."""
+    from .message_queue import enqueue_status_update
 
-async def _handle_subagent_stop(event: HookEvent, bot: Bot) -> None:  # noqa: ARG001
-    """Handle SubagentStop — remove subagent from tracking."""
     users = _resolve_users_for_window_key(event.window_key)
     if not users:
         return
@@ -176,21 +209,29 @@ async def _handle_subagent_stop(event: HookEvent, bot: Bot) -> None:  # noqa: AR
     window_id = users[0][2]
     subagent_id = event.data.get("subagent_id", "")
 
-    ids = _active_subagents.get(window_id)
-    if not ids:
+    agents = _active_subagents.get(window_id)
+    if not agents:
         return
-    ids.discard(subagent_id)
-    if not ids:
+    name = agents.pop(subagent_id, subagent_id[:12] or "subagent")
+    if not agents:
         _active_subagents.pop(window_id, None)
 
-    count = get_subagent_count(window_id)
     logger.debug(
-        "Subagent stopped: window=%s, remaining=%d, id=%s",
+        "Subagent stopped: window=%s, remaining=%d, name=%s",
         window_id,
-        count,
-        subagent_id,
+        len(_active_subagents.get(window_id, {})),
+        name,
     )
 
+    for user_id, thread_id, _ in users:
+        await enqueue_status_update(
+            bot,
+            user_id,
+            window_id,
+            f"\U0001f916 Subagent done: {name}",
+            thread_id=thread_id,
+        )
+
 
 async def _handle_teammate_idle(event: HookEvent, bot: Bot) -> None:
     """Handle TeammateIdle — notify topic that a teammate went idle."""
@@ -254,9 +295,11 @@ async def _handle_session_end(event: HookEvent, bot: Bot) -> None:
         reason,
     )
 
-    # Clear session association so next launch gets a fresh session
+    # Clear session association and subagent tracking so next launch starts fresh
     if users:
-        session_manager.clear_window_session(users[0][2])
+        window_id = users[0][2]
+        session_manager.clear_window_session(window_id)
+        clear_subagents(window_id)
 
     for user_id, thread_id, window_id in users:
         clear_seen_status(window_id)

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/handlers/message_queue.py

@@ -83,18 +83,23 @@ def _is_batch_eligible(task: MessageTask) -> bool:
     )
 
 
-def format_batch_message(entries: list[ToolBatchEntry]) -> str:
+def format_batch_message(
+    entries: list[ToolBatchEntry], subagent_label: str | None = None
+) -> str:
     """Render a batch of tool calls as a single compact message.
 
     Format:
-        ⚡ 3 tool calls
+        ⚡ 3 tool calls [🤖 write-tests]
         📖 Read  src/foo.py       ⎿  42 lines
         ✏️ Edit  src/foo.py       ⎿  +3 −1
         ⚡ Bash  make test        ⏳
     """
     count = len(entries)
     label = "tool call" if count == 1 else "tool calls"
-    lines = [f"\u26a1 {count} {label}"]
+    header = f"\u26a1 {count} {label}"
+    if subagent_label:
+        header = f"{header} [{subagent_label}]"
+    lines = [header]
 
     for entry in entries:
         line = entry.tool_use_text
@@ -400,7 +405,10 @@ async def _process_batch_task(bot: Bot, user_id: int, task: MessageTask) -> None
         return
 
     # Send or edit batch message
-    batch_text = format_batch_message(batch.entries)
+    from .hook_events import build_subagent_label, get_subagent_names
+
+    subagent_label = build_subagent_label(get_subagent_names(window_id))
+    batch_text = format_batch_message(batch.entries, subagent_label=subagent_label)
 
     if batch.telegram_msg_id is None:
         # Clear status message first, then send new batch message
@@ -445,7 +453,11 @@ async def _flush_batch(bot: Bot, user_id: int, thread_id_or_0: int) -> None:
 
     thread_id: int | None = thread_id_or_0 if thread_id_or_0 != 0 else None
     chat_id = session_manager.resolve_chat_id(user_id, thread_id)
-    batch_text = format_batch_message(batch.entries)
+
+    from .hook_events import build_subagent_label, get_subagent_names
+
+    subagent_label = build_subagent_label(get_subagent_names(batch.window_id))
+    batch_text = format_batch_message(batch.entries, subagent_label=subagent_label)
 
     if batch.telegram_msg_id is None:
         # First send failed earlier — attempt one send before dropping
@@ -878,9 +890,14 @@ async def _check_and_send_status(
 
     status = get_provider_for_window(window_id).parse_terminal_status(pane_text)
     if status and not status.is_interactive:
-        await _do_send_status_message(
-            bot, user_id, thread_id_or_0, window_id, status.display_label
-        )
+        from .hook_events import build_subagent_label, get_subagent_names
+
+        display = status.display_label
+        subagent_names = get_subagent_names(window_id)
+        if subagent_names:
+            label = build_subagent_label(subagent_names)
+            display = f"{display} ({label})"
+        await _do_send_status_message(bot, user_id, thread_id_or_0, window_id, display)
 
 
 async def enqueue_content_message(

{ccgram-2.2.0 → ccgram-2.2.2}/src/ccgram/handlers/status_polling.py

@@ -824,13 +824,14 @@ async def update_status_message(
         ws.startup_time = None
         await _send_typing_throttled(bot, user_id, thread_id)
         if notif_mode not in ("muted", "errors_only"):
-            # Append subagent count if any are active
-            from .hook_events import get_subagent_count
+            # Append subagent names if any are active
+            from .hook_events import build_subagent_label, get_subagent_names
 
-            subagent_count = get_subagent_count(window_id)
+            subagent_names = get_subagent_names(window_id)
             display_status = status_line
-            if subagent_count:
-                display_status = f"{status_line} ({subagent_count} subagent{'s' if subagent_count > 1 else ''})"
+            if subagent_names:
+                label = build_subagent_label(subagent_names)
+                display_status = f"{status_line} ({label})"
             await enqueue_status_update(
                 bot,
                 user_id,

{ccgram-2.2.0 → ccgram-2.2.2}/tests/ccgram/test_hook_events.py

@@ -8,9 +8,10 @@ from ccgram.handlers.hook_events import (
     HookEvent,
     _active_subagents,
     _resolve_users_for_window_key,
+    build_subagent_label,
     clear_subagents,
     dispatch_hook_event,
-    get_subagent_count,
+    get_subagent_names,
 )
 
 
@@ -64,17 +65,55 @@ class TestSubagentTracking:
     def setup_method(self) -> None:
         _active_subagents.clear()
 
-    def test_start_increments_count(self) -> None:
-        _active_subagents["@0"] = {"a1"}
-        assert get_subagent_count("@0") == 1
+    def test_count_via_names(self) -> None:
+        _active_subagents["@0"] = {"a1": "agent-1"}
+        assert len(get_subagent_names("@0")) == 1
 
     def test_clear_removes_all(self) -> None:
-        _active_subagents["@0"] = {"a1", "a2"}
+        _active_subagents["@0"] = {"a1": "agent-1", "a2": "agent-2"}
         clear_subagents("@0")
-        assert get_subagent_count("@0") == 0
+        assert get_subagent_names("@0") == []
 
-    def test_count_missing_window(self) -> None:
-        assert get_subagent_count("@999") == 0
+    def test_names_missing_window(self) -> None:
+        assert get_subagent_names("@999") == []
+
+    def test_get_names_returns_values(self) -> None:
+        _active_subagents["@0"] = {"a1": "write-tests", "a2": "refactor"}
+        names = get_subagent_names("@0")
+        assert sorted(names) == ["refactor", "write-tests"]
+
+    def test_get_names_empty_after_clear(self) -> None:
+        _active_subagents["@0"] = {"a1": "agent-1"}
+        clear_subagents("@0")
+        assert get_subagent_names("@0") == []
+
+
+class TestBuildSubagentLabel:
+    def test_empty_list(self) -> None:
+        assert build_subagent_label([]) is None
+
+    def test_single_name(self) -> None:
+        assert build_subagent_label(["write-tests"]) == "\U0001f916 write-tests"
+
+    def test_multiple_names(self) -> None:
+        result = build_subagent_label(["write-tests", "refactor"])
+        assert result is not None
+        assert "\U0001f916" in result
+        assert "2 subagents" in result
+        assert "write-tests" in result
+        assert "refactor" in result
+
+    def test_three_names(self) -> None:
+        result = build_subagent_label(["a", "b", "c"])
+        assert result is not None
+        assert "3 subagents" in result
+
+    def test_truncates_at_three(self) -> None:
+        result = build_subagent_label(["a", "b", "c", "d"])
+        assert result is not None
+        assert "4 subagents" in result
+        assert "a, b, c" in result
+        assert "d" not in result
 
 
 class TestDispatchHookEvent:
@@ -219,25 +258,132 @@ class TestHandleSubagentStart:
             lambda: iter([(100, 42, "@0")]),
         )
         bot = AsyncMock(spec=Bot)
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            event = _make_event(
+                event_type="SubagentStart",
+                data={"subagent_id": "sub-1", "name": "researcher"},
+            )
+            await dispatch_hook_event(event, bot)
+            assert len(get_subagent_names("@0")) == 1
+            assert get_subagent_names("@0") == ["researcher"]
+            mock_enqueue.assert_called_once_with(
+                bot, 100, "@0", "\U0001f916 Subagent started: researcher", thread_id=42
+            )
+
+    async def test_tracks_multiple_subagents(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            for sub_id in ("sub-1", "sub-2"):
+                event = _make_event(
+                    event_type="SubagentStart", data={"subagent_id": sub_id}
+                )
+                await dispatch_hook_event(event, bot)
+            assert len(get_subagent_names("@0")) == 2
+            assert mock_enqueue.call_count == 2
+
+    async def test_name_fallback_to_description(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            event = _make_event(
+                event_type="SubagentStart",
+                data={"subagent_id": "sub-1", "description": "explore code"},
+            )
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == ["explore code"]
+            assert "explore code" in mock_enqueue.call_args[0][3]
+
+    async def test_name_fallback_to_truncated_id(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            event = _make_event(
+                event_type="SubagentStart",
+                data={"subagent_id": "abcdef123456789"},
+            )
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == ["abcdef123456"]
+            assert "abcdef123456" in mock_enqueue.call_args[0][3]
+
+    async def test_whitespace_name_falls_back(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch("ccgram.handlers.message_queue.enqueue_status_update"):
+            event = _make_event(
+                event_type="SubagentStart",
+                data={"subagent_id": "sub-1", "name": "   ", "description": "real"},
+            )
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == ["real"]
+
+    async def test_empty_everything_uses_fallback(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch("ccgram.handlers.message_queue.enqueue_status_update"):
+            event = _make_event(
+                event_type="SubagentStart",
+                data={"subagent_id": "", "name": "", "description": ""},
+            )
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == ["subagent"]
+
+    async def test_no_users_does_not_track(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([]),
+        )
+        bot = AsyncMock(spec=Bot)
         event = _make_event(
             event_type="SubagentStart",
-            data={"subagent_id": "sub-1", "name": "researcher"},
+            data={"subagent_id": "sub-1", "name": "test"},
         )
         await dispatch_hook_event(event, bot)
-        assert get_subagent_count("@0") == 1
+        assert _active_subagents == {}
 
-    async def test_tracks_multiple_subagents(self, monkeypatch) -> None:
+    async def test_notifies_multiple_users(self, monkeypatch) -> None:
         monkeypatch.setattr(
             "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
-            lambda: iter([(100, 42, "@0")]),
+            lambda: iter([(100, 42, "@0"), (200, 99, "@0")]),
         )
         bot = AsyncMock(spec=Bot)
-        for sub_id in ("sub-1", "sub-2"):
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
             event = _make_event(
-                event_type="SubagentStart", data={"subagent_id": sub_id}
+                event_type="SubagentStart",
+                data={"subagent_id": "sub-1", "name": "researcher"},
             )
             await dispatch_hook_event(event, bot)
-        assert get_subagent_count("@0") == 2
+            assert mock_enqueue.call_count == 2
+            calls = mock_enqueue.call_args_list
+            assert calls[0][0][1] == 100  # first user_id
+            assert calls[1][0][1] == 200  # second user_id
+            assert calls[0][0][2] == "@0"  # window_id from outer scope
+            assert calls[1][0][2] == "@0"
 
 
 class TestHandleSubagentStop:
@@ -249,23 +395,49 @@ class TestHandleSubagentStop:
             "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
             lambda: iter([(100, 42, "@0")]),
         )
-        _active_subagents["@0"] = {"sub-1", "sub-2"}
+        _active_subagents["@0"] = {"sub-1": "agent-1", "sub-2": "agent-2"}
         bot = AsyncMock(spec=Bot)
-        event = _make_event(event_type="SubagentStop", data={"subagent_id": "sub-1"})
-        await dispatch_hook_event(event, bot)
-        assert get_subagent_count("@0") == 1
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            event = _make_event(
+                event_type="SubagentStop", data={"subagent_id": "sub-1"}
+            )
+            await dispatch_hook_event(event, bot)
+            assert len(get_subagent_names("@0")) == 1
+            mock_enqueue.assert_called_once_with(
+                bot, 100, "@0", "\U0001f916 Subagent done: agent-1", thread_id=42
+            )
 
     async def test_removes_last_subagent_cleans_dict(self, monkeypatch) -> None:
         monkeypatch.setattr(
             "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
             lambda: iter([(100, 42, "@0")]),
         )
-        _active_subagents["@0"] = {"sub-1"}
+        _active_subagents["@0"] = {"sub-1": "agent-1"}
         bot = AsyncMock(spec=Bot)
-        event = _make_event(event_type="SubagentStop", data={"subagent_id": "sub-1"})
-        await dispatch_hook_event(event, bot)
-        assert get_subagent_count("@0") == 0
-        assert "@0" not in _active_subagents
+        with patch("ccgram.handlers.message_queue.enqueue_status_update"):
+            event = _make_event(
+                event_type="SubagentStop", data={"subagent_id": "sub-1"}
+            )
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == []
+            assert "@0" not in _active_subagents
+
+    async def test_unknown_id_no_notification(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        bot = AsyncMock(spec=Bot)
+        with patch(
+            "ccgram.handlers.message_queue.enqueue_status_update"
+        ) as mock_enqueue:
+            event = _make_event(
+                event_type="SubagentStop", data={"subagent_id": "never-seen"}
+            )
+            await dispatch_hook_event(event, bot)
+            mock_enqueue.assert_not_called()
 
 
 class TestHandleTeammateIdle:
@@ -383,6 +555,9 @@ class TestHandleStopFailure:
 
 
 class TestHandleSessionEnd:
+    def setup_method(self) -> None:
+        _active_subagents.clear()
+
     async def test_transitions_to_done(self, monkeypatch) -> None:
         monkeypatch.setattr(
             "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
@@ -415,6 +590,33 @@ class TestHandleSessionEnd:
             mock_enqueue.assert_called_once_with(bot, 100, "@0", None, thread_id=42)
             mock_clear_session.assert_called_once_with("@0")
 
+    async def test_clears_subagents_on_session_end(self, monkeypatch) -> None:
+        monkeypatch.setattr(
+            "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",
+            lambda: iter([(100, 42, "@0")]),
+        )
+        _active_subagents["@0"] = {"sub-1": "researcher"}
+        bot = AsyncMock(spec=Bot)
+        with (
+            patch(
+                "ccgram.handlers.hook_events.session_manager.resolve_chat_id",
+                return_value=-100,
+            ),
+            patch(
+                "ccgram.handlers.hook_events.session_manager.get_display_name",
+                return_value="project",
+            ),
+            patch(
+                "ccgram.handlers.hook_events.session_manager.clear_window_session",
+            ),
+            patch("ccgram.handlers.topic_emoji.update_topic_emoji"),
+            patch("ccgram.handlers.message_queue.enqueue_status_update"),
+            patch("ccgram.handlers.status_polling.clear_seen_status"),
+        ):
+            event = _make_event(event_type="SessionEnd", data={"reason": "clear"})
+            await dispatch_hook_event(event, bot)
+            assert get_subagent_names("@0") == []
+
     async def test_no_users_skips(self, monkeypatch) -> None:
         monkeypatch.setattr(
             "ccgram.handlers.hook_events.session_manager.iter_thread_bindings",