docs(hooks): note stateful-provider caveat on ephemeral context injections

[Brian Krabach (bkrabach)]

Summary

context/understanding-mechanisms/mechanisms/hooks.md's "Ephemeral
Injections" section describes what Amplifier's local context module
does with an ephemeral=True injection ("never passed to
context.add_message()", "evaporates after the call"). That's accurate
for the local context module, but on providers that chain conversation
state server-side (e.g. OpenAI's Responses API with
previous_response_id), the message still persists in the provider's own
server-held history for the rest of the chain once sent — there's no
retraction API, and repeated injections accumulate rather than replace.
Hook authors reading this doc had no way to know the local guarantee
doesn't extend past the wire.

This is a docs-only PR — zero behavior changes.

What's added

One caveat paragraph in the "Ephemeral Injections (recommended default)"
section, pointing to amplifier-core's docs/HOOKS_API.md ("Ephemeral
Semantics on Stateful Providers", added in microsoft/amplifier-core#105)
for the full contract:

Provider caveat: everything above describes the local context
module — what Amplifier itself retains between calls. It says nothing
about what a given LLM provider does with the message once it has been
sent. On providers that chain conversation state server-side (e.g.
OpenAI's Responses API with previous_response_id), a
user/assistant-role ephemeral injection still rides the request once
and then persists in the provider's own server-held history for the rest
of the chain — there is no retraction API, and repeated injections
accumulate rather than replace (bounded in practice by the provider's own
prompt caching and by compaction, which resets the chain). system-role
injections are generally retractable on those providers instead, since
the per-request system/instructions field is typically re-derived each
turn rather than carried from the chain root. See amplifier-core's
docs/HOOKS_API.md ("Ephemeral Semantics on Stateful Providers") for the
full contract.

Scope note (discrepancy found during investigation)

The task driving this PR named two specific targets to check:
modules/hooks-status-context and the todo reminder hook
(hooks-todo-reminder). Neither exists in this repo. Both are
external modules, sourced via git+https:// in
behaviors/status-context.yaml and behaviors/todo-reminder.yaml
respectively:

• hooks-status-context → microsoft/amplifier-module-hooks-status-context
• hooks-todo-reminder → microsoft/amplifier-module-hooks-todo-reminder

Confirmed via git log --all -- modules/hooks-status-context /
modules/hooks-todo-reminder (empty — these paths never existed in this
repo's history). This is the same situation the task already flagged for
wayfinder ("lives in its own repo — skip it"); I've applied the same
treatment here rather than fabricating edits to nonexistent paths.

I grepped the full modules/ tree for the same overclaim pattern. The
only in-tree modules constructing HookResult(..., ephemeral=True, ...)
are hooks-process-guard and hooks-progress-monitor — neither carries
an explanatory docstring/comment making the "not stored" claim, just the
field usage itself, so there was nothing to correct there.
modules/tool-delegate was left untouched, per scope.

If the two external modules' own docstrings need the same fix, that's a
follow-up PR against their own repos (out of scope here, same as
wayfinder).

Testing

Docs-only change (one markdown file). Full test suite run before opening
this PR: 1790 passed, 1 skipped (1791 collected via
uv run pytest -q) — no failures, no regressions.

---

🤖 Generated with Amplifier

[Brian Krabach (bkrabach)]

Admin merge notice: this PR is self-authored (docs-only, zero behavior
changes) and is being merged via `--admin` at the repo owner's
direction, since branch protection requires a review this account cannot
self-approve. All CI checks are green (Tests on ubuntu-latest/windows-latest
x Python 3.11/3.12/3.13, license/cla) — merging only after that, never
over a failing check.