feat: move stream approvals to AgentStream.Approve and deprecate Agent.OnApproval

[vinodvx]

Description

• Add AgentStream.Approve / StreamHandle.Approve as the preferred stream HITL path (token from CUSTOM events).
• Keep Agent.OnApproval / Runtime.OnApproval as deprecated wrappers until v0.4.0; share private approve in local and Temporal runtimes.
• Point docs, README, examples, and CLI at stream.Approve only. Run path stays WithApprovalHandler + req.Respond.

Test plan

• go test ./pkg/agent/ ./internal/runtime/local/ ./internal/runtime/temporal/ -count=1
• cd examples && go run ./agent_with_subagents — answer y/n on delegation approval
• Spot-check Run approval still works: go run ./agent_with_tools/approval

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactor / chore

Related issues

Closes #55

Checklist

• I have run task check
• I have run task examples:all
• I have run task tidy if I added or removed dependencies
• Commit messages follow conventional commits (e.g. feat:, fix:, docs:)
• I have added/updated tests for my changes
• Documentation is updated if needed

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agent-sdk-go	🟢 Ready	View Preview	Jul 27, 2026, 3:28 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agent-sdk-go	🟡 Building	–	Jul 27, 2026, 3:28 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 42.30769% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/local/stream_handle.go	33.33%	4 Missing ⚠️
internal/runtime/temporal/stream_handle.go	0.00%	4 Missing ⚠️
internal/runtime/temporal/runtime.go	25.00%	3 Missing ⚠️
internal/runtime/local/runtime.go	60.00%	2 Missing ⚠️
pkg/agent/agent_stream.go	50.00%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!