fix(agent,channels): forward receipts through delegate sub-loops + strict disabled coverage

Address #6214 review feedback against #6182's full acceptance criteria.

- Add `TOOL_LOOP_RECEIPT_CONTEXT` task-local in `agent::tool_receipts`,
  matching the existing `TOOL_LOOP_COST_TRACKING_CONTEXT` pattern. The
  orchestrator scopes the per-turn `Arc<Mutex<Vec<String>>>` collector
  plus the process-lifetime `ReceiptGenerator` clone before entering the
  tool-call loop.
- `DelegateTool::execute_sync` reads the scope and forwards generator +
  collector into the sub-agent's `run_tool_call_loop`, replacing the
  prior `None, None` placeholders at delegate.rs:1184. Multi-agent
  resilience: `execute_parallel` captures the parent scope and re-enters
  it inside each spawned sub-agent so parallel sub-tool receipts land in
  the same per-turn collector via `Arc` sharing. Background spawns stay
  unsigned by design (per-turn collector is already rendered before they
  finish; documented as a known limitation).
- Strict #6182 disabled coverage:
  `process_channel_message_disabled_receipt_generator_emits_no_receipts_anywhere`
  asserts no `zc-receipt-` token in any sent message and no `[receipt:`
  trailer in conversation history when `receipt_generator: None`.
  Distinct from the existing `show_in_response = false` test (which
  keeps the generator on but suppresses the user-visible block).
- Delegate forwarding coverage: positive test exercises `execute_agentic`
  inside a scoped `TOOL_LOOP_RECEIPT_CONTEXT` and verifies a real
  `echo_tool` sub-call lands in the parent collector with a valid
  `zc-receipt-` HMAC token; negative test confirms unsigned sub-loop
  output when no scope is set.
- Clarify "session" semantics in `docs/book/src/security/tool-receipts.md`:
  the HMAC key is per daemon process (not per conversation or channel),
  generated at `start_channels` and rotated on restart. Add explicit
  "what receipts don't isolate" entries for cross-channel and
  background-delegate spawns.

Author: singlerider

crates/zeroclaw-channels/src/orchestrator/mod.rs

@@ -3143,8 +3143,17 @@ async fn process_channel_message(
     // Per-turn collector. `tool_execution::execute_one_tool` pushes
     // `<tool_name>: <receipt>` here whenever a receipt is generated, so the
     // orchestrator can render the trailing `Tool receipts:` block after the
-    // loop returns. Inert when `receipt_generator` is `None`.
-    let tool_receipts_collector: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(Vec::new());
+    // loop returns. Wrapped in `Arc` so the same handle can be shared into
+    // `TOOL_LOOP_RECEIPT_CONTEXT` for subagent forwarding (#6182). Inert when
+    // `receipt_generator` is `None`.
+    let tool_receipts_collector: std::sync::Arc<std::sync::Mutex<Vec<String>>> =
+        std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    let receipt_scope = ctx.receipt_generator.as_ref().map(|generator| {
+        zeroclaw_runtime::agent::tool_receipts::ReceiptScope {
+            generator: generator.clone(),
+            collector: std::sync::Arc::clone(&tool_receipts_collector),
+        }
+    });
     let (llm_result, fallback_info) = scope_provider_fallback(async {
         let llm_result = loop {
             let loop_result = tokio::select! {
@@ -3157,6 +3166,8 @@ async fn process_channel_message(
                             .or_else(|| Some(msg.id.clone())),
                         zeroclaw_runtime::agent::loop_::TOOL_LOOP_COST_TRACKING_CONTEXT.scope(
                             cost_tracking_context.clone(),
+                        zeroclaw_runtime::agent::tool_receipts::TOOL_LOOP_RECEIPT_CONTEXT.scope(
+                            receipt_scope.clone(),
                         run_tool_call_loop(
                         active_provider.as_ref(),
                         &mut history,
@@ -3195,7 +3206,8 @@ async fn process_channel_message(
                         // call site reflects that coupling explicitly.
                         ctx.receipt_generator
                             .as_ref()
-                            .map(|_| &tool_receipts_collector),
+                            .map(|_| tool_receipts_collector.as_ref()),
+                    ),
                     ),
                     ),
                     ),
@@ -3479,6 +3491,9 @@ async fn process_channel_message(
             );
             // Build the trailing `Tool receipts:` block from the per-turn
             // collector. Empty when receipts are disabled or no tool ran.
+            // Includes receipts from delegate sub-agents because the same
+            // `Arc<Mutex<Vec<String>>>` is forwarded via
+            // `TOOL_LOOP_RECEIPT_CONTEXT` into sub-loops (see #6182).
             let receipts_block = if ctx.show_receipts_in_response {
                 let receipts = tool_receipts_collector
                     .lock()
@@ -7604,6 +7619,136 @@ BTC is currently around $65,000 based on latest tool output."#
         );
     }
 
+    #[tokio::test]
+    async fn process_channel_message_disabled_receipt_generator_emits_no_receipts_anywhere() {
+        // Strict #6182 acceptance criterion: enabled=false must emit no
+        // receipt anywhere — not in any sent message, not in the model's
+        // view of conversation history. `receipt_generator: None` is the
+        // wire-level reflection of `[agent.tool_receipts] enabled = false`.
+        // Distinct from the show_in_response=false test above (which keeps
+        // the generator on but suppresses the trailing block); this one
+        // proves nothing is signed in the first place.
+        let channel_impl = Arc::new(RecordingChannel::default());
+        let channel: Arc<dyn Channel> = channel_impl.clone();
+
+        let mut channels_by_name = HashMap::new();
+        channels_by_name.insert(channel.name().to_string(), channel);
+
+        let runtime_ctx = Arc::new(ChannelRuntimeContext {
+            channels_by_name: Arc::new(channels_by_name),
+            provider: Arc::new(ToolCallingProvider),
+            default_provider: Arc::new("test-provider".to_string()),
+            memory: Arc::new(NoopMemory),
+            tools_registry: Arc::new(vec![Box::new(MockPriceTool)]),
+            observer: Arc::new(NoopObserver),
+            system_prompt: Arc::new("test-system-prompt".to_string()),
+            model: Arc::new("test-model".to_string()),
+            temperature: 0.0,
+            auto_save_memory: false,
+            max_tool_iterations: 10,
+            min_relevance_score: 0.0,
+            conversation_histories: Arc::new(Mutex::new(lru::LruCache::new(
+                std::num::NonZeroUsize::new(MAX_CONVERSATION_SENDERS).unwrap(),
+            ))),
+            pending_new_sessions: Arc::new(Mutex::new(HashSet::new())),
+            provider_cache: Arc::new(Mutex::new(HashMap::new())),
+            route_overrides: Arc::new(Mutex::new(HashMap::new())),
+            api_key: None,
+            api_url: None,
+            reliability: Arc::new(zeroclaw_config::schema::ReliabilityConfig::default()),
+            provider_runtime_options: zeroclaw_providers::ProviderRuntimeOptions::default(),
+            workspace_dir: Arc::new(std::env::temp_dir()),
+            prompt_config: Arc::new(zeroclaw_config::schema::Config::default()),
+            message_timeout_secs: CHANNEL_MESSAGE_TIMEOUT_SECS,
+            interrupt_on_new_message: InterruptOnNewMessageConfig {
+                telegram: false,
+                slack: false,
+                discord: false,
+                mattermost: false,
+                matrix: false,
+            },
+            non_cli_excluded_tools: Arc::new(Vec::new()),
+            autonomy_level: AutonomyLevel::Full,
+            tool_call_dedup_exempt: Arc::new(Vec::new()),
+            multimodal: zeroclaw_config::schema::MultimodalConfig::default(),
+            media_pipeline: zeroclaw_config::schema::MediaPipelineConfig::default(),
+            transcription_config: zeroclaw_config::schema::TranscriptionConfig::default(),
+            hooks: None,
+            model_routes: Arc::new(Vec::new()),
+            query_classification: zeroclaw_config::schema::QueryClassificationConfig::default(),
+            ack_reactions: true,
+            show_tool_calls: true,
+            session_store: None,
+            approval_manager: Arc::new(ApprovalManager::for_non_interactive(&{
+                let mut autonomy = zeroclaw_config::schema::AutonomyConfig::default();
+                autonomy.level = zeroclaw_config::autonomy::AutonomyLevel::Full;
+                autonomy.auto_approve.push("mock_price".to_string());
+                autonomy
+            })),
+            activated_tools: None,
+            cost_tracking: None,
+            pacing: zeroclaw_config::schema::PacingConfig::default(),
+            max_tool_result_chars: 0,
+            context_token_budget: 0,
+            debouncer: Arc::new(zeroclaw_infra::debounce::MessageDebouncer::new(
+                Duration::ZERO,
+            )),
+            receipt_generator: None,
+            show_receipts_in_response: false,
+        });
+
+        process_channel_message(
+            runtime_ctx.clone(),
+            zeroclaw_api::channel::ChannelMessage {
+                id: "msg-1".to_string(),
+                sender: "alice".to_string(),
+                reply_target: "chat-42".to_string(),
+                content: "What is the BTC price now?".to_string(),
+                channel: "test-channel".to_string(),
+                timestamp: 1,
+                thread_ts: None,
+                interruption_scope_id: None,
+                attachments: vec![],
+            },
+            CancellationToken::new(),
+        )
+        .await;
+
+        let sent_messages = channel_impl.sent_messages.lock().await;
+        assert!(
+            !sent_messages.is_empty(),
+            "agent must still respond when receipts are disabled"
+        );
+        assert!(
+            !sent_messages.iter().any(|m| m.contains("zc-receipt-")),
+            "no zc-receipt- token must appear in any sent message when receipts are disabled, got {:?}",
+            sent_messages.as_slice()
+        );
+        assert!(
+            !sent_messages.iter().any(|m| m.contains("Tool receipts:")),
+            "no `Tool receipts:` block must be sent when receipts are disabled, got {:?}",
+            sent_messages.as_slice()
+        );
+
+        // Strict surface check: the model's view of conversation history must
+        // not carry a `[receipt: ` trailer either, otherwise an LLM trained
+        // on echoing receipts could leak signed-looking output even though
+        // nothing was actually signed.
+        let histories = runtime_ctx
+            .conversation_histories
+            .lock()
+            .unwrap_or_else(|e| e.into_inner());
+        for (_key, turns) in histories.iter() {
+            for msg in turns.iter() {
+                assert!(
+                    !msg.content.contains("[receipt: "),
+                    "no `[receipt: ` trailer must appear in conversation history when receipts are disabled, got: {}",
+                    msg.content
+                );
+            }
+        }
+    }
+
     #[tokio::test]
     async fn process_channel_message_telegram_does_not_persist_tool_summary_prefix() {
         let channel_impl = Arc::new(TelegramRecordingChannel::default());

crates/zeroclaw-runtime/src/agent/tool_receipts.rs

@@ -120,6 +120,23 @@ impl ReceiptGenerator {
     }
 }
 
+/// Per-turn receipt forwarding scope, used to thread the generator and
+/// the per-turn collector through delegate sub-loops without changing the
+/// `Tool` trait signature. Mirrors the pattern used by
+/// `TOOL_LOOP_COST_TRACKING_CONTEXT`.
+#[derive(Clone)]
+pub struct ReceiptScope {
+    pub generator: ReceiptGenerator,
+    pub collector: std::sync::Arc<std::sync::Mutex<Vec<String>>>,
+}
+
+tokio::task_local! {
+    /// Set by the orchestrator when `[agent.tool_receipts] enabled = true`.
+    /// `DelegateTool` reads this to forward receipts into sub-agent tool loops
+    /// so subagent tool calls land in the same per-turn collector.
+    pub static TOOL_LOOP_RECEIPT_CONTEXT: Option<ReceiptScope>;
+}
+
 /// Parse a receipt string into (timestamp, hash).
 /// Expected format: `zc-receipt-{timestamp}-{base64url_hash}`
 fn parse_receipt(receipt: &str) -> Option<(u64, &str)> {

crates/zeroclaw-runtime/src/tools/delegate.rs

@@ -788,6 +788,18 @@ impl DelegateTool {
             }
         }
 
+        // Capture the current receipt scope so each spawned sub-agent task
+        // re-enters it. `tokio::spawn` does not propagate task-locals, so
+        // without this `execute_sync`'s `try_with` would resolve to `None`
+        // inside the spawn and the parallel agents would run unsigned even
+        // when the parent turn has receipts enabled. The collector is `Arc`'d
+        // inside `ReceiptScope`, so all parallel agents push into the same
+        // per-turn collector the orchestrator renders after the loop returns.
+        let parent_receipt_scope = crate::agent::tool_receipts::TOOL_LOOP_RECEIPT_CONTEXT
+            .try_with(Clone::clone)
+            .ok()
+            .flatten();
+
         // Spawn all agents concurrently
         let mut handles = Vec::with_capacity(agent_names.len());
         for agent_name in &agent_names {
@@ -804,6 +816,7 @@ impl DelegateTool {
             let agent_name = agent_name.clone();
             let prompt = prompt.to_string();
             let args_clone = args.clone();
+            let receipt_scope = parent_receipt_scope.clone();
 
             handles.push(tokio::spawn(async move {
                 let inner = DelegateTool {
@@ -819,8 +832,13 @@ impl DelegateTool {
                     cancellation_token,
                     memory: None,
                 };
-                let result = Box::pin(inner.execute_sync(&agent_name, &prompt, &args_clone)).await;
-                (agent_name, result)
+                let agent_name_for_return = agent_name.clone();
+                let result = crate::agent::tool_receipts::TOOL_LOOP_RECEIPT_CONTEXT
+                    .scope(receipt_scope, async move {
+                        Box::pin(inner.execute_sync(&agent_name, &prompt, &args_clone)).await
+                    })
+                    .await;
+                (agent_name_for_return, result)
             }));
         }
 
@@ -1153,6 +1171,17 @@ impl DelegateTool {
         let agentic_timeout_secs = agent_config
             .agentic_timeout_secs
             .unwrap_or(self.delegate_config.agentic_timeout_secs);
+        // Forward the per-turn receipt scope from the parent loop so subagent
+        // tool calls land in the same collector as the top-level turn. When
+        // receipts are disabled (or no scope is set, e.g. CLI / background
+        // delegate spawn) this resolves to `None` and the sub-loop runs
+        // unsigned, matching the parent.
+        let receipt_scope = crate::agent::tool_receipts::TOOL_LOOP_RECEIPT_CONTEXT
+            .try_with(Clone::clone)
+            .ok()
+            .flatten();
+        let receipt_generator = receipt_scope.as_ref().map(|s| &s.generator);
+        let collected_receipts = receipt_scope.as_ref().map(|s| s.collector.as_ref());
         let result = tokio::time::timeout(
             Duration::from_secs(agentic_timeout_secs),
             run_tool_call_loop(
@@ -1181,8 +1210,8 @@ impl DelegateTool {
                 0,    // context_token_budget: 0 = disabled for subagents
                 None, // shared_budget: TODO thread from parent in future
                 None, // channel: delegate subagents don't support approval
-                None, // receipt_generator
-                None, // collected_receipts
+                receipt_generator,
+                collected_receipts,
             ),
         )
         .await;
@@ -1899,6 +1928,81 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn execute_agentic_forwards_receipt_scope_into_subagent_loop() {
+        // Receipt forwarding through the delegate sub-loop is the activation
+        // pass for #6182's delegate.rs:1184 acceptance criterion. With
+        // `TOOL_LOOP_RECEIPT_CONTEXT` scoped, every sub-tool call inside the
+        // delegate must produce a receipt that lands in the same per-turn
+        // collector the parent passed in. Without the task-local read in
+        // `execute_sync` this test fails: the collector stays empty because
+        // the sub-loop runs unsigned with `None, None` for the receipt args.
+        use crate::agent::tool_receipts::{
+            ReceiptGenerator, ReceiptScope, TOOL_LOOP_RECEIPT_CONTEXT,
+        };
+
+        let config = agentic_config(vec!["echo_tool".to_string()], 10);
+        let tool = DelegateTool::new(HashMap::new(), None, test_security())
+            .with_parent_tools(Arc::new(RwLock::new(vec![Arc::new(EchoTool)])));
+
+        let collector: Arc<std::sync::Mutex<Vec<String>>> =
+            Arc::new(std::sync::Mutex::new(Vec::new()));
+        let scope = ReceiptScope {
+            generator: ReceiptGenerator::new(),
+            collector: Arc::clone(&collector),
+        };
+
+        let provider = OneToolThenFinalProvider;
+        let result = TOOL_LOOP_RECEIPT_CONTEXT
+            .scope(Some(scope), async {
+                tool.execute_agentic("agentic", &config, &provider, "run", 0.2)
+                    .await
+            })
+            .await
+            .unwrap();
+
+        assert!(
+            result.success,
+            "delegate sub-loop must complete: {result:?}"
+        );
+        let receipts = collector.lock().unwrap();
+        assert_eq!(
+            receipts.len(),
+            1,
+            "expected exactly one receipt for the single echo_tool sub-call, got: {:?}",
+            receipts.as_slice()
+        );
+        assert!(
+            receipts[0].starts_with("echo_tool: zc-receipt-"),
+            "sub-tool receipt must be tagged with the tool name and a zc-receipt- HMAC token, got: {}",
+            receipts[0]
+        );
+    }
+
+    #[tokio::test]
+    async fn execute_agentic_emits_no_receipts_when_scope_absent() {
+        // Backward-compat for callers without a scoped receipt context (CLI,
+        // background spawn that does not forward scope, tests). The sub-loop
+        // must run unsigned and the agent output must not carry a
+        // `[receipt: ` trailer.
+        let config = agentic_config(vec!["echo_tool".to_string()], 10);
+        let tool = DelegateTool::new(HashMap::new(), None, test_security())
+            .with_parent_tools(Arc::new(RwLock::new(vec![Arc::new(EchoTool)])));
+
+        let provider = OneToolThenFinalProvider;
+        let result = tool
+            .execute_agentic("agentic", &config, &provider, "run", 0.2)
+            .await
+            .unwrap();
+
+        assert!(result.success);
+        assert!(
+            !result.output.contains("[receipt: "),
+            "no receipt trailer must appear in agent output when receipts are disabled, got: {}",
+            result.output
+        );
+    }
+
     #[tokio::test]
     async fn execute_agentic_propagates_provider_errors() {
         let config = agentic_config(vec!["echo_tool".to_string()], 10);