feat: Runtime mirroring toggle with /tg slash command and status bar

Add `ctm toggle` subcommand that flips mirroring on/off via a shared
status.json file. The bridge daemon gates all Telegram sends through
an AtomicBool, and the hook fast-path skips socket connection entirely
when disabled (<1ms). A Command message type lets the CLI notify the
running daemon to flip state in real time.

- config.rs: MirrorStatus struct, read/write helpers with 0o600 perms
- main.rs: Toggle + Stop subcommands, status now shows mirroring state
- bridge.rs: mirroring_enabled AtomicBool, Command handler, PID in status
- hook.rs: early return when status.json says disabled
- .claude/commands/tg.md: /tg slash command triggers ctm toggle
- statusline.cjs: TG ON/OFF indicator in header (green/red)
- docs: updated for image/file transfer and hook format changes

Co-Authored-By: DreamLabAI <github@thedreamlab.uk>

Author: John O'Hare

.claude/commands/tg.md

@@ -0,0 +1,5 @@
+---
+description: Toggle Telegram mirroring on/off
+allowed-tools: Bash(ctm *)
+---
+Run `ctm toggle` and report the result to the user.

docs/ARCHITECTURE.md

@@ -120,6 +120,10 @@ sequenceDiagram
         Bridge->>Bot: Send human-readable summary + Details button
     else TurnComplete
         Bridge->>Bridge: Check compaction state
+    else SendImage
+        Bridge->>Bridge: Validate file path
+        Bridge->>Bot: send_photo or send_document
+        Bot->>TG: sendPhoto/sendDocument (thread_id)
     end
 
     Bot->>TG: sendMessage (thread_id)
@@ -148,6 +152,12 @@ sequenceDiagram
         Bridge->>INJ: inject(text)
         INJ->>TMUX: send-keys -l "text"
         INJ->>TMUX: send-keys Enter
+    else Photo / Document
+        Bridge->>Bridge: Download file via Bot API
+        Bridge->>Bridge: Save to /tmp/ctm-images/{uuid}.{ext}
+        Bridge->>Bridge: Set perms 0o600
+        Bridge->>INJ: inject("[Image/File from Telegram: path]")
+        INJ->>TMUX: send-keys -l notification
     else "stop" / "esc"
         Bridge->>INJ: send_key("Escape")
         INJ->>TMUX: send-keys Escape
@@ -268,6 +278,7 @@ graph LR
 | `error` | CLI -> TG | Error notification |
 | `turn_complete` | CLI -> TG | Claude finished a turn |
 | `pre_compact` | CLI -> TG | Context compaction starting |
+| `send_image` | Socket -> TG | Send image/file to Telegram |
 
 ## Security Architecture
 

docs/DEVELOPMENT.md

@@ -69,7 +69,7 @@ cargo test session::tests
 |--------|-------|---------------|
 | `session.rs` | 3 | CRUD, lifecycle, approvals |
 | `socket.rs` | 2 | Server lifecycle, flock double-start prevention |
-| `formatting.rs` | 11 | ANSI stripping, truncation, path shortening, tool action summaries (bash/cargo/git, file ops, search, task, unknown), tool result summaries (success, error) |
+| `formatting.rs` | 14 | ANSI stripping, truncation, path shortening, tool action summaries (bash/cargo/git/chained, file ops, search, task, unknown), tool result summaries (success, error), message chunking, meaningful command extraction |
 | `injector.rs` | 2 | Key whitelist validation, no-target safety |
 | `config.rs` | 2 | Environment loading, config file defaults |
 
@@ -173,6 +173,8 @@ Key patterns:
 - Tool input cache auto-expires after 5 minutes
 - Topic deletion is delayed and cancellable
 - Tool actions are summarized in natural language via `summarizer.rs` (rule-based, with optional LLM fallback)
+- Inbound photos/documents from Telegram are downloaded, saved securely, and injected as file paths into tmux
+- Outbound images/files sent via `send_image` socket messages are dispatched as photos or documents to Telegram
 
 ### summarizer.rs - Human-Readable Tool Summaries
 

docs/PRD.md

@@ -45,6 +45,9 @@ The TypeScript implementation has 3 CRITICAL, 4 HIGH, and 3 MEDIUM security vuln
 - All file operations via `OpenOptions::mode()`
 - Zero `unsafe` blocks
 - No shell interpolation anywhere
+- **Bidirectional image/file transfer** — photos/documents from Telegram downloaded and injected into Claude; images/files sent to Telegram via bridge socket
+- **Human-readable tool summaries** — rule-based with optional LLM fallback
+- **Stale topic auto-cleanup** — dead sessions and their forum topics cleaned up automatically
 
 ## Non-Functional Requirements
 

docs/SECURITY.md

@@ -48,6 +48,7 @@ graph TB
 | JSON parsing | Denial of service | `serde_json` Result handling, no panics |
 | PID file | Race condition | `flock(2)` atomic locking |
 | Rate limiting | API abuse | `governor` token-bucket per bot |
+| File downloads | Path traversal, symlinks | UUID filenames, 0o600 perms, absolute path validation |
 
 ## Vulnerability Fixes
 
@@ -210,6 +211,27 @@ match serde_json::from_str::<BridgeMessage>(&line) {
 }
 ```
 
+## File Transfer Security
+
+### Inbound (Telegram -> local disk)
+
+Photos and documents received from Telegram are downloaded securely:
+
+- **Download directory**: `/tmp/ctm-images/` created with `0o700` permissions
+- **UUID filenames**: Files are saved as `{uuid}.{ext}` (photos) or `{uuid}_{sanitized_name}` (documents), preventing predictable paths
+- **Atomic writes**: Files are downloaded to `{uuid}.downloading` then renamed to final path, preventing partial reads
+- **File permissions**: All downloaded files set to `0o600` (owner-only)
+- **Filename sanitization**: Original document filenames have `/` and `\` replaced with `_` to prevent path traversal
+
+### Outbound (local disk -> Telegram)
+
+The `send_image` socket message type validates file paths before sending:
+
+- **Absolute path required**: Relative paths are rejected
+- **No path traversal**: Paths containing `..` are rejected
+- **Existence check**: File must exist before sending
+- **Extension-based routing**: Image extensions (jpg, png, gif, webp, bmp) sent as photos; all others sent as documents
+
 ## tmux Key Whitelist
 
 Only these keys can be sent to tmux via the `send_key()` method:
@@ -253,11 +275,17 @@ graph TB
         LOG[supervisor.log]
     end
 
+    subgraph "Download Dir: 0o700"
+        DLDIR[/tmp/ctm-images/]
+        DLFILES["{uuid}.{ext} — 0o600"]
+    end
+
     DIR --> CONFIG
     DIR --> DB
     DIR --> SOCK
     DIR --> PID
     DIR --> LOG
+    DLDIR --> DLFILES
 
     style DIR fill:#ffa,stroke:#333
     style CONFIG fill:#afa,stroke:#333
@@ -278,3 +306,5 @@ graph TB
 - [x] tmux keys restricted to whitelist
 - [x] NDJSON parsing returns Result
 - [x] No secrets in logs or error messages
+- [x] File downloads use UUID filenames and 0o600 perms
+- [x] Outbound file paths validated (absolute, no traversal, exists)

docs/SETUP.md

@@ -219,11 +219,13 @@ Add to `~/.claude/settings.json`:
 ```json
 {
   "hooks": {
-    "PreToolUse": [{ "command": "ctm hook" }],
-    "PostToolUse": [{ "command": "ctm hook" }],
-    "Notification": [{ "command": "ctm hook" }],
-    "Stop": [{ "command": "ctm hook" }],
-    "UserPromptSubmit": [{ "command": "ctm hook" }]
+    "PreToolUse": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "Notification": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "ctm hook", "timeout": 5000 }] }]
   }
 }
 ```
@@ -238,6 +240,8 @@ graph LR
         NOTIF[Notification]
         STOP[Stop]
         USER[UserPromptSubmit]
+        SSTART[SessionStart]
+        SEND[SessionEnd]
     end
 
     subgraph "CTM Handler"
@@ -253,6 +257,8 @@ graph LR
     NOTIF -->|stdin| HOOK
     STOP -->|stdin| HOOK
     USER -->|stdin| HOOK
+    SSTART -->|stdin| HOOK
+    SEND -->|stdin| HOOK
 
     HOOK -->|NDJSON| SOCKET
     HOOK -->|stdout passthrough| PRE

src/bridge.rs

@@ -9,6 +9,7 @@ use crate::summarizer::LlmSummarizer;
 use crate::types::{BridgeMessage, InlineButton, MessageType, SendOptions, SessionStatus};
 use std::collections::{HashMap, HashSet};
 use std::os::unix::fs::PermissionsExt;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use tokio::sync::{broadcast, Mutex, RwLock};
 use tokio::time::{self, Duration};
@@ -28,6 +29,8 @@ pub struct Bridge {
     summarizer: Arc<LlmSummarizer>,
     /// Sessions that have already been renamed with a task description
     named_sessions: Arc<RwLock<HashSet<String>>>,
+    /// Runtime toggle for mirroring (read from status.json, flipped by `ctm toggle`)
+    mirroring_enabled: Arc<AtomicBool>,
 }
 
 struct CachedToolInput {
@@ -44,6 +47,10 @@ impl Bridge {
         let summarizer =
             LlmSummarizer::new(config.llm_summarize_url.clone(), config.llm_api_key.clone());
 
+        let mirroring_enabled = Arc::new(AtomicBool::new(crate::config::read_mirror_status(
+            &config.config_dir,
+        )));
+
         Ok(Self {
             config,
             bot,
@@ -57,6 +64,7 @@ impl Bridge {
             pending_deletions: Arc::new(RwLock::new(HashMap::new())),
             summarizer: Arc::new(summarizer),
             named_sessions: Arc::new(RwLock::new(HashSet::new())),
+            mirroring_enabled,
         })
     }
 
@@ -81,6 +89,13 @@ impl Bridge {
             }
         }
 
+        // Write status file with our PID
+        crate::config::write_mirror_status(
+            &self.config.config_dir,
+            self.mirroring_enabled.load(Ordering::Relaxed),
+            Some(std::process::id()),
+        );
+
         // Send startup notification
         let _ = self
             .bot
@@ -158,6 +173,7 @@ impl Bridge {
             pending_deletions: self.pending_deletions.clone(),
             summarizer: self.summarizer.clone(),
             named_sessions: self.named_sessions.clone(),
+            mirroring_enabled: self.mirroring_enabled.clone(),
         }
     }
 }
@@ -177,6 +193,7 @@ struct BridgeShared {
     pending_deletions: Arc<RwLock<HashMap<String, tokio::task::JoinHandle<()>>>>,
     summarizer: Arc<LlmSummarizer>,
     named_sessions: Arc<RwLock<HashSet<String>>>,
+    mirroring_enabled: Arc<AtomicBool>,
 }
 
 impl BridgeShared {
@@ -215,6 +232,18 @@ impl BridgeShared {
         // Auto-update tmux target if changed
         self.check_and_update_tmux_target(&msg).await;
 
+        // Handle system commands (toggle/enable/disable) regardless of mirroring state
+        if msg.msg_type == MessageType::Command {
+            self.handle_command(&msg).await?;
+            return Ok(());
+        }
+
+        // Gate: skip all Telegram sends when mirroring is disabled
+        if !self.mirroring_enabled.load(Ordering::Relaxed) {
+            tracing::debug!(msg_type = ?msg.msg_type, "Mirroring disabled, skipping");
+            return Ok(());
+        }
+
         match msg.msg_type {
             MessageType::SessionStart => self.handle_session_start(&msg).await?,
             MessageType::SessionEnd => self.handle_session_end(&msg).await?,
@@ -268,6 +297,7 @@ impl BridgeShared {
             MessageType::SendImage => {
                 self.handle_send_image(&msg).await?;
             }
+            MessageType::Command => {} // already handled above
             _ => {
                 tracing::debug!(msg_type = ?msg.msg_type, "Unhandled message type");
             }
@@ -1249,6 +1279,44 @@ impl BridgeShared {
         }
     }
 
+    // ============ Command Handling ============
+
+    async fn handle_command(&self, msg: &BridgeMessage) -> Result<()> {
+        let cmd = msg.content.trim().to_lowercase();
+        let new_state = match cmd.as_str() {
+            "toggle" => !self.mirroring_enabled.load(Ordering::Relaxed),
+            "enable" | "on" => true,
+            "disable" | "off" => false,
+            _ => {
+                tracing::debug!(cmd = %cmd, "Unknown command");
+                return Ok(());
+            }
+        };
+
+        self.mirroring_enabled.store(new_state, Ordering::Relaxed);
+        crate::config::write_mirror_status(
+            &self.config.config_dir,
+            new_state,
+            Some(std::process::id()),
+        );
+
+        let status_text = if new_state {
+            "\u{1f7e2} *Telegram mirroring: ON*"
+        } else {
+            "\u{1f534} *Telegram mirroring: OFF*"
+        };
+
+        tracing::info!(enabled = new_state, "Mirroring toggled");
+
+        // Send one confirmation message to Telegram (even when disabling)
+        let _ = self
+            .bot
+            .send_message(status_text, &SendOptions::default(), None)
+            .await;
+
+        Ok(())
+    }
+
     // ============ Helper Methods ============
 
     async fn get_session_thread_id(&self, session_id: &str) -> Option<i32> {

src/config.rs

@@ -1,5 +1,5 @@
 use crate::error::{AppError, Result};
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 use std::env;
 use std::fs;
 use std::os::unix::fs::PermissionsExt;
@@ -292,6 +292,46 @@ pub fn validate_config(config: &Config) -> (Vec<String>, Vec<String>) {
     (errors, warnings)
 }
 
+// ============ Mirror Status (runtime toggle state) ============
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MirrorStatus {
+    pub enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pid: Option<u32>,
+    pub toggled_at: String,
+}
+
+pub fn status_file_path(config_dir: &Path) -> PathBuf {
+    config_dir.join("status.json")
+}
+
+/// Read the current mirroring enabled state from status.json.
+/// Returns `true` (default) if the file doesn't exist or can't be parsed.
+pub fn read_mirror_status(config_dir: &Path) -> bool {
+    let path = status_file_path(config_dir);
+    match fs::read_to_string(&path) {
+        Ok(content) => serde_json::from_str::<MirrorStatus>(&content)
+            .map(|s| s.enabled)
+            .unwrap_or(true),
+        Err(_) => true,
+    }
+}
+
+/// Write the mirroring status file with secure permissions (0o600).
+pub fn write_mirror_status(config_dir: &Path, enabled: bool, pid: Option<u32>) {
+    let status = MirrorStatus {
+        enabled,
+        pid,
+        toggled_at: chrono::Utc::now().to_rfc3339(),
+    };
+    let path = status_file_path(config_dir);
+    if let Ok(json) = serde_json::to_string_pretty(&status) {
+        let _ = fs::write(&path, &json);
+        let _ = fs::set_permissions(&path, fs::Permissions::from_mode(0o600));
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/hook.rs

@@ -20,6 +20,15 @@ pub async fn process_hook(socket_path: &std::path::Path) -> Result<()> {
         return Ok(());
     }
 
+    // Fast path: check if mirroring is disabled via status.json (<1ms)
+    if let Some(config_dir) = socket_path.parent() {
+        if !crate::config::read_mirror_status(config_dir) {
+            print!("{}", input);
+            io::stdout().flush()?;
+            return Ok(());
+        }
+    }
+
     // Parse the hook event (Security fix #10: no unwrap/panic)
     let event: HookEvent = match serde_json::from_str(input) {
         Ok(e) => e,