[AAASM-3540] ✨ (adapters): Add Haystack framework adapter

[Chisanan232]

Description

Adds full Python SDK governance support for deepset Haystack (pip install haystack-ai, imported as haystack).

The adapter intercepts tool execution at haystack.tools.Tool.invoke(**kwargs) — the single execution chokepoint in Haystack 2.x. Both the bare Tool.invoke() path and the agentic Agent → ToolInvoker tool-call loop ultimately call tool.invoke(**final_args) (via ToolInvoker._make_context_bound_invoke), so patching Tool.invoke governs every tool execution from one place.

Governance behavior mirrors the CrewAI / Pydantic AI tool-call adapters: a check_tool_start pre-execution allow/deny/pending gate, an optional wait_for_tool_approval pending flow, and post-execution record_result / on_tool_end auditing. Unknown / malformed verdicts fail closed under the enforce posture (AAASM-3107).

HaystackAdapter is registered in the builtin registry and priority map, so init_assembly() auto-detects and hooks Haystack whenever it is importable.

Type of Change

• ✨ New feature

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-3540 (parent AAASM-3535)

Testing

• Unit tests added/updated

test/unit/adapters/haystack/test_patch.py (24 tests). Proves real governance, not a no-op (AAASM-3528 lesson):

• test_real_haystack_tool_is_genuinely_governed — drives a real haystack.tools.Tool; on deny the wrapped function never runs (side_effects == []) and a [BLOCKED by governance policy] string is returned; after revert() the same tool runs normally. This is the negative control — it fails if the patch is a pass-through.
• test_real_haystack_tool_allow_runs_and_records — real Tool runs on allow and the result is recorded.
• deny/allow/pending/timeout flows, idempotent apply, clean revert, and AAASM-3107 fail-closed parametrized cases.

Validated locally: full suite pytest test/ → 603 passed, 13 skipped; ruff check clean on new files; mypy agent_assembly clean for the new module (only pre-existing _core/grpc-stub errors remain); pre-commit (black/isort/autoflake/mypy) green.

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed (README + docs/compatibility/frameworks.md)
• All tests passing

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.78882% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agent_assembly/adapters/haystack/adapter.py	64.70%	6 Missing ⚠️
agent_assembly/adapters/haystack/patch.py	97.14%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate failed

Failed conditions
7.7% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[Chisanan232]

Claude Code — review result

✅ Real CI green. Only SonarCloud fails — acceptance gate, ignored per standing rule.

• Adapter: hooks haystack.tools.Tool.invoke (the single tool-execution chokepoint in Haystack 2.x; ToolInvoker routes through it). Registered, get_supported_versions() = >=2.0.0,<3.0.
• Governance proven: real Tool through a real ToolInvoker — on deny the body never runs; negative-control test fails if the patch is a no-op (AAASM-3528 lesson). ✔
• Shared files (registry.py, README.md, docs/compatibility/frameworks.md): trivial keep-all overlap with the 4 sibling framework PRs — distinct registry key, no semantic collision. I'll rebase onto master (keep-all) after siblings merge.

Ready to merge. Merge before the examples PR #149 + a python-sdk release (the example import resolves only after b5 is on PyPI). Full cross-repo review on AAASM-3535.

[Chisanan232]

Claude Code — SonarCloud new-code review (round 2)

New-code pass: 0 issues — no new Security / Reliability / Maintainability / Hotspot / Coverage findings.

The quality gate is red solely on new_duplicated_lines_density = 7.7% (> 3%). This is the Haystack adapter mirroring the established CrewAI adapter's decision/format plumbing — intentional template parity across the framework adapters (operator decision: not worth a cross-adapter refactor of proven code). Per the standing rule, this acceptance-dimension gate can be overridden at merge.

✅ Ready to merge (modulo the trivial keep-all rebase as siblings land).