Modularity Review — ccgram

Executive Summary

System Overview

Structural strengths:

• message_task.py — pure frozen dataclass sum type, zero project imports
• polling_coordinator.py — 87 lines, thin orchestration shell
• providers/base.py — zero ccgram imports; clean protocol boundary
• topic_state_registry.py — self-registration pattern replaces scattered lazy cleanup imports
• hook.py — correctly isolated from config.py (deployed in agent panes)

Open Issues

Issue 1 — session.py Is a De-Facto Hub with 32 Handler Dependents [Critical]

Files: session.py (783 lines), imported by 32+ handler modules.

Every Telegram handler that needs window state, mode settings, session resolution, display names, or state persistence imports session_manager directly.

Coupling: HIGH strength + HIGH volatility (WindowState schema extended repeatedly) → UNBALANCED.

AI context impact: Any session change requires loading session.py (783 lines) + every handler that mutates the relevant field. Adding a new per-window flag means auditing 32+ files for usage sites.

Recommendation: Enforce that handlers read via view_window() and write only through explicit setters. A WindowModeService wrapping approval/notification/batch modes would reduce most handlers' dependency to a 2-method slice.

Issue 2 — claude_task_state.py Is Shared Mutable State with No Ownership Discipline [High]

Files: claude_task_state.py (562 lines), write access from 6 modules across core and handler layers.

The coordination failure: session_lifecycle.py is designated the single authority for session-end cleanup. The hook_events.py SessionEnd handler correctly calls session_lifecycle.handle_session_end(window_id) — but then performs additional cleanup directly alongside it:

session_lifecycle.handle_session_end(window_id)   # designated authority
session_manager.clear_window_session(window_id)   # also done directly
clear_subagents(window_id)                        # also done directly

Cleanup is split between the authority module and the caller. Anyone adding new per-session state cleared on SessionEnd has two sites to update — miss either and state leaks.

More broadly, claude_task_state has 6 independent write paths with no coordination protocol: session_lifecycle (clear_window), transcript_reader (set_window_tasks, mark_task_completed), hook_events (add/remove/clear_subagents), plus read access from window_tick, tool_batch, and status_bubble.

Coupling: HIGH strength + HIGH distance (monitoring layer ↔ display/handler layer) + HIGH volatility → UNBALANCED. Any schema change requires auditing 6 callers across 2 layers.

Recommendation: Consolidate all write access in session_lifecycle.py. Have hook_events.py delegate fully — remove the parallel cleanup block alongside the handle_session_end() call. Give display modules a read-only interface via get_claude_task_snapshot().

Issue 3 — hook_events.py Crosses the Hook→Polling Boundary [High]

Files: handlers/hook_events.py, handlers/periodic_tasks.py

# hook_events.py:180-182
from .periodic_tasks import run_broker_cycle
await run_broker_cycle(bot, idle_windows=frozenset({event.window_key}))

9 of hook_events.py's imports are inside function bodies. The same message_queue import appears in 4 separate functions — hidden fan-out invisible to static analysis.

Coupling: HIGH strength (cross-subsystem direct call) + HIGH volatility → UNBALANCED.

Recommendation: Replace the direct run_broker_cycle call with a registered callback. Consolidate deferred message_queue imports to top-level.

Issue 4 — status_bubble.py Queries Polling State Directly [Medium]

Files: handlers/status_bubble.py, handlers/polling_strategies.py

from .polling_strategies import terminal_screen_buffer
rc_active=terminal_screen_buffer.is_rc_active(window_id)

Display logic (status_bubble) depends on polling state (polling_strategies) for a single boolean. Low volatility makes it tolerable today; architecturally surprising.

Recommendation: Pass rc_active: bool as a parameter to build_status_keyboard(). One-line fix.

Issue 5 — Shell Feature Has Runtime Circular Dependency [Medium]

Files: handlers/shell_capture.py, handlers/shell_commands.py

shell_capture._maybe_suggest_fix() calls shell_commands.show_command_approval() via a deferred runtime import. Additionally, shell_capture.py bypasses tmux_manager with a direct asyncio.create_subprocess_exec("tmux", ...) call.

Recommendation: Introduce a CommandApprovalCallback protocol. Route the capture-pane call through tmux_manager.

Summary Matrix

Recommended Priorities

1. claude_task_state write discipline — designate session_lifecycle.py as the single write authority; remove the hook_events → claude_task_state direct mutation path. Highest-risk shared-state pattern: volatile schema + 6 callers + violated authority claim.
2. hook_events.py boundary crossing — replace direct run_broker_cycle call with a callback. Consolidate 4× deferred message_queue imports to top-level. Hidden runtime dependencies are the most expensive pattern for AI context loading.
3. session.py interface narrowing — enforce view_window() for reads and explicit setters for writes. The 32-file fan-out is a symptom; narrowing each handler's dependency to the methods it actually uses is the fix.
4. status_bubble → polling_strategies severance — pass rc_active: bool as a parameter to build_status_keyboard(). One-line fix, zero risk.
5. Shell circular dependency — introduce CommandApprovalCallback protocol; route capture-pane through tmux_manager.