[VibeSWE]

Stacked on #62 (base upstream/tool-catalog-1831). Retarget to main after #62 merges.

Problem

Follow-up 20 from the #62 review. execute_oss_tool and execute_oss_tool_with_query_headers (in src/tool_executor.rs, inherited from upstream 32979cb) are pub. They look up tools in the full oss_tool_specs(), which includes the alert action tools create_alert, enable_alert, disable_alert, evaluate_alert and create_alert_target. They then validate arguments and dispatch. Unlike call_tool_registry, they skip the Users.session_exists check, check_suspension_for_tenant(tenant, Action::Query), and the global authorize(Query, None). They also don't restrict execution to the read catalog. Each tool's own authorize() still runs.

I confirmed this against the current code. Nothing in the fork calls these helpers, so this is a hazard for future callers, not a live bug.

Fix

Doc comments only, with no runtime change. execute_oss_tool gains a "Caller obligations" section listing the four gates a caller must apply: session validity, tenant suspension, global Query authorization, and tool restriction plus confirmation for action tools. execute_oss_tool_with_query_headers points back to that list.

Why documentation rather than a shared gate helper:

• The helpers have no callers in the fork. A helper would be dead code, and it would add another divergence from upstream.
• Upstream says Enterprise applies its own agent policy before calling these functions. Adding gates inside them would change upstream semantics, and Enterprise might double-gate or reject differently.
• If the fork ever adds a caller, that caller should be reviewed against this list. At that point, extracting the gates from call_tool_registry into a shared helper is the natural next step.

docs/tool-api.md is unchanged because nothing caller-visible changed.

Tests

No code changed, so I added no new tests.

• cargo clippy -- -D warnings: clean
• cargo clippy --all-targets: no warnings in src/tool_executor.rs
• RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc --no-deps --lib: clean, so the new intra-doc links resolve
• cargo test --lib tool_: 38 passed, 0 failed

Upstream fidelity

The diff only adds doc comments, about 24 lines, to two upstream functions, so the risk of merge conflicts is minimal. I've drafted an equivalent docs-only upstream change but haven't filed it.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}