Subcontext hierarchies

Subcontext lets you organize related context items as a parent with one or more child items (one level deep). When a parent is selected for an agent, its children can be included automatically — either always or only when relevant to the current task.

Subcontext hierarchy is enabled by default. Site builders can turn it off at Context item settings (/admin/config/ai/context/settings/items).

When to use subcontext

Large topics — split broad context (for example, "Product catalog") into focused child items ("Electronics", "Clothing", "Home goods").
Editorial grouping — keep related detail together under one parent in the admin UI and in agent configuration.
Token-focused workflows — use conditional children so detail is included only when the task warrants it (see Token and selection tradeoffs).

When to skip it

You have a small, flat set of context items and scopes already narrow selection enough.
Your team wants the simplest editorial model first — every item top-level, no parent/child concepts.
You are not ready to configure an AI provider for conditional subcontext (required subcontext still works without a provider).

Required vs conditional children

Each child has a subcontext type:

Type	Behavior
Required	Selected when the parent is selected. Rendering can still shorten or omit its content at the token limit.
Conditional	Included only when Enable conditional subcontext AI decisions is on and the configured AI provider/model decides the child is relevant to the current task. Requires an AI provider/model in general settings.

If Enable conditional subcontext AI decisions is off, conditional children are excluded from normal context selection (no AI call). They may still be included when selected by other paths — for example, an agent's Always include list, custom scope, or context-auto rules. Required children are still included when their parent is selected.

If conditional AI decisions are enabled but no AI provider/model is configured, conditional subcontext is unavailable in the item form and existing conditional children are ignored at runtime until a provider is configured. If provider selection fails at runtime, conditional children are skipped rather than included by default. The same fail-closed behavior applies when the decision cap is exhausted, the response is invalid, the provider does not support chat, or the provider throws an exception. Required children remain selected in these cases. See Debugging for warning categories.

Configure the provider at General settings.

When conditional AI is disabled

When Enable conditional subcontext AI decisions is off:

Conditional children are excluded during normal subcontext resolution.
Required children are still included with their parent.
Conditional children can still appear via agent Always include, custom scope, or other non-subcontext selection paths.

The admin UI helps editors understand this state:

On the context items listing, conditional child rows are visually de-emphasized (ghosted) and expose status text plus a link to Context item settings.
Editing a conditional child shows a warning that the item is excluded from normal selection until the toggle is re-enabled.

Use the ?fieldset= query parameter to open a settings fieldset directly — for example, /admin/config/ai/context/settings/items?fieldset=subcontext. See Settings deep links.

Writing Purpose for conditional children

When Conditional subcontext AI is enabled, the provider receives each candidate child's ID and Purpose (plus a snippet of parent Content and the current task). Purpose is the primary editorial control for inclusion decisions — not the child label, description, or full content.

Good Purpose examples

Write concrete, task-oriented criteria:

Include for returns, refunds, exchanges, and cancellation-policy questions.
Include for delivery timing, shipping methods, fulfillment, and delivery-location questions.
Include for image selection, photography style, and brand imagery questions.

Anti-patterns to avoid

Problem	Example	Why it fails
Vague	`Useful supporting information.`	Matches too many unrelated tasks.
Overlapping siblings	Pricing: `purchasing-cost questions.` Shipping: `delivery charges.`	Shared wording can cause false positives when both children are candidates.
Too broad	`Include for product page work.`	Selects on weak intent instead of a specific need.

Prefer distinct, non-overlapping Purpose text across sibling conditional children. Optional routing rules in parent Content can help edge cases, but clear Purpose values should be the default approach.

Creating subcontext items

From the context items listing (/admin/config/ai/context/items):

Create or edit a parent (top-level) item.
Use Add subcontext on the parent row to create a child with the parent pre-filled.
Choose Required or Conditional in the subcontext settings fieldset.
In the Context Scope section, leave Same as parent checked to use the parent's scope, or uncheck it to customize scope for this child (see Parent scope).

See Context items for field descriptions. Persistence rules (one level deep, validation on save) are summarized there.

Token and selection tradeoffs

Required-only subcontext: When a parent is selected, all required children are selected. That can use more tokens than a smaller parent alone, but the token limit can still shorten or omit their rendered content.

Conditional subcontext: Adds an LLM step to choose which conditional children match the current task. That step has latency and API cost, but may reduce tokens compared to always injecting all child content. Results depend on your provider, prompts, item sizes, and task patterns — there is no guaranteed cost or token savings. Evaluate with your own content and usage tracking.

In all cases, rendering is still capped by Max tokens for injection in general settings; content may be truncated if the budget is exceeded.

Limits interaction

General settings define Max global context items and Max tokens for injection:

Max global context items limits only the Global priority group.
Parent items and their required or selected conditional children are merged without a total item-count limit.
Max tokens applies to the final rendered output for all parent and child items together.

See Configuration for the global-item and token-budget settings.

Parent scope

Subcontext items can use the parent's scope instead of storing their own scope values. On the item form, the Same as parent checkbox (enabled by default for new children) controls this behavior.

Parent scope	Stored scope on child	Effective scope at runtime
Uses parent	Cleared on save (empty scope map, no entity items)	Parent's scope values
Custom	Saved on the child	Child's own scope values

The effective scope is resolved through AiContextItem::getScopeItem(). Scope plugins, the scope index, global detection, and entity item matching all use this resolved scope — not the child's empty stored values while parent scope is active (inherit_parent_scope / inheritsParentScope()).

Specific Entities scope

Specific Entities scope is stored in the Entity items field (dynamic entity references), not in the scope map. When parent scope is active:

The child uses the parent's entity items for matching and selection.
Any entity items previously stored on the child are cleared on save.
The edit form shows scope and entity item fields only when Same as parent is unchecked; the summary reflects values stored on the child, not the parent's values.

When parent scope is off, the child uses its own entity items like any top-level item.

Scope index and parent updates

The scope index stores effective scope values per item ID. For children with parent scope active, indexed rows mirror the parent's scope map (language, use case, tag, and so on).

When a parent item is updated, those children are reindexed automatically so SQL prefiltering and admin listings stay aligned with the parent's current scope. Custom-scope children are reindexed from their own stored values only.

Entity item references are not stored in the scope index table; Specific Entities behavior for parent-scope children is evaluated at runtime from the parent's DER field.

Selection behavior

Children with parent scope active are not top-level selection candidates. The selector skips items with inheritsParentScope() during the main published-item scan, so a child cannot appear as a global item, score against agent subscriptions, or enter via match-all because it mirrors the parent's scope.

Those children are included only when:

Their parent is selected and subcontext resolution adds them (required or conditional), or
They are listed in the agent's Always include overrides.

Custom-scope children (inherit_parent_scope disabled) remain eligible as top-level candidates. For example, a child that sets its own Global scope can be selected independently of its parent. Prefer leaving Same as parent checked unless the child needs distinct scope rules.

Deleting a parent

When a parent item is deleted, its children are detached: their parent, subcontext_type, and inherit_parent_scope fields are cleared so they become top-level items.

Children that used the parent's scope had no scope of their own, so once detached they would match every agent. To avoid silently widening selection, those children are unpublished on parent deletion (a warning is logged). On moderated sites the moderation state is moved to an unpublished state (archived in the module's ai_context_editorial workflow) so content_moderation does not revert the change. Restore them after giving them their own scope if you still need them.
Custom-scope children keep their own scope and remain published; they simply become independent top-level items.

If a child's parent reference becomes dangling (for example, a syncing import that references a parent that does not exist), the child is treated as inheriting but has no loadable parent. It is excluded from selection (never match-all) — including when it is listed in an agent's Always include overrides — and a warning is logged until the parent is restored or the reference cleared.

How children get selected

Primary path: A parent is selected (by scope, global rules, always include, or context-auto). Subcontext resolution then loads and filters its children.

Always include: A child ID in an agent's Always include list is loaded directly, even when parent scope is active on the child. When the child's parent is also selected, the child is placed immediately after its parent in the rendered output; when the parent is not selected, the child appears at its own always-include position.

Custom scope only: A child with custom scope can also enter selection through the normal top-level paths (global cap, scope subscriptions, context-auto such as entity items, or match-all) without its parent being selected. This is intentional for items that define their own scope.

Subcontext items with parent scope active are designed to ride along with their parent; attach detail as subcontext rather than giving children independent scopes unless you mean to.

Children appear nested under their parent in agent context settings.

Disabling subcontext hierarchy

When Enable subcontext hierarchy is turned off in context item settings:

Parent and subcontext type fields are hidden on item forms.
Subcontext resolution is skipped at runtime (children are not auto-included with parents).
Warning: Saving any context item clears its parent and subcontext_type values. This is not reversible from the UI. Children that used the parent's scope have no scope of their own, so they are also unpublished on that save (the same protection as parent deletion, including the moderation-state move on moderated sites) to keep them from matching every agent; a warning is logged.
Syncing saves (configuration import, migrations, and update-hook backfills such as ai_context_update_10011()) never trigger the strip: only a normal editorial re-save detaches an item, so running database updates with the feature disabled does not purge stored hierarchy.

Re-enable the feature before editing items if you need to preserve hierarchy data.

Planned: tooling to analyze large context items and suggest logical subcontext splits for editorial review (see drupal.org issue #3574929). That complements manual subcontext hierarchy; it does not replace it.