---
id: 20260605-004807-hook-context-system-item-sink
slug: hook-context-system-item-sink
title: Hook: add context handles for host-mediated SystemItem append
status: closed
kind: feature
priority: P1
labels: [hooks, feature-registry, history, task-reminder]
created_at: 2026-06-05T00:48:07Z
updated_at: 2026-06-05T01:26:06Z
assignee: null
legacy_ticket: null
---

## Issue

Built-in feature modules need a closed way to influence Pod-side behavior without adding feature-specific logic back into `Pod` / `PodInterceptor`. Task reminders are the immediate example: a Task feature should be able to observe request/tool activity and append a `SystemItem::TaskReminder`, but it should not receive `Pod`, `Worker`, raw history writers, raw `llm_worker::Item` injection, or a generic effect channel.

The current Hook surface already has per-hook-point action types after `hook-public-surface-hardening`, and those action types should remain flow-control oriented. The missing piece is event-specific Hook context carrying host-owned handles for allowed side effects, especially a durable `SystemItem` append path.

## Current findings

- `crates/pod/src/hook.rs` already distinguishes hook point output types such as `HookPromptAction`, `HookPreRequestAction`, `HookPreToolAction`, `HookPostToolAction`, and `HookTurnEndAction`.
- `PreLlmRequest` / `OnTurnEnd` public actions no longer expose raw `Item` injection.
- Hook inputs are currently summary structs (`PreRequestInfo`, `ToolCallSummary`, etc.), not context objects with host handles.
- `TaskReminder` emission currently lives in `PodInterceptor::pending_history_appends()` and uses Pod-owned `TaskStore` / `TaskReminderState`.
- Existing durable model-visible path is `SystemItem` commit -> `LogEntry::SystemItem` -> `Event::SystemItem` / model context, and this path must remain the only model-visible append mechanism.

## Direction

Introduce event-specific Hook context objects that carry narrow, host-created handles. Keep Hook return values as per-hook-point flow-control actions.

- Side effects are not returned as arbitrary `HookEffect` enums.
- Side effects are requested through typed handles on the Hook context.
- Handles have private constructors and are created only by the Pod host.
- Missing authority/handle should prevent installation or make the handle unavailable; runtime rejection is defense-in-depth, not the normal API path.

## Requirements

- Define event-specific Hook context types, or evolve `HookEventKind::Input` into context values without losing the existing per-event action types.
  - `PreLlmRequest` context should be able to carry request summary plus a SystemItem append handle where the host grants it.
  - Tool hook contexts should continue to expose bounded call/result summaries.
- Add a host-owned `SystemItemAppendHandle` / sink concept for model-visible durable system items.
  - It must not expose raw `llm_worker::Item` or raw history writer access.
  - It should append/push only approved `SystemItem` request kinds, initially including TaskReminder/Notification-like system items as needed.
  - Actual commit timing remains host-controlled through the existing pending history append / `LogEntry::SystemItem` / `Event::SystemItem` path.
- Preserve per-hook-point flow-control action types.
  - Do not collapse every hook into one generic `HookDecision`.
  - Do not reintroduce `ContinueWith(Vec<Item>)`, no-result tool skip, arbitrary `ToolResult` construction, or hidden context mutation.
- Keep internal built-in module usage distinct from external-plugin authority approval.
  - Built-in modules may receive host handles according to host policy.
  - Future external plugins receive model-visible append handles only when the external-plugin authority model grants them.
- Provide tests showing:
  - Hook actions remain flow-control only;
  - model-visible side effects use the SystemItem append handle;
  - no raw `Item` / raw history writer / raw event sender is exposed through public Hook context;
  - missing/unavailable handles do not produce invisible context injection.

## Non-goals

- Moving TaskStore/reminder state into the Task feature; that is tracked by `task-feature-own-store-reminder-hooks`.
- TUI dialog/custom UI work.
- Generic plugin event channels.
- External plugin loading/WASM boundary implementation.
- Changing ToolRegistry / PreToolCall permission behavior.

## Acceptance criteria

- Hook contexts can carry host-owned typed handles for allowed side effects, starting with durable SystemItem append.
- Hook return values remain event-specific flow-control actions.
- Model-visible additions through Hooks are committed through the durable SystemItem path and are user-inspectable.
- Public Hook APIs still do not expose raw `Item` injection, raw Pod/Worker/session internals, or generic UI/event payload channels.
- The resulting API is sufficient for a later Task reminder Hook to append `SystemItem::TaskReminder` without Pod-specific Task logic in `PodInterceptor`.