feat(sdk/agent): Handoff DSL; deprecate sdk-internal tool implementations (4/4)

[lIang70]

Summary

Final PR (4 of 4) in the v0.2.x additive SDK batch. No [skip-tag:sdk]
marker — merging this PR triggers the cumulative sdk/v0.2.9 tag covering
PRs #74, #75, #76, and this one.

sdk/agent — Handoff DSL

Declarative inter-agent control transfer that surfaces as an LLM-callable tool:

• Handoff / HandoffArgs / HandoffEvent value types describing intent.
• HandoffTool(h) — builds a tool.Tool from a Handoff entry; the tool
  signals intent only and never mutates the board directly.
• HandoffTools(ctx, req, hs) — request-scoped filter over available handoffs
  (per-Request Filter callback, agent allow-listing, etc.).
• HandoffDecider(hs) — agent.Decider that observes BeforeFinalize,
  detects the first matching handoff tool call, records the event on the
  board under HandoffStateKey, and triggers finalize via
  HandoffFinalizeReason.
• HandoffFromResult(res) retrieves the event from an agent.Result.
• DefaultHandoffToolName(agentID) for canonical naming.

Handoff stays in sdk/agent rather than sdkx/tool/... because it is an
internal agent-orchestration primitive — it has no external protocol surface
and is consumed by agent.Run itself.

Deprecation: sdk-internal LLM tool implementations

Marked // Deprecated: (no behaviour change) and scheduled for migration to
sdkx/tool/... in v0.3.0:

Package	Symbol(s)	New home (v0.3.0)
sdk/knowledge	NewSearchServiceTool, NewPutServiceTool	sdkx/tool/knowledge
sdk/kanban	SubmitTool, TaskContextTool, WithKanban, KanbanFrom	sdkx/tool/kanban
sdk/history	ToolDeps, RegisterTools	sdkx/tool/history

Rationale: sdk should host stable interfaces and engine primitives; concrete
LLM tool implementations belong in sdkx, mirroring the existing sdkx/llm/...
provider layout. Migration guide in docs/migrations/v0.3.0.md.

docs/migrations/v0.3.0.md

Walks through:

• The sdk ↔ sdkx layering rule and why these tools relocate.
• A symbol-by-symbol relocation table.
• Why sdk/agent.Handoff stays in sdk.
• Planned sdkx/tool/memory (Anthropic-compatible) and sdkx/tool/mcp clients.
• The sdk/workflow deletion (already deprecated).
• A backwards-compatibility shim plan for users who can't switch immediately.

.gitignore

Adds !docs/migrations/ and !docs/migrations/** to the whitelist so the
new migration doc tracks. docs/roadmap.md remains intentionally ignored.

Test plan

• go vet ./sdk/agent/... ./sdk/history/... ./sdk/kanban/... ./sdk/knowledge/...
• go test ./sdk/agent/... ./sdk/history/... ./sdk/kanban/... ./sdk/knowledge/... -count=1
• sdk/agent/handoff_test.go covers DefaultHandoffToolName,
  HandoffTool definition + panic handling, OnInvoke callback,
  HandoffTools filter behaviour, HandoffDecider first-match-wins and
  no-match paths, and HandoffFromResult safety on missing state.
• No new tests for the deprecated symbols — behaviour is unchanged and
  existing tests in sdk/{knowledge,kanban,history} remain green.

Release notes

This PR is additive only. Merging it cuts sdk/v0.2.9 (cumulative across
PRs #74, #75, #76, and this one). All v0.2.x changes are backwards-compatible;
breaking changes land in v0.3.0 per the migration guide.

Made with Cursor