[AAASM-3402] ✨ (python-sdk): Wire native gateway check/register into SDK lifecycle

[Chisanan232]

Description

Wires the SDK's pre-execution policy check and agent registration to the native aa-sdk-client path and retires the legacy raw-REST register/check, closing the unwired-enforcement gap (AAASM-3021 family).

What changed

• init_assembly now connects a single native RuntimeClient, calls its register() (AAASM-3399) on startup so the agent registers with the gateway and the issued credential token is stored on the shared client, and reuses that same client for the RuntimeQueryInterceptor's query_policy checks (so every check authenticates).
• A native deny decision now actually blocks the tool call before it runs, via the adapter check_tool_start contract.
• Removed GatewayClient.register_agent() and GatewayClient.check_policy_compliance() — these issued raw HTTP to the core, which ADR 0004 forbids. report_edge()/dispatch_tool() (genuinely HTTP routes) are retained.
• Corrected in-repo prose (README + docstrings) that claimed registration/policy checks go to core over HTTP; restated as SDK → aa-sdk-client → core over gRPC/UDS.

Why
Previously the public SDK never called the native register/query_policy; the in-process check was effectively a no-op, so a denied action was not blocked at the SDK layer even with a reachable core. This PR closes that gap.

How it works (enforcement semantics preserved)

• enforce: register failure or an unreachable/erroring runtime → fail closed (init aborts on register failure; queries deny).
• observe / disabled (or no mode): register failure is swallowed and queries proceed → fail open.
• Native extension missing entirely: SDK fast path is simply not engaged (bare client, every mode) — unchanged.

Follow-up (documented, out of scope): the native register() signature does not yet carry the topology/lineage fields (parent_agent_id, team_id, delegation_reason, spawned_by_tool, depth) that the old REST register forwarded. Those fields are still stored on GatewayClient; forwarding them over the native register call is a tracked follow-up.

Type of Change

• ✨ New feature
• ♻️ Refactoring
• 📚 Documentation update

Breaking Changes

• No
• Yes (please describe below)

GatewayClient.register_agent() and GatewayClient.check_policy_compliance() are removed. These were internal-facing helpers (not part of the supported init_assembly flow); the public entrypoint init_assembly is unchanged and now performs registration automatically over the native path.

Related Issues

• Related JIRA ticket: AAASM-3402
• Builds on AAASM-3399 (native register()/query_policy() shim)

Closes AAASM-3402

Testing

Describe the testing performed for this PR:

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed

New regression tests (test/unit/core/test_init_registration.py + _fake_core.py fakes):

• init_assembly calls native register on startup.
• A native deny makes the adapter interceptor's check_tool_start block (the core of the fixed bug).
• observe swallows a registration failure; enforce propagates it (fail closed).

Retired the REST register/check unit + integration tests; kept the topology-field-storage tests.

Local validation (native _core not built on this macOS host, so native-only suites skip as designed):

• .venv/bin/python -m pytest test/ → 565 passed, 13 skipped
• .venv/bin/mypy (CI config, --ignore-missing-imports) → clean
• pre-commit run (black / isort / autoflake / mypy) on changed files → clean

CI for python-sdk is minimal (mypy type-check workflow; no ruff gate in pre-commit). Validated locally as above.

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

❌ Patch coverage is 93.18182% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agent_assembly/core/runtime_interceptor.py	90.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[Chisanan232]

Claude Code — PR review (AAASM-3402)

Verdict: ✅ ready to merge. CI all green (CI Success gate, unit + integration, SonarCloud, codecov, CodeQL; only e2e/deploy intentionally skipped). Scope clean: gateway.py, core/assembly.py, core/runtime_interceptor.py, README + 5 test files.

Scope reviewed

• Root cause confirmed & fixed: the public SDK never called native register/query_policy (from AAASM-3399), so the pre-exec check was a no-op — a denied action was not blocked at the SDK layer. ✅ Now init_assembly connects one native RuntimeClient, registers on startup (token stored on the shared client), and the same client backs the RuntimeQueryInterceptor, so deny actually blocks the tool.
• Legacy raw-REST GatewayClient.register_agent() / check_policy_compliance() (ADR-0004 violations) removed. ✅
• Enforcement semantics preserved: enforce = fail-closed, observe/disabled = fail-open. ✅
• README + docstrings corrected to native gRPC path. Regression tests: register-on-init + deny-blocks. 565 pass / 13 skip (native _core not built on macOS host — expected).

Follow-up filed (not a blocker)

The native register() does not yet forward the topology/lineage fields (parent_agent_id, team_id, …) the old REST register sent — they're still stored on GatewayClient but not carried over the native path. This matters because team_id drives team-budget attribution and the topology graph. Tracked as a separate ticket under Epic AAASM-3395 (likely needs the Register proto to carry these fields → affects all SDKs). Closing the unwired-enforcement gap here is correct and self-contained.

Good to merge.