bamboo-hooks 2026.10.13

Lifecycle hook dispatch and external script orchestration for Bamboo
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use super::*;
use async_trait::async_trait;
use std::sync::atomic::{AtomicBool, Ordering};

struct DeclaredHook {
    declared: Arc<AtomicBool>,
    result: HookResult,
}

#[async_trait]
impl AgentHook for DeclaredHook {
    fn point(&self) -> AgentHookPoint {
        AgentHookPoint::AfterToolExecution
    }

    fn may_suspend(&self) -> bool {
        self.declared.load(Ordering::SeqCst)
    }

    async fn run(&self, _: AgentHookPoint, _: &HookPayload, _: &Session) -> HookResult {
        self.result.clone()
    }
}

fn payload() -> HookPayload {
    HookPayload::ToolResult {
        tool_name: "loop_control".into(),
        tool_call_id: "native-contract".into(),
        outcome: bamboo_domain::HookToolOutcome {
            success: true,
            result: Some("original immutable receipt".into()),
            error: None,
            needs_human: false,
            duration_ms: 0,
        },
    }
}

#[tokio::test]
async fn non_suspending_declaration_is_frozen_and_violation_aborts_with_context() {
    let declared = Arc::new(AtomicBool::new(false));
    let mut runner = HookDispatcher::new();
    runner.register(Arc::new(DeclaredHook {
        declared: declared.clone(),
        result: HookResult::WithContext {
            text: "outer feedback".into(),
            result: Box::new(HookResult::WithContext {
                text: "inner feedback".into(),
                result: Box::new(HookResult::Suspend {
                    reason: "requested wait".into(),
                }),
            }),
        },
    }));
    declared.store(true, Ordering::SeqCst);
    assert!(!runner.has_suspending_hooks_for(AgentHookPoint::AfterToolExecution));
    let session = Session::new("non-suspending-contract", "synthetic-only");
    let report = runner
        .run_hooks(AgentHookPoint::AfterToolExecution, &payload(), &session)
        .await;
    assert!(
        matches!(&report.outcome.decision, HookResult::Abort { reason }
        if reason.contains("non-suspending") && reason.contains("requested wait"))
    );
    assert_eq!(
        report.outcome.injected_contexts,
        ["outer feedback", "inner feedback"]
    );
    assert_eq!(report.executions.len(), 1);
    assert!(matches!(
        &report.executions[0].result,
        HookResult::WithContext { .. }
    ));
}

#[tokio::test]
async fn non_suspending_declaration_preserves_allow_deny_ask_and_feedback() {
    for decision in [
        HookResult::Continue,
        HookResult::Allow,
        HookResult::Deny {
            reason: "trusted denial".into(),
        },
        HookResult::Ask,
        HookResult::Abort {
            reason: "trusted abort".into(),
        },
    ] {
        let mut runner = HookDispatcher::new();
        runner.register(Arc::new(DeclaredHook {
            declared: Arc::new(AtomicBool::new(false)),
            result: HookResult::WithContext {
                result: Box::new(decision.clone()),
                text: "retained feedback".into(),
            },
        }));
        let session = Session::new("non-suspending-controls", "synthetic-only");
        let report = runner
            .run_hooks(AgentHookPoint::AfterToolExecution, &payload(), &session)
            .await;
        assert_eq!(report.outcome.decision, decision);
        assert_eq!(report.outcome.injected_contexts, ["retained feedback"]);
        assert_eq!(report.executions.len(), 1);
    }
}

struct UnknownHook;

#[async_trait]
impl AgentHook for UnknownHook {
    fn point(&self) -> AgentHookPoint {
        AgentHookPoint::AfterToolExecution
    }

    async fn run(&self, _: AgentHookPoint, _: &HookPayload, _: &Session) -> HookResult {
        HookResult::Suspend {
            reason: "ordinary suspension".into(),
        }
    }
}

#[tokio::test]
async fn unknown_native_hook_keeps_original_suspension_contract() {
    let mut runner = HookDispatcher::new();
    runner.register(Arc::new(UnknownHook));
    assert!(runner.has_suspending_hooks_for(AgentHookPoint::AfterToolExecution));
    let report = runner
        .run_hooks(
            AgentHookPoint::AfterToolExecution,
            &payload(),
            &Session::new("ordinary-native", "synthetic-only"),
        )
        .await;
    assert_eq!(
        report.outcome.decision,
        HookResult::Suspend {
            reason: "ordinary suspension".into()
        }
    );
}