[AAASM-3491] 🐛 (python-sdk): Honor live op-control signal in tool path

[Chisanan232]

Description

Honors the gateway's live op-control kill switch (PolicyService.OpControlStream) in the Python SDK tool path. The SDK already shipped a complete OpControlSubscriber (agent_assembly/op_control.py) but it was orphaned — never consulted by the per-tool chokepoint, so an operator terminate/pause never reached a running tool.

What lands here:

• agent_assembly/core/runtime_interceptor.py: RuntimeQueryInterceptor.check_tool_start now consults an optional OpControlSubscriber for the call's op_id before the native runtime query — a terminated op is denied immediately (short-circuit) and a paused op blocks cooperatively in await_op until resume. Threaded through build_governance_interceptor(op_control=...). op_id resolves from an explicit op_id kwarg or "{trace_id}:{span_id}".
• agent_assembly/op_control.py: docstring updated — the subscriber now has a wiring point (no longer fully orphaned); automatic construction at init_assembly time remains a follow-up.

This is the SDK-layer companion to the authoritative runtime enforcement in ai-agent-assembly/agent-assembly PR #1176 (where the runtime's own OpControlStream consumer halts terminated ops at the query_policy/CheckAction path). Node/Go SDKs are deferred to AAASM-3500 / AAASM-3501 (their consumers already exist but are dead/unexported).

Type of Change

• 🔧 Bug fix

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-3491
• Cross-repo: ai-agent-assembly/agent-assembly PR #1176
• Follow-ups: AAASM-3500 (node-sdk), AAASM-3501 (go-sdk)

Testing

• Unit tests added/updated

New tests prove: a terminate for the call's op_id denies the tool before the runtime is queried (short-circuit), a paused op consults await_op then proceeds on resume, a call without trace identity skips op control, and the op_id resolver composes trace_id/span_id.

pytest test/ → 577 passed, 13 skipped. ruff check / ruff format --check clean; mypy clean (pre-existing _core/grpc baseline only, no new errors). Pre-commit hooks pass.

QA evidence: agent-assembly repo verification-reports/base-branch-2026-06/qa3464-ops-registry-control.md.

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed
• All tests passing

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

🔎 Review (Claude Code) — ready for approval

CI: ✅ All green — 17 checks pass, 0 failures (Analyze/CodeQL/SonarCloud, codecov, integration + unit suites). pytest test/ 577 passed locally.

Scope vs AAASM-3491 (python-sdk surface): ✅ Fully covers the reported gap. The ticket flagged op_control.py as orphaned (referenced only by an exception docstring). This PR wires OpControlSubscriber into RuntimeQueryInterceptor.check_tool_start before the native runtime query, threaded via build_governance_interceptor(op_control=...). New tests prove the four contract points: terminate short-circuits before the runtime is queried, pause consults await_op then proceeds on resume, a call without trace identity skips op-control, and the op_id resolver composes trace_id/span_id.

Companion to agent-assembly #1176 (authoritative runtime enforcement). Node/Go are tracked as AAASM-3500/3501.

Note (non-blocking): automatic OpControlSubscriber construction at init_assembly time is acknowledged as a follow-up — the wiring point exists; auto-wiring is the next step.

Verdict: Scope complete, CI green, regression tests present. Ready to approve & merge pending Pioneer review. Bug AAASM-3491 stays open until merge + re-verification under AAASM-3464 (per the QA gate).