experimental-ash 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # experimental-ash
 
+## 0.36.0
+
+### Minor Changes
+
+- 34722b0: Unify runtime data access: `ctx` is available as the last argument to all ALS-scoped authored callbacks. Omit it when you don't need it.
+
+  **Breaking changes:**
+
+  - Tool `execute(input)` → `execute(input, ctx)` — access session, sandbox, and skills via `ctx`
+  - Hook lifecycle `(input, ctx)` → `(ctx)` — session identity, auth, and turn info are on `ctx.session`
+  - Hook/channel events `(event, ctx)` → same shape, but `ctx` now carries `session`, `getSandbox()`, `getSkill()`
+  - `SessionHandle.id` (unchanged), `.auth` is now `{ current, initiator }` (was flat)
+  - `getSession()`, `getSandbox()`, `getSkill()` removed — use `ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`
+  - `HookContext.ash` removed — use `defineState` for durable state
+  - `CompactionHookInput` → `onCompact({ history, signal }, ctx)`
+  - `LifecycleHookInput` removed (absorbed into `HookContext`)
+
+  Non-ALS callbacks unchanged: schedule `run`, sandbox `bootstrap`/`onSession`, instrumentation `setup`.
+
+### Patch Changes
+
+- 4e50396: Fixed parked subagent/remote-agent turns persisting a stale (default) emission state. The runtime-action park now stamps the live turn's emission identity onto the parked session, so the resume turn is classified as a continuation instead of a fresh turn — preventing duplicate `session.started`/`turn.started` events and empty `turnId`s on resume.
+
 ## 0.35.0
 
 ### Minor Changes

package/dist/docs/internals/context.md

@@ -17,7 +17,7 @@ interface AshContext {
 }
 ```
 
-`loadContext()` returns the active context or throws. Public accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it.
+`loadContext()` returns the active context or throws. Internal accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it — these are implementation details, not public exports. Authored code uses `ctx.session`, `ctx.getSandbox()`, and `ctx.getSkill()` instead.
 
 ## Type Hierarchy
 
@@ -78,9 +78,10 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 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. See
-[Hooks](./hooks.md) for the full pipeline and the
-`SessionPreparedKey` flag's failure semantics.
+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
@@ -91,7 +92,7 @@ call only and are never persisted to durable session history.
 
 ## Channel Context
 
-Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a `ContextAccessor` and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
+Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a context accessor and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
 
 Auth lives on the run and deliver inputs:
 

package/dist/docs/internals/core-beliefs.md

@@ -15,8 +15,8 @@ source of truth; a repeated `name` field is a second source that can drift.
 
 The hooks surface (`agent/hooks/`) deliberately reuses the unified
 `AshContext` rather than introducing a parallel state-patch channel:
-hooks read and write through `ctx.ash` like every other authored
-function. One context, one set of keys, one place to look when debugging.
+hooks read and write through `ctx` like every other authored function.
+One context, one set of keys, one place to look when debugging.
 
 ## Durable Work Belongs In The Runtime
 

package/dist/docs/internals/hooks.md

@@ -18,15 +18,20 @@ through one runtime registry, one `HookContext`, one set of ordering
 rules.
 
 The hooks surface deliberately reuses the unified `AshContext`:
-`HookContext.ash` is the same `ContextAccessor` tools, providers, and
-channels get. There is no parallel state-patch channel — one
-`AshContext`, one set of keys, one place to look when debugging.
+`HookContext` extends `AshCallbackContext`, giving hooks the same
+context surface tools, providers, and channels get. There is no
+parallel state-patch channel — one `AshContext`, one set of keys, one
+place to look when debugging.
 
-`HookContext` itself is intentionally tiny: `agent`, `channel`, `session`
-identity plus the `ash` accessor. Per-turn `turnId` and `sequence` come
-from `LifecycleHookInput.turn` for lifecycle hooks, and from
-`event.data.{turnId, sequence}` for stream-event hooks — never duplicated
-on the context.
+`HookContext` carries `agent`, `channel`, and `session` (which includes
+`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
+stream-event hooks — never duplicated on the context.
 
 ## Authoring shape
 
@@ -87,7 +92,7 @@ the workflow path.
 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 `ctx.ash` like every other authored
+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
@@ -142,7 +147,7 @@ Subagent hooks are fully isolated by structural construction:
   established by the existing subagent invocation pipeline. Hooks
   resolve from the subagent node's `hookRegistry`, not the parent
   agent's.
-- `ctx.ash` reads hit the subagent's container, not the parent's.
+- `ctx` reads hit the subagent's container, not the parent's.
 - Lexicographic ordering applies within a subagent's hook set only.
   Parent and child registries do not interleave.
 
@@ -188,7 +193,7 @@ documented expectations:
 - Hook modules never import workflow primitives (`start`, `resumeHook`,
   `createHook`, `getWritable`).
 - Hook return shapes have no `state` field — durable state goes through
-  `ctx.ash`.
+  `ctx`.
 - Subagent hooks never read parent ALS context.
 
 ## Related Pages

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

@@ -68,10 +68,10 @@ flags new `@workflow/*` imports from channel, harness, and hook code.
 ### Hooks Use The Single State Channel
 
 Authored hook modules (`agent/hooks/**`) must read and write durable state
-through `ctx.ash` (the unified `ContextAccessor`). The hooks surface
-introduces no parallel state-patch channel — lifecycle return shapes
-expose only `modelContext` (a one-shot per-call ephemeral message list),
-and subagent hooks never read parent ALS context.
+through `ctx` (the unified context). The hooks surface introduces no
+parallel state-patch channel — lifecycle return shapes expose only
+`modelContext` (a one-shot per-call ephemeral message list), and subagent
+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

package/dist/docs/internals/testing.md

@@ -62,7 +62,7 @@ Ad-hoc tmp directories with `package.json` + `agent/` scaffolding.
 
 - Unit tier: `unit-guard.ts` throws on disk writes, subprocesses, `process.chdir`, real fetch. If you hit a guard throw, move the test to a higher tier.
 - Never mutate the process-default `RuntimeSession` — let `createTestRuntime().run(fn)` scope it. Do not call `installBundledCompiledArtifacts` / `resetBundledCompiledArtifacts` / `clearProcessDefaultRuntimeSession` directly.
-- Use `runAsSession({}, ...)` when the test needs `getSession()` / `getSandbox()` / `getSkill()` to resolve. Use `run(...)` when only compiled artifacts + bundle cache need scoping.
+- Use `runAsSession({}, ...)` when the test needs `ctx.session` / `ctx.getSandbox()` / `ctx.getSkill()` to resolve (the internal `getSession()`, `getSandbox()`, `getSkill()` free functions still work but are not public API). Use `run(...)` when only compiled artifacts + bundle cache need scoping.
 - Cleanup is automatic for `mockSkill`, `useScenarioApp`, and `useTemporaryAppRoots`.
 - Do not commit new fixtures under `test/fixtures/` — CI guard will fail. Use descriptors in `src/internal/testing/scenario-apps/`.
 - Prefer `vi.stubEnv` over direct `process.env` mutation.

package/dist/docs/public/README.md

@@ -60,7 +60,7 @@ Ash then gives you:
 - a reconnectable session stream
 - durable session state across turns
 - a per-agent sandbox with a shared runtime workspace
-- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
+- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`)
 
 ## The Runtime Shape
 

package/dist/docs/public/auth-and-route-protection.md

@@ -163,7 +163,7 @@ configured, and their `environment` matches `VERCEL_TARGET_ENV` or `VERCEL_ENV`
 those user tokens, `external_sub` becomes the session subject, `external_iss` becomes the session
 issuer when present, and `connector_id` is used as the issuer fallback before the Vercel OIDC issuer.
 String OIDC profile claims such as `name`, `picture`, and `email` are exposed in
-`getSession().auth.current.attributes`.
+`ctx.session.auth.current.attributes`.
 
 ### `none`
 
@@ -195,7 +195,7 @@ re-materializes them from the authored channel definition when it needs the live
 
 ## What Auth Reaches Authored Code
 
-Inside runtime code, `getSession().auth` gives you the caller snapshot.
+Inside runtime code, `ctx.session.auth` gives you the caller snapshot.
 
 Important behavior:
 
@@ -207,8 +207,8 @@ Important behavior:
   accepts with a `SessionAuthContext` or returns `401`
 
 Auth on follow-up messages (`deliver()`) is honored by the workflow runtime. When a different
-user sends a follow-up to the same session, `session.auth.current` reflects the new caller on
-that turn while `session.auth.initiator` stays the same.
+user sends a follow-up to the same session, `ctx.session.auth.current` reflects the new caller on
+that turn while `ctx.session.auth.initiator` stays the same.
 
 ## What Ash Does Not Do
 

package/dist/docs/public/channels/{README.md → index.md}

@@ -179,7 +179,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -372,7 +372,7 @@ Semantics:
 
 - The target channel's authored `receive(input, { send })` hook owns the continuation-token
   format and the initial state. Callers supply only `{ message, args, auth }`.
-- `auth` flows through to `session.initiatorAuth` so the target's event handlers and the
+- `auth` flows through to `session.auth.initiator` so the target's event handlers and the
   agent's tools can read who started the session.
 - Calling `args.receive(...)` does **not** also start a session on the current channel. The
   inbound channel's response is whatever the route handler returns explicitly (e.g.

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

@@ -163,7 +163,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -194,8 +194,8 @@ export default slackChannel({
   webhook side via `waitUntil`, so the channel returns `200 OK` to Slack immediately.
 
 `events: { ... }` handlers receive runtime events emitted by the harness after the turn dispatches
-(`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
-not on the inbound webhook side.
+(`turn.started`, `message.completed`, `session.failed`, etc.). They receive `(eventData, ctx)` and
+run inside the workflow context, not on the inbound webhook side.
 
 ### Thread Context
 

package/dist/docs/public/cli-build-and-debugging.md

@@ -77,7 +77,7 @@ When something is wrong:
 
 - `schedules/` are root-only today
 - `agent.ts` no longer owns inbound auth or network policy; those live on the HTTP channel layer
-- runtime helpers such as `getSession()` do not work at module top level
+- runtime helpers on `ctx` (like `ctx.session`) do not work at module top level
 - skill guidance belongs in `skills/`, not in tool descriptions
 
 ## What To Read Next

package/dist/docs/public/faqs.md

@@ -56,12 +56,11 @@ the framework's mechanical invariants.
 
 If you want session data from your own code, there are two supported surfaces:
 
-- **Tools** can read the current session's metadata (sessionId, turn, auth,
-  parent lineage) via `getSession()` from `experimental-ash/context`. This is
+- **Tools** can read the current session's metadata (id, turn, auth,
+  parent lineage) via `ctx.session` from the optional `ctx` parameter on `execute`. This is
   read-only.
-- **Durable context keys + `ContextProvider`** are the supported pattern for
-  reading or writing session-scoped durable state from authored code — see
-  [Session Context](./session-context.md).
+- **`defineState`** is the supported pattern for reading or writing session-scoped durable state
+  from authored code — see [Session Context](./session-context.md).
 
 For the wire-level session lifecycle (creating sessions, streaming events,
 reconnecting by event index) see [Sessions And Streaming](./runs-and-streaming.md).

package/dist/docs/public/hooks.md

@@ -20,7 +20,7 @@ import { defineHook } from "experimental-ash/hooks";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      console.info("session started", { sessionId: ctx.session.sessionId });
+      console.info("session started", { sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       console.info("model finished", { length: event.data.message?.length ?? 0 });
@@ -33,8 +33,7 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 `agent/hooks/auth/load-profile.ts` → `"auth/load-profile"`.
 
 `defineHook`, `HookDefinition`, and `HookContext` live on
-`experimental-ash/hooks`. Runtime context helpers (`getSession`,
-`getContext`, …) live on `experimental-ash/context`.
+`experimental-ash/hooks`. The `defineState` helper lives on `experimental-ash/context`.
 
 ## Shape
 
@@ -55,16 +54,10 @@ Every handler receives the same `HookContext`:
 interface HookContext {
   readonly agent: { readonly name: string; readonly nodeId?: string };
   readonly channel: { readonly kind?: string; readonly continuationToken?: string };
-  readonly session: { readonly sessionId: string };
-  readonly ash: ContextAccessor;
+  readonly session: { readonly id: string };
 }
 ```
 
-`ctx.ash` is the same `ContextAccessor` tools, providers, and channels use.
-Hooks read and write durable state through `ctx.ash.set(...)` /
-`ctx.ash.get(...)`. The hooks surface deliberately introduces no parallel
-state-patch channel — one `AshContext`, one set of keys.
-
 ### Narrowing tool results
 
 `toolResultFrom` narrows an `action.result` event to a specific authored
@@ -108,11 +101,13 @@ Lifecycle hooks share one signature:
 
 ```ts
 type LifecycleHook = (
-  input: { session: { sessionId: string }; turn: { sequence: number; turnId: string } },
   ctx: HookContext,
 ) => void | { modelContext?: readonly ModelMessage[]; skills?: readonly NamedSkillDefinition[] } | Promise<…>;
 ```
 
+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.
@@ -130,24 +125,24 @@ lifecycle hook messages.
 
 ```ts
 // agent/hooks/load-profile.ts
-import { ContextKey } from "experimental-ash/context";
+import { defineState } from "experimental-ash/context";
 import { defineHook } from "experimental-ash/hooks";
 import { fetchGithubProfile, type GithubProfile } from "../lib/github";
 
-const GithubProfileKey = new ContextKey<GithubProfile>("myapp.githubProfile");
+const githubProfile = defineState<GithubProfile | null>("myapp.githubProfile", () => null);
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
-      const profile = await fetchGithubProfile(ctx.session.sessionId);
-      ctx.ash.set(GithubProfileKey, profile);
+    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 `ctx.ash.get(GithubProfileKey)`.
+through `githubProfile.get()`.
 
 ### Inject ephemeral system text
 
@@ -158,7 +153,7 @@ import { fetchActiveIncident } from "../lib/linear";
 
 export default defineHook({
   lifecycle: {
-    async turn() {
+    async turn(ctx) {
       const incident = await fetchActiveIncident();
       if (incident === null) return;
 
@@ -186,7 +181,7 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session() {
+    async session(ctx) {
       return {
         skills: [
           {
@@ -216,12 +211,12 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
+    async session(ctx) {
       return {
         modelContext: [
           {
             role: "system",
-            content: `Greet the user by name (${await lookupName(ctx.session.sessionId)}).`,
+            content: `Greet the user by name (${await lookupName(ctx.session.id)}).`,
           },
         ],
       };
@@ -247,7 +242,7 @@ import { postToHoneycomb } from "../lib/honeycomb";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.sessionId });
+      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       await postToHoneycomb({ event: "message.completed", payload: event.data });
@@ -282,7 +277,7 @@ in `try`/`catch` — Ash treats a thrown hook as a real failure.
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks
 fire only inside the subagent scope; parent-agent hooks do not fire for
 subagent turns, and subagent hooks see only the subagent's own
-`ctx.ash`.
+context.
 
 ## When to use a hook vs a tool vs a provider
 

package/dist/docs/public/meta.json

@@ -2,20 +2,20 @@
   "pages": [
     "getting-started",
     "---",
-    "project-layout",
     "agent-ts",
-    "context-control",
     "skills",
     "tools",
-    "hooks",
     "human-in-the-loop",
     "sandbox",
     "channels",
-    "auth-and-route-protection",
     "subagents",
     "schedules",
     "connections",
     "---",
+    "project-layout",
+    "context-control",
+    "hooks",
+    "auth-and-route-protection",
     "vercel-deployment",
     "runs-and-streaming",
     "session-context",

package/dist/docs/public/sandbox.md

@@ -114,18 +114,17 @@ and `write_file` tools. The runtime name comes from the file stem (here, `repo_s
 ## Using The Sandbox From Authored Code
 
 Any authored runtime function (tool, step, or model callback) can bind a live sandbox handle via
-`getSandbox()`:
+`ctx.getSandbox()`:
 
 ```ts
-import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Append an analytics event to the running session log.",
   inputSchema: z.object({ kind: z.string(), payload: z.string() }),
-  async execute({ kind, payload }) {
-    const sandbox = await getSandbox();
+  async execute({ kind, payload }, ctx) {
+    const sandbox = await ctx.getSandbox();
     await sandbox.run({
       command: `echo ${JSON.stringify(JSON.stringify({ kind, payload }))} >> /var/lib/analytics/events.log`,
     });
@@ -136,7 +135,7 @@ export default defineTool({
 
 Important rules:
 
-- `getSandbox()` takes no arguments and is async.
+- `ctx.getSandbox()` takes no arguments and is async.
 - It only works inside authored runtime execution.
 - Visibility is node-local: the root agent sees the root agent's sandbox; a local subagent sees its
   own sandbox, not the parent's.
@@ -154,7 +153,7 @@ Use it when you need an absolute path to interpolate into a generated command or
 hardcoding `/workspace/` yourself:
 
 ```ts
-const sandbox = await getSandbox();
+const sandbox = await ctx.getSandbox();
 const analysisRoot = sandbox.resolvePath("python-analysis");
 
 await sandbox.writeFile("python-analysis/run.py", "print('ok')\n");
@@ -176,7 +175,7 @@ different skills, so they should not inherit the parent's filesystem.
   with that workspace seeded in.
 - If a subagent authors neither, the framework default is used as-is.
 
-Inside a subagent's authored code, `getSandbox()` binds to the subagent's own sandbox.
+Inside a subagent's authored code, `ctx.getSandbox()` binds to the subagent's own sandbox.
 
 ## Lifecycle Semantics
 
@@ -210,18 +209,17 @@ returned. The accepted option shape is whatever the backend's update call accept
 factory; `onSession`'s `use()` overrides any overlapping fields post-create.
 
 Unlike `bootstrap`, `onSession` runs inside the active Ash runtime context, so user-scoped setup can
-call `getSession()` and derive the current principal without baking credentials into the reusable
+read `ctx.session` and derive the current principal without baking credentials into the reusable
 template:
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: vercelBackend(),
-  async onSession({ use }) {
+  async onSession({ use, ctx }) {
     const sandbox = await use({ networkPolicy: "deny-all" });
-    const user = getSession().auth.current;
+    const user = ctx.session.auth.current;
     if (user === null) return;
 
     await sandbox.writeFile(

package/dist/docs/public/schedules.md

@@ -162,7 +162,7 @@ When a schedule fires, the dispatcher takes one of two paths:
 2. The agent runs in **task mode** with the app principal.
 3. Output is discarded.
 
-In both cases, the schedule session uses the **app principal**: `getSession().auth.current` and `getSession().auth.initiator` are set to `"ash:app"` with `principalType: "runtime"`.
+In both cases, the schedule session uses the **app principal**: `ctx.session.auth.current` and `ctx.session.auth.initiator` are set to `"ash:app"` with `principalType: "runtime"`.
 
 The session goes through the same durable runtime engine as any other Ash session.
 

package/dist/docs/public/session-context.md

@@ -1,42 +1,40 @@
 ---
 title: "Session Context"
-description: "Runtime helpers: getSession, getSandbox, getSkill, and defineState."
+description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
 ---
 
-Ash exposes runtime helpers for authored code:
+Ash exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers,
+and channel event handlers:
 
-- `getSession()`
-- `getSandbox()`
-- `getSkill(identifier)`
-- `defineState(name, initial)` -- typed durable state with `get()` and `update()`
+- `ctx.session` -- session metadata, turn, auth, and parent lineage
+- `ctx.getSandbox()` -- live sandbox handle for the current agent
+- `ctx.getSkill(identifier)` -- handle for a named skill visible to the current agent
+- `defineState(name, initial)` -- typed durable state with `get()` and `update()` (imported from `"experimental-ash/context"`)
 
 These APIs work only inside active authored runtime execution such as tools, channel event
 handlers, and authored hooks. They throw when called outside a managed context.
 
-## `getSession()`
+## `ctx.session`
 
-Use `getSession()` when you need durable runtime metadata about the current execution.
+Use `ctx.session` when you need durable runtime metadata about the current execution.
 
 `agent/tools/who_called_me.ts`
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Return the active session metadata.",
   inputSchema: z.object({}),
-  async execute() {
-    const session = getSession();
-
+  async execute(_input, ctx) {
     return {
-      sessionId: session.sessionId,
-      turnId: session.turn.id,
-      turnSequence: session.turn.sequence,
-      currentCaller: session.auth.current?.principalId,
-      initiator: session.auth.initiator?.principalId,
-      parentSessionId: session.parent?.sessionId,
+      sessionId: ctx.session.id,
+      turnId: ctx.session.turn.id,
+      turnSequence: ctx.session.turn.sequence,
+      currentCaller: ctx.session.auth.current?.principalId,
+      initiator: ctx.session.auth.initiator?.principalId,
+      parentSessionId: ctx.session.parent?.id,
     };
   },
 });
@@ -46,7 +44,7 @@ Public session fields:
 
 - `auth.current`
 - `auth.initiator`
-- `sessionId`
+- `id`
 - `turn.id`
 - `turn.sequence`
 - optional `parent`
@@ -59,12 +57,12 @@ Important behavior:
 - top-level schedule sessions expose the framework app principal (`principalId: "ash:app"`, `principalType: "runtime"`)
 - `parent` is present for child subagent sessions
 
-## `getSandbox()`
+## `ctx.getSandbox()`
 
-`getSandbox()` returns a live handle for the current agent's sandbox.
+`ctx.getSandbox()` returns a live handle for the current agent's sandbox.
 
 ```ts
-const sandbox = await getSandbox();
+const sandbox = await ctx.getSandbox();
 const result = await sandbox.run({ command: "pnpm test" });
 ```
 
@@ -81,12 +79,12 @@ child process.
 
 See [Sandboxes](./sandbox.md) for lifecycle details.
 
-## `getSkill(identifier)`
+## `ctx.getSkill(identifier)`
 
-`getSkill(identifier)` returns a handle for a named skill visible to the current agent.
+`ctx.getSkill(identifier)` returns a handle for a named skill visible to the current agent.
 
 ```ts
-const skill = getSkill("research");
+const skill = ctx.getSkill("research");
 const notes = await skill.file("references/checklist.md").text();
 ```
 
@@ -151,7 +149,7 @@ import { budget } from "../lib/budget.js";
 
 export default defineHook({
   lifecycle: {
-    turn() {
+    turn(ctx) {
       // Reset budget each turn
       budget.update(() => ({ count: 0, cap: 25 }));
     },
@@ -175,7 +173,7 @@ export default defineHook({
 
 Safe places:
 
-- inside `defineTool(...).execute(...)`
+- inside `defineTool(...).execute(input, ctx)`
 - inside authored callbacks Ash runs inside the runtime
 - after asynchronous boundaries inside the same authored execution chain
 

package/dist/docs/public/skills.md

@@ -77,18 +77,17 @@ Packaged skills are useful when you want files like:
 - `scripts/`
 - example inputs or templates
 
-Inside authored runtime code, you can read those packaged files through `getSkill(identifier)`.
+Inside authored runtime code, you can read those packaged files through `ctx.getSkill(identifier)`.
 
 ```ts
-import { getSkill } from "experimental-ash/skills";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Load a packaged skill reference file.",
   inputSchema: z.object({}),
-  async execute() {
-    const research = getSkill("research");
+  async execute(_input, ctx) {
+    const research = ctx.getSkill("research");
     return await research.file("references/checklist.md").text();
   },
 });

package/dist/docs/public/subagents.md

@@ -108,7 +108,7 @@ Subagent execution gets:
 - its own tools
 - its own sandbox (independent of the parent's sandbox)
 - its own `skills/` set (independent of the parent's skills)
-- immediate parent lineage in `getSession().parent`
+- immediate parent lineage in `ctx.session.parent`
 
 Skills and sandboxes do not cross the parent/child boundary. The subagent only sees skills
 authored under `agent/subagents/<id>/skills/`; skills under the root `agent/skills/` are not