Add subtask support to the To-do list entity model

[FezVrasta]

Context

The To-do list platform models a list as a flat sequence of TodoItems. Several of the backends behind it do not: they model subtasks, and integrations currently have to throw that structure away on the way in.

• Google Tasks has a parent on every task. google_tasks filters subtasks out entirely, with a comment in _order_tasks stating that "Home Assistant To-do items do not support the Google Task parent/sibling relationships and the desired behavior is for them to be filtered". Items the user created in the Google app are simply invisible in Home Assistant.
• CalDAV and Local to-do both sit on RFC 5545, which expresses the same relationship with RELATED-TO;RELTYPE=PARENT.
• Todoist has the same concept as parent_id on its tasks.

Typical use cases: a shopping list grouped by aisle or store, a recipe broken into steps, a project checklist where the parent is only done when its children are, or simply seeing in Home Assistant what the user already created in the source app.

This proposal covers the entity model change only. No integration is changed by it, so the contract can be agreed on before backends adopt it.

Proposal

Add one optional field to TodoItem, next to the existing optional fields:

• parent_uid: str | None — the uid of the item this item is a subtask of. None means top level.

Add a feature flag so entities can advertise support:

• TodoListEntityFeature.SET_PARENT_ON_ITEM = 128

And a service field on todo.add_item and todo.update_item:

• parent — names the parent by uid or summary, exactly like the existing item field already resolves on update_item. It is filtered on SET_PARENT_ON_ITEM in services.yaml, like the other optional fields. Passing an empty parent to todo.update_item turns a subtask back into a top-level item.

action: todo.add_item
target:
  entity_id: todo.shopping_list
data:
  item: Milk
  parent: Dairy

Serialization needs no change: todo.get_items and the todo/item/list and todo/item/subscribe websocket commands build their payloads from the dataclass fields, so parent_uid is exposed automatically.

Hierarchy rules

Subtasks are limited to a single level. _resolve_parent_uid enforces this in the platform, so every entity gets the same guarantees regardless of what the backend would tolerate:

• the parent must exist on the same list (parent_not_found),
• an item cannot be its own parent (parent_is_self),
• the parent may not itself be a subtask (parent_is_subtask),
• an item that already has subtasks cannot be given a parent (item_has_subtasks).

The last two rules are what keep the tree from ever growing a third level, and together they also make cycles structurally impossible: a parent is always a root, so no chain longer than one edge can exist. A subtask can still be moved to a different top-level parent.

Why one level

Every backend listed above supports exactly one level in practice — Google Tasks enforces it in its API, and the CalDAV clients people actually use render it that way. It is also what the to-do card renders. Allowing arbitrary depth in core would mean every backend has to either flatten or reject deeper trees on write, which pushes the inconsistency out to integrations instead of resolving it. A depth limit can be relaxed later without breaking the field; going the other way would be a breaking change.

Why a uid pointer rather than nested children

An alternative shape is TodoItem.subtasks: list[TodoItem]. A flat list with a parent pointer was chosen because:

• The list stays flat, so async_get_items, the existing service handlers, filtering by status, and every current consumer keep working unchanged. Nesting would change the shape of every payload the platform already emits, which is a breaking change for existing consumers.
• It matches every backend: all of them store a parent reference on the child, not an embedded array.
• Updating a single item stays a single-item operation. With nesting, todo.update_item on a child would have to rewrite the parent.
• Ordering and hierarchy stay independent concerns. MOVE_TODO_ITEM continues to work on a flat list of uids.

Why on the item rather than a separate service

parent is item data, not a list operation — the backends store it on the item, and add_item needs to set it at creation time anyway. Modelling it as a field means it reuses the existing field description mechanism, feature filtering, and validation rather than adding a parallel path.

Out of scope

• Integration adoption. Google Tasks, Local to-do, and CalDAV are the obvious first candidates, as follow-up PRs once this lands.
• Parents across different lists.
• Deeper nesting.
• Any implied semantics between a parent's status and its children's (e.g. auto-completing children). Backends differ here; this proposal only models the relationship.

Implementation

• Core: Add subtask support to the To-do list platform core#180732
• Frontend: Show to-do subtasks in the list card and item dialog frontend#53885
• Documentation: Document to-do list subtasks home-assistant.io#47737

[allenporter]

The proposal of adding subtasks in line with the RFC is solid.

Aside: The proposal gets many of the nuanced details right around how to handle parent references in services: we do not expose the concept of a "uid" in the services today, so using the item name like this is the consistent choice. Most rfc5545 related proposals miss this.

[ivenos]

CalDAV would use this too. I maintain a custom CalDAV integration that already does subtasks this way, with the same parent and parent_uid names, and would do the CalDAV part in core once this is accepted.

home-assistant/core#180732 was closed while this waits. @MartinHjelmare could it go on the agenda of an architecture meeting, like #1349?

[MartinHjelmare]

I've put it on the agenda for next meeting.

[MartinHjelmare]

This proposal was approved in the architecture meeting on 2026-11-05.