feat(tools): mark alias tools with deprecation metadata

Add `wrap_with_deprecation_notice` helper in the subagent module that
merges a `_deprecation` block into a ToolResult's metadata. Applied
exclusively on alias invocations:

- `spawn_agent` → use `agent_spawn` (removed in v0.8.0)
- `delegate_to_agent` → use `agent_spawn` (removed in v0.8.0)
- `close_agent` → use `agent_cancel` (removed in v0.8.0)
- `send_input` → use `agent_send_input` (removed in v0.8.0)

Canonical names are unaffected. Each alias invocation also emits a
`tracing::warn` so the deprecation appears in audit logs. Documents
the deprecation schedule in `docs/TOOL_SURFACE.md`. Four unit tests
verify the notice shape and that canonical tools stay clean.

Refs #72

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/TOOL_SURFACE.md

@@ -79,6 +79,37 @@ no longer pollute the model's tool list):
 - `close_agent` → use `agent_cancel`.
 - `assign_agent` → use `agent_assign`.
 
+## Deprecation schedule (v0.6.2 → v0.8.0)
+
+The alias tools below still execute successfully but now attach a
+`_deprecation` block to every result they return. Models should migrate to
+the canonical name before v0.8.0, when the aliases will be removed.
+
+| Deprecated alias | Canonical name | Warning since | Removal |
+|---|---|---|---|
+| `spawn_agent` | `agent_spawn` | v0.6.2 | v0.8.0 |
+| `delegate_to_agent` | `agent_spawn` | v0.6.2 | v0.8.0 |
+| `close_agent` | `agent_cancel` | v0.6.2 | v0.8.0 |
+| `send_input` | `agent_send_input` | v0.6.2 | v0.8.0 |
+
+The `_deprecation` block shape:
+
+```json
+{
+  "_deprecation": {
+    "this_tool": "spawn_agent",
+    "use_instead": "agent_spawn",
+    "removed_in": "0.8.0",
+    "message": "Tool 'spawn_agent' is deprecated; switch to 'agent_spawn' before v0.8.0."
+  }
+}
+```
+
+This block is merged into the tool result's `metadata` object alongside any
+other metadata keys (e.g. `status`, `timed_out`) so it does not displace
+existing metadata.  A one-line deprecation warning is also emitted to the
+audit log at `tracing::warn` level every time an alias is invoked.
+
 ## Why we don't ship a single `bash` tool
 
 Single-`bash` agents (Claude Code's design) are powerful but hand the model