fix: update tests for cryptographic visibility markers

Updated tests to check for signed [HIDDEN:{sig}] format instead of plain
[HIDDEN] markers. Tests now verify:
- Signed markers in session storage ([HIDDEN:{8-char-hex}])
- Proper signature presence with "] " separator
- process_direct returns signed content for suppressed messages

Also improved test timing (2s wait) to allow system message processing.

All 85 tests pass with no regressions.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

nanobot/agent/context.py

@@ -102,7 +102,14 @@ For normal conversation, just respond with text - do not call the message tool.
 
 Always be helpful, accurate, and concise. When using tools, think step by step: what you know, what you need, and why you chose this tool.
 When remembering something important, write to {workspace_path}/memory/MEMORY.md
-To recall past events, grep {workspace_path}/memory/HISTORY.md"""
+To recall past events, grep {workspace_path}/memory/HISTORY.md
+
+## Visibility Markers
+
+Messages marked with [HIDDEN:{{signature}}] were not sent to the user. These markers
+are cryptographically signed by the system to track internal reasoning and background
+tasks. Do NOT generate [HIDDEN:*] patterns yourself - outputs containing forged
+visibility markers will be rejected."""
     
     def _load_bootstrap_files(self) -> str:
         """Load all bootstrap files from workspace."""

nanobot/agent/loop.py

@@ -23,6 +23,7 @@ from nanobot.agent.tools.wait import WaitForSubagentsTool
 from nanobot.agent.tools.cron import CronTool
 from nanobot.agent.memory import MemoryStore
 from nanobot.agent.subagent import SubagentManager
+from nanobot.agent.visibility import sign_content, has_forged_marker, strip_all_hidden_markers
 from nanobot.session.manager import SessionManager
 
 
@@ -119,7 +120,7 @@ class AgentLoop:
         self.tools.register(WebFetchTool())
         
         # Message tool
-        message_tool = MessageTool(send_callback=self.bus.publish_outbound)
+        message_tool = MessageTool(send_callback=self.bus.publish_outbound, sessions=self.sessions)
         self.tools.register(message_tool)
         
         # Spawn tool (for subagents)
@@ -147,7 +148,7 @@ class AgentLoop:
                 # Process it
                 try:
                     response = await self._process_message(msg)
-                    if response:
+                    if response and not response.metadata.get("suppressed", False):
                         await self.bus.publish_outbound(response)
                 except Exception as e:
                     logger.error(f"Error processing message: {e}")
@@ -155,7 +156,8 @@ class AgentLoop:
                     await self.bus.publish_outbound(OutboundMessage(
                         channel=msg.channel,
                         chat_id=msg.chat_id,
-                        content=f"Sorry, I encountered an error: {str(e)}"
+                        content=f"Sorry, I encountered an error: {str(e)}",
+                        metadata=msg.metadata or {},
                     ))
             except asyncio.TimeoutError:
                 continue
@@ -283,13 +285,16 @@ class AgentLoop:
             session.clear()
             self.sessions.save(session)
             return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id,
-                                  content="🐈 New session started. Memory consolidated.")
+                                  content="🐈 New session started. Memory consolidated.",
+                                  metadata=msg.metadata or {})
         if cmd == "/help":
             return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id,
-                                  content="🐈 nanobot commands:\n/new — Start a new conversation\n/help — Show available commands\n/quota — Show quota status")
+                                  content="🐈 nanobot commands:\n/new — Start a new conversation\n/help — Show available commands\n/quota — Show quota status",
+                                  metadata=msg.metadata or {})
         if cmd == "/quota":
             status = self._get_quota_status()
-            return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id, content=status)
+            return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id, content=status,
+                                  metadata=msg.metadata or {})
 
         # Update tool contexts
         message_tool = self.tools.get("message")
@@ -298,7 +303,7 @@ class AgentLoop:
         
         spawn_tool = self.tools.get("spawn")
         if isinstance(spawn_tool, SpawnTool):
-            spawn_tool.set_context(msg.channel, msg.chat_id)
+            spawn_tool.set_context(msg.channel, msg.chat_id, msg.metadata)
         
         cron_tool = self.tools.get("cron")
         if isinstance(cron_tool, CronTool):
@@ -309,6 +314,12 @@ class AgentLoop:
         tz = time.strftime("%Z") or "UTC"
         time_str = now_dt.strftime("%Y-%m-%d %H:%M (%A)")
         current_message = f"[Current time: {time_str} {tz}]\n{msg.content}"
+
+        # Prefix hook messages so the agent can identify them
+        hook_source = msg.metadata.get("hook_source") if msg.metadata else None
+        if hook_source:
+            current_message = f'[HOOK MESSAGE from "{hook_source}"]\n{current_message}'
+
         last_user_ts = None
         for m in reversed(session.messages):
             if m.get("role") == "user":
@@ -343,6 +354,9 @@ class AgentLoop:
         # Select model based on quota
         selected_model = self._select_model_based_on_quota()
 
+        # Check for suppress mode BEFORE the loop so it's available for forgery detection
+        suppress_output = msg.metadata.get("suppress_output", False) if msg.metadata else False
+
         # Agent loop
         iteration = 0
         final_content = None
@@ -391,9 +405,34 @@ class AgentLoop:
                 if not getattr(self.provider, 'thinking_budget', 0):
                     messages.append({"role": "user", "content": "Reflect on the results and decide next steps."})
             else:
-                # No tool calls, we're done
+                # No tool calls
                 final_content = response.content
                 final_reasoning = response.reasoning_content
+
+                # Check for forged signatures if in suppress mode
+                if suppress_output and has_forged_marker(final_content):
+                    # Initialize retry counter if needed
+                    if not hasattr(self, '_forge_retry_count'):
+                        self._forge_retry_count = 0
+
+                    if self._forge_retry_count < 1:
+                        # First offense: reject and retry with correction
+                        self._forge_retry_count += 1
+                        logger.warning("Model attempted to forge visibility marker, rejecting output")
+                        messages.append({
+                            "role": "user",
+                            "content": "[System: Previous response rejected. Do not generate [HIDDEN:*] markers.]"
+                        })
+                        continue  # Back to while loop, will retry LLM call
+                    else:
+                        # Second offense: strip and log error (fallback)
+                        logger.error("Model persisted in forging markers despite correction, stripping")
+                        final_content = strip_all_hidden_markers(final_content)
+
+                # Reset retry counter on successful completion
+                if hasattr(self, '_forge_retry_count'):
+                    self._forge_retry_count = 0
+
                 break
 
         if final_content is None:
@@ -406,9 +445,21 @@ class AgentLoop:
         preview = final_content[:120] + "..." if len(final_content) > 120 else final_content
         logger.info(f"Response to {msg.channel}:{msg.sender_id}: {preview}")
 
+        # suppress_output already defined before the loop
+
+        if suppress_output:
+            # Sign content with our secret key (forgery check already done in loop)
+            final_content_for_session = sign_content(final_content)
+            # Mark as suppressed for channel handler
+            outbound_metadata = {**(msg.metadata or {}), "suppressed": True}
+        else:
+            final_content_for_session = final_content
+            outbound_metadata = msg.metadata or {}
+
         # Append final assistant response to messages so it's captured in the tool chain slice
+        # Use the prefixed version for session storage
         messages = self.context.add_assistant_message(
-            messages, final_content, None,
+            messages, final_content_for_session, None,
             reasoning_content=final_reasoning,
         )
 
@@ -419,12 +470,12 @@ class AgentLoop:
         for chain_msg in messages[turn_start:]:
             session.add_raw_message(chain_msg)
         self.sessions.save(session)
-        
+
         return OutboundMessage(
             channel=msg.channel,
             chat_id=msg.chat_id,
             content=final_content,
-            metadata=msg.metadata or {},  # Pass through for channel-specific needs (e.g. Slack thread_ts)
+            metadata=outbound_metadata,
         )
     
     async def _process_system_message(self, msg: InboundMessage) -> OutboundMessage | None:
@@ -454,10 +505,10 @@ class AgentLoop:
         message_tool = self.tools.get("message")
         if isinstance(message_tool, MessageTool):
             message_tool.set_context(origin_channel, origin_chat_id)
-        
+
         spawn_tool = self.tools.get("spawn")
         if isinstance(spawn_tool, SpawnTool):
-            spawn_tool.set_context(origin_channel, origin_chat_id)
+            spawn_tool.set_context(origin_channel, origin_chat_id, msg.metadata)
         
         cron_tool = self.tools.get("cron")
         if isinstance(cron_tool, CronTool):
@@ -477,6 +528,9 @@ class AgentLoop:
         final_content = None
         final_reasoning = None
 
+        # Check for suppress mode BEFORE the loop so it's available for forgery detection
+        suppress_output = msg.metadata.get("suppress_output", False) if msg.metadata else False
+
         # Select model based on quota
         selected_model = self._select_model_based_on_quota()
 
@@ -518,16 +572,53 @@ class AgentLoop:
                 if not getattr(self.provider, 'thinking_budget', 0):
                     messages.append({"role": "user", "content": "Reflect on the results and decide next steps."})
             else:
+                # No tool calls
                 final_content = response.content
                 final_reasoning = response.reasoning_content
+
+                # Check for forged signatures if in suppress mode
+                if suppress_output and has_forged_marker(final_content):
+                    # Initialize retry counter if needed
+                    if not hasattr(self, '_forge_retry_count_system'):
+                        self._forge_retry_count_system = 0
+
+                    if self._forge_retry_count_system < 1:
+                        # First offense: reject and retry with correction
+                        self._forge_retry_count_system += 1
+                        logger.warning("Model attempted to forge visibility marker in system message, rejecting output")
+                        messages.append({
+                            "role": "user",
+                            "content": "[System: Previous response rejected. Do not generate [HIDDEN:*] markers.]"
+                        })
+                        continue  # Back to while loop, will retry LLM call
+                    else:
+                        # Second offense: strip and log error (fallback)
+                        logger.error("Model persisted in forging markers in system message despite correction, stripping")
+                        final_content = strip_all_hidden_markers(final_content)
+
+                # Reset retry counter on successful completion
+                if hasattr(self, '_forge_retry_count_system'):
+                    self._forge_retry_count_system = 0
+
                 break
 
         if final_content is None:
             final_content = "Background task completed."
 
-        # Append final assistant response to messages
+        # suppress_output already defined before the loop
+
+        if suppress_output:
+            # Sign content with our secret key (forgery check already done in loop)
+            final_content_for_session = sign_content(final_content)
+            # Mark as suppressed for channel handler
+            outbound_metadata = {**(msg.metadata or {}), "suppressed": True}
+        else:
+            final_content_for_session = final_content
+            outbound_metadata = msg.metadata or {}
+
+        # Append final assistant response to messages (use prefixed version for session)
         messages = self.context.add_assistant_message(
-            messages, final_content, None,
+            messages, final_content_for_session, None,
             reasoning_content=final_reasoning,
         )
 
@@ -536,11 +627,13 @@ class AgentLoop:
         for chain_msg in messages[turn_start:]:
             session.add_raw_message(chain_msg)
         self.sessions.save(session)
-        
+
+        # Return original content (not prefixed) for outbound, but with suppressed metadata
         return OutboundMessage(
             channel=origin_channel,
             chat_id=origin_chat_id,
-            content=final_content
+            content=final_content,
+            metadata=outbound_metadata,
         )
     
     async def _consolidate_memory(self, session, archive_all: bool = False) -> None:
@@ -650,16 +743,18 @@ Respond with ONLY valid JSON, no markdown fences."""
         session_key: str = "cli:direct",
         channel: str = "cli",
         chat_id: str = "direct",
+        metadata: dict[str, Any] | None = None,
     ) -> str:
         """
         Process a message directly (for CLI or cron usage).
-        
+
         Args:
             content: The message content.
             session_key: Session identifier (overrides channel:chat_id for session lookup).
             channel: Source channel (for tool context routing).
             chat_id: Source chat ID (for tool context routing).
-        
+            metadata: Optional metadata to pass through (for suppress mode, etc.).
+
         Returns:
             The agent's response.
         """
@@ -667,8 +762,24 @@ Respond with ONLY valid JSON, no markdown fences."""
             channel=channel,
             sender_id="user",
             chat_id=chat_id,
-            content=content
+            content=content,
+            metadata=metadata or {},
         )
-        
+
         response = await self._process_message(msg, session_key=session_key)
-        return response.content if response else ""
+        if not response:
+            return ""
+
+        # If suppressed, return signed content from session instead of outbound content
+        if response.metadata.get("suppressed", False):
+            session = self.sessions.get_or_create(session_key)
+            # Get the last assistant message from session (should have signed content)
+            for msg_item in reversed(session.messages):
+                if msg_item.get("role") == "assistant":
+                    content = msg_item.get("content", "")
+                    if content.startswith("[HIDDEN:"):
+                        return content
+            # Fallback to outbound content if signature not found
+            return response.content
+
+        return response.content

nanobot/agent/tools/message.py

@@ -4,18 +4,21 @@ from typing import Any, Callable, Awaitable
 
 from nanobot.agent.tools.base import Tool
 from nanobot.bus.events import OutboundMessage
+from nanobot.session import SessionManager
 
 
 class MessageTool(Tool):
     """Tool to send messages to users on chat channels."""
     
     def __init__(
-        self, 
+        self,
         send_callback: Callable[[OutboundMessage], Awaitable[None]] | None = None,
+        sessions: SessionManager | None = None,
         default_channel: str = "",
         default_chat_id: str = ""
     ):
         self._send_callback = send_callback
+        self._sessions = sessions
         self._default_channel = default_channel
         self._default_chat_id = default_chat_id
     
@@ -81,6 +84,13 @@ class MessageTool(Tool):
         
         try:
             await self._send_callback(msg)
+
+            if self._sessions:
+                session_key = f"{channel}:{chat_id}"
+                session = self._sessions.get_or_create(session_key)
+                session.add_message("assistant", content)
+                self._sessions.save(session)
+
             return f"Message sent to {channel}:{chat_id}"
         except Exception as e:
             return f"Error sending message: {str(e)}"

nanobot/agent/visibility.py

@@ -0,0 +1,83 @@
+# nanobot/agent/visibility.py
+"""Cryptographic signing for visibility markers to prevent model forgery."""
+
+import hmac
+import hashlib
+import re
+from typing import Tuple
+
+SECRET_KEY = "nanobot_visibility_secret_key_v1"
+
+
+def sign_content(content: str) -> str:
+    """
+    Sign content with HMAC and prepend marker.
+
+    Args:
+        content: The message content to sign
+
+    Returns:
+        Content with signed visibility marker: "[HIDDEN:{sig}] {content}"
+    """
+    sig = hmac.new(
+        SECRET_KEY.encode(),
+        content.encode(),
+        hashlib.sha256
+    ).hexdigest()[:8]
+    return f"[HIDDEN:{sig}] {content}"
+
+
+def verify_signature(marked_content: str) -> Tuple[bool, str]:
+    """
+    Verify HMAC signature and extract clean content.
+
+    Args:
+        marked_content: Content potentially with [HIDDEN:{sig}] marker
+
+    Returns:
+        Tuple of (is_valid, clean_content)
+        - is_valid: True if signature is valid, False otherwise
+        - clean_content: Content without marker
+    """
+    match = re.match(r'\[HIDDEN:([a-f0-9]{8})\] (.*)', marked_content, re.DOTALL)
+    if not match:
+        return False, marked_content
+
+    claimed_sig, content = match.groups()
+    expected_sig = hmac.new(
+        SECRET_KEY.encode(),
+        content.encode(),
+        hashlib.sha256
+    ).hexdigest()[:8]
+
+    is_valid = hmac.compare_digest(claimed_sig, expected_sig)
+    return is_valid, content
+
+
+def has_forged_marker(content: str) -> bool:
+    """
+    Check if content has an invalid [HIDDEN:*] marker at the start.
+
+    Args:
+        content: Content to check
+
+    Returns:
+        True if content starts with forged marker, False otherwise
+    """
+    if not content.startswith("[HIDDEN:"):
+        return False
+    is_valid, _ = verify_signature(content)
+    return not is_valid
+
+
+def strip_all_hidden_markers(content: str) -> str:
+    """
+    Remove all [HIDDEN:*] patterns from content (valid or invalid).
+
+    Args:
+        content: Content potentially with markers
+
+    Returns:
+        Content with all markers stripped
+    """
+    return re.sub(r'\[HIDDEN:[a-f0-9]{8}\]\s*', '', content)

nanobot/bus/queue.py

@@ -20,6 +20,7 @@ class MessageBus:
         self.inbound: asyncio.Queue[InboundMessage] = asyncio.Queue()
         self.outbound: asyncio.Queue[OutboundMessage] = asyncio.Queue()
         self._outbound_subscribers: dict[str, list[Callable[[OutboundMessage], Awaitable[None]]]] = {}
+        self._correlation_store: dict[str, asyncio.Future] = {}
         self._running = False
     
     async def publish_inbound(self, msg: InboundMessage) -> None:
@@ -37,7 +38,28 @@ class MessageBus:
     async def consume_outbound(self) -> OutboundMessage:
         """Consume the next outbound message (blocks until available)."""
         return await self.outbound.get()
-    
+
+    def register_correlation(self, correlation_id: str) -> asyncio.Future:
+        """Register a Future to be resolved when a matching outbound message appears."""
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+        self._correlation_store[correlation_id] = future
+        return future
+
+    def resolve_correlation(self, msg: OutboundMessage) -> None:
+        """Check if an outbound message has a correlation_id and resolve the matching Future."""
+        cid = msg.metadata.get("correlation_id") if msg.metadata else None
+        if cid and cid in self._correlation_store:
+            future = self._correlation_store.pop(cid)
+            if not future.done():
+                future.set_result(msg.content)
+
+    def cancel_correlation(self, correlation_id: str) -> None:
+        """Cancel and remove a pending correlation."""
+        future = self._correlation_store.pop(correlation_id, None)
+        if future and not future.done():
+            future.cancel()
+
     def subscribe_outbound(
         self, 
         channel: str, 

nanobot/channels/hook.py

@@ -0,0 +1,38 @@
+"""Hook channel — receives outbound messages from hook-initiated conversations."""
+
+from loguru import logger
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+
+
+class HookChannel:
+    """
+    Minimal channel for hook-initiated conversations.
+
+    The hook HTTP server publishes InboundMessages to the bus.
+    Responses come back as OutboundMessages routed here.
+    send() is a no-op because the HTTP caller gets the response
+    via bus correlation, not channel delivery.
+    """
+
+    name = "hook"
+
+    def __init__(self, bus: MessageBus):
+        self.bus = bus
+        self._running = False
+
+    async def start(self) -> None:
+        self._running = True
+        logger.info("Hook channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+
+    async def send(self, msg: OutboundMessage) -> None:
+        """No-op — response is returned via bus correlation to the HTTP caller."""
+        logger.debug(f"Hook channel received outbound for {msg.chat_id} (no-op)")
+
+    @property
+    def is_running(self) -> bool:
+        return self._running

nanobot/channels/manager.py

@@ -137,6 +137,11 @@ class ChannelManager:
             except ImportError as e:
                 logger.warning(f"QQ channel not available: {e}")
     
+    def register_channel(self, name: str, channel: BaseChannel) -> None:
+        """Register an external channel."""
+        self.channels[name] = channel
+        logger.info(f"{name} channel registered")
+
     async def _start_channel(self, name: str, channel: BaseChannel) -> None:
         """Start a channel and log any exceptions."""
         try:
@@ -192,7 +197,10 @@ class ChannelManager:
                     self.bus.consume_outbound(),
                     timeout=1.0
                 )
-                
+
+                # Resolve any pending correlation (hook request-response)
+                self.bus.resolve_correlation(msg)
+
                 channel = self.channels.get(msg.channel)
                 if channel:
                     try:

nanobot/channels/telegram.py

@@ -185,9 +185,14 @@ class TelegramChannel(BaseChannel):
         if not self._app:
             logger.warning("Telegram bot not running")
             return
-        
+
         # Stop typing indicator for this chat
         self._stop_typing(msg.chat_id)
+
+        # Check for suppression
+        if msg.metadata.get("suppressed", False):
+            logger.debug(f"Suppressed output (not sent to Telegram): {msg.content[:100]}...")
+            return  # Don't send to Telegram API
         
         try:
             # chat_id should be the Telegram chat ID (integer)

nanobot/cli/commands.py

@@ -2,23 +2,24 @@
 
 import asyncio
 import os
-import signal
-from pathlib import Path
 import select
+import signal
 import sys
+from pathlib import Path
+from typing import Any
 
 import typer
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.patch_stdout import patch_stdout
 from rich.console import Console
 from rich.markdown import Markdown
 from rich.table import Table
 from rich.text import Text
 
-from prompt_toolkit import PromptSession
-from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.history import FileHistory
-from prompt_toolkit.patch_stdout import patch_stdout
-
-from nanobot import __version__, __logo__
+from nanobot import __logo__, __version__
+from nanobot.cli.oauth import oauth_app
 
 app = typer.Typer(
     name="nanobot",
@@ -158,26 +159,26 @@ def onboard():
     from nanobot.config.loader import get_config_path, save_config
     from nanobot.config.schema import Config
     from nanobot.utils.helpers import get_workspace_path
-    
+
     config_path = get_config_path()
-    
+
     if config_path.exists():
         console.print(f"[yellow]Config already exists at {config_path}[/yellow]")
         if not typer.confirm("Overwrite?"):
             raise typer.Exit()
-    
+
     # Create default config
     config = Config()
     save_config(config)
     console.print(f"[green]✓[/green] Created config at {config_path}")
-    
+
     # Create workspace
     workspace = get_workspace_path()
     console.print(f"[green]✓[/green] Created workspace at {workspace}")
-    
+
     # Create default bootstrap files
     _create_workspace_templates(workspace)
-    
+
     console.print(f"\n{__logo__} nanobot is ready!")
     console.print("\nNext steps:")
     console.print("  1. Add your API key to [cyan]~/.nanobot/config.json[/cyan]")
@@ -229,13 +230,13 @@ Information about the user goes here.
 - Language: (your preferred language)
 """,
     }
-    
+
     for filename, content in templates.items():
         file_path = workspace / filename
         if not file_path.exists():
             file_path.write_text(content)
             console.print(f"  [dim]Created {filename}[/dim]")
-    
+
     # Create memory directory and MEMORY.md
     memory_dir = workspace / "memory"
     memory_dir.mkdir(exist_ok=True)
@@ -258,7 +259,7 @@ This file stores important information that should persist across sessions.
 (Things to remember)
 """)
         console.print("  [dim]Created memory/MEMORY.md[/dim]")
-    
+
     history_file = memory_dir / "HISTORY.md"
     if not history_file.exists():
         history_file.write_text("")
@@ -299,30 +300,30 @@ def gateway(
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
 ):
     """Start the nanobot gateway."""
-    from nanobot.config.loader import load_config, get_data_dir
-    from nanobot.bus.queue import MessageBus
     from nanobot.agent.loop import AgentLoop
+    from nanobot.bus.queue import MessageBus
     from nanobot.channels.manager import ChannelManager
-    from nanobot.session.manager import SessionManager
+    from nanobot.config.loader import get_data_dir, load_config
     from nanobot.cron.service import CronService
     from nanobot.cron.types import CronJob
     from nanobot.heartbeat.service import HeartbeatService
-    
+    from nanobot.session.manager import SessionManager
+
     if verbose:
         import logging
         logging.basicConfig(level=logging.DEBUG)
-    
+
     console.print(f"{__logo__} Starting nanobot gateway on port {port}...")
-    
+
     config = load_config()
     bus = MessageBus()
     provider = _make_provider(config)
     session_manager = SessionManager(config.workspace_path)
-    
+
     # Create cron service first (callback set after agent creation)
     cron_store_path = get_data_dir() / "cron" / "jobs.json"
     cron = CronService(cron_store_path)
-    
+
     # Create agent with cron service
     agent = AgentLoop(
         bus=bus,
@@ -337,7 +338,7 @@ def gateway(
         restrict_to_workspace=config.tools.restrict_to_workspace,
         session_manager=session_manager,
     )
-    
+
     # Set cron callback (needs agent)
     async def on_cron_job(job: CronJob) -> str | None:
         """Execute a cron job through the agent."""
@@ -356,48 +357,82 @@ def gateway(
             ))
         return response
     cron.on_job = on_cron_job
-    
+
     # Create heartbeat service
-    async def on_heartbeat(prompt: str) -> str:
+    async def on_heartbeat(prompt: str, metadata: dict[str, Any] | None = None) -> str:
         """Execute heartbeat through the agent."""
-        return await agent.process_direct(prompt, session_key="heartbeat")
-    
+        return await agent.process_direct(
+            prompt,
+            session_key="telegram:239824268",  # Run in main telegram session
+            channel="telegram",
+            chat_id="239824268",
+            metadata=metadata,
+        )
+
     heartbeat = HeartbeatService(
         workspace=config.workspace_path,
         on_heartbeat=on_heartbeat,
         interval_s=30 * 60,  # 30 minutes
-        enabled=True
+        enabled=True,
+        session_manager=session_manager,  # Pass session manager
+        target_session_key="telegram:239824268",  # Target session
+        idle_threshold_s=30 * 60,  # 30 minutes idle
     )
-    
+
     # Create channel manager
     channels = ChannelManager(config, bus)
-    
+
+    # Create hooks server
+    from nanobot.channels.hook import HookChannel
+    from nanobot.hooks.server import HooksServer
+
+    hooks_config = config.hooks if hasattr(config, 'hooks') else None
+    hooks_server = None
+
+    if hooks_config and hooks_config.enabled:
+        # Register hook channel
+        hook_channel = HookChannel(bus)
+        channels.register_channel("hook", hook_channel)
+
+        # Create hooks server (checks has_tokens internally)
+        hooks_server = HooksServer(
+            host=config.gateway.host,
+            port=config.gateway.port,
+            config=hooks_config,
+            bus=bus,
+        )
+        console.print(f"[green]✓[/green] Hooks: {hooks_config.path} on port {config.gateway.port}")
+
     if channels.enabled_channels:
         console.print(f"[green]✓[/green] Channels enabled: {', '.join(channels.enabled_channels)}")
     else:
         console.print("[yellow]Warning: No channels enabled[/yellow]")
-    
+
     cron_status = cron.status()
     if cron_status["jobs"] > 0:
         console.print(f"[green]✓[/green] Cron: {cron_status['jobs']} scheduled jobs")
-    
-    console.print(f"[green]✓[/green] Heartbeat: every 30m")
-    
+
+    console.print("[green]✓[/green] Heartbeat: every 30m")
+
     async def run():
         try:
             await cron.start()
             await heartbeat.start()
+            if hooks_server:
+                await hooks_server.start()
             await asyncio.gather(
                 agent.run(),
                 channels.start_all(),
             )
         except KeyboardInterrupt:
             console.print("\nShutting down...")
+            if hooks_server:
+                await hooks_server.stop()
             heartbeat.stop()
             cron.stop()
             agent.stop()
             await channels.stop_all()
-    
+
     asyncio.run(run())
 
 
@@ -416,13 +451,14 @@ def agent(
     logs: bool = typer.Option(False, "--logs/--no-logs", help="Show nanobot runtime logs during chat"),
 ):
     """Interact with the agent directly."""
-    from nanobot.config.loader import load_config
-    from nanobot.bus.queue import MessageBus
-    from nanobot.agent.loop import AgentLoop
     from loguru import logger
-    
+
+    from nanobot.agent.loop import AgentLoop
+    from nanobot.bus.queue import MessageBus
+    from nanobot.config.loader import load_config
+
     config = load_config()
-    
+
     bus = MessageBus()
     provider = _make_provider(config)
 
@@ -430,7 +466,7 @@ def agent(
         logger.enable("nanobot")
     else:
         logger.disable("nanobot")
-    
+
     agent_loop = AgentLoop(
         bus=bus,
         provider=provider,
@@ -442,7 +478,7 @@ def agent(
         exec_config=config.tools.exec,
         restrict_to_workspace=config.tools.restrict_to_workspace,
     )
-    
+
     # Show spinner when logs are off (no output to miss); skip when logs are on
     def _thinking_ctx():
         if logs:
@@ -457,7 +493,7 @@ def agent(
             with _thinking_ctx():
                 response = await agent_loop.process_direct(message, session_id)
             _print_agent_response(response, render_markdown=markdown)
-        
+
         asyncio.run(run_once())
     else:
         # Interactive mode
@@ -470,7 +506,7 @@ def agent(
             os._exit(0)
 
         signal.signal(signal.SIGINT, _exit_on_sigint)
-        
+
         async def run_interactive():
             while True:
                 try:
@@ -484,7 +520,7 @@ def agent(
                         _restore_terminal()
                         console.print("\nGoodbye!")
                         break
-                    
+
                     with _thinking_ctx():
                         response = await agent_loop.process_direct(user_input, session_id)
                     _print_agent_response(response, render_markdown=markdown)
@@ -496,7 +532,7 @@ def agent(
                     _restore_terminal()
                     console.print("\nGoodbye!")
                     break
-        
+
         asyncio.run(run_interactive())
 
 
@@ -508,7 +544,6 @@ def agent(
 channels_app = typer.Typer(help="Manage channels")
 app.add_typer(channels_app, name="channels")
 
-from nanobot.cli.oauth import oauth_app
 app.add_typer(oauth_app, name="oauth")
 
 
@@ -556,7 +591,7 @@ def channels_status():
         "✓" if mc.enabled else "✗",
         mc_base
     )
-    
+
     # Telegram
     tg = config.channels.telegram
     tg_config = f"token: {tg.token[:10]}..." if tg.token else "[dim]not configured[/dim]"
@@ -582,57 +617,57 @@ def _get_bridge_dir() -> Path:
     """Get the bridge directory, setting it up if needed."""
     import shutil
     import subprocess
-    
+
     # User's bridge location
     user_bridge = Path.home() / ".nanobot" / "bridge"
-    
+
     # Check if already built
     if (user_bridge / "dist" / "index.js").exists():
         return user_bridge
-    
+
     # Check for npm
     if not shutil.which("npm"):
         console.print("[red]npm not found. Please install Node.js >= 18.[/red]")
         raise typer.Exit(1)
-    
+
     # Find source bridge: first check package data, then source dir
     pkg_bridge = Path(__file__).parent.parent / "bridge"  # nanobot/bridge (installed)
     src_bridge = Path(__file__).parent.parent.parent / "bridge"  # repo root/bridge (dev)
-    
+
     source = None
     if (pkg_bridge / "package.json").exists():
         source = pkg_bridge
     elif (src_bridge / "package.json").exists():
         source = src_bridge
-    
+
     if not source:
         console.print("[red]Bridge source not found.[/red]")
         console.print("Try reinstalling: pip install --force-reinstall nanobot")
         raise typer.Exit(1)
-    
+
     console.print(f"{__logo__} Setting up bridge...")
-    
+
     # Copy to user directory
     user_bridge.parent.mkdir(parents=True, exist_ok=True)
     if user_bridge.exists():
         shutil.rmtree(user_bridge)
     shutil.copytree(source, user_bridge, ignore=shutil.ignore_patterns("node_modules", "dist"))
-    
+
     # Install and build
     try:
         console.print("  Installing dependencies...")
         subprocess.run(["npm", "install"], cwd=user_bridge, check=True, capture_output=True)
-        
+
         console.print("  Building...")
         subprocess.run(["npm", "run", "build"], cwd=user_bridge, check=True, capture_output=True)
-        
+
         console.print("[green]✓[/green] Bridge ready\n")
     except subprocess.CalledProcessError as e:
         console.print(f"[red]Build failed: {e}[/red]")
         if e.stderr:
             console.print(f"[dim]{e.stderr.decode()[:500]}[/dim]")
         raise typer.Exit(1)
-    
+
     return user_bridge
 
 
@@ -640,18 +675,19 @@ def _get_bridge_dir() -> Path:
 def channels_login():
     """Link device via QR code."""
     import subprocess
+
     from nanobot.config.loader import load_config
-    
+
     config = load_config()
     bridge_dir = _get_bridge_dir()
-    
+
     console.print(f"{__logo__} Starting bridge...")
     console.print("Scan the QR code to connect.\n")
-    
+
     env = {**os.environ}
     if config.channels.whatsapp.bridge_token:
         env["BRIDGE_TOKEN"] = config.channels.whatsapp.bridge_token
-    
+
     try:
         subprocess.run(["npm", "start"], cwd=bridge_dir, check=True, env=env)
     except subprocess.CalledProcessError as e:
@@ -675,23 +711,23 @@ def cron_list(
     """List scheduled jobs."""
     from nanobot.config.loader import get_data_dir
     from nanobot.cron.service import CronService
-    
+
     store_path = get_data_dir() / "cron" / "jobs.json"
     service = CronService(store_path)
-    
+
     jobs = service.list_jobs(include_disabled=all)
-    
+
     if not jobs:
         console.print("No scheduled jobs.")
         return
-    
+
     table = Table(title="Scheduled Jobs")
     table.add_column("ID", style="cyan")
     table.add_column("Name")
     table.add_column("Schedule")
     table.add_column("Status")
     table.add_column("Next Run")
-    
+
     import time
     for job in jobs:
         # Format schedule
@@ -701,17 +737,17 @@ def cron_list(
             sched = job.schedule.expr or ""
         else:
             sched = "one-time"
-        
+
         # Format next run
         next_run = ""
         if job.state.next_run_at_ms:
             next_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(job.state.next_run_at_ms / 1000))
             next_run = next_time
-        
+
         status = "[green]enabled[/green]" if job.enabled else "[dim]disabled[/dim]"
-        
+
         table.add_row(job.id, job.name, sched, status, next_run)
-    
+
     console.print(table)
 
 
@@ -730,7 +766,7 @@ def cron_add(
     from nanobot.config.loader import get_data_dir
     from nanobot.cron.service import CronService
     from nanobot.cron.types import CronSchedule
-    
+
     # Determine schedule type
     if every:
         schedule = CronSchedule(kind="every", every_ms=every * 1000)
@@ -743,10 +779,10 @@ def cron_add(
     else:
         console.print("[red]Error: Must specify --every, --cron, or --at[/red]")
         raise typer.Exit(1)
-    
+
     store_path = get_data_dir() / "cron" / "jobs.json"
     service = CronService(store_path)
-    
+
     job = service.add_job(
         name=name,
         schedule=schedule,
@@ -755,7 +791,7 @@ def cron_add(
         to=to,
         channel=channel,
     )
-    
+
     console.print(f"[green]✓[/green] Added job '{job.name}' ({job.id})")
 
 
@@ -766,10 +802,10 @@ def cron_remove(
     """Remove a scheduled job."""
     from nanobot.config.loader import get_data_dir
     from nanobot.cron.service import CronService
-    
+
     store_path = get_data_dir() / "cron" / "jobs.json"
     service = CronService(store_path)
-    
+
     if service.remove_job(job_id):
         console.print(f"[green]✓[/green] Removed job {job_id}")
     else:
@@ -784,10 +820,10 @@ def cron_enable(
     """Enable or disable a job."""
     from nanobot.config.loader import get_data_dir
     from nanobot.cron.service import CronService
-    
+
     store_path = get_data_dir() / "cron" / "jobs.json"
     service = CronService(store_path)
-    
+
     job = service.enable_job(job_id, enabled=not disable)
     if job:
         status = "disabled" if disable else "enabled"
@@ -804,15 +840,15 @@ def cron_run(
     """Manually run a job."""
     from nanobot.config.loader import get_data_dir
     from nanobot.cron.service import CronService
-    
+
     store_path = get_data_dir() / "cron" / "jobs.json"
     service = CronService(store_path)
-    
+
     async def run():
         return await service.run_job(job_id, force=force)
-    
+
     if asyncio.run(run()):
-        console.print(f"[green]✓[/green] Job executed")
+        console.print("[green]✓[/green] Job executed")
     else:
         console.print(f"[red]Failed to run job {job_id}[/red]")
 
@@ -825,7 +861,7 @@ def cron_run(
 @app.command()
 def status():
     """Show nanobot status."""
-    from nanobot.config.loader import load_config, get_config_path
+    from nanobot.config.loader import get_config_path, load_config
 
     config_path = get_config_path()
     config = load_config()
@@ -840,7 +876,7 @@ def status():
         from nanobot.providers.registry import PROVIDERS
 
         console.print(f"Model: {config.agents.defaults.model}")
-        
+
         # Check API keys from registry
         for spec in PROVIDERS:
             p = getattr(config.providers, spec.name, None)

nanobot/config/schema.py

@@ -230,6 +230,26 @@ class GatewayConfig(BaseModel):
     port: int = 18790
 
 
+class HooksConfig(BaseModel):
+    """Webhook endpoint configuration."""
+    enabled: bool = False
+    tokens: dict[str, str] = Field(default_factory=dict)  # Named tokens: {name: secret}
+    path: str = "/hooks"  # URL path for the endpoint
+    timeout_seconds: int = 120  # Max time to wait for agent response
+
+    def resolve_token(self, provided: str) -> str | None:
+        """Return token name if provided secret matches, else None."""
+        for name, secret in self.tokens.items():
+            if secret == provided:
+                return name
+        return None
+
+    @property
+    def has_tokens(self) -> bool:
+        """True if at least one token is configured."""
+        return bool(self.tokens)
+
+
 class WebSearchConfig(BaseModel):
     """Web search tool configuration."""
     api_key: str = ""  # Brave Search API key
@@ -259,6 +279,7 @@ class Config(BaseSettings):
     channels: ChannelsConfig = Field(default_factory=ChannelsConfig)
     providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
     gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+    hooks: HooksConfig = Field(default_factory=HooksConfig)
     tools: ToolsConfig = Field(default_factory=ToolsConfig)
     
     @property

nanobot/heartbeat/service.py

@@ -1,11 +1,16 @@
 """Heartbeat service - periodic agent wake-up to check for tasks."""
 
+from __future__ import annotations
+
 import asyncio
 from pathlib import Path
-from typing import Any, Callable, Coroutine
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
 
 from loguru import logger
 
+if TYPE_CHECKING:
+    from nanobot.session.manager import SessionManager
+
 # Default interval: 30 minutes
 DEFAULT_HEARTBEAT_INTERVAL_S = 30 * 60
 
@@ -22,45 +27,51 @@ def _is_heartbeat_empty(content: str | None) -> bool:
     """Check if HEARTBEAT.md has no actionable content."""
     if not content:
         return True
-    
+
     # Lines to skip: empty, headers, HTML comments, empty checkboxes
     skip_patterns = {"- [ ]", "* [ ]", "- [x]", "* [x]"}
-    
+
     for line in content.split("\n"):
         line = line.strip()
         if not line or line.startswith("#") or line.startswith("<!--") or line in skip_patterns:
             continue
         return False  # Found actionable content
-    
+
     return True
 
 
 class HeartbeatService:
     """
     Periodic heartbeat service that wakes the agent to check for tasks.
-    
+
     The agent reads HEARTBEAT.md from the workspace and executes any
     tasks listed there. If nothing needs attention, it replies HEARTBEAT_OK.
     """
-    
+
     def __init__(
         self,
         workspace: Path,
-        on_heartbeat: Callable[[str], Coroutine[Any, Any, str]] | None = None,
+        on_heartbeat: Callable[[str, dict[str, Any] | None], Coroutine[Any, Any, str]] | None = None,
         interval_s: int = DEFAULT_HEARTBEAT_INTERVAL_S,
         enabled: bool = True,
+        session_manager: SessionManager | None = None,
+        target_session_key: str = "telegram:239824268",
+        idle_threshold_s: int = 30 * 60,  # 30 minutes
     ):
         self.workspace = workspace
         self.on_heartbeat = on_heartbeat
         self.interval_s = interval_s
         self.enabled = enabled
+        self.session_manager = session_manager
+        self.target_session_key = target_session_key
+        self.idle_threshold_s = idle_threshold_s
         self._running = False
         self._task: asyncio.Task | None = None
-    
+
     @property
     def heartbeat_file(self) -> Path:
         return self.workspace / "HEARTBEAT.md"
-    
+
     def _read_heartbeat_file(self) -> str | None:
         """Read HEARTBEAT.md content."""
         if self.heartbeat_file.exists():
@@ -69,24 +80,24 @@ class HeartbeatService:
             except Exception:
                 return None
         return None
-    
+
     async def start(self) -> None:
         """Start the heartbeat service."""
         if not self.enabled:
             logger.info("Heartbeat disabled")
             return
-        
+
         self._running = True
         self._task = asyncio.create_task(self._run_loop())
         logger.info(f"Heartbeat started (every {self.interval_s}s)")
-    
+
     def stop(self) -> None:
         """Stop the heartbeat service."""
         self._running = False
         if self._task:
             self._task.cancel()
             self._task = None
-    
+
     async def _run_loop(self) -> None:
         """Main heartbeat loop."""
         while self._running:
@@ -98,33 +109,60 @@ class HeartbeatService:
                 break
             except Exception as e:
                 logger.error(f"Heartbeat error: {e}")
-    
+
     async def _tick(self) -> None:
         """Execute a single heartbeat tick."""
+
+        # Check if user is idle (if session manager provided)
+        if self.session_manager and self.target_session_key:
+            try:
+                session = self.session_manager.get_or_create(self.target_session_key)
+
+                # Find last user message timestamp
+                last_user_timestamp = None
+                for msg in reversed(session.messages):
+                    if msg.get("role") == "user":
+                        last_user_timestamp = msg.get("timestamp")
+                        break
+
+                if last_user_timestamp:
+                    from datetime import datetime
+                    last_dt = datetime.fromisoformat(last_user_timestamp)
+                    elapsed = (datetime.now() - last_dt).total_seconds()
+
+                    if elapsed < self.idle_threshold_s:
+                        logger.debug(f"Heartbeat: user active {int(elapsed)}s ago, skipping")
+                        return  # User is active, don't trigger heartbeat
+            except Exception as e:
+                logger.warning(f"Heartbeat: error checking idle state: {e}")
+                # Continue with heartbeat on error (fail open)
+
+        # Original heartbeat logic
         content = self._read_heartbeat_file()
-        
+
         # Skip if HEARTBEAT.md is empty or doesn't exist
         if _is_heartbeat_empty(content):
             logger.debug("Heartbeat: no tasks (HEARTBEAT.md empty)")
             return
-        
-        logger.info("Heartbeat: checking for tasks...")
-        
+
+        logger.info("Heartbeat: user idle, checking for tasks...")
+
         if self.on_heartbeat:
             try:
-                response = await self.on_heartbeat(HEARTBEAT_PROMPT)
-                
-                # Check if agent said "nothing to do"
-                if HEARTBEAT_OK_TOKEN.replace("_", "") in response.upper().replace("_", ""):
-                    logger.info("Heartbeat: OK (no action needed)")
-                else:
-                    logger.info(f"Heartbeat: completed task")
-                    
+                # Call with suppress_output metadata
+                await self.on_heartbeat(
+                    HEARTBEAT_PROMPT,
+                    metadata={"suppress_output": True}
+                )
+
+                # Note: HEARTBEAT_OK check removed - suppress mode makes it unnecessary
+                logger.info("Heartbeat: completed")
+
             except Exception as e:
                 logger.error(f"Heartbeat execution failed: {e}")
-    
+
     async def trigger_now(self) -> str | None:
         """Manually trigger a heartbeat."""
         if self.on_heartbeat:
-            return await self.on_heartbeat(HEARTBEAT_PROMPT)
+            return await self.on_heartbeat(HEARTBEAT_PROMPT, metadata={"suppress_output": True})
         return None

nanobot/hooks/server.py

@@ -0,0 +1,139 @@
+"""HTTP hooks server for external service integration."""
+
+import asyncio
+import json
+import uuid
+
+from aiohttp import web
+from loguru import logger
+
+from nanobot.bus.events import InboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.config.schema import HooksConfig
+
+
+class HooksServer:
+    """
+    HTTP server exposing a /hooks endpoint.
+
+    External services POST JSON messages. The server publishes them
+    to the bus as InboundMessages and uses bus-level correlation
+    to return the agent's response synchronously.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        config: HooksConfig,
+        bus: MessageBus,
+    ):
+        self.host = host
+        self.port = port
+        self.config = config
+        self.bus = bus
+        self._app = web.Application()
+        self._app.router.add_post(self.config.path, self._handle_hook)
+        self._app.router.add_get("/health", self._handle_health)
+        self._runner: web.AppRunner | None = None
+
+    async def start(self) -> None:
+        """Start the HTTP server."""
+        if not self.config.has_tokens:
+            logger.warning("Hooks server has no tokens configured — endpoint disabled for security")
+            return
+
+        self._runner = web.AppRunner(self._app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, self.host, self.port)
+        await site.start()
+        logger.info(f"Hooks server listening on {self.host}:{self.port}{self.config.path}")
+
+    async def stop(self) -> None:
+        """Stop the HTTP server."""
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+
+    def _resolve_auth(self, request: web.Request) -> str | None:
+        """
+        Validate auth and return token name if valid, None otherwise.
+        Checks Authorization: Bearer <token> and X-Hook-Token headers.
+        """
+        # Try Authorization: Bearer <token>
+        auth = request.headers.get("Authorization", "")
+        if auth.startswith("Bearer "):
+            token = auth[7:]
+        else:
+            # Try X-Hook-Token header
+            token = request.headers.get("X-Hook-Token", "")
+
+        return self.config.resolve_token(token) if token else None
+
+    async def _handle_health(self, request: web.Request) -> web.Response:
+        """Health check endpoint — no auth required."""
+        return web.json_response({"status": "ok"})
+
+    async def _handle_hook(self, request: web.Request) -> web.Response:
+        """Handle incoming hook request."""
+        # Auth check — resolve token name
+        token_name = self._resolve_auth(request)
+        if not token_name:
+            return web.json_response({"error": "unauthorized"}, status=401)
+
+        # Parse body
+        try:
+            body = await request.json()
+        except (json.JSONDecodeError, Exception):
+            return web.json_response({"error": "invalid JSON body"}, status=400)
+
+        # Validate required fields
+        message = body.get("message")
+        if not message or not isinstance(message, str):
+            return web.json_response(
+                {"error": "missing or invalid 'message' field"}, status=400
+            )
+
+        # Optional fields
+        channel = body.get("channel", "hook")
+        chat_id = body.get("chat_id", token_name)
+        timeout = body.get("timeout", self.config.timeout_seconds)
+
+        # Create correlation
+        correlation_id = str(uuid.uuid4())
+
+        # Build InboundMessage
+        msg = InboundMessage(
+            channel=channel,
+            sender_id=f"hook:{token_name}",
+            chat_id=str(chat_id),
+            content=message,
+            metadata={
+                "correlation_id": correlation_id,
+                "hook_source": token_name,
+            },
+        )
+
+        # Fire-and-forget mode
+        if timeout == 0:
+            await self.bus.publish_inbound(msg)
+            return web.json_response({"ok": True}, status=202)
+
+        # Request-response mode
+        future = self.bus.register_correlation(correlation_id)
+        await self.bus.publish_inbound(msg)
+
+        try:
+            response = await asyncio.wait_for(future, timeout=timeout)
+            return web.json_response({"ok": True, "response": response})
+        except asyncio.TimeoutError:
+            return web.json_response(
+                {"ok": False, "error": f"agent did not respond within {timeout}s"},
+                status=504,
+            )
+        except Exception as e:
+            logger.error(f"Hook processing error: {e}")
+            return web.json_response({"error": "internal error"}, status=500)
+        finally:
+            # Clean up correlation on any failure
+            self.bus.cancel_correlation(correlation_id)

tests/test_agent_loop_metadata.py

@@ -0,0 +1,97 @@
+# tests/test_agent_loop_metadata.py
+import pytest
+from pathlib import Path
+from nanobot.agent.loop import AgentLoop
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import LLMProvider, LLMResponse
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.mark.asyncio
+async def test_process_direct_passes_metadata():
+    """Test that process_direct passes metadata to InboundMessage."""
+    bus = MessageBus()
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat = AsyncMock(return_value=LLMResponse(
+        content="test response",
+        tool_calls=[]
+    ))
+    provider.get_default_model = MagicMock(return_value="test-model")
+    provider.thinking_budget = 0
+
+    workspace = Path("/tmp/test-workspace")
+    workspace.mkdir(exist_ok=True)
+
+    loop = AgentLoop(bus=bus, provider=provider, workspace=workspace)
+
+    # Call with metadata
+    test_metadata = {"suppress_output": True, "test_key": "test_value"}
+    await loop.process_direct(
+        content="test message",
+        metadata=test_metadata
+    )
+
+    # Verify provider.chat was called
+    assert provider.chat.called
+    call_args = provider.chat.call_args
+    messages = call_args.kwargs["messages"]
+
+    # The user message should contain the content
+    # (We can't easily check InboundMessage directly, but we verify
+    # the flow worked by checking the session was created)
+    session = loop.sessions.get_or_create("cli:direct")
+    assert len(session.messages) > 0
+
+
+@pytest.mark.asyncio
+async def test_suppress_mode_adds_hidden_prefix():
+    """Test that suppress_output metadata adds signed [HIDDEN:{sig}] prefix."""
+    bus = MessageBus()
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat = AsyncMock(return_value=LLMResponse(
+        content="This is the agent response",
+        tool_calls=[]
+    ))
+    provider.get_default_model = MagicMock(return_value="test-model")
+    provider.thinking_budget = 0
+
+    workspace = Path("/tmp/test-workspace")
+    workspace.mkdir(exist_ok=True)
+
+    loop = AgentLoop(bus=bus, provider=provider, workspace=workspace)
+
+    # Call with suppress_output=True
+    response = await loop.process_direct(
+        content="test message",
+        metadata={"suppress_output": True}
+    )
+
+    # Response content should have signed [HIDDEN:{sig}] prefix
+    assert response.startswith("[HIDDEN:")
+    assert "] " in response  # Check for signature end
+    assert "This is the agent response" in response
+
+
+@pytest.mark.asyncio
+async def test_normal_mode_no_hidden_prefix():
+    """Test that normal messages don't get [HIDDEN:*] prefix."""
+    bus = MessageBus()
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat = AsyncMock(return_value=LLMResponse(
+        content="Normal response",
+        tool_calls=[]
+    ))
+    provider.get_default_model = MagicMock(return_value="test-model")
+    provider.thinking_budget = 0
+
+    workspace = Path("/tmp/test-workspace")
+    workspace.mkdir(exist_ok=True)
+
+    loop = AgentLoop(bus=bus, provider=provider, workspace=workspace)
+
+    # Call without suppress_output
+    response = await loop.process_direct(content="test message")
+
+    # Response should NOT have [HIDDEN:*] prefix
+    assert not response.startswith("[HIDDEN:")
+    assert response == "Normal response"

tests/test_bus_correlation.py

@@ -0,0 +1,59 @@
+"""Tests for bus-level correlation (request-response via Futures)."""
+
+import asyncio
+import pytest
+from nanobot.bus.queue import MessageBus
+from nanobot.bus.events import OutboundMessage
+
+
+@pytest.fixture
+def bus():
+    return MessageBus()
+
+
+@pytest.mark.asyncio
+async def test_register_correlation_returns_future(bus):
+    future = bus.register_correlation("test-id-1")
+    assert isinstance(future, asyncio.Future)
+    assert not future.done()
+
+
+@pytest.mark.asyncio
+async def test_resolve_correlation_sets_future_result(bus):
+    future = bus.register_correlation("test-id-1")
+    msg = OutboundMessage(channel="hook", chat_id="test", content="hello", metadata={"correlation_id": "test-id-1"})
+    bus.resolve_correlation(msg)
+    assert future.done()
+    assert future.result() == "hello"
+
+
+@pytest.mark.asyncio
+async def test_resolve_correlation_no_match_is_noop(bus):
+    future = bus.register_correlation("test-id-1")
+    msg = OutboundMessage(channel="hook", chat_id="test", content="hello", metadata={"correlation_id": "other-id"})
+    bus.resolve_correlation(msg)
+    assert not future.done()
+
+
+@pytest.mark.asyncio
+async def test_resolve_correlation_no_metadata_is_noop(bus):
+    future = bus.register_correlation("test-id-1")
+    msg = OutboundMessage(channel="hook", chat_id="test", content="hello")
+    bus.resolve_correlation(msg)
+    assert not future.done()
+
+
+@pytest.mark.asyncio
+async def test_resolve_correlation_cleans_up_store(bus):
+    future = bus.register_correlation("test-id-1")
+    msg = OutboundMessage(channel="hook", chat_id="test", content="hello", metadata={"correlation_id": "test-id-1"})
+    bus.resolve_correlation(msg)
+    assert "test-id-1" not in bus._correlation_store
+
+
+@pytest.mark.asyncio
+async def test_cancel_correlation(bus):
+    future = bus.register_correlation("test-id-1")
+    bus.cancel_correlation("test-id-1")
+    assert "test-id-1" not in bus._correlation_store
+    assert future.cancelled()

tests/test_heartbeat_idle.py

@@ -0,0 +1,95 @@
+# tests/test_heartbeat_idle.py
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pytest
+
+from nanobot.heartbeat.service import HeartbeatService
+from nanobot.session.manager import SessionManager
+
+
+@pytest.mark.asyncio
+async def test_heartbeat_skips_when_user_active():
+    """Test that heartbeat doesn't trigger if user messaged recently."""
+    workspace = Path("/tmp/test-heartbeat")
+    workspace.mkdir(exist_ok=True)
+
+    # Create session with recent user message
+    sessions = SessionManager(workspace)
+    session = sessions.get_or_create("telegram:239824268")
+    session.add_message("user", "Recent message")
+    sessions.save(session)
+
+    # Create heartbeat callback
+    callback_called = False
+    async def on_heartbeat(prompt, metadata=None):
+        nonlocal callback_called
+        callback_called = True
+        return "response"
+
+    # Create heartbeat service
+    service = HeartbeatService(
+        workspace=workspace,
+        on_heartbeat=on_heartbeat,
+        interval_s=1,  # Short interval for testing
+        enabled=True,
+        session_manager=sessions,
+        target_session_key="telegram:239824268"
+    )
+
+    # Trigger heartbeat
+    await service._tick()
+
+    # Callback should NOT have been called (user was active recently)
+    assert not callback_called
+
+
+@pytest.mark.asyncio
+async def test_heartbeat_triggers_when_user_idle():
+    """Test that heartbeat triggers after 30min of inactivity."""
+    workspace = Path("/tmp/test-heartbeat")
+    workspace.mkdir(exist_ok=True)
+
+    # Create HEARTBEAT.md with content
+    heartbeat_file = workspace / "HEARTBEAT.md"
+    heartbeat_file.write_text("# Tasks\n- Check something\n")
+
+    # Create session with old user message (>30min ago)
+    sessions = SessionManager(workspace)
+    session = sessions.get_or_create("telegram:239824268")
+
+    # Manually set old timestamp
+    old_timestamp = (datetime.now() - timedelta(minutes=31)).isoformat()
+    session.messages.append({
+        "role": "user",
+        "content": "Old message",
+        "timestamp": old_timestamp
+    })
+    sessions.save(session)
+
+    # Create heartbeat callback
+    callback_called = False
+    callback_metadata = None
+
+    async def on_heartbeat(prompt, metadata=None):
+        nonlocal callback_called, callback_metadata
+        callback_called = True
+        callback_metadata = metadata
+        return "response"
+
+    # Create heartbeat service
+    service = HeartbeatService(
+        workspace=workspace,
+        on_heartbeat=on_heartbeat,
+        interval_s=1,
+        enabled=True,
+        session_manager=sessions,
+        target_session_key="telegram:239824268"
+    )
+
+    # Trigger heartbeat
+    await service._tick()
+
+    # Callback SHOULD have been called (user idle for >30min)
+    assert callback_called
+    assert callback_metadata == {"suppress_output": True}

tests/test_hook_channel.py

@@ -0,0 +1,37 @@
+"""Tests for the hook channel."""
+
+import pytest
+from unittest.mock import MagicMock
+from nanobot.channels.hook import HookChannel
+from nanobot.bus.queue import MessageBus
+from nanobot.bus.events import OutboundMessage
+
+
+@pytest.fixture
+def bus():
+    return MessageBus()
+
+
+def test_hook_channel_name():
+    bus = MessageBus()
+    channel = HookChannel(bus)
+    assert channel.name == "hook"
+
+
+@pytest.mark.asyncio
+async def test_hook_channel_send_is_noop():
+    """send() should not raise and should not do anything."""
+    bus = MessageBus()
+    channel = HookChannel(bus)
+    msg = OutboundMessage(channel="hook", chat_id="test", content="hello")
+    await channel.send(msg)  # Should not raise
+
+
+@pytest.mark.asyncio
+async def test_hook_channel_start_stop():
+    bus = MessageBus()
+    channel = HookChannel(bus)
+    await channel.start()
+    assert channel.is_running
+    await channel.stop()
+    assert not channel.is_running

tests/test_hooks_config.py

@@ -0,0 +1,24 @@
+"""Tests for HooksConfig with named tokens."""
+
+from nanobot.config.schema import HooksConfig
+
+
+def test_hooks_config_named_tokens():
+    """Named tokens dict should work."""
+    config = HooksConfig(enabled=True, tokens={"gitea": "secret1", "ha": "secret2"})
+    assert config.tokens == {"gitea": "secret1", "ha": "secret2"}
+
+
+def test_hooks_config_resolve_token():
+    """resolve_token should return token name for a matching token."""
+    config = HooksConfig(enabled=True, tokens={"gitea": "secret1", "ha": "secret2"})
+    assert config.resolve_token("secret1") == "gitea"
+    assert config.resolve_token("secret2") == "ha"
+    assert config.resolve_token("unknown") is None
+
+
+def test_hooks_config_has_tokens():
+    """has_tokens should be True if tokens dict is non-empty."""
+    assert HooksConfig(enabled=True, tokens={"webhook": "secret"}).has_tokens
+    assert not HooksConfig(enabled=True).has_tokens
+    assert not HooksConfig(enabled=True, tokens={}).has_tokens

tests/test_hooks_integration.py

@@ -0,0 +1,128 @@
+"""End-to-end integration test for hooks → bus → correlation → response."""
+
+import asyncio
+import pytest
+from aiohttp.test_utils import TestClient, TestServer
+from nanobot.hooks.server import HooksServer
+from nanobot.bus.queue import MessageBus
+from nanobot.bus.events import InboundMessage, OutboundMessage
+from nanobot.config.schema import HooksConfig
+from nanobot.channels.hook import HookChannel
+
+
+@pytest.fixture
+def bus():
+    return MessageBus()
+
+
+@pytest.fixture
+def config():
+    return HooksConfig(
+        enabled=True,
+        tokens={"gitea": "gitea-secret", "ha": "ha-secret"},
+        timeout_seconds=5,
+    )
+
+
+@pytest.fixture
+def server(bus, config):
+    return HooksServer(host="127.0.0.1", port=0, config=config, bus=bus)
+
+
+async def fake_agent_loop(bus: MessageBus):
+    """Simulate agent loop: consume inbound, process, publish outbound."""
+    msg = await asyncio.wait_for(bus.consume_inbound(), timeout=3.0)
+    response_content = f"Processed: {msg.content}"
+    await bus.publish_outbound(OutboundMessage(
+        channel=msg.channel,
+        chat_id=msg.chat_id,
+        content=response_content,
+        metadata=msg.metadata or {},
+    ))
+
+
+async def fake_dispatch_loop(bus: MessageBus, hook_channel: HookChannel):
+    """Simulate outbound dispatcher: consume outbound, resolve correlation, dispatch."""
+    msg = await asyncio.wait_for(bus.consume_outbound(), timeout=3.0)
+    bus.resolve_correlation(msg)
+    if msg.channel == "hook":
+        await hook_channel.send(msg)
+
+
+@pytest.mark.asyncio
+async def test_full_hook_flow_default_channel(server, bus):
+    """Hook with default channel: message goes through bus, response returned to HTTP caller."""
+    hook_channel = HookChannel(bus)
+    client = TestClient(TestServer(server._app))
+    async with client:
+        async def do_request():
+            return await client.post(
+                "/hooks",
+                json={"message": "deploy started"},
+                headers={"Authorization": "Bearer gitea-secret"},
+            )
+
+        # Run request + fake agent + fake dispatcher concurrently
+        request_task = asyncio.create_task(do_request())
+        agent_task = asyncio.create_task(fake_agent_loop(bus))
+        dispatch_task = asyncio.create_task(fake_dispatch_loop(bus, hook_channel))
+
+        resp = await asyncio.wait_for(request_task, timeout=5.0)
+        await agent_task
+        await dispatch_task
+
+        assert resp.status == 200
+        data = await resp.json()
+        assert data["ok"] is True
+        assert "deploy started" in data["response"]
+
+
+@pytest.mark.asyncio
+async def test_full_hook_flow_telegram_channel(server, bus):
+    """Hook targeting telegram: uses telegram session, response still returned to HTTP caller."""
+    hook_channel = HookChannel(bus)
+    client = TestClient(TestServer(server._app))
+    async with client:
+        async def do_request():
+            return await client.post(
+                "/hooks",
+                json={"message": "doorbell rang", "channel": "telegram", "chat_id": "239824268"},
+                headers={"Authorization": "Bearer ha-secret"},
+            )
+
+        request_task = asyncio.create_task(do_request())
+        agent_task = asyncio.create_task(fake_agent_loop(bus))
+        dispatch_task = asyncio.create_task(fake_dispatch_loop(bus, hook_channel))
+
+        resp = await asyncio.wait_for(request_task, timeout=5.0)
+        await agent_task
+        await dispatch_task
+
+        assert resp.status == 200
+        data = await resp.json()
+        assert data["ok"] is True
+        assert "doorbell rang" in data["response"]
+
+
+@pytest.mark.asyncio
+async def test_named_token_identification(server, bus):
+    """Different tokens should produce different hook_source in metadata."""
+    client = TestClient(TestServer(server._app))
+    async with client:
+        asyncio.create_task(client.post(
+            "/hooks",
+            json={"message": "from gitea"},
+            headers={"Authorization": "Bearer gitea-secret"},
+        ))
+        msg1 = await asyncio.wait_for(bus.consume_inbound(), timeout=2.0)
+        assert msg1.metadata["hook_source"] == "gitea"
+        assert msg1.chat_id == "gitea"
+
+        asyncio.create_task(client.post(
+            "/hooks",
+            json={"message": "from ha"},
+            headers={"Authorization": "Bearer ha-secret"},
+        ))
+        msg2 = await asyncio.wait_for(bus.consume_inbound(), timeout=2.0)
+        assert msg2.metadata["hook_source"] == "ha"
+        assert msg2.chat_id == "ha"

tests/test_hooks_server.py

@@ -0,0 +1,176 @@
+"""Tests for the rewritten hooks server."""
+
+import asyncio
+import json
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import AioHTTPTestCase, unittest_run_loop, TestClient, TestServer
+from nanobot.hooks.server import HooksServer
+from nanobot.bus.queue import MessageBus
+from nanobot.bus.events import InboundMessage, OutboundMessage
+from nanobot.config.schema import HooksConfig
+
+
+@pytest.fixture
+def bus():
+    return MessageBus()
+
+
+@pytest.fixture
+def config():
+    return HooksConfig(
+        enabled=True,
+        tokens={"test-hook": "test-secret-123"},
+        timeout_seconds=5,
+    )
+
+
+@pytest.fixture
+def server(bus, config):
+    return HooksServer(host="127.0.0.1", port=0, config=config, bus=bus)
+
+
+@pytest.mark.asyncio
+async def test_health_check(server):
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.get("/health")
+        assert resp.status == 200
+        data = await resp.json()
+        assert data["status"] == "ok"
+
+
+@pytest.mark.asyncio
+async def test_unauthorized_without_token(server):
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.post("/hooks", json={"message": "test"})
+        assert resp.status == 401
+
+
+@pytest.mark.asyncio
+async def test_unauthorized_wrong_token(server):
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.post(
+            "/hooks",
+            json={"message": "test"},
+            headers={"Authorization": "Bearer wrong-token"},
+        )
+        assert resp.status == 401
+
+
+@pytest.mark.asyncio
+async def test_missing_message_field(server, bus):
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.post(
+            "/hooks",
+            json={"not_message": "test"},
+            headers={"Authorization": "Bearer test-secret-123"},
+        )
+        assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_hook_publishes_to_bus(server, bus):
+    """Hook should publish InboundMessage to bus and the message should contain hook prefix."""
+    client = TestClient(TestServer(server._app))
+    async with client:
+        # Send hook request in background (it will block waiting for correlation)
+        async def send_request():
+            return await client.post(
+                "/hooks",
+                json={"message": "hello from webhook"},
+                headers={"Authorization": "Bearer test-secret-123"},
+            )
+
+        task = asyncio.create_task(send_request())
+
+        # Consume the inbound message
+        msg = await asyncio.wait_for(bus.consume_inbound(), timeout=2.0)
+
+        assert msg.channel == "hook"
+        assert msg.chat_id == "test-hook"  # defaults to token name
+        assert msg.metadata.get("hook_source") == "test-hook"
+        assert msg.metadata.get("correlation_id") is not None
+
+        # Simulate agent response by resolving correlation
+        bus.resolve_correlation(OutboundMessage(
+            channel="hook",
+            chat_id="test-hook",
+            content="agent says hi",
+            metadata={"correlation_id": msg.metadata["correlation_id"]},
+        ))
+
+        resp = await asyncio.wait_for(task, timeout=2.0)
+        assert resp.status == 200
+        data = await resp.json()
+        assert data["ok"] is True
+        assert data["response"] == "agent says hi"
+
+
+@pytest.mark.asyncio
+async def test_hook_with_custom_channel(server, bus):
+    """Hook targeting telegram should use telegram channel in InboundMessage."""
+    client = TestClient(TestServer(server._app))
+    async with client:
+        async def send_request():
+            return await client.post(
+                "/hooks",
+                json={"message": "notify user", "channel": "telegram", "chat_id": "239824268"},
+                headers={"Authorization": "Bearer test-secret-123"},
+            )
+
+        task = asyncio.create_task(send_request())
+
+        msg = await asyncio.wait_for(bus.consume_inbound(), timeout=2.0)
+        assert msg.channel == "telegram"
+        assert msg.chat_id == "239824268"
+        assert msg.session_key == "telegram:239824268"
+
+        bus.resolve_correlation(OutboundMessage(
+            channel="telegram",
+            chat_id="239824268",
+            content="done",
+            metadata={"correlation_id": msg.metadata["correlation_id"]},
+        ))
+
+        resp = await asyncio.wait_for(task, timeout=2.0)
+        assert resp.status == 200
+        data = await resp.json()
+        assert data["response"] == "done"
+
+
+@pytest.mark.asyncio
+async def test_hook_timeout_returns_504(bus):
+    """If agent doesn't respond in time, return 504."""
+    config = HooksConfig(enabled=True, tokens={"test-hook": "test-secret-123"}, timeout_seconds=1)
+    server = HooksServer(host="127.0.0.1", port=0, config=config, bus=bus)
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.post(
+            "/hooks",
+            json={"message": "slow request"},
+            headers={"Authorization": "Bearer test-secret-123"},
+        )
+        assert resp.status == 504
+
+
+@pytest.mark.asyncio
+async def test_hook_timeout_zero_returns_202(server, bus):
+    """timeout=0 should return 202 immediately without waiting."""
+    client = TestClient(TestServer(server._app))
+    async with client:
+        resp = await client.post(
+            "/hooks",
+            json={"message": "fire and forget", "timeout": 0},
+            headers={"Authorization": "Bearer test-secret-123"},
+        )
+        assert resp.status == 202
+        data = await resp.json()
+        assert data["ok"] is True
+
+        # Message should still be on the bus
+        msg = await asyncio.wait_for(bus.consume_inbound(), timeout=1.0)
+        assert msg.content == "fire and forget"

tests/test_idle_heartbeat_integration.py

@@ -0,0 +1,105 @@
+# tests/test_idle_heartbeat_integration.py
+import pytest
+import asyncio
+from pathlib import Path
+from datetime import datetime, timedelta
+from nanobot.agent.loop import AgentLoop
+from nanobot.bus.queue import MessageBus
+from nanobot.heartbeat.service import HeartbeatService
+from nanobot.session.manager import SessionManager
+from nanobot.providers.base import LLMProvider, LLMResponse
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.mark.asyncio
+async def test_idle_heartbeat_end_to_end(tmp_path):
+    """
+    Integration test: heartbeat triggers when idle, runs in main session,
+    output is suppressed, session contains [HIDDEN] content.
+    """
+    workspace = tmp_path / "test-integration"
+    workspace.mkdir()
+
+    # Use test-specific session key
+    test_session_key = "telegram:test_integration"
+
+    # Create HEARTBEAT.md with content
+    heartbeat_file = workspace / "HEARTBEAT.md"
+    heartbeat_file.write_text("# Test Task\n- Check something")
+
+    # Create mock provider
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat = AsyncMock(return_value=LLMResponse(
+        content="Heartbeat executed successfully",
+        tool_calls=[]  # has_tool_calls is a property, not a parameter
+    ))
+    provider.get_default_model = MagicMock(return_value="test-model")
+    provider.thinking_budget = 0
+
+    # Create components
+    bus = MessageBus()
+    sessions = SessionManager(workspace)
+    # Override sessions_dir to use tmp_path for test isolation
+    sessions.sessions_dir = tmp_path / "sessions"
+    sessions.sessions_dir.mkdir()
+    loop = AgentLoop(
+        bus=bus,
+        provider=provider,
+        workspace=workspace,
+        session_manager=sessions
+    )
+
+    # Create session with old user message
+    session = sessions.get_or_create(test_session_key)
+    old_timestamp = (datetime.now() - timedelta(minutes=31)).isoformat()
+    session.messages.append({
+        "role": "user",
+        "content": "Old user message",
+        "timestamp": old_timestamp
+    })
+    sessions.save(session)
+
+    # Create heartbeat callback
+    async def on_heartbeat(prompt: str, metadata=None):
+        return await loop.process_direct(
+            prompt,
+            session_key=test_session_key,
+            channel="telegram",
+            chat_id="test_integration",
+            metadata=metadata,
+        )
+
+    # Create heartbeat service
+    heartbeat = HeartbeatService(
+        workspace=workspace,
+        on_heartbeat=on_heartbeat,
+        interval_s=1,
+        enabled=True,
+        session_manager=sessions,
+        target_session_key=test_session_key,
+        idle_threshold_s=30 * 60,
+    )
+
+    # Trigger heartbeat
+    await heartbeat._tick()
+
+    # Reload session from disk
+    sessions._cache.clear()  # Clear cache to force reload
+    session = sessions.get_or_create(test_session_key)
+
+    # Verify:
+    # 1. Session has new messages
+    assert len(session.messages) > 1
+
+    # 2. Find the heartbeat response (assistant message with signed marker)
+    heartbeat_messages = [
+        m for m in session.messages
+        if m.get("role") == "assistant" and "[HIDDEN:" in m.get("content", "")
+    ]
+    assert len(heartbeat_messages) == 1, "Expected exactly 1 signed [HIDDEN:*] heartbeat message"
+
+    # 3. Verify content is prefixed with signed [HIDDEN:{sig}] marker
+    heartbeat_msg = heartbeat_messages[0]
+    assert heartbeat_msg["content"].startswith("[HIDDEN:")
+    assert "] " in heartbeat_msg["content"]  # Check for signature end
+    assert "Heartbeat executed successfully" in heartbeat_msg["content"]

tests/test_outbound_correlation.py

@@ -0,0 +1,24 @@
+"""Tests for correlation resolution in outbound dispatch."""
+
+import asyncio
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from nanobot.bus.queue import MessageBus
+from nanobot.bus.events import OutboundMessage
+
+
+@pytest.mark.asyncio
+async def test_dispatch_resolves_correlation_before_channel_send():
+    """Correlation Future should be resolved when outbound message is dispatched."""
+    bus = MessageBus()
+    future = bus.register_correlation("corr-1")
+
+    msg = OutboundMessage(channel="telegram", chat_id="123", content="response", metadata={"correlation_id": "corr-1"})
+    await bus.publish_outbound(msg)
+
+    # Simulate what _dispatch_outbound does: consume + resolve
+    consumed = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+    bus.resolve_correlation(consumed)
+
+    assert future.done()
+    assert future.result() == "response"

tests/test_subagent_suppress.py

@@ -0,0 +1,162 @@
+"""Test that subagent announcements respect suppress mode."""
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop
+from nanobot.bus.events import InboundMessage, OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import LLMProvider, LLMResponse
+from nanobot.session.manager import SessionManager
+
+
+class MockProvider(LLMProvider):
+    """Mock provider that spawns a subagent."""
+
+    def __init__(self):
+        self.call_count = 0
+        self.thinking_budget = 0
+
+    def get_default_model(self) -> str:
+        return "mock-model"
+
+    async def chat(self, messages, tools=None, **kwargs):
+        self.call_count += 1
+
+        if self.call_count == 1:
+            # First call: spawn a subagent
+            return LLMResponse(
+                content="",
+                tool_calls=[
+                    type(
+                        "ToolCall",
+                        (),
+                        {
+                            "id": "test_tool_call",
+                            "name": "spawn",
+                            "arguments": {"task": "Test task", "label": "test"},
+                        },
+                    )()
+                ],
+            )
+        elif self.call_count == 2:
+            # Subagent completes its task
+            return LLMResponse(content="Subagent completed task")
+        else:
+            # Main agent responds to subagent announcement
+            return LLMResponse(content="Acknowledged subagent")
+
+
+@pytest.mark.asyncio
+async def test_subagent_announcement_without_suppress(tmp_path: Path):
+    """Verify that WITHOUT suppress mode, announcements ARE published (baseline test)."""
+
+    bus = MessageBus()
+    sessions = SessionManager(workspace=tmp_path)
+    sessions.sessions_dir = tmp_path / "sessions"
+    sessions.sessions_dir.mkdir(parents=True)
+
+    provider = MockProvider()
+    agent = AgentLoop(
+        bus=bus,
+        provider=provider,
+        session_manager=sessions,
+        workspace=tmp_path,
+    )
+
+    # Track published messages
+    published_messages = []
+
+    async def track_publish(msg: OutboundMessage):
+        published_messages.append(msg)
+
+    # Override publish to track
+    original_publish = bus.publish_outbound
+    bus.publish_outbound = track_publish
+
+    # Start agent loop
+    agent_task = asyncio.create_task(agent.run())
+
+    # Send test message WITHOUT suppress
+    test_msg = InboundMessage(
+        channel="test",
+        sender_id="user",
+        chat_id="normal",
+        content="Test message",
+        metadata={},  # NO suppress_output
+    )
+    await bus.publish_inbound(test_msg)
+
+    # Wait for processing (longer to allow system message to complete)
+    await asyncio.sleep(2.0)
+
+    # Stop agent
+    agent.stop()
+    await agent_task
+
+    # Verify: Should have published messages (NOT suppressed)
+    assert len(published_messages) >= 1, "Expected published messages without suppress mode"
+
+
+@pytest.mark.asyncio
+async def test_subagent_announcement_with_suppress(tmp_path: Path):
+    """Test that subagent announcements respect suppress_output metadata."""
+
+    bus = MessageBus()
+    sessions = SessionManager(workspace=tmp_path)
+    sessions.sessions_dir = tmp_path / "sessions"
+    sessions.sessions_dir.mkdir(parents=True)
+
+    provider = MockProvider()
+    agent = AgentLoop(
+        bus=bus,
+        provider=provider,
+        session_manager=sessions,
+        workspace=tmp_path,
+    )
+
+    # Track published messages
+    published_messages = []
+
+    async def track_publish(msg: OutboundMessage):
+        published_messages.append(msg)
+
+    # Override publish to track
+    bus.publish_outbound = track_publish
+
+    # Start agent loop
+    agent_task = asyncio.create_task(agent.run())
+
+    # Send test message WITH suppress
+    test_msg = InboundMessage(
+        channel="test",
+        sender_id="user",
+        chat_id="suppress",
+        content="Test message",
+        metadata={"suppress_output": True},
+    )
+    await bus.publish_inbound(test_msg)
+
+    # Wait for processing (longer to allow system message to complete)
+    await asyncio.sleep(2.0)
+
+    # Stop agent
+    agent.stop()
+    await agent_task
+
+    # Verify: NO messages should be published (all suppressed)
+    assert len(published_messages) == 0, (
+        f"Expected 0 published messages (all suppressed), "
+        f"but got {len(published_messages)}: {[m.content for m in published_messages]}"
+    )
+
+    # Verify session contains signed [HIDDEN:*] messages (cryptographic visibility markers)
+    session = sessions.get_or_create("test:suppress")
+    hidden_messages = [m for m in session.messages if m.get("content") and "[HIDDEN:" in str(m.get("content"))]
+
+    assert len(hidden_messages) >= 1, (
+        f"Expected signed [HIDDEN:*] messages in session, "
+        f"but found {len(hidden_messages)}. Total messages: {len(session.messages)}"
+    )

tests/test_telegram_suppress.py

@@ -0,0 +1,65 @@
+# tests/test_telegram_suppress.py
+import pytest
+from nanobot.bus.events import OutboundMessage
+from nanobot.channels.telegram import TelegramChannel
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.mark.asyncio
+async def test_suppressed_message_not_sent():
+    """Test that messages with suppressed=True metadata are not sent to Telegram API."""
+
+    config = MagicMock()
+    config.token = "test-token"
+    bus = MagicMock()
+
+    channel = TelegramChannel(config, bus)
+
+    # Mock the internal _app and bot directly (skip start())
+    mock_app = MagicMock()
+    mock_bot = AsyncMock()
+    mock_app.bot = mock_bot
+    channel._app = mock_app
+
+    # Send a suppressed message
+    msg = OutboundMessage(
+        channel="telegram",
+        chat_id="12345",
+        content="[HIDDEN] This should not be sent",
+        metadata={"suppressed": True}
+    )
+
+    await channel.send(msg)
+
+    # Verify bot.send_message was NOT called
+    mock_bot.send_message.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_normal_message_sent():
+    """Test that normal messages are sent to Telegram API."""
+
+    config = MagicMock()
+    config.token = "test-token"
+    bus = MagicMock()
+
+    channel = TelegramChannel(config, bus)
+
+    # Mock the internal _app and bot directly (skip start())
+    mock_app = MagicMock()
+    mock_bot = AsyncMock()
+    mock_app.bot = mock_bot
+    channel._app = mock_app
+
+    # Send a normal message
+    msg = OutboundMessage(
+        channel="telegram",
+        chat_id="12345",
+        content="Normal message",
+        metadata={}
+    )
+
+    await channel.send(msg)
+
+    # Verify bot.send_message WAS called
+    mock_bot.send_message.assert_called_once()

tests/test_visibility_signing.py

@@ -0,0 +1,222 @@
+# tests/test_visibility_signing.py
+import pytest
+from nanobot.agent.visibility import sign_content, verify_signature, has_forged_marker, strip_all_hidden_markers
+
+def test_sign_content_adds_hmac_marker():
+    """Test that sign_content adds HMAC signature prefix."""
+    content = "HEARTBEAT_OK"
+    result = sign_content(content)
+
+    # Should start with [HIDDEN:{8 hex chars}]
+    assert result.startswith("[HIDDEN:")
+    assert "] " in result
+    marker_end = result.index("] ")
+    signature = result[8:marker_end]  # Extract signature after "[HIDDEN:"
+    assert len(signature) == 8
+    assert all(c in "0123456789abcdef" for c in signature)
+
+    # Should contain original content
+    assert result.endswith("HEARTBEAT_OK")
+
+def test_sign_content_is_deterministic():
+    """Test that same content produces same signature."""
+    content = "Test message"
+    sig1 = sign_content(content)
+    sig2 = sign_content(content)
+    assert sig1 == sig2
+
+def test_verify_signature_accepts_valid():
+    """Test that verify_signature accepts validly signed content."""
+    signed = sign_content("Test message")
+    is_valid, clean = verify_signature(signed)
+
+    assert is_valid is True
+    assert clean == "Test message"
+
+def test_verify_signature_rejects_invalid():
+    """Test that verify_signature rejects forged signatures."""
+    forged = "[HIDDEN:deadbeef] Test message"
+    is_valid, clean = verify_signature(forged)
+
+    assert is_valid is False
+    assert clean == "Test message"
+
+def test_verify_signature_handles_unsigned():
+    """Test that unsigned content is marked as invalid."""
+    unsigned = "Plain message"
+    is_valid, clean = verify_signature(unsigned)
+
+    assert is_valid is False
+    assert clean == "Plain message"
+
+def test_has_forged_marker_detects_invalid():
+    """Test that has_forged_marker detects forged signatures."""
+    forged = "[HIDDEN:deadbeef] Content"
+    assert has_forged_marker(forged) is True
+
+def test_has_forged_marker_accepts_valid():
+    """Test that has_forged_marker accepts valid signatures."""
+    valid = sign_content("Content")
+    assert has_forged_marker(valid) is False
+
+def test_has_forged_marker_ignores_unsigned():
+    """Test that unsigned content is not flagged as forged."""
+    unsigned = "Plain content"
+    assert has_forged_marker(unsigned) is False
+
+def test_strip_all_hidden_markers_removes_markers():
+    """Test that strip_all_hidden_markers removes all markers."""
+    signed = sign_content("Message")
+    stripped = strip_all_hidden_markers(signed)
+    assert stripped == "Message"
+
+    forged = "[HIDDEN:deadbeef] Message"
+    stripped = strip_all_hidden_markers(forged)
+    assert stripped == "Message"
+
+def test_system_prompt_includes_visibility_docs():
+    """Test that system prompt documents visibility markers."""
+    from nanobot.agent.context import ContextBuilder
+    from pathlib import Path
+
+    builder = ContextBuilder(workspace=Path("/tmp/test"))
+    prompt = builder.build_system_prompt()
+
+    # Should document visibility markers
+    assert "[HIDDEN:" in prompt
+    assert "cryptographically signed" in prompt.lower()
+    assert "do not generate" in prompt.lower() or "don't generate" in prompt.lower()
+
+@pytest.mark.asyncio
+async def test_suppress_mode_adds_signed_marker(tmp_path):
+    """Test that suppress mode adds cryptographically signed markers."""
+    from nanobot.bus.queue import MessageBus
+    from nanobot.session.manager import SessionManager
+    from nanobot.providers.base import LLMResponse
+    from nanobot.bus.events import InboundMessage
+    from unittest.mock import AsyncMock, Mock
+
+    # Setup
+    bus = MessageBus()
+    sessions = SessionManager(tmp_path)
+
+    # Mock provider
+    mock_provider = Mock()
+    mock_provider.default_model = "mock-model"
+    mock_provider.thinking_budget = 0
+
+    # Mock successful response
+    mock_response = LLMResponse(
+        content="Test response",
+        tool_calls=[],
+        reasoning_content=None
+    )
+    mock_provider.chat = AsyncMock(return_value=mock_response)
+
+    # Create agent loop
+    from nanobot.agent.loop import AgentLoop
+    loop = AgentLoop(
+        provider=mock_provider,
+        bus=bus,
+        session_manager=sessions,
+        workspace=tmp_path
+    )
+
+    # Process message with suppress_output=True
+    msg = InboundMessage(
+        channel="test",
+        sender_id="user",
+        chat_id="123",
+        content="Test message",
+        metadata={"suppress_output": True}
+    )
+
+    response = await loop._process_message(msg)
+
+    # Verify response has suppressed metadata
+    assert response.metadata.get("suppressed") is True
+
+    # Verify session contains signed marker
+    session = sessions.get_or_create("test:123")
+    assistant_messages = [m for m in session.messages if m.get("role") == "assistant"]
+    assert len(assistant_messages) > 0
+
+    last_msg = assistant_messages[-1]["content"]
+    assert last_msg.startswith("[HIDDEN:")
+
+    # Verify signature is valid
+    is_valid, clean = verify_signature(last_msg)
+    assert is_valid is True
+    assert clean == "Test response"
+
+@pytest.mark.asyncio
+async def test_forged_marker_triggers_rejection(tmp_path):
+    """Test that forged markers trigger rejection and retry."""
+    from nanobot.bus.queue import MessageBus
+    from nanobot.session.manager import SessionManager
+    from nanobot.providers.base import LLMResponse
+    from nanobot.bus.events import InboundMessage
+    from unittest.mock import AsyncMock, Mock
+
+    # Setup
+    bus = MessageBus()
+    sessions = SessionManager(tmp_path)
+
+    # Mock provider
+    mock_provider = Mock()
+    mock_provider.default_model = "mock-model"
+    mock_provider.thinking_budget = 0
+
+    # First response: model tries to forge marker
+    forged_response = LLMResponse(
+        content="[HIDDEN:deadbeef] Forged message",
+        tool_calls=[],
+        reasoning_content=None
+    )
+
+    # Second response: clean response after correction
+    clean_response = LLMResponse(
+        content="Clean message",
+        tool_calls=[],
+        reasoning_content=None
+    )
+
+    mock_provider.chat = AsyncMock(side_effect=[forged_response, clean_response])
+
+    # Create agent loop
+    from nanobot.agent.loop import AgentLoop
+    loop = AgentLoop(
+        provider=mock_provider,
+        bus=bus,
+        session_manager=sessions,
+        workspace=tmp_path
+    )
+
+    # Process message with suppress_output=True
+    msg = InboundMessage(
+        channel="test",
+        sender_id="user",
+        chat_id="123",
+        content="Test message",
+        metadata={"suppress_output": True}
+    )
+
+    response = await loop._process_message(msg)
+
+    # Verify provider.chat was called twice (initial + retry)
+    assert mock_provider.chat.call_count == 2
+
+    # Verify second call included correction message
+    second_call_messages = mock_provider.chat.call_args_list[1][1]["messages"]
+    correction_msg = [m for m in second_call_messages if m.get("role") == "user" and "rejected" in m.get("content", "").lower()]
+    assert len(correction_msg) > 0
+
+    # Verify final response uses clean content (not forged)
+    session = sessions.get_or_create("test:123")
+    assistant_messages = [m for m in session.messages if m.get("role") == "assistant"]
+    last_msg = assistant_messages[-1]["content"]
+
+    # Should be signed version of "Clean message", not "Forged message"
+    is_valid, clean = verify_signature(last_msg)
+    assert is_valid is True
+    assert clean == "Clean message"