experimental-ash 0.47.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # experimental-ash
 
+## 0.49.0
+
+### Minor Changes
+
+- 72cd8be: Channels now deliver their inbound `<*_context>` block as a dedicated session-context entry instead of prepending it onto the user's turn message. This applies to Slack, Teams, Discord, Telegram, and Twilio so the model sees the actor/channel metadata as its own message ahead of the user text, and the user turn stays clean. The unused `prependTeamsContext`, `prependDiscordContext`, and `prependTelegramContext` helpers are removed from the public API; use the corresponding `format*ContextBlock` functions if you need to render a block yourself.
+- a703ebb: Remove lifecycle hooks (`lifecycle.session`, `lifecycle.turn`) from the hook system. Hooks now only support stream-event subscribers (`events`). The `LifecycleHook`, `LifecycleHooks` types and `SessionPreparedKey` context key are removed. The `HookDefinition` interface no longer accepts a `lifecycle` field.
+
+### Patch Changes
+
+- ce09ade: Carry durable session snapshots through Workflow step results and remove `ash.session` write plumbing from current runs. The `ash.session` stream remains only as a legacy read fallback for old stream-backed handles.
+
+## 0.48.0
+
+### Minor Changes
+
+- 28259a5: Align dynamic tools, instructions, and skills with consistent additive semantics and strict role boundaries.
+
+  **Breaking changes:**
+
+  - `InstructionsDefinition.modelContext` removed — instructions produce system messages only via `markdown`
+  - `DeliverPayload.modelContext` replaced with `context: string[]` — channel context is now user messages persisted in session history
+  - `StepInput.modelContext` replaced with `context: string[]`
+  - `SendPayload.modelContext` replaced with `context: string[]`
+  - Dynamic instructions restricted to `session.started` and `turn.started` events (no `step.started`)
+  - Dynamic skills restricted to `session.started` and `turn.started` events (no `step.started`)
+  - Compaction output changed from `role: "system"` to a user/assistant turn in conversation history
+
+  **New features:**
+
+  - `defineInstructions` contributions persist across workflow step boundaries via scoped durable keys
+  - `defineSkill` stamps `SKILL_BRAND` for consistent entry detection (replaces duck-typing)
+  - System cache breakpoint added (4th Anthropic cache slot) to preserve system prefix when tools change
+  - Null-returning tool resolvers correctly clear durable metadata
+  - Skill announcements use virtual context with durable backing (rebuild from manifest on step boundaries)
+  - Shared `buildResolveContext` extracted for all three dynamic lifecycle dispatchers
+
 ## 0.47.0
 
 ### Minor Changes

package/dist/docs/internals/context.md

@@ -45,7 +45,6 @@ Set by the runtime entry point. Serialized at `"use step"` boundaries via their
 | `ParentSessionKey`     | `SessionParent`              |
 | `ChannelKey`           | `Channel`                    |
 | `BundleKey`            | `CompiledBundle`             |
-| `SessionPreparedKey`   | `boolean`                    |
 
 ## Virtual Keys
 
@@ -77,17 +76,12 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 4. Run the callback inside `contextStorage.run(ctx, ...)`
 5. Call framework provider `commit` hooks for provider-owned session state
 
-Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
-runs inside step (4)'s ALS scope, before the harness step. Lifecycle
-hooks receive `(ctx)`, and event hooks receive `(event, ctx)`. See
-[Hooks](./hooks.md) for the full pipeline and the `SessionPreparedKey`
-flag's failure semantics.
-
-`StepInput.modelContext` has two producers. Channels can provide
-ephemeral messages through `SendPayload.modelContext`, and lifecycle
-hooks can provide them through `LifecycleHookResult.modelContext`.
-The merge order is channel first, then `lifecycle.session`, then
-`lifecycle.turn`. The merged messages are visible to the next model
+Authored hook stream-event dispatch runs inside step (4)'s ALS scope.
+Event hooks receive `(event, ctx)`. See [Hooks](./hooks.md) for the
+full pipeline.
+
+`StepInput.modelContext` is provided by channels through
+`SendPayload.modelContext`. The messages are visible to the next model
 call only and are never persisted to durable session history.
 
 ## Channel Context

package/dist/docs/internals/hooks.md

@@ -1,8 +1,7 @@
 # Hooks
 
 Hooks are the first-class extension point for authored agent code that needs
-to run **around** a turn instead of inside it. Tools answer the model;
-hooks answer the runtime.
+to observe runtime events. Tools answer the model; hooks answer the runtime.
 
 This page explains the discovery → compile → resolve → dispatch pipeline
 and the runtime contract every authored hook handler relies on. The
@@ -11,8 +10,8 @@ end-user-facing reference lives at
 
 ## Architectural Rationale
 
-Plugins and authored agent code need to subscribe to the same lifecycle
-moments. Shipping hooks first closes the gap between "extension authored
+Plugins and authored agent code need to subscribe to the same stream
+events. Shipping hooks first closes the gap between "extension authored
 inside the agent" and "extension contributed by a plugin": both flow
 through one runtime registry, one `HookContext`, one set of ordering
 rules.
@@ -27,20 +26,14 @@ place to look when debugging.
 `id`, `auth`, `turn`, and `parent`). `session.auth` is a nested
 `SessionAuth` with `{ current, initiator }`.
 
-Lifecycle hooks receive `(ctx)` — a single `HookContext` argument.
 Event hooks receive `(event, ctx)` — event first, context last (omit `ctx` when unused).
-Per-turn `turnId` and `sequence` come from `ctx.session.turn` for
-lifecycle hooks, and from `event.data.{turnId, sequence}` for
+Per-turn `turnId` and `sequence` come from `event.data.{turnId, sequence}` for
 stream-event hooks — never duplicated on the context.
 
 ## Authoring shape
 
 ```ts
 defineHook({
-  lifecycle?: {
-    session?: LifecycleHook;
-    turn?: LifecycleHook;
-  };
   events?: {
     [K in HandleMessageStreamEvent["type"]]?: StreamEventHook<…>;
     "*"?: StreamEventHook<HandleMessageStreamEvent>;
@@ -48,10 +41,9 @@ defineHook({
 });
 ```
 
-The split between `lifecycle:` and `events:` is structural so the
-contract is explicit at the call site. Both are side-effect-only — hooks
-cannot inject model context. Use `defineDynamic` + `defineInstructions`
-in `agent/instructions/` to contribute runtime model messages.
+Hooks are observe-only — they cannot inject model context. Use
+`defineDynamic` + `defineInstructions` in `agent/instructions/` to
+contribute runtime model messages.
 
 ## Pipeline
 
@@ -69,17 +61,14 @@ compiler performs no per-handler validation — hook handlers are
 arbitrary functions and can only be inspected at runtime.
 
 Resolve (`src/runtime/resolve-hook.ts`) loads the authored module
-export and reads its nested `lifecycle` and `events` maps directly. Each
-declared handler must be a function; mismatches throw
-`ResolveAgentError` so typos surface at boot. There is no hardcoded
-list of valid event types — unknown event keys are accepted at resolve
-time and simply never fire at dispatch time.
+export and reads its `events` map directly. Each declared handler must
+be a function; mismatches throw `ResolveAgentError` so typos surface at
+boot. There is no hardcoded list of valid event types — unknown event
+keys are accepted at resolve time and simply never fire at dispatch time.
 
 Registry (`src/runtime/hooks/registry.ts`) builds a
 `RuntimeHookRegistry` per resolved agent node:
 
-- `session` — flat ordered array of `lifecycle.session` subscribers.
-- `turn` — flat ordered array of `lifecycle.turn` subscribers.
 - `streamEventsByType` — bucketed map keyed by event type.
 - `streamEventsWildcard` — flat array of `*` subscribers.
 
@@ -89,38 +78,6 @@ the workflow path.
 
 ## Dispatch
 
-Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. The
-workflow runtime entry point (`execution/workflow-steps.ts`) calls
-`runHookLifecycleStep` once per turn, **inside** the active ALS scope
-so hook code can read and write context like every other authored
-function. `runHookLifecycleStep` wraps `dispatchHookLifecycle`, lowers
-a `turn-failed` outcome into a parking `StepResult` (`{ next: null }`
-for conversation mode, `{ next: { done: true, output } }` for task
-mode), and otherwise hands off to the supplied harness step callback
-with the (possibly augmented) input.
-
-Dispatch is gated on `getHarnessEmissionState(session).turnId === ""`
-so tool-loop continuations and runtime-action resumes (which are
-continuations of an existing turn) skip the lifecycle stack.
-
-Stages, in order:
-
-1. **`lifecycle.session`** runs sequentially in registry order, but
-   only when `ash.sessionPrepared` is unset. The dispatcher sets the
-   flag **before** running the chain so a thrown hook does not retry on
-   the next turn — `lifecycle.session` errors are terminal session
-   failures (`session.failed`).
-2. **`lifecycle.turn`** runs sequentially. A thrown hook is
-   caught here and lowered into a recoverable `turn.failed` cascade
-   (`session.started` once → `turn.started` → `message.received` →
-   `step.failed` → `turn.failed` → `session.waiting`).
-
-If an event hook subscribed to one of the failure-cascade events
-itself throws while the dispatcher is emitting the recoverable
-`turn.failed`, the throw escalates and the runtime emits
-`session.failed` instead. This is the bounded second-order behavior
-when both a `lifecycle.turn` and a `turn.failed` event hook fail.
-
 ### Stream event dispatch (`handleEvent`)
 
 Every stream event passes through one `handleEvent` function
@@ -151,13 +108,6 @@ right before each model call. See the [event dispatch
 doc](../../research/active/unified-event-dispatch.md) for the full
 design.
 
-## `SessionPreparedKey`
-
-Lives in `src/context/keys.ts`. JSON-safe boolean, no codec. Set
-**before** the `lifecycle.session` chain runs so a thrown hook leaves
-the flag set — the next turn does not retry. Compaction does not clear
-the flag.
-
 ## Subagent Isolation
 
 Subagent hooks are fully isolated by structural construction:
@@ -175,19 +125,13 @@ The `discover/discover-subagent.ts` path walks each local subagent's
 
 ## Error Containment
 
-| Stage               | On throw                                                                               |
-| ------------------- | -------------------------------------------------------------------------------------- |
-| `lifecycle.session` | Re-thrown by dispatcher → terminal session failure (`session.failed`)                  |
-| `lifecycle.turn`    | Caught by dispatcher → recoverable `turn.failed` cascade emitted                       |
-| Stream-event hooks  | Propagated through the emit composer → existing harness error path emits `turn.failed` |
+| Stage              | On throw                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| Stream-event hooks | Propagated through the emit composer → existing harness error path emits `turn.failed` |
 
 ### Full per-turn execution order
 
 ```
-dispatchHookLifecycle():
-  lifecycle.session hooks        (once per session, side-effect-only)
-  lifecycle.turn hooks           (once per turn, side-effect-only)
-
 emitTurnPreamble() via handleEvent:
   handleEvent(session.started)   → emit, hooks, dynamic tool resolvers
   handleEvent(turn.started)      → emit, hooks, dynamic tool resolvers
@@ -213,9 +157,8 @@ emitStepActions() via handleEvent:
   (`src/runtime/hooks/registry.ts` ⇄ `runtime/hooks/registry.test.ts`,
   `src/compiler/normalize-hook.ts` ⇄ `compiler/normalize-hook.test.ts`,
   `src/runtime/resolve-hook.ts` ⇄ `runtime/resolve-hook.test.ts`).
-- Lifecycle dispatcher behavior is covered by
+- Stream-event dispatcher behavior is covered by
   `src/context/hook-lifecycle.integration.test.ts` (synthetic context,
-  session/turn lifecycle dispatch, recoverable turn-failed path,
   stream-event fan-out, error propagation).
 - Discovery integration is folded into
   `src/discover/agent.integration.test.ts` (recursive walk,
@@ -231,8 +174,6 @@ documented expectations:
 
 - Hook modules never import workflow primitives (`start`, `resumeHook`,
   `createHook`, `getWritable`).
-- Hook return shapes have no `state` field — durable state goes through
-  `ctx`.
 - Subagent hooks never read parent ALS context.
 
 ## Related Pages

package/dist/docs/internals/mechanical-invariants.md

@@ -92,10 +92,9 @@ hooks never read parent ALS context.
 Enforcement: rule 27 in `scripts/guard-agents-rules.mjs` fails if a
 `state:` (or `readonly state:`, `state?:`) field is declared on any
 type in `packages/ash/src/public/definitions/hook.ts`. The lint guards
-maintainers from accidentally widening `LifecycleHookResult` (which
-today exposes only `modelContext`) into a parallel state channel. The
-TypeScript surface itself rejects authored hooks that return any field
-the type does not declare.
+maintainers from accidentally widening hook types into a parallel state
+channel. The TypeScript surface itself rejects authored hooks that
+return any field the type does not declare.
 
 The complementary "subagent hooks never read parent ALS context"
 invariant is enforced structurally by the `runStep` ALS-scope split

package/dist/docs/internals/message-runtime.md

@@ -46,9 +46,8 @@ step.completed → turn.completed → session.waiting / session.completed
 ```
 
 Failure variants: `step.failed`, `turn.failed`, `session.failed`.
-A thrown `lifecycle.session` hook produces a terminal `session.failed`;
-a thrown `lifecycle.turn` hook produces a recoverable `turn.failed`
-cascade. See [Hooks](./hooks.md).
+A thrown stream-event hook propagates through the emit composer; the
+existing harness error path emits `turn.failed`. See [Hooks](./hooks.md).
 
 `message.appended` and `reasoning.appended` carry both delta and cumulative text. `step.completed.data.finishReason` mirrors the model-step outcome (`tool-calls` means the turn continues).
 

package/dist/docs/public/advanced/hooks.mdx

@@ -1,28 +1,25 @@
 ---
 title: "Hooks"
-description: "Subscribe to lifecycle moments and runtime stream events from agent/hooks/."
+description: "Subscribe to runtime stream events from agent/hooks/."
 url: /hooks
 ---
 
-Hooks are Ash's authored extension points for the per-turn lifecycle and
-the runtime event stream.
+Hooks are Ash's authored extension points for the runtime event stream.
 
 This page is about `agent/hooks/*.ts` runtime hooks. For the React client hook,
 see [`useAshAgent`](../frontend/use-ash-agent.md).
 
-Use a hook when you want to run code **around** a turn (before the model
-runs, around stream events) without writing a tool, a context provider,
-or a channel adapter handler.
+Use a hook when you want to observe stream events (audit, metrics,
+alerting) without writing a tool, a context provider, or a channel
+adapter handler.
 
-<CopyPrompt text="Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events. Use lifecycle hooks when the model needs ephemeral modelContext before the next model call; use events handlers for observe-only side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only when durable shared state is needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the relevant lifecycle or stream event behavior, and do not commit unless the user asks.">
+<CopyPrompt text="Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from experimental-ash/hooks, and can subscribe to stream events. Use event handlers for observe-only side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only when durable shared state is needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the relevant stream event behavior, and do not commit unless the user asks.">
   Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from
-  experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events.
-  Use lifecycle hooks when the model needs ephemeral modelContext before the next model call; use
-  events handlers for observe-only side effects after events are durably recorded. Inspect existing
-  hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only
-  when durable shared state is needed, wrap best-effort side effects so they do not fail sessions
-  accidentally, verify the relevant lifecycle or stream event behavior, and do not commit unless the
-  user asks.
+  experimental-ash/hooks, and can subscribe to stream events. Use event handlers for observe-only
+  side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the
+  smallest hook file and path-derived slug, use defineState only when durable shared state is
+  needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the
+  relevant stream event behavior, and do not commit unless the user asks.
 </CopyPrompt>
 
 ## The Main API
@@ -52,16 +49,27 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 
 ## Shape
 
-A hook file declares two kinds of subscribers under named maps:
+A hook file declares stream-event subscribers under the `events` map:
 
-- `lifecycle: { session?, turn? }` — runs **before** the harness step.
-  Side-effect-only.
-- `events: { ... }` — runs **after** Ash has accepted a stream event
-  and written it to the durable stream. Observe-only.
+```ts
+defineHook({
+  events: {
+    "session.started"(event, ctx) {
+      /* ... */
+    },
+    "turn.completed"(event, ctx) {
+      /* ... */
+    },
+    "*"(event, ctx) {
+      /* wildcard — fires for every event */
+    },
+  },
+});
+```
 
-The split is structural so the contract is explicit at a glance: code
-under `lifecycle:` may change what the model sees on the next call;
-code under `events:` cannot.
+Handlers are observe-only — they cannot inject model context. To
+contribute runtime model messages, use `defineDynamic` +
+`defineInstructions` in `agent/instructions/`.
 
 Every handler receives the same `HookContext`:
 
@@ -110,48 +118,6 @@ callId }` with `output` typed as the tool's `TOutput`. For connections
 it includes `{ output, toolName, connectionToolName, callId }` with
 `output` as `unknown`.
 
-## Lifecycle
-
-Lifecycle hooks share one signature:
-
-```ts
-type LifecycleHook = (ctx: HookContext) => void | Promise<void>;
-```
-
-Session and turn metadata are available on `ctx.session`. For example,
-`ctx.session.turn.sequence` gives the current turn sequence number.
-
-`lifecycle.session` runs **once per durable session**, before the first
-model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
-continuations and HITL resumes do not re-fire it.
-
-Hooks are side-effect-only — they cannot inject model context. To
-contribute runtime model messages, use `defineDynamic` +
-`defineInstructions` in `agent/instructions/`.
-
-### Seed durable context
-
-```ts
-// agent/hooks/load-profile.ts
-import { defineState } from "experimental-ash/context";
-import { defineHook } from "experimental-ash/hooks";
-import { fetchGithubProfile, type GithubProfile } from "../lib/github";
-
-const githubProfile = defineState<GithubProfile | null>("myapp.githubProfile", () => null);
-
-export default defineHook({
-  lifecycle: {
-    async session(ctx) {
-      const profile = await fetchGithubProfile(ctx.session.id);
-      githubProfile.update(() => profile);
-    },
-  },
-});
-```
-
-The profile is now visible to every tool, provider, and subsequent hook
-through `githubProfile.get()`.
-
 ## Stream Events
 
 Side-effect-only handlers for accepted runtime events. Subscribe by
@@ -190,11 +156,9 @@ Hooks always run **after** the event is durably recorded — if a hook throws, t
 
 ## Errors
 
-| Stage               | On throw                                                                                                                                                                                             |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lifecycle.session` | Terminal session failure (`session.failed`). The flag is set before the chain runs, so the next turn does not retry.                                                                                 |
-| `lifecycle.turn`    | Recoverable turn failure (`turn.failed`). Session keeps living.                                                                                                                                      |
-| `events.*`          | Propagates through the emit composer; the existing harness error path emits `turn.failed`. If the hook subscribed to a failure-cascade event also throws, the runtime escalates to `session.failed`. |
+| Stage      | On throw                                                                                                                                                                                             |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `events.*` | Propagates through the emit composer; the existing harness error path emits `turn.failed`. If the hook subscribed to a failure-cascade event also throws, the runtime escalates to `session.failed`. |
 
 If you want belt-and-suspenders semantics inside a hook, wrap the body
 in `try`/`catch` — Ash treats a thrown hook as a real failure.
@@ -208,13 +172,12 @@ context.
 
 ## When to use a hook vs a tool vs a provider
 
-| Need                                                 | Use                                          |
-| ---------------------------------------------------- | -------------------------------------------- |
-| Run before a turn (seed context, inject system text) | `lifecycle.session` / `lifecycle.turn`       |
-| Observe runtime events (audit, metrics, alerting)    | `events.<type>` (or channel adapter handler) |
-| Provide structured input to the model on demand      | a tool                                       |
-| Make a value available across the entire step        | a context provider                           |
-| Subscribe to platform-specific events                | a channel adapter handler                    |
+| Need                                              | Use                                          |
+| ------------------------------------------------- | -------------------------------------------- |
+| Observe runtime events (audit, metrics, alerting) | `events.<type>` (or channel adapter handler) |
+| Provide structured input to the model on demand   | a tool                                       |
+| Make a value available across the entire step     | a context provider                           |
+| Subscribe to platform-specific events             | a channel adapter handler                    |
 
 Stream-event hooks and channel adapter event handlers are structurally
 identical — choose the channel adapter handler when you are authoring

package/dist/docs/public/advanced/project-layout.md

@@ -149,8 +149,7 @@ Use:
 - `instructions.md` (or `instructions.ts`) for always-on identity and behavior
 - `skills/` for optional procedures the model should load on demand
 - `tools/` for typed business logic and API calls
-- `hooks/` for lifecycle (`lifecycle.session`, `lifecycle.turn`) and
-  stream-event subscribers
+- `hooks/` for stream-event subscribers
 - `connections/` for external services exposed via MCP (model discovers and calls their tools)
 - `sandbox/` for sandbox overrides and seeded workspace files
 - `channels/` for HTTP or messaging ingress and delivery

package/dist/docs/public/advanced/typescript-api.md

@@ -112,7 +112,7 @@ Channel and Slack types exported from `experimental-ash/channels/slack`:
   `since: (message) => boolean` for a custom boundary.
 - `SlackInteractionAction` - action type for `onInteraction`
 - `SlackMentionResult` / `SlackInboundResult` - return type of `onAppMention` / `onDirectMessage`
-  (`{ auth, modelContext? } | null`)
+  (`{ auth, context? } | null`)
 - `defaultSlackAuth(message, ctx)` - default Slack actor-to-session-auth projection
 - `Card`, `Button`, `Actions`, `Section`, `Modal`, `Table`, etc. - card builders re-exported for
   rendering Slack messages

package/dist/docs/public/channels/index.md

@@ -412,8 +412,8 @@ await args.receive(slack, {
 ```
 
 For inbound mentions in an existing Slack thread, `onAppMention` and
-`onDirectMessage` may return `modelContext` to inject fetched thread
-history into the next model call without persisting it. See
+`onDirectMessage` may return `context` to inject thread history as
+user messages in session history. See
 [Slack thread context](/docs/channels/slack#thread-context).
 
 `threadTs` and `initialMessage` are mutually exclusive: pass `threadTs` to join an existing

package/dist/docs/public/channels/slack.mdx

@@ -188,8 +188,8 @@ export default slackChannel({
 - **`onAppMention(ctx, message)`** -- decides whether to dispatch a turn for an inbound
   `app_mention`, with what `auth` context, and runs any pre-dispatch side effects (typing
   indicators, logging, feature-flag lookups). Return `{ auth }` to dispatch or `null` to silently
-  drop the mention. Return `{ auth, modelContext }` to add ephemeral messages to the next model
-  call without writing them to durable session history. May be sync or async; the framework awaits
+  drop the mention. Return `{ auth, context }` to append context strings as user messages in
+  session history before the delivery message. May be sync or async; the framework awaits
   the result before dispatching. Thrown errors are caught, logged, and drop the mention -- wrap
   best-effort side effects in `try/catch` if you want them to be non-fatal. The default
   `onAppMention` derives a workspace-scoped auth from the Slack actor and posts a `"Thinking…"`
@@ -212,19 +212,18 @@ run inside the workflow context, not on the inbound webhook side.
 
 When the bot is mentioned in an existing Slack thread, the triggering mention is delivered to the
 agent by default, but prior thread replies are not injected automatically. Fetch thread history in
-`onAppMention` or `onDirectMessage` and return `modelContext` when the agent should see that
-background on the next model call.
+`onAppMention` or `onDirectMessage` and return `context` when the agent should see that
+background.
 
 Use `since: "last-agent-reply"` for repeated tags in the same thread. It returns only messages
 after the agent's last Slack reply and before the current mention, so the injected context stays
-small and can be modeled as a `role: "user"` message without changing the system prompt.
+small.
 
 ```ts
 import {
   defaultSlackAuth,
   loadThreadContextMessages,
   slackChannel,
-  type ModelMessage,
 } from "experimental-ash/channels/slack";
 
 export default slackChannel({
@@ -242,23 +241,19 @@ export default slackChannel({
       .map((entry) => `${entry.isMe ? "you" : (entry.user ?? "user")}: ${entry.markdown}`)
       .join("\n");
 
-    const modelContext: ModelMessage[] = [
-      {
-        role: "user",
-        content:
-          "Recent Slack thread messages since your last reply, oldest first. " +
-          "Use them as background context for the current mention.\n\n" +
-          transcript,
-      },
+    const context = [
+      "Recent Slack thread messages since your last reply, oldest first. " +
+        "Use them as background context for the current mention.\n\n" +
+        transcript,
     ];
 
-    return { auth, modelContext };
+    return { auth, context };
   },
 });
 ```
 
-`modelContext` is one-shot context: it is used for the model call that dispatches this inbound
-message and is never persisted to `session.history`.
+`context` strings are appended as user messages to `session.history` before the delivery message.
+They persist across the session and are visible to the model on all subsequent turns.
 
 ### Direct Messages
 

package/dist/docs/public/frontend/use-ash-agent.md

@@ -193,26 +193,22 @@ const agent = useAshAgent({
 });
 ```
 
-`clientContext` is rendered as ephemeral model context for the next turn only.
-It is never persisted to durable message history.
+`clientContext` is appended as user messages to session history before
+the delivery message. It persists across the session and is visible
+to the model on all subsequent turns (until compaction summarizes it).
 
-Use authored lifecycle hooks for server-side enrichment:
+Use dynamic instructions for server-side system prompt enrichment:
 
 ```ts
-// agent/hooks/profile.ts
-import { defineHook } from "experimental-ash/hooks";
-
-export default defineHook({
-  lifecycle: {
-    async session(_input, ctx) {
-      return {
-        modelContext: [
-          {
-            role: "system",
-            content: `Session ${ctx.session.sessionId} has server-side profile context.`,
-          },
-        ],
-      };
+// agent/instructions/profile.ts
+import { defineDynamic, defineInstructions } from "experimental-ash/instructions";
+
+export default defineDynamic({
+  events: {
+    async "session.started"(_event, ctx) {
+      return defineInstructions({
+        markdown: `Session ${ctx.session.id} has server-side profile context.`,
+      });
     },
   },
 });

package/dist/src/channel/adapter.js

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";const log=createLogger(`channel.adapter`);function defaultDeliverResult(e){let{inputResponses:t,message:n,modelContext:r,outputSchema:i}=e;if(!(n===void 0&&!t?.length&&!r?.length&&i===void 0))return{inputResponses:t,message:n,modelContext:r,outputSchema:i}}function getAdapterKind(e){return e.kind}async function callAdapterEventHandler(e,n,r){let i=e[n.type];if(i===void 0)return n;try{await i(`data`in n?n.data:void 0,r)}catch(r){log.error(`adapter event handler threw — event swallowed`,{adapterKind:getAdapterKind(e),eventType:n.type,error:r})}return n}export{callAdapterEventHandler,defaultDeliverResult,getAdapterKind};
+import{createLogger}from"#internal/logging.js";const log=createLogger(`channel.adapter`);function defaultDeliverResult(e){if(e.message!==void 0)return{inputResponses:e.inputResponses,message:e.message,context:e.context,outputSchema:e.outputSchema};if(e.inputResponses!==void 0&&e.inputResponses.length>0)return{inputResponses:e.inputResponses,context:e.context,outputSchema:e.outputSchema};if(e.context!==void 0&&e.context.length>0)return{context:e.context,outputSchema:e.outputSchema};if(e.outputSchema!==void 0)return{outputSchema:e.outputSchema}}function getAdapterKind(e){return e.kind}async function callAdapterEventHandler(e,t,n){let r=e[t.type];if(r===void 0)return t;try{await r(`data`in t?t.data:void 0,n)}catch(n){log.error(`adapter event handler threw — event swallowed`,{adapterKind:getAdapterKind(e),eventType:t.type,error:n})}return t}export{callAdapterEventHandler,defaultDeliverResult,getAdapterKind};

package/dist/src/channel/routes.d.ts

@@ -1,4 +1,4 @@
-import type { ModelMessage, UserContent } from "ai";
+import type { UserContent } from "ai";
 import type { CrossChannelReceiveFn } from "#channel/cross-channel-receive.js";
 import type { SessionAuthContext, SessionCallback } from "#channel/types.js";
 import type { InputResponse } from "#runtime/input/types.js";
@@ -24,13 +24,11 @@ export interface SendPayload {
     readonly message?: string | UserContent;
     readonly inputResponses?: readonly InputResponse[];
     /**
-     * Ephemeral messages contributed by the channel, appended to the
-     * dispatched turn's first model call via `StepInput.modelContext`.
-     * Never persisted to durable session history. Use `role: "system"`
-     * for background context that should land before the user message;
-     * other roles land after the user message.
+     * Context strings contributed by the channel. Each entry is appended
+     * as a `role: "user"` message to `session.history` before the
+     * delivery message, persisted across the session.
      */
-    readonly modelContext?: readonly ModelMessage[];
+    readonly context?: readonly string[];
     /**
      * Run-scoped JSON schema the turn's result must match. Orthogonal to
      * {@link BaseSendOptions.mode}: a schema is enforced in either mode. Mode

package/dist/src/channel/send.js

@@ -1 +1 @@
-import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,modelContext:h,outputSchema:g}=normalizeSendInput(a),_=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:_,modelContext:h,outputSchema:g}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let v=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:v,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,channelName:i,callback:c,continuationToken:f,input:{message:_??``,modelContext:h,outputSchema:g},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};
+import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,context:h,outputSchema:g}=normalizeSendInput(a),_=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:_,context:h,outputSchema:g}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let v=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:v,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,channelName:i,callback:c,continuationToken:f,input:{message:_??``,context:h,outputSchema:g},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};