Document agent ctx-cancel suspend contract

Add a Cancellation semantics section explaining ctx.Done() =
graceful suspend, the WithoutCancel shadow inside coreLoop, the
implication for context.WithTimeout deadlines, the absence of an
in-process hard-abort, and the supervisor-side mapping of SIGTERM
shutdown onto cancelRun(ErrSuspendForCheckpoint).

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

contrib/claude/agent.md

@@ -41,6 +41,30 @@ type Tool interface {
 
 `agent.AsTool(name, description)` wraps an agent as a tool for composition.
 
+## Cancellation semantics
+
+`ctx.Done()` is a **graceful-suspend signal**, not a hard abort. When the
+caller cancels `ctx`, `Run`/`RunStreamed`/`Resume`/`Restore` finish their
+in-flight LLM call and tool, persist a checkpoint via the configured
+`Checkpointer`, and return `*SuspendedError`. Internally `coreLoop`
+shadows the incoming ctx with `context.WithoutCancel(ctx)` and uses the
+shadow for every downstream call so the cancel never kills work
+in-progress; only the at-boundary check observes the original ctx.
+
+Implications:
+
+- A `context.WithTimeout` becomes a "max wall-clock budget then suspend"
+  — strictly better than today's "deadline kills work outright."
+- There is no in-process hard-abort path. Callers that genuinely need
+  to kill a run terminate the process; stale recovery handles the row.
+- Tools that need their own deadline must derive it themselves
+  (`context.WithTimeout(ctx, ...)` *inside* the tool body).
+
+The supervisor (`pkg/probo/agent_run_handler.go`) maps a SIGTERM-driven
+shutdown broadcast onto a per-run `cancelRun(ErrSuspendForCheckpoint)`,
+so the same contract drives both the public Go API and the worker
+infrastructure path.
+
 ## Limits
 
 - Max turns: 10 (default)