Correct review findings and document the v2.5.2 opt-out fix

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

Author: snopoke

docs/changelog.md

@@ -7,14 +7,22 @@ hide:
 
 Full release notes for the Python SDK are available on [GitHub](https://github.com/taskbadger/taskbadger-python/releases).
 
+## v2.5.2
+
+**2026-08-07**
+
+**Python SDK**
+
+* **FIX** [`taskbadger_track=False`](python-celery.md#opting-out) now opts a single Celery execution out of tracking, as an `apply_async` argument or in the message headers. Previously it could only ever enable tracking: it was ignored when the `CelerySystemIntegration` was auto-tracking, and `apply_async` overwrote it on tasks using `base=Task`.
+
 ## v2.5.1
 
-**2026-08-06**
+**2026-08-07**
 
 **Python SDK**
 
 * **CHANGED** [`list_tasks`](python.md#listing-tasks) returns a `TaskList` of `taskbadger.Task` objects, which can be iterated over directly. It previously returned the generated `PaginatedTaskList`, whose `results` were internal models without the SDK's update methods. Note that an empty `TaskList` is falsy, where `PaginatedTaskList` was always truthy.
-* **FIX** Eager and canvas Celery tasks honour an explicit [`taskbadger_parent`](python-celery.md#subtasks), including `taskbadger_parent=None` to opt out of nesting.
+* **FIX** Eager Celery tasks honour an explicit [`taskbadger_parent`](python-celery.md#subtasks), including `taskbadger_parent=None` to opt out of nesting.
 * **FIX** Copying or pickling a `Task` no longer recurses until the stack overflows.
 
 ## v2.5.0

docs/data_model.md

@@ -85,9 +85,12 @@ The main attributes or a task are:
 
 :   The ID of the task this task is part of. Tasks can only be nested one level deep, so the parent
     must be a task that is not itself a child. A task's parent can not be changed once it has been
-    set. The `track` decorator and the Celery and Procrastinate integrations set this automatically
-    for tasks enqueued from within a tracked task, and it can also be set explicitly when creating or
-    updating a task.
+    set. Both rules are enforced by the API, so breaking either one causes the request to fail.
+
+    It can be set explicitly when creating or updating a task. The Celery and Procrastinate
+    integrations also set it automatically for tasks enqueued from within a tracked task, and the
+    `track` decorator sets it on a decorated function called from within one. Each integration
+    excludes some cases — see [Python SDK](python.md#parent-and-child-tasks) for details.
 
 ### Example Task
 

docs/python-celery.md

@@ -110,14 +110,17 @@ You can pass additional parameters to the Task Badger `Task` class which will be
 This can be done by passing keyword arguments prefixed with `taskbadger_` to the `.apply_async()` function or
 to the task decorator.
 
-!!! warning "`taskbadger_` arguments require the task base class"
+!!! warning "`taskbadger_` arguments to `apply_async` require the task base class"
 
     It is `taskbadger.celery.Task` that intercepts `taskbadger_`-prefixed arguments to `apply_async`, so
-    they only work on tasks declared with `base=Task`. On a plain Celery task they are silently ignored:
+    those only work on tasks declared with `base=Task`. On a plain Celery task they are silently ignored:
     the task still publishes, and is still tracked if the
     [system integration](#celery-system-integration) tracks it, but the options have no effect.
 
-    To customize a task that is tracked by the system integration alone, pass the options in the
+    `taskbadger_` arguments on the **task decorator** are not affected. They are read off the task class
+    when the task is published, so they apply whether or not the task uses `base=Task`.
+
+    To set options per call on a task that is tracked by the system integration alone, pass them in the
     message headers instead — see [Customization without the task base class](#customization-without-the-task-base-class).
 
 ```python
@@ -181,6 +184,16 @@ Unlike the `taskbadger_`-prefixed arguments, the header is read when the task is
 by the task class, so no `base=Task` is needed. It takes the same options as `taskbadger_kwargs`, minus
 the prefix, and takes precedence over values set on the task decorator.
 
+!!! warning "Eager tasks read fewer options from the header"
+
+    That applies to tasks which are actually published. When Celery runs a task [eagerly][always_eager]
+    nothing is published, so the Task Badger task is created as the task starts instead, reading the
+    header directly. Only `parent`, `heartbeat_interval` and `stale_timeout` are honoured there —
+    `name`, `value_max` and `data` are ignored.
+
+    `taskbadger_track` is also *required* for an eager task that doesn't use `base=Task`, even if the
+    system integration would otherwise track it.
+
 If the task would not otherwise be tracked — it isn't using the base class and doesn't match the system
 integration's tracking rules — add `taskbadger_track` to the headers to track it anyway:
 
@@ -355,18 +368,30 @@ task a root task even though it was published from inside a tracked task:
 
 ```python
 # nest under a different task
-my_task.apply_async(taskbadger_parent=other_task.id)
+my_task.apply_async(args=[arg1, arg2], taskbadger_parent=parent_task.id)
 
 # opt out of nesting
-my_task.apply_async(taskbadger_parent=None)
+my_task.apply_async(args=[arg1, arg2], taskbadger_parent=None)
 ```
 
-As with the other `taskbadger_` arguments this requires the task to use `base=Task`; without it, pass
-`headers={"taskbadger_kwargs": {"parent": None}}` instead. See
+`taskbadger_parent` takes a **Task Badger** task ID, not a Celery task or result ID.
+
+As with the other `taskbadger_` arguments to `apply_async` this requires the task to use `base=Task`;
+without it, pass `headers={"taskbadger_kwargs": {"parent": None}}` instead. See
 [Customization without the task base class](#customization-without-the-task-base-class).
 
-==Since v2.5.1== eager tasks and [canvas primitives](#canvas-primitives-map-starmap-chunks) honour
-`taskbadger_parent` too; before that they always nested under the enclosing task.
+==Since v2.5.1== eager tasks honour `taskbadger_parent`; before that they always nested under the
+enclosing task.
+
+!!! warning "Canvas primitives ignore `taskbadger_parent`"
+
+    [Canvas primitives](#canvas-primitives-map-starmap-chunks) (`map`, `starmap`, `chunks`) are
+    published under Celery's own `celery.map` / `celery.starmap` task rather than your own, so
+    `taskbadger_parent` is never intercepted and the `taskbadger_kwargs` header doesn't reach the
+    worker. On a worker their parent can't be set per call, and they are not nested at all.
+
+    Run eagerly they do nest under the enclosing task, and there the parent can be overridden with
+    `headers={"taskbadger_kwargs": {"parent": ...}}`.
 
 ## External ID
 
@@ -376,8 +401,42 @@ originating Celery task.
 
 ## Opting out
 
-If you want to prevent TaskBadger from tracking a particular execution, set the `taskbadger_track` header (False) when publishing:
+To stop Task Badger tracking a single execution, set `taskbadger_track` to `False`, either as an
+argument to `apply_async` or in the message headers:
 
 ```python
+# as an argument — needs base=Task
+my_task.apply_async(args=[arg1, arg2], taskbadger_track=False)
+
+# in the headers — works for any task
+my_task.apply_async(args=[arg1, arg2], headers={"taskbadger_track": False})
+
+# canvas primitives take the header form only
 add.map([(1, 2), (2, 3)]).apply_async(headers={"taskbadger_track": False})
 ```
+
+This takes precedence over the `CelerySystemIntegration`, so it opts out even when `auto_track_tasks`
+is on, and over the `base=Task` class.
+
+The value must be exactly `False`. Omitting it leaves tracking to the normal rules.
+
+!!! warning "The argument form needs the task base class"
+
+    As with the other [`taskbadger_` arguments to `apply_async`](#task-customization),
+    `taskbadger_track=False` is intercepted by `taskbadger.celery.Task`, so it only works on tasks
+    declared with `base=Task`. On a plain Celery task, or on a
+    [canvas primitive](#canvas-primitives-map-starmap-chunks), it is silently ignored and the task
+    stays tracked.
+
+    The header form works in all three cases, so prefer it unless you know the task uses `base=Task`.
+
+To exclude a task from tracking on every call rather than per execution, use the `excludes` argument to
+[`CelerySystemIntegration`](#celery-system-integration), which matches on task name.
+
+!!! warning "Only works from v2.5.2"
+
+    ==Since v2.5.2==
+
+    Before that this header could only ever *enable* tracking, never suppress it. `False` was
+    indistinguishable from omitting the header, and `apply_async` on a `base=Task` task overwrote it
+    with `True`. On earlier versions use `excludes` instead.

docs/python-decorator.md

@@ -30,10 +30,14 @@ from the body, as well as [Celery](python-celery.md#subtasks) and
 [Procrastinate](python-procrastinate.md#subtasks) tasks enqueued from it. A bare `Task.create` in the
 function body is not nested unless you pass `parent` yourself.
 
+Each integration carves out some exceptions — Celery, for instance, doesn't nest chain successors,
+`link` callbacks, or canvas primitives running on a worker. The [Celery](python-celery.md#subtasks) and
+[Procrastinate](python-procrastinate.md#subtasks) pages list what does and doesn't get nested.
+
 Tasks nest a single level deep, so anything created by a decorated function that is itself a child
 becomes a sibling of that child rather than a grandchild. Passing `parent` to the decorator explicitly
 overrides the automatic nesting.
 
 ## API Docs
 
-::: taskbadger.track
+::: taskbadger.track

docs/python-procrastinate.md

@@ -216,7 +216,7 @@ A job deferred from inside a tracked task is automatically nested under it via t
 Tasks nest a single level deep, so a job deferred by a task that is itself a child becomes a sibling
 of that child rather than a grandchild.
 
-Nesting relies on the same wrapping as the rest of the integration, so the deferrals listed under
+Nesting relies on the same wrapping as the rest of the integration, so the cases listed under
 [Known Limitations](#known-limitations) are neither tracked nor nested.
 
 ## External ID

docs/python.md

@@ -86,8 +86,8 @@ for task in taskbadger.list_tasks(page_size=50):
         task.canceled()
 ```
 
-The `next_` and `previous` attributes hold the URL of the adjacent page, or are unset if there isn't
-one. To fetch the next page, pass its `cursor` query parameter back to `list_tasks`:
+The `next_` and `previous` attributes hold the URL of the adjacent page, or `None` if there isn't one.
+To fetch the next page, pass its `cursor` query parameter back to `list_tasks`:
 
 ```python
 from urllib.parse import parse_qs, urlparse
@@ -127,7 +127,8 @@ child = Task.create("import.chunk", parent=parent.id)
 ```
 
 Tasks nest a single level deep, so `parent` must be the ID of a task that is not itself a child.
-A task's parent can not be changed once it has been set.
+A task's parent can not be changed once it has been set. Both rules are enforced by the API rather
+than by the SDK, so breaking either one surfaces as a failed request.
 
 Use `list_tasks` to fetch the children of a task:
 
@@ -141,7 +142,11 @@ for child in taskbadger.list_tasks(parent=parent.id):
 `Task.create` and `create_task` only nest a task when you pass `parent` explicitly. The
 [function decorator](python-decorator.md#nested-tasks), [Celery](python-celery.md#subtasks) and
 [Procrastinate](python-procrastinate.md#subtasks) integrations do it for you: a task enqueued while
-another tracked task is running is nested under it automatically.
+another tracked task is running is nested under it automatically. Because nesting is capped at one
+level, a task enqueued from within a *child* becomes a sibling of that child rather than a grandchild.
+
+Each integration excludes a few cases from the automatic nesting — see the linked pages for what
+does and doesn't get nested.
 
 ### Connection management
 
@@ -217,9 +222,24 @@ def before_create(task_data: dict) -> dict:
 
 Context providers attach extra data to a task when it errors, for example a link back to the system
 that reported the exception. They are consulted whenever a tracked task fails — via the
-[function decorator](python-decorator.md), the [Celery](python-celery.md) or
-[Procrastinate](python-procrastinate.md) integrations, or `Task.error(exception=...)` — and whatever
-a provider returns is stored on the task [`data`](data_model.md#data) under the provider's identifier.
+[function decorator](python-decorator.md), or the [Celery](python-celery.md) or
+[Procrastinate](python-procrastinate.md) integrations — and whatever a provider returns is stored on
+the task [`data`](data_model.md#data) under the provider's identifier.
+
+You can also call `Task.error(exception=...)` yourself, but read the caveat below first.
+
+!!! warning "`Task.error()` on its own has no baseline"
+
+    Those three integrations record the state of each provider as the task *starts*, so a provider can
+    tell context belonging to this task from context left over from something unrelated.
+
+    Calling `task.error(exception=...)` directly does consult the providers, but nothing took that
+    baseline, so they have nothing to compare against. With
+    [`SentryContextProvider`](#sentry) that means the task gets a link to whatever
+    `sentry_sdk.last_event_id()` happens to be — quite possibly a stale, unrelated issue.
+
+    Prefer letting an integration own the error path. If you must call `Task.error` yourself and the
+    link matters, pass the context in explicitly via `data` instead of relying on a provider.
 
 Providers are registered with `taskbadger.init`:
 
@@ -238,8 +258,9 @@ task update.
 
 ### Sentry
 
-`SentryContextProvider` links a failed task to the Sentry issue for the same exception. It requires
-the `sentry-sdk` package, available via the `sentry` extra:
+`SentryContextProvider` links a failed task to the Sentry issue for the same exception. It needs the
+`sentry-sdk` package, available via the `sentry` extra. If the package isn't installed the provider is
+a silent no-op — it adds no context and reports no error, so install the extra:
 
 ```bash
 uv add 'taskbadger[sentry]'
@@ -271,11 +292,18 @@ Failed tasks then carry the Sentry event ID in their data, plus a link to the is
 
 Pass `base_url` if you are running a self-hosted Sentry.
 
+The `exception` value is `str(exception)`, except on the Celery path, where Celery's own exception info
+is used and the value is a full traceback.
+
 !!! note
 
     The provider does not report the exception to Sentry itself. It assumes your application already
     does that (e.g. via a framework integration) and reads back the event ID, which avoids reporting
-    the same exception twice. If the exception never reaches Sentry, no context is added.
+    the same exception twice.
+
+    To avoid linking to an unrelated event, the provider records Sentry's current event ID when the
+    task starts and only attaches context if it has changed by the time the task errors. So no context
+    is added when the exception never reaches Sentry, or when Sentry saw nothing new while the task ran.
 
 ### Custom providers