Tighten ctx-suspend plumbing and trim docs

Address review feedback:

- Move ErrSuspendForCheckpoint from checkpoint.go to errors.go
  next to the rest of the agent error declarations; drop the
  colon in the error string so it matches the existing
  `agent run <event>` style used by the supervisor sentinels.
- Replace the inline `outerCtx := ctx; ctx = context.WithoutCancel(ctx)`
  pattern with a small `suspendShield` helper in context.go used
  by coreLoop, resumeWithOpts, and resumeNested. Reads more
  cleanly and stops surfacing the WithoutCancel mechanism at
  every call site.
- Trim the doc comments on Run, RunStreamed, Resume, Restore, the
  ErrSuspendForCheckpoint declaration, and the saveCtx comment in
  restoreNestedSuspended down to the contract bullet.

Signed-off-by: Aurélien Sibiril <81782+aureliensibiril@users.noreply.github.com>

pkg/agent/restore.go

@@ -25,11 +25,8 @@ import (
 
 // Restore continues a previously suspended or approval-interrupted agent run
 // from its last persisted checkpoint. The registry must contain all agents
-// that may have been active (including handoff targets).
-//
-// ctx follows the same graceful-suspend contract as Run: cancelling it
-// asks the resumed loop to checkpoint at the next safe boundary and
-// return a *SuspendedError with the new checkpoint. See Run for details.
+// that may have been active (including handoff targets). ctx follows Run's
+// graceful-suspend contract.
 func Restore(
 	ctx context.Context,
 	store Checkpointer,
@@ -138,13 +135,8 @@ func restoreNestedSuspended(
 	runID string,
 	registry AgentRegistry,
 ) (*Result, error) {
-	// Graceful-suspend contract: the saveProgress closure and the
-	// snapshot hook must survive a cancellation on the supervisor's
-	// runCtx so a partial save can land before we surface
-	// SuspendedError. Use a non-cancellable shadow for those sites
-	// only; the recursive restoreCheckpoint call keeps the original
-	// ctx so the nested coreLoop sees the cancel and suspends at its
-	// own next turn boundary.
+	// saveCtx survives an outer cancel so partial restore progress
+	// is persisted before SuspendedError surfaces.
 	saveCtx := context.WithoutCancel(ctx)
 
 	type nestedRestoreEntry struct {