fix(ai-red-teaming): register provision_environment and generate_agentic_suite_attack as tools (ENG-8467)

[GangGreenTemperTatum]

Summary

Fixes ENG-8467. In the ai-red-teaming capability, provision_environment (and, found by a systematic variant scan, generate_agentic_suite_attack) were defined without the registration decorator. Dreadnode's capability loader (_discover_python_tools) only registers module attributes that are Tool instances (@tool/@safe_tool) or Toolset instances — a bare function is silently dropped with no error.

As a result, agents following the shipped skills and agent prompt hit:

Tool 'ai_red_teaming__provision_environment' not found.

on the first step of every hosted-target run (ml-extraction-*, *-mesh), and the documented "run all possible attacks" path (generate_agentic_suite_attack) shipped with no executable tool. The skill provisioning-and-lifecycle explicitly forbids the CLI fallback ("provision_environment is the only supported path"), so the workflow was hard-blocked.

Root cause

• tools/environments.py — provision_environment lacked @safe_tool (its siblings list_environments / teardown_environment have it). Introduced undecorated in 236a798e; fixes a0b356b (fix(ai-red-teaming): recover cleanly from transient tool errors + right endpoint per target (ENG-8427) #141) and 172e429 (fix(ai-red-teaming): resolve bare task names across accessible orgs + steer off the CLI (ENG-8434) #142) referenced it by name without verifying registration.
• tools/attacks.py — generate_agentic_suite_attack lacked @safe_tool despite being documented as a first-class tool in agents/ai-red-teaming-agent.md.

Changes

File	Change
tools/environments.py	@safe_tool on provision_environment; not-found task now returns a plain Error: string with the resolution hint instead of raising (kept raise for non-not-found so safe_tool's transient-retry still applies); comment marking teardown_session_environments as intentionally not a tool; note documenting the test coupling at the lazy TaskEnvironment import
tools/attacks.py	@safe_tool on generate_agentic_suite_attack
tests/test_tool_surface.py (new)	Regression + invariant tests (see below)
skills/error-troubleshooting/SKILL.md	Truthfulness fix: removed the false "catches the 404 and retries as <org>/<name> automatically" claim — the tool does not auto-retry, and qualification does not bypass the visibility rule
capability.yaml	Version 1.15.0 → 1.16.0 (two tools added to the public tool surface; repo convention bumps on every change)

Tests

tests/test_tool_surface.py — four-layer coverage:

1. Regression (ENG-8467): provision_environment and generate_agentic_suite_attack are registered Tool instances with the expected names — fails pre-fix, passes post-fix (verified via stash).
2. Invariant (general form): every skill allowed-tools name must resolve to a registered Tool or be explicitly allowlisted as platform-provided (PLATFORM_PROVIDED_TOOLS — the 5 trace-analysis-advisor analytics tools). Catches both the missing-decorator class and documented-but-implemented-nowhere phantom tools.
3. Error contract: not-found → Error: string with hint (never raises); other failures → formatted Error: string via safe_tool (never a traceback).
4. E2E (real loader): the patched capability loaded through the actual SDK load_capability discovery path registers both tools.

Verification performed

• Real-loader E2E: provision_environment + generate_agentic_suite_attack registered as Tool instances; fails on pre-fix tree (loader drops both), passes post-fix.
• Regression tests: red pre-fix / green post-fix (stash cycle).
• Full AIRT suite: 226 passed; the 11 failures are environmental and reproduce byte-identically on origin/main (sandbox lacks ~/.dreadnode/airt/my-org/other-ws scaffold, attack_runner image assertion vs installed SDK, missing pytest-asyncio plugin). Note: CI (ci.yml) runs ruff + YAML only; capability tests are author-owned and were run locally (pytest under Python 3.13 + SDK editable).
• Ruff CI gate E9,F63,F7,F82: pass. The only E/F/W findings in the touched modules are 2 pre-existing (E402 attacks.py:29, F541 environments.py:359), both in untouched code. New test file is ruff-clean and ruff format-clean.
• YAML frontmatter/capability.yaml validation: pass.
• Scanned all capabilities for the same missing-decorator pattern (AST scan over every tools/*.py): the only two instances are fixed here; remaining public-undecorated defs are intentional helpers used by @tool_methods or assessment plumbing.

Follow-ups (out of scope for this PR)

• skills/trace-analysis-advisor/SKILL.md documents 5 tools (analyze_attack_effectiveness, suggest_optimal_transforms, predict_attack_success, identify_vulnerability_patterns, get_historical_metrics) that exist nowhere in the repo or SDK — documented placeholders for a platform ClickHouse analytics service. Now surfaced by the new invariant via PLATFORM_PROVIDED_TOOLS; either the platform should expose them or the skill should be updated.

Test plan

uv run --with dreadnode --with pytest pytest capabilities/ai-red-teaming/tests/test_tool_surface.py