feat: RemoteGuard — remote kill switch for AI agents

[bmdhodl]

Summary

• RemoteGuard — new guard that polls the dashboard /api/v1/status endpoint via a background thread. When the dashboard sends a kill signal, check() raises AgentKilled. Linked BudgetGuard limits are updated in-place from remote budget changes. Falls back gracefully on network failure (agent keeps running with local guards).
• BudgetGuard.from_remote() — class method that fetches initial budget config from the dashboard API with local fallback defaults.
• HttpSink heartbeat — new heartbeat_interval and heartbeat_guards params emit periodic heartbeat events with current guard state, so the dashboard knows the agent is alive and its current spend.

This is the SDK side of the remote kill switch (Move 1 of the platform-first strategy). The dashboard API endpoints (POST /api/v1/agents/:id/kill, GET /api/v1/status) are the next step in the dashboard repo.

What changed

File	Change
sdk/agentguard/guards.py	+AgentKilled exception, +RemoteGuard class, +BudgetGuard.from_remote()
sdk/agentguard/__init__.py	Export new symbols
sdk/agentguard/sinks/http.py	+heartbeat mechanism
sdk/tests/test_guards.py	+15 RemoteGuard tests, +3 BudgetGuard.from_remote() tests
sdk/tests/test_http_sink.py	+2 heartbeat tests
sdk/tests/test_exports.py	Updated expected export set
sdk/tests/test_architecture.py	Added RemoteGuard to THREAD_SAFE_CLASSES

Design decisions

• Zero new dependencies — uses urllib.request (same as HttpSink)
• Daemon thread — background poller is a daemon thread (same pattern as HttpSink flush thread)
• Thread-safe — _lock on all mutable state, added to THREAD_SAFE_CLASSES
• Graceful degradation — network failures are silently caught; agent keeps running with local guards
• guards.py stays at 797 lines (under 800 limit)

Test plan

• RemoteGuard receives kill signal → raises AgentKilled
• RemoteGuard receives budget update → modifies linked BudgetGuard
• Network failure → agent continues (graceful fallback)
• auto_check() delegates to check()
• reset() clears kill state
• start() is idempotent
• BudgetGuard.from_remote() fetches remote config
• BudgetGuard.from_remote() falls back on network failure
• Heartbeat emits events with guard state at configured interval
• Heartbeat disabled by default
• 530 tests pass, 93.73% coverage, all 9 architectural invariants pass

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.