@gjermundgaraba/effect-actions 0.1.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: Schema.Struct({ name: Schema.String }),
   success: Schema.String,
-  mcp: { readOnly: true },
+  access: "read",
 });
 
 export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
@@ -61,8 +61,9 @@ const greeting = Effect.gen(function* () {
 ## Why
 
 - Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
-- A handler may fail only with the errors its action declares. Shared failures such as `Forbidden` are declared once on the group.
+- A handler may fail only with the errors its action declares. Shared failures such as `Forbidden` are declared once on the group, and one `before` hook runs on every surface before every handler, so a policy such as scope enforcement is written once and cannot be forgotten.
 - The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
+- Every action states its `access` (`"read"` or `"write"`, defaulting to `"write"`), so authorization reads the contract instead of a hand-maintained list of mutation names.
 - Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
 - Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
 
@@ -101,6 +102,10 @@ The `effect` peer is pinned to an exact Effect 4 release candidate and moves wit
 release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
+## Acknowledgements
+
+A few idea (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/dist/Action.d.mts

@@ -1,14 +1,19 @@
 import { Effect, Schema } from "effect";
 declare namespace Action_d_exports {
-  export { Action, Any, Codec, Handler, McpOptions, Options, make };
+  export { Access, Action, Any, Codec, Handler, McpOptions, Options, make };
 }
 /** Any service-free schema. Only handlers may require services. */
 export type Codec = Schema.Codec<unknown, unknown, never, never>;
+/**
+ * What an action does to the resource it serves: `"read"` observes, `"write"`
+ * may change it. Authorization metadata, not an MCP hint.
+ */
+export type Access = "read" | "write";
 /** MCP tool metadata; every field has a default derived from the action. */
 export interface McpOptions {
   /** Tool name; defaults to the action name. Must match `^[A-Za-z0-9_-]{1,128}$`. */
   readonly name?: string;
-  /** `readOnlyHint`; defaults to `false`. */
+  /** `readOnlyHint`; defaults to `access === "read"`. */
   readonly readOnly?: boolean;
   /** `destructiveHint`; defaults to `!readOnly`, as the MCP spec only defines it for writes. */
   readonly destructive?: boolean;
@@ -32,6 +37,12 @@ export interface Options<Input extends Codec, Output extends Codec, Errors exten
   readonly success: Output;
   /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
   readonly errors?: Errors;
+  /**
+   * What the action does to its resource. Defaults to `"write"`, so an action
+   * nobody classified is treated as the more dangerous one. Read by a group's
+   * `before` hook; the library itself authorizes nothing.
+   */
+  readonly access?: Access;
   /** `false` hides the action from HTTP routes and clients. */
   readonly http?: Http;
   /** `false` hides the action from MCP; otherwise tool metadata. */
@@ -44,6 +55,7 @@ export interface Action<Name extends string, Input extends Codec, Output extends
   readonly input: Input;
   readonly success: Output;
   readonly errors: Errors;
+  readonly access: Access;
   readonly http: Http;
   readonly mcp: ResolvedMcp<Name, Mcp>;
 }

package/dist/Action.mjs

@@ -5,7 +5,8 @@ import { Schema } from "effect";
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
 	assertName("action name", name);
-	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? false;
+	const access = options.access ?? "write";
+	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? access === "read";
 	const mcp = options.mcp === false ? false : {
 		name: options.mcp?.name ?? name,
 		readOnly,
@@ -21,6 +22,7 @@ function make(name, options) {
 		input: options.input ?? NoInput,
 		success: options.success,
 		errors: options.errors ?? [],
+		access,
 		http: options.http !== false,
 		mcp
 	};

package/dist/ActionCatalog.d.mts

@@ -1,4 +1,4 @@
-import { Action_d_exports, Any } from "./Action.mjs";
+import { Access, Action_d_exports, Any } from "./Action.mjs";
 import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
 import { JsonSchema } from "effect";
 //#region src/ActionCatalog.d.ts
@@ -8,6 +8,8 @@ export interface Entry {
   readonly group: string;
   readonly name: string;
   readonly description: string;
+  /** Authorization metadata, resolved: `"write"` unless the contract says `"read"`. */
+  readonly access: Access;
   readonly http: boolean;
   readonly mcp: Any["mcp"];
   readonly input: JsonSchema.JsonSchema;

package/dist/ActionCatalog.mjs

@@ -23,6 +23,7 @@ const make = (...groups) => {
 			group: group.name,
 			name: action.name,
 			description: action.description,
+			access: action.access,
 			http: action.http,
 			mcp: action.mcp,
 			input: jsonSchema(action.input),

package/dist/ActionCli.d.mts

@@ -18,10 +18,10 @@ type BoundHandler<Name extends string, A extends Any, R> = Readonly<Record<Name,
  * Project one explicitly selected local action into a native Effect CLI command.
  * The action name resolves against the bound group; no HTTP fallback exists.
  */
-export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], Parameters>) => Command.Command<string, never, {}, EX | import("effect/Schema").SchemaError | Extract<G["actions"][number], {
+export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, RB, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX, RB>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], Parameters>) => Command.Command<string, never, {}, EX | import("effect/Schema").SchemaError | Extract<G["actions"][number], {
   readonly name: Name;
-}>["errors"][number]["Type"], Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
+}>["errors"][number]["Type"], Exclude<RB, Scope.Scope> | Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
 /** Project every local action below its group namespace with default CLI options. */
-export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX>(app: Implementation<G, H, EX, RX>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
+export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX, RB>(app: Implementation<G, H, EX, RX, RB>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RB, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
 //#endregion
 export type { Options };

package/dist/ActionCli.mjs

@@ -8,7 +8,7 @@ const select = (group, name) => {
 	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
 	return action;
 };
-const local = (app, action, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)));
+const local = (app, action, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, app.before)(input)));
 /**
 * Project one explicitly selected local action into a native Effect CLI command.
 * The action name resolves against the bound group; no HTTP fallback exists.
@@ -19,7 +19,7 @@ const command = (app, name, options) => {
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)))));
+	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, app.before)(input)))));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionCliClient.d.mts

@@ -1,3 +1,4 @@
+import { Action_d_exports, Codec } from "./Action.mjs";
 import { Actions } from "./internal/actions.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
@@ -27,19 +28,19 @@ type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Ex
 type HttpNames<G extends Actions> = Extract<G["actions"][number], {
   readonly http: true;
 }>["name"];
-type ApiGroups<Groups extends ReadonlyArray<Actions>> = Api<Groups[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
-type Endpoint<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups>>>>, {
+type ApiGroups<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>> = Api<Groups[number], Errors[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
+type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
   readonly identifier: ActionName;
 }>;
-type NativeMethod<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
-type RemoteCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>>;
-type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
+type NativeMethod<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, Errors, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
+type RemoteCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>>;
+type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
 /**
  * Project one HTTP action retained by the binding into a native Effect CLI command.
  * Group and action selectors resolve exclusively from `http.groups`; runtime guards
  * keep dynamically supplied selector strings from reaching the native client.
  */
-export declare const command: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, GroupName, ActionName>;
+export declare const command: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups, Errors>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, Errors, GroupName, ActionName>;
 /** Project all HTTP-enabled actions retained by one group below its group namespace. */
-export declare const group: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"]>(http: Http<Groups>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, GroupName>;
+export declare const group: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"]>(http: Http<Groups, Errors>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, Errors, GroupName>;
 //#endregion

package/dist/ActionGroup.d.mts

@@ -3,7 +3,7 @@ import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect, Scope } from "effect";
 declare namespace ActionGroup_d_exports {
-  export { Any, Group, Implementation, Options, SchemaErrorPolicy, make };
+  export { Any, Group, ImplementOptions, Implementation, Options, SchemaErrorPolicy, make };
 }
 type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 /** Group-level errors join each action's own, so a shared set is declared once. */
@@ -17,14 +17,24 @@ export interface Options<Name extends string, Errors extends ReadonlyArray<Codec
   /** How HTTP answers failed decoding or encoding of these actions; MCP keeps its native answers. */
   readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
 }
+/** What `implement` accepts besides the handlers themselves. */
+export interface ImplementOptions<Errors extends ReadonlyArray<Codec>, R> {
+  /**
+   * Runs once per invocation before the selected handler, on every surface, with
+   * the action contract it is about to run. It may fail only with the group's own
+   * `errors`, because those are the failures every action of the group declares.
+   * Its services are request-time requirements, like a handler's.
+   */
+  readonly before: (action: Any$1) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
 /** A named set of action contracts: what adapters serve and what `implement` binds. */
-export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>, Errors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never, RB = never>(build: H | Effect.Effect<H, EX, RX>, options?: ImplementOptions<Errors, RB>) => Implementation<Group<Name, Actions$1, PolicyErrors, Errors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>, NoInfer<RB>>;
 }
-/** Any group, with its actions erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>>;
+/** Any group, with its actions and error schemas erased. */
+export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>, any>;
 /** Define a group. Invalid or duplicate action and MCP names fail here, at definition time. */
-export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors, Errors>;
 //#endregion
 export { ActionGroup_d_exports, type Implementation, type SchemaErrorPolicy };

package/dist/ActionGroup.mjs

@@ -15,9 +15,10 @@ function make(options, ...declared) {
 		name,
 		actions,
 		schemaError: options.schemaError,
-		implement: (build) => {
+		implement: (build, options) => {
 			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
-			return Implementation.make(group, built);
+			const before = options?.before;
+			return Implementation.make(group, built, before);
 		}
 	};
 	return group;

package/dist/ActionHttp.d.mts

@@ -10,20 +10,28 @@ declare namespace ActionHttp_d_exports {
   export { Api, Http, Options, make };
 }
 /** Contract-level configuration: servers and clients must agree on it. */
-export interface Options {
+export interface Options<Errors extends ReadonlyArray<Codec> = []> {
   readonly apiPath: `/${string}`;
+  /**
+   * Failures the surface around these endpoints answers with instead of a
+   * handler: authentication, authorization, rate limits. Declared on every
+   * endpoint, so `HttpApiClient` and `ActionCliClient` decode them as typed
+   * failures rather than reporting a decode error. Each schema keeps its own
+   * `httpApiStatus`, and no two of them may share a status with an action error.
+   */
+  readonly errors?: Errors;
 }
 type Endpoint<A extends Any, E extends Codec> = A extends {
   readonly http: false;
 } ? never : A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["errors"][number] | E>, never> : never;
-type ApiGroup<G extends Actions> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G>>> : never;
+type ApiGroup<G extends Actions, E extends Codec> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G> | E>> : never;
 /** The native `HttpApi` of every HTTP-enabled action of `G`, one group per action group. */
-export type Api<G extends Actions> = HttpApi.HttpApi<"actions", ApiGroup<G>>;
+export type Api<G extends Actions, E extends Codec = never> = HttpApi.HttpApi<"actions", ApiGroup<G, E>>;
 /** A namespaced HTTP binding. */
-export interface Http<Groups extends ReadonlyArray<Actions>> {
+export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec> = []> {
   /** The exact contracts bound to this HTTP adapter, in declaration order. */
   readonly groups: Groups;
-  readonly api: Api<Groups[number]>;
+  readonly api: Api<Groups[number], Errors[number]>;
   /**
    * Serve any number of implementations in one layer. Build failures, build
    * services and request services are unions over precisely those apps.
@@ -34,6 +42,6 @@ export interface Http<Groups extends ReadonlyArray<Actions>> {
  * Bind the contract-level configuration once. Every route is `POST
  * <apiPath>/<group>/<action>`, so action names may repeat across groups.
  */
-export declare function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G>;
+export declare function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(options: Options<E>, ...groups: G): Http<G, E>;
 //#endregion
 export { ActionHttp_d_exports };

package/dist/ActionHttp.mjs

@@ -4,26 +4,40 @@ import { Effect, Layer } from "effect";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
 //#region src/ActionHttp.ts
 const httpActions = (group) => group.actions.filter((action) => action.http);
-const endpoint = (apiPath, group, action) => HttpApiEndpoint.post(action.name, `${apiPath}/${group.name}/${action.name}`, {
+/** Surface errors join an action's own, without repeating a schema it already declares. */
+const errorsOf = (options, action) => [...action.errors, ...(options.errors ?? []).filter((error) => !action.errors.includes(error))];
+const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
-	error: [...action.errors, ...group.schemaError?.errors ?? []]
+	error: errorsOf(options, action)
 }).annotate(OpenApi.Description, action.description);
-function erasedApi(groups, options) {
-	const [first, ...rest] = groups.flatMap((group) => {
-		const [first, ...rest] = httpActions(group).map((action) => endpoint(options.apiPath, group, action));
-		return first === void 0 ? [] : [HttpApiGroup.make(group.name).add(first, ...rest)];
-	});
-	const empty = HttpApi.make("actions");
-	return first === void 0 ? empty : empty.add(first, ...rest);
-}
-const schemaErrorMiddleware = (policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: policy.errors }) {}
+/** The native middleware declares the policy's errors on every endpoint it wraps. */
+const schemaErrorMiddleware = (name, policy) => {
+	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policy.errors }) {}
 	return {
 		SchemaErrors,
 		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
 	};
 };
+function bind(options, group) {
+	const [first, ...rest] = httpActions(group).map((action) => endpoint(options, group, action));
+	if (first === void 0) return void 0;
+	const native = HttpApiGroup.make(group.name).add(first, ...rest);
+	if (group.schemaError === void 0) return {
+		native,
+		policy: Layer.empty
+	};
+	const policy = schemaErrorMiddleware(group.name, group.schemaError);
+	return {
+		native: native.middleware(policy.SchemaErrors),
+		policy: policy.layer
+	};
+}
+function apiOf(groups) {
+	const [first, ...rest] = groups;
+	const empty = HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" });
+	return first === void 0 ? empty : empty.add(first, ...rest);
+}
 /**
 * `HttpApiBuilder.handleAll` registers a dynamically assembled record. The
 * action selected by the native router determines the input before `dispatch`
@@ -34,32 +48,33 @@ const schemaErrorMiddleware = (policy) => {
 const erasedHandlers = (handlers) => {
 	return handlers;
 };
-/** Build routes for one group. Handler erasure is limited to native dynamic endpoint registration. */
-const groupLayer = (options, app) => {
-	const actions = httpActions(app.group);
-	if (actions.length === 0) return Layer.empty;
-	const api = erasedApi([app.group], options);
-	const entries = (record) => Object.fromEntries(actions.map((action) => [action.name, (request) => dispatch(app.group, action, record)(request.payload)]));
-	const handlers = (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(record)));
-	if (app.group.schemaError === void 0) return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(api).pipe(Layer.provide(handlers(erasedHandlers(record))))));
-	const schemaErrors = schemaErrorMiddleware(app.group.schemaError);
-	const policyApi = api.middleware(schemaErrors.SchemaErrors);
-	const policyHandlers = (record) => HttpApiBuilder.group(policyApi, app.group.name, (builder) => {
-		const dynamicEntries = entries(record);
-		return builder.handleAll(dynamicEntries);
-	});
-	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(policyApi).pipe(Layer.provide(policyHandlers(erasedHandlers(record))), Layer.provide(schemaErrors.layer))));
+/** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
+const groupHandlers = (api, app, policy) => {
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, app.before)(request.payload)]));
+	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(policy));
 };
 function make(options, ...groups) {
 	assertDistinct("action group", groups.map((group) => group.name));
+	const bound = new Map(groups.flatMap((group) => {
+		const binding = bind(options, group);
+		return binding === void 0 ? [] : [[group, binding]];
+	}));
 	const layer = (...apps) => {
 		assertDistinct("implementation group", apps.map((app) => app.group.name));
 		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
-		return apps.map((app) => groupLayer(options, app)).reduce((all, app) => Layer.merge(all, app), Layer.empty);
+		const served = apps.flatMap((app) => {
+			const binding = bound.get(app.group);
+			return binding === void 0 ? [] : [{
+				app,
+				...binding
+			}];
+		});
+		const api = apiOf(served.map(({ native }) => native));
+		return served.reduce((layer, { app, policy }) => layer.pipe(Layer.provide(groupHandlers(api, app, policy))), HttpApiBuilder.layer(api));
 	};
 	return {
 		groups,
-		api: erasedApi(groups, options),
+		api: apiOf([...bound.values()].map(({ native }) => native)),
 		layer
 	};
 }

package/dist/ActionMcp.d.mts

@@ -1,6 +1,6 @@
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
 import { Cause, Layer } from "effect";
-import { McpServer } from "effect/unstable/ai";
+import { McpSchema, McpServer } from "effect/unstable/ai";
 import { HttpRouter } from "effect/unstable/http";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
@@ -24,18 +24,20 @@ export interface StdioOptions {
   readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
   readonly instructions?: string;
 }
+/** The native server supplies its own request context to every tool call. */
+type ToolRequestContext<App> = Exclude<RequestContext<App>, McpSchema.McpRequestContext>;
 /**
  * Serve MCP tools over one Streamable HTTP endpoint.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number]>>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | RequestContext<Apps[number]>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number]>>;
 //#endregion

package/dist/ActionToolkit.d.mts

@@ -1,5 +1,5 @@
 import { Action_d_exports, Any } from "./Action.mjs";
-import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
+import { AnyImplementation, BeforeContext, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
 import { Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
 //#region src/ActionToolkit.d.ts
@@ -14,10 +14,11 @@ type NativeTool<A extends Any, R> = A extends {
   readonly failure: Schema.Union<A["errors"]>;
   readonly failureMode: "return";
 }, R> : never;
-type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any> ? H : never;
+type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any, any> ? H : never;
+/** A tool needs what its handler needs, plus what the group's `before` hook needs. */
 type ToolForAction<App extends AnyImplementation, A extends Any> = A extends {
   readonly mcp: object;
-} ? NativeTool<A, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>>> : never;
+} ? NativeTool<A, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | BeforeContext<App>> : never;
 type ToolsFor<App extends AnyImplementation> = App extends AnyImplementation ? ToolForAction<App, App["group"]["actions"][number]> : never;
 type ToolkitTools<Apps extends ReadonlyArray<AnyImplementation>> = { readonly [T in ToolsFor<Apps[number]> as T["name"]]: T; };
 /** Native tools and the layer that binds their action implementations. */

package/dist/internal/implementation.d.mts

@@ -9,31 +9,40 @@ type ErasedHandler<R> = {
 }["handle"];
 /** An adapter's erased view of a record of handlers with request requirements `R`. */
 export type Handlers<R> = Readonly<Record<string, ErasedHandler<R>>>;
+/**
+ * An adapter's erased view of the pre-handler hook. It sees the selected action
+ * contract, so a group-wide policy reads `access` rather than the action name.
+ */
+export type Before<R> = (action: Any) => Effect.Effect<void, ErasedValue, R>;
 /** Per-request requirements of the handler selected by an action name. */
 export type HandlerContext<H, Name extends keyof H> = H[Name] extends ((input: never) => Effect.Effect<infer _A, infer _E, infer R>) ? R : never;
 /** The union of per-request requirements declared by a handler record. */
 export type HandlersContext<H> = { readonly [K in keyof H]: HandlerContext<H, K>; }[keyof H];
 /**
- * An acquired handler record for a group.
+ * An acquired handler record for a group, with the hook that runs before each of them.
  *
  * The private field makes this class nominal: a structurally similar object,
  * including one made by spreading an implementation, is not an implementation.
  */
-export declare class Implementation<G extends Actions, H, EX, RX> {
+export declare class Implementation<G extends Actions, H, EX, RX, RB> {
   #private;
   /** The group whose exact handler record was built. */
   readonly group: G;
   private constructor();
   /** Acquire the exact handler record in the adapter layer's scope. */
   get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
-  static make<G extends Actions, H, EX, RX>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>): Implementation<G, H, EX, RX>;
+  /** Runs once per invocation, before the selected handler, on every surface. */
+  get before(): Before<RB> | undefined;
+  static make<G extends Actions, H, EX, RX, RB>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>, before: Before<RB> | undefined): Implementation<G, H, EX, RX, RB>;
 }
 /** Any nominal implementation of `G`, with its record and channels erased. */
-export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
+export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any, any>;
+/** Pre-handler requirements of one implementation, or of a union of them. */
+export type BeforeContext<App> = App extends Implementation<any, any, any, any, infer RB> ? RB : never;
 /** Per-request requirements of one implementation, or of a union of them. */
-export type RequestContext<App> = App extends Implementation<any, infer H, any, any> ? HandlersContext<H> : never;
+export type RequestContext<App> = App extends Implementation<any, infer H, any, any, infer RB> ? HandlersContext<H> | RB : never;
 /** Handler-acquisition failures of one implementation, or of a union of them. */
-export type BuildError<App> = App extends Implementation<any, any, infer EX, any> ? EX : never;
+export type BuildError<App> = App extends Implementation<any, any, infer EX, any, any> ? EX : never;
 /** Handler-acquisition requirements of one implementation, or of a union of them. */
-export type BuildContext<App> = App extends Implementation<any, any, any, infer RX> ? RX : never;
+export type BuildContext<App> = App extends Implementation<any, any, any, infer RX, any> ? RX : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 //#region src/internal/implementation.ts
 /**
-* An acquired handler record for a group.
+* An acquired handler record for a group, with the hook that runs before each of them.
 *
 * The private field makes this class nominal: a structurally similar object,
 * including one made by spreading an implementation, is not an implementation.
@@ -9,28 +9,37 @@ import { Effect } from "effect";
 var Implementation = class Implementation {
 	group;
 	#build;
-	constructor(group, build) {
+	#before;
+	constructor(group, build, before) {
 		this.group = group;
 		this.#build = build;
+		this.#before = before;
 	}
 	/** Acquire the exact handler record in the adapter layer's scope. */
 	get build() {
 		return this.#build;
 	}
-	static make(group, build) {
-		return new Implementation(group, build);
+	/** Runs once per invocation, before the selected handler, on every surface. */
+	get before() {
+		return this.#before;
+	}
+	static make(group, build, before) {
+		return new Implementation(group, build, before);
 	}
 };
 /**
 * Select and invoke a handler after an adapter has selected a concrete action.
+* The pre-handler hook runs first, inside the action's span, so every surface
+* applies it exactly once and its failures are declared errors of the action.
 * `R` remains in the returned effect so transport layers cannot erase required
 * per-request services while assembling routes.
 */
-const dispatch = (group, action, handlers) => {
+const dispatch = (group, action, handlers, before) => {
 	const handle = handlers[action.name];
 	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
 	return (input) => {
-		return Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+		const run = () => before === void 0 ? handle(input) : Effect.flatMap(before(action), () => handle(input));
+		return Effect.withSpan(Effect.suspend(run), `${group.name}.${action.name}`, { captureStackTrace: false });
 	};
 };
 //#endregion

package/dist/internal/tools.mjs

@@ -55,11 +55,12 @@ const assertMcpObjectInput = (action, tool) => {
 };
 const project = (projection, entry) => {
 	const tool = projection === "native" ? nativeTool(entry.action) : mcpTool(entry.action);
-	if (projection === "mcp") assertMcpObjectInput(entry.action, tool);
-	return tool;
+	if (projection === "native") return tool;
+	assertMcpObjectInput(entry.action, tool);
+	return tool.annotate(Tool.Strict, true);
 };
 const handler = (projection, app, action, handlers) => {
-	const run = (input) => dispatch(app.group, action, handlers)(input);
+	const run = (input) => dispatch(app.group, action, handlers, app.before)(input);
 	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
 };
 /**

package/docs/Action.md

@@ -16,18 +16,22 @@ function make<Name, Input = NoInput, Output, Errors = [], Http = true, Mcp = und
   options: Options<Input, Output, Errors, Http, Mcp>,
 ): Action<Name, Input, Output, Errors, Http, Mcp>;
 
+/** What the action does to its resource. Authorization metadata, not an MCP hint. */
+type Access = "read" | "write";
+
 interface Options<Input, Output, Errors, Http, Mcp> {
   readonly description: string;
   readonly input?: Input; // omit for an action without arguments
   readonly success: Output;
   readonly errors?: Errors; // ReadonlyArray<Codec>; defaults to []
+  readonly access?: Access; // defaults to "write"
   readonly http?: Http; // false hides the action from HTTP routes and clients
   readonly mcp?: Mcp; // false hides the action from MCP; otherwise McpOptions
 }
 
 interface McpOptions {
   readonly name?: string; // tool name; defaults to the action name; ^[A-Za-z0-9_-]{1,128}$
-  readonly readOnly?: boolean; // readOnlyHint, default false
+  readonly readOnly?: boolean; // readOnlyHint, default access === "read"
   readonly destructive?: boolean; // destructiveHint, default !readOnly
   readonly idempotent?: boolean; // idempotentHint, default false
   readonly openWorld?: boolean; // openWorldHint, default true
@@ -39,6 +43,7 @@ interface Action<Name, Input, Output, Errors, Http, Mcp> {
   readonly input: Input;
   readonly success: Output;
   readonly errors: Errors;
+  readonly access: Access; // resolved
   readonly http: Http;
   readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld }; // resolved
 }
@@ -63,27 +68,42 @@ export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
   { httpApiStatus: 404 },
 ) {}
 
+// `access: "read"` states the fact once: it is what the group's `before` hook
+// authorizes on, and it is where `mcp.readOnly` comes from.
 export const GetUser = Action.make("getUser", {
   description: "Look up a user in your tenant.",
   input: Schema.Struct({ id: Schema.String }),
   success: Schema.Struct({ id: Schema.String, name: Schema.String }),
   errors: [UserNotFound],
-  mcp: { name: "get_user", readOnly: true },
+  access: "read",
+  mcp: { name: "get_user" },
+});
+
+// A write. `access` defaults to "write", but say it: the default is a fallback,
+// not a statement, and an unclassified action is the one a reviewer must check.
+export const RenameUser = Action.make("renameUser", {
+  description: "Rename a user in your tenant.",
+  input: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  success: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  errors: [UserNotFound],
+  access: "write",
+  mcp: { name: "rename_user", destructive: false },
 });
 
 // No arguments: omit `input`. Identity comes from request context, never from input.
 export const WhoAmI = Action.make("whoAmI", {
   description: "Inspect the authenticated actor.",
   success: Schema.Struct({ id: Schema.String, tenantId: Schema.String }),
-  mcp: { readOnly: true },
+  access: "read",
 });
 
 // MCP-only: no HTTP route, no client method.
 export const ListChanges = Action.make("listChanges", {
   description: "List renames in your tenant, oldest first.",
   success: Schema.Struct({ changes: Schema.Array(Schema.String) }),
+  access: "read",
   http: false,
-  mcp: { name: "list_changes", readOnly: true },
+  mcp: { name: "list_changes" },
 });
 
 // Input decoding is the schema's: "21" on the wire, 21 in the handler.
@@ -91,7 +111,7 @@ export const Double = Action.make("double", {
   description: "Double a finite number supplied as a string.",
   input: Schema.Struct({ value: Schema.FiniteFromString }),
   success: Schema.Finite,
-  mcp: { readOnly: true },
+  access: "read",
 });
 ```
 
@@ -101,13 +121,15 @@ export const Double = Action.make("double", {
 - Omit `input` for a no-argument action. The default is an empty object schema, which satisfies MCP's object-root requirement. Clients still pass `{ payload: {} }`.
 - `errors` is a list of schemas, default none. Each keeps its own `httpApiStatus` annotation; an unannotated error is served as HTTP 500. Group-level `errors` are appended to every action of the group (see [ActionGroup.md](ActionGroup.md)).
 - A handler may fail only with the declared errors. Anything else is a defect.
+- `access` is `"read"` or `"write"` and defaults to `"write"`, so an action nobody classified is treated as the dangerous one. It is authorization metadata for a group's `before` hook (see [ActionGroup.md](ActionGroup.md)); the library itself authorizes nothing and no adapter reads it.
+- `access` is independent of `mcp`. A local-only action (`mcp: false`) still has one, and an action may set `access: "write"` with `mcp: { readOnly: true }` if the tool hint should say something else. Derive authorization from `access`, never from a tool hint.
 - Both transports are on by default. `http: false` removes the route and the client method. `mcp: false` removes the tool. Both `false` makes a local-only action, reachable through `ActionCli` only.
 - MCP input must have an object-root JSON Schema. Scalar or array input is fine for HTTP, but `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, and `ActionToolkit.make` throw when called with such an action. Success and error schemas may be any shape.
 - `mcp.name` is the tool name, at most 128 characters, unique within the group and within any Toolkit or MCP projection that serves the group. Default is the action name.
-- Hint defaults: `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
+- Hint defaults: `readOnly: access === "read"`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
 - Schemas must be service-free. Put service access in the handler.
 - The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
-- Object schemas strip excess fields on decode unless the schema is configured to reject them.
+- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP is not strict, and cannot be made strict without a hack: Effect merges one `HttpApi.ParseOptions` per endpoint and uses it for payload decoding _and_ error encoding, so `onExcessProperty: "error"` also rejects a `TaggedError` instance's own `message` and `stack`, turning a declared 409 into an empty 500. Making the payload schema itself strict would require wrapping it in an open schema, which erases its OpenAPI shape. Declare the fields you accept and treat extra HTTP fields as ignored.
 
 ## Failure modes
 
@@ -115,3 +137,5 @@ export const Double = Action.make("double", {
 - Type error `Effect<..., X, ...> is not assignable` in `implement`: the handler fails with an undeclared error `X`. Add it to `errors` or handle it.
 - `<action>: MCP input must have an object root` thrown by `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, or `ActionToolkit.make`: an MCP-enabled action has non-object input. Wrap it in `Schema.Struct` or set `mcp: false`.
 - Handler receives a string where a number was expected: the schema is `Schema.String`, not a transforming codec such as `Schema.FiniteFromString`.
+- A read action is refused by an authorization hook that reads `access`: `access` was omitted, so it defaulted to `"write"`. Declare it.
+- A tool shows `readOnlyHint: false` for a read: the action sets `mcp: { readOnly: false }` explicitly, which wins over `access`.

package/docs/ActionCatalog.md

@@ -20,6 +20,7 @@ interface Entry {
   readonly group: string;
   readonly name: string;
   readonly description: string;
+  readonly access: "read" | "write"; // resolved; "write" unless the contract says otherwise
   readonly http: boolean;
   readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld };
   readonly input: JsonSchema.JsonSchema;
@@ -47,6 +48,7 @@ process.stdout.write(JSON.stringify(catalog, null, 2));
 - Schemas describe encoded action values: the JSON on the wire, not MCP's `{ value }` envelope and not deployment URLs.
 - Each schema owns its `$defs`. Equal schema identifiers in different entries never replace each other. Recursive references stay local to their schema.
 - `errors` includes group-level errors. HTTP schema-policy errors are listed separately in `httpSchemaErrors`.
+- `access` is the action's resolved authorization metadata, not a permission. A reader may use it to tell reads from writes; it grants nothing and names no scope.
 - Local-only actions (`http: false`, `mcp: false`) are included. Presence in a catalog is descriptive. It is not authorization, tool publication, or proof that a route is mounted. The host decides what to publish.
 - The package adds no search, no catalog HTTP endpoint, and no TypeScript code generation.
 

package/docs/ActionCli.md

@@ -9,15 +9,15 @@ nothing is fetched over HTTP.
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 
 /** One explicitly selected action. */
-const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, Parameters = never>(
-  app: Implementation<G, H, EX, RX>,
+const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, RB, Parameters = never>(
+  app: Implementation<G, H, EX, RX, RB>,
   name: Name,
   options?: Options<SuccessType, Parameters>,
-) => Command.Command<string, never, {}, EX | SchemaError | DeclaredErrors, Exclude<RX | HandlerContext, Scope>>;
+) => Command.Command<string, never, {}, EX | SchemaError | DeclaredErrors, Exclude<RX | RB | HandlerContext, Scope>>;
 
 /** Every action of the group, including local-only ones, under the group name. */
-const group: <G, H, EX, RX>(
-  app: Implementation<G, H, EX, RX>,
+const group: <G, H, EX, RX, RB>(
+  app: Implementation<G, H, EX, RX, RB>,
   options?: GroupOptions,
 ) => Command.Command<string, {}, {}, EX | SchemaError | DeclaredErrors, ...>;
 
@@ -49,6 +49,7 @@ import { Console, Effect, Logger } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { actors, CurrentActor } from "./auth.js";
 import { UserApp } from "./handlers.js";
 import { Users } from "./users.js";
 
@@ -64,6 +65,9 @@ const all = ActionCli.group(UserApp);
 Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
   Effect.tapCause((cause) => Console.error(cause)),
   Effect.provideService(Logger.LogToStderr, true),
+  // The group's `before` hook runs here too, so a local caller supplies the
+  // identity it reads exactly as HTTP middleware does for a request.
+  Effect.provideService(CurrentActor, actors.alice),
   Effect.provide(Users.layerMemory),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain({ disableErrorReporting: true }),
@@ -80,6 +84,7 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 - Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output; `--json` selects JSON again. Rendering cannot bypass validation.
 - Explicit flag names must not collide with the renderer's `--json` flag. A payload field named `json` is ordinary data; only the flag name is reserved.
 - Each invocation acquires the implementation in a scope and releases it after the call. Domain services and authority come from the host's provided layers. There is no HTTP fallback.
+- The group's pre-handler hook runs here too, before every command's handler. Its services are the caller's to provide, so a local CLI supplies the identity the hook reads exactly as HTTP middleware does. A CLI is not a trusted bypass.
 - Group commands use the default JSON syntax. For a custom tree, compose individual `command` results with native `Command` combinators.
 
 ## Failure modes
@@ -88,4 +93,5 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 - Command rejects `--input`: the command was built with `parameters`. Use its flags.
 - Type error: `name` is not an action of the group. Check `group.actions` names, not MCP tool names.
 - Handler cannot find a service: provide its Layer to the runtime (`Effect.provide`) before `runMain`. The command does not supply services.
+- A command requires a request-identity tag no handler yields: the group's `before` hook yields it. Provide it, or bind a separate implementation without the hook for local use.
 - `--json` flag conflict at definition: rename the native flag; the config property can keep its name.

package/docs/ActionGroup.md

@@ -1,7 +1,8 @@
 # ActionGroup
 
 A named set of actions. The group is what adapters serve, what clients are grouped by, and
-what `implement` binds handlers to. Shared errors and the HTTP schema-error policy live here.
+what `implement` binds handlers to. Shared errors, the pre-handler hook, and the HTTP
+schema-error policy live here.
 
 ## API
 
@@ -11,7 +12,7 @@ import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 function make<Name, Actions, Errors = [], PolicyErrors = []>(
   options: Options<Name, Errors, PolicyErrors>,
   ...actions: Actions
-): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+): Group<Name, WithErrors<Actions, Errors>, PolicyErrors, Errors>;
 
 interface Options<Name, Errors, PolicyErrors> {
   readonly name: Name; // HttpApiGroup identifier, OpenAPI tag, operation-ID prefix
@@ -24,20 +25,33 @@ interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
   readonly map: (failure: HttpApiError.HttpApiSchemaError) => Errors[number]["Type"];
 }
 
-interface Group<Name, Actions, PolicyErrors> {
+interface ImplementOptions<Errors, RB> {
+  /** Runs before every handler, on every surface. May fail only with the group's `errors`. */
+  readonly before: (action: Action.Any) => Effect.Effect<void, Errors[number]["Type"], RB>;
+}
+
+interface Group<Name, Actions, PolicyErrors, Errors> {
   readonly name: Name;
   readonly actions: Actions;
   readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
   /** Bind every handler at once; build-time services resolve once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never>(
+  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never, RB = never>(
     build: H | Effect.Effect<H, EX, RX>,
-  ) => Implementation<Group<Name, Actions, PolicyErrors>, H, EX, Exclude<RX, Scope.Scope>>;
+    options?: ImplementOptions<Errors, RB>,
+  ) => Implementation<
+    Group<Name, Actions, PolicyErrors, Errors>,
+    H,
+    EX,
+    Exclude<RX, Scope.Scope>,
+    RB
+  >;
 }
 
 /** Nominal. `group` is the bound contract; `build` acquires the handler record in a scope. */
-class Implementation<G, H, EX, RX> {
+class Implementation<G, H, EX, RX, RB> {
   readonly group: G;
   get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
+  get before(): ((action: Action.Any) => Effect.Effect<void, unknown, RB>) | undefined;
 }
 ```
 
@@ -50,7 +64,8 @@ all required.
 import { Effect, Schema } from "effect";
 import type { HttpApiError } from "effect/unstable/httpapi";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
-import { Forbidden, authorize, CurrentActor } from "./auth.js";
+import type * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Forbidden, CurrentActor } from "./auth.js";
 import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
 import { Users } from "./users.js";
 
@@ -82,28 +97,29 @@ export const UserActions = ActionGroup.make(
   WhoAmI,
 );
 
+// One rule for the whole group, read from each contract's own `access`. It runs
+// on HTTP, MCP, Toolkit and CLI alike, so no handler contains authorization code.
+const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
+  const permission = action.access === "read" ? "users:read" : "users:write";
+  const actor = yield* CurrentActor;
+
+  if (!actor.permissions.includes(permission)) return yield* new Forbidden({ permission });
+});
+
 // Build-time services (Users) are yielded in the builder, once per adapter layer.
-// Request-time services (CurrentActor) are yielded inside handlers.
+// Request-time services (CurrentActor) are yielded inside handlers and in `before`.
 export const UserApp = UserActions.implement(
   Effect.gen(function* () {
     const users = yield* Users;
 
     return {
-      getUser: ({ id }) =>
-        Effect.gen(function* () {
-          const actor = yield* authorize("users:read");
-
-          return yield* users.get(actor.tenantId, id);
-        }),
+      getUser: ({ id }) => Effect.flatMap(CurrentActor, (actor) => users.get(actor.tenantId, id)),
       renameUser: ({ id, name }) =>
-        Effect.gen(function* () {
-          const actor = yield* authorize("users:write");
-
-          return yield* users.rename(actor, id, name);
-        }),
+        Effect.flatMap(CurrentActor, (actor) => users.rename(actor, id, name)),
       whoAmI: () => Effect.map(CurrentActor, ({ id, tenantId }) => ({ id, tenantId })),
     };
   }),
+  { before: authorize },
 );
 
 // No build-time services: pass the record directly.
@@ -120,15 +136,24 @@ export const MathApp = MathActions.implement({ double: ({ value }) => Effect.suc
 - `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
 - `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and is not a substitute for adapter tests. There is no public handler service or Layer.
 
+### Pre-handler hook
+
+- `implement(handlers, { before })` binds one hook to the whole implementation. It runs once per invocation, immediately before the selected handler, on **every** surface: `ActionHttp`, `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, `ActionToolkit`, and `ActionCli`. There is no surface that skips it and no per-action opt-out.
+- It receives the selected action contract (`Action.Any`), so a policy reads `action.access`, `action.name` or `action.mcp` instead of a hand-maintained list. Write authorization against `access`.
+- It may fail only with the group's own `errors`, because those are the failures every action of the group declares. A hook that fails with anything else is a compile error; a group with no `errors` has no failure a hook could use. Its failure is encoded exactly like a handler's: the error's `httpApiStatus` on HTTP, an `isError` tool result on MCP.
+- Services it yields are request-time requirements, like a handler's, and they join the adapter's request context. A local caller (`ActionCli`, `ActionToolkit`, stdio) supplies them itself.
+- It runs inside the `<group>.<action>` span, before the handler. When it fails, the handler never runs.
+- It is not authentication. Establish identity in middleware, then let the hook authorize what that identity may do.
+
 ### Schema-error policy
 
 - Without a policy, HTTP answers decoding and encoding failures with Effect's native empty 400.
 - With a policy, `map` receives the native `HttpApiSchemaError` (`kind`, `cause`) and returns one of `errors`. HTTP uses that error's `httpApiStatus`, and the error appears in `Http.api`, in clients, and in OpenAPI.
-- `kind` values: `Payload` (input decoding), `Body` (success encoding), plus `Parameters`, `RequestHeaders`, `Query`, `ResponseHeaders`.
+- `kind` values: `Payload` (input decoding) and `Body` (success encoding). Actions declare no parameters, query, or headers, so no other kind occurs.
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
-- `cause` may contain input values. Never reflect it into the response.
+- HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
 - Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
 
@@ -139,3 +164,6 @@ export const MathApp = MathActions.implement({ double: ({ value }) => Effect.suc
 - Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
 - `map` is not typed from `errors` when declared as a standalone constant: annotate its parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`).
 - A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.
+- Type error on `before`'s error channel: the hook fails with an error the group does not declare. Add it to the group's `errors` so every action declares it.
+- `Type 'X' is not assignable to type 'never'` on `before` in a group without `errors`: the group declares no shared failure. Declare one.
+- The hook does not run for an action: it cannot happen through an adapter. A handler invoked directly through `build` is not dispatched and is not hooked; use an adapter, or `ActionCli`, in tests that must exercise the policy.

package/docs/ActionHttp.md

@@ -8,13 +8,17 @@ of groups into a contract value shared by the server, every client, and the Open
 ```ts
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 
-function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G>;
+function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(
+  options: Options<E>,
+  ...groups: G
+): Http<G, E>;
 
-interface Options {
+interface Options<Errors = []> {
   readonly apiPath: `/${string}`; // no default
+  readonly errors?: Errors; // failures the surface answers with, declared on every endpoint
 }
 
-interface Http<Groups> {
+interface Http<Groups, Errors = []> {
   readonly groups: Groups; // the exact contracts bound, in declaration order
   readonly api: HttpApi.HttpApi<"actions", ...>; // native HttpApi, one HttpApiGroup per group
   /** Serve implementations. Errors and requirements are unions over exactly these apps. */
@@ -42,10 +46,16 @@ import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi"
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { PublicActions, UserActions } from "./contracts.js";
 import { PublicApp, UserApp } from "./handlers.js";
-import { authentication } from "./auth.js";
-
-// Contract: shared by server and clients.
-export const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
+import { authentication, Unauthenticated } from "./auth.js";
+
+// Contract: shared by server and clients. `errors` are the failures the surface
+// itself renders — here the 401 from `authentication` — so a typed client decodes
+// them instead of reporting a decode error on an unexpected status.
+export const Http = ActionHttp.make(
+  { apiPath: "/api/actions", errors: [Unauthenticated] },
+  PublicActions,
+  UserActions,
+);
 
 // One layer per middleware set. Middleware provided to a layer applies to that layer only.
 const routes = Layer.mergeAll(
@@ -85,12 +95,15 @@ export const greeting = Effect.gen(function* () {
 ## Rules
 
 - `apiPath` has no default. Group names must be unique within one `make`. Action names need only be unique within their group; equal action names in different groups do not collide.
+- `errors` declares the failures the surface around these endpoints answers with rather than a handler: authentication, authorization, rate limiting, upstream unavailability. They are added to every endpoint's error schemas, so `HttpApiClient`, `ActionCliClient` and the in-memory `Testing.httpClient` decode them as typed failures, and they appear in OpenAPI on every operation. A schema an action already declares is not repeated.
+- No two schemas reachable from one endpoint may share an `httpApiStatus`: the client selects the decoder by status. Keep surface statuses (401, 403, 429, 503) apart from action statuses.
+- `errors` changes only what is declared. Nothing produces them: the middleware that renders those responses must encode a body that matches the schema, or the client sees a decode error again. Handlers cannot fail with them.
 - `Http.layer(...apps)` mounts only the supplied implementations. A group that is never passed to `layer` has no routes. A group with no HTTP-enabled actions is not built at all.
 - Middleware is per layer call. Groups that need different middleware go in separate `Http.layer` calls, merged with `Layer.mergeAll`.
 - Request-time handler services are `HttpRouter.Request.From<"Requires", R>`. Supply them with router middleware (`Authentication.middleware`, `HttpRouter.middleware`), `HttpRouter.provideRequest`, or the request context. Build-time services are ordinary layer requirements.
 - `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `HttpApi.addHttpApi` to combine with other APIs, `HttpApiClient.make`.
 - Client calls always take `{ payload }`. No-input actions take `{ payload: {} }`. Pass `null` or `undefined` only when the codec accepts it. There is no flat client.
-- Client effects fail with the declared errors, the group's policy errors, `SchemaError` for local codec failures, and native `HttpClientError`. MCP-only actions are absent from the client.
+- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures, and native `HttpClientError`. MCP-only actions are absent from the client.
 - Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.
 - Wire format without a policy: input failure is an empty 400, success is the encoded body, a declared error is its JSON encoding with its `httpApiStatus`, an encoding failure is an empty 400, a defect is an empty 500. Full table in [guarantees.md](guarantees.md).
 - Each handler runs in a span named `<group>.<action>`, a child of the request span. Decoding and encoding are outside it.
@@ -104,3 +117,5 @@ export const greeting = Effect.gen(function* () {
 - Client method missing for an action: the action is `http: false`.
 - Empty 400 on a valid-looking request: input did not decode. Set a `schemaError` policy on the group to get a typed body, and check `Content-Type: application/json`.
 - 415: wrong or missing content type.
+- `HttpClientError: Decode error (401 POST ...)` from a typed client: the surface answered with a status no endpoint declares. Add that error schema to `ActionHttp.make`'s `errors`.
+- A surface error decodes as the wrong type: two schemas share an `httpApiStatus` on the same endpoint. Give them distinct statuses.

package/docs/ActionMcp.md

@@ -118,9 +118,12 @@ Layer.launch(layer).pipe(
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in the handler.
 - Cancellation is Effect's native RPC interruption.
+- Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
 - stdio: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly, including the trusted principal. There is no authentication middleware. Tool arguments never establish identity. Keep stdout for protocol messages only and route logs to stderr.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
 
+- The group's pre-handler hook runs before every tool call. A refusal is the tool's declared failure: an `isError` result whose text is the error's JSON encoding, exactly as for a handler failure.
+
 ## Failure modes
 
 - `<action>: MCP input must have an object root; omit input for no arguments` thrown at the `layerHttp` or `layerStdio` call: the action has scalar or array input. Wrap it in a struct or set `mcp: false`.

package/docs/ActionToolkit.md

@@ -64,6 +64,8 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 - Supply identity at invocation, never when building the layer. Native context capture is not a security boundary.
 - This is not an MCP server. Use `ActionMcp` to expose the same actions to external clients.
 
+- The group's pre-handler hook runs before every tool call, and its services join each tool's requirements. The caller supplies them, as it does a handler's.
+
 ## Failure modes
 
 - Tool missing from the toolkit: the action has `mcp: false`. The Toolkit selects by MCP enablement.

package/docs/Authentication.md

@@ -2,7 +2,8 @@
 
 Two helpers for hosts that own identity: router middleware that provides a request-scoped
 identity service, and RFC 9728 protected-resource discovery with bearer challenges. Token
-verification, login, and consent stay in the application.
+verification, login, and consent stay in the application. Authorization is a group's
+pre-handler hook ([ActionGroup.md](ActionGroup.md)), not part of this module.
 
 ## API
 
@@ -103,7 +104,8 @@ export const routes = Layer.mergeAll(
 - `protectedResource` publishes what it is given. The deployment must ensure `resource` and `authorizationServers` are valid OAuth URLs (HTTPS, or loopback HTTP in development).
 - Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. Mount `discovery.layer` outside the authenticated layers. Caching policy is the host's.
 - `challenge()` quotes and escapes parameter values; it never rejects them. Name only the scopes needed for the request in `scope`; `scopesSupported` advertises the full set in metadata.
-- Tool discovery is never filtered by actor. Authorization is a handler concern (`yield* CurrentActor`, then check).
+- Tool discovery is never filtered by actor. Authorization belongs in the group's `before` hook, which runs on every surface with the action contract in hand; write the rule against `action.access` rather than repeating a check in each handler.
+- A response this middleware renders is not part of any endpoint's contract. Declare its schema in `ActionHttp.make`'s `errors` so typed clients decode the 401 instead of reporting a decode error ([ActionHttp.md](ActionHttp.md)).
 
 ## Failure modes
 
@@ -112,3 +114,4 @@ export const routes = Layer.mergeAll(
 - Discovery returns 404: the request path does not match `resource`'s path and query exactly, or `discovery.layer` is not merged into the served layer.
 - Discovery requires a token: `discovery.layer` was placed under the authentication middleware. Mount it separately.
 - 401 response lacks `WWW-Authenticate`: the host's failure response did not set it. Use `discovery.challenge(...)` in its headers.
+- A typed client reports `Decode error (401 ...)` instead of the failure schema: the response this middleware renders is not declared. Add it to `ActionHttp.make`'s `errors`.

package/docs/CONTEXT.md

@@ -5,12 +5,14 @@ use these words with these meanings.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, and transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, authorization metadata (`access`), and transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **Access**: `"read"` or `"write"` on an action, defaulting to `"write"`. States what the action does to its resource. Authorization metadata read by a pre-handler hook, independent of the MCP `readOnly` hint, which defaults from it.
 - **Group**: a named, ordered set of actions plus group-level errors and an optional schema-error policy. Adapters serve groups, clients are organized by group, and the group name is the OpenAPI tag. Made by `ActionGroup.make`.
 - **Contract**: an action or a group. Pure data; safe to import anywhere, including browsers.
 - **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors, possibly requiring services.
 - **Implementation**: a nominal binding of a complete handler record to a group, made by `group.implement`. Carries build-time error and requirement channels. Adapters accept implementations; `ActionCatalog` accepts contracts.
 - **Builder**: the record or Effect passed to `implement`. Runs once per adapter layer that serves the implementation.
+- **Pre-handler hook**: the `before` function passed to `implement`. Runs once per invocation, on every surface, with the selected action contract, before its handler. May fail only with the group's own errors. Its services are request-time requirements.
 - **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
 - **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
 - **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
@@ -18,6 +20,7 @@ use these words with these meanings.
 - **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. Encoded on every transport with its `httpApiStatus`.
 - **Schema-error policy**: a group option mapping Effect's `HttpApiSchemaError` (decode or encode failure) to a declared policy error with a status. HTTP only.
 - **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
+- **Surface error**: an error declared on an `ActionHttp` binding rather than on an action. Produced by middleware around the endpoints, never by a handler; declared so typed clients decode it.
 - **Local-only action**: `http: false` and `mcp: false`. Reachable through `ActionCli` and listed in the catalog.
 - **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
 - **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
@@ -31,6 +34,6 @@ use these words with these meanings.
 - `src/internal/actions.ts` and `src/internal/implementation.ts` hold the shared shapes adapters consume: the contract half of a group, the schema-error policy, and the nominal `Implementation` class. Everything under `src/internal` is not public API; the public modules re-export the types consumers need.
 - Each adapter owns its own mapping from contracts to its surface and never reaches into another adapter. HTTP does not know about tool names; MCP does not know about routes.
 - Adapters build on Effect's own servers and clients: `HttpApi` for HTTP, `McpServer` for MCP, `Toolkit` for the AI toolkit, `Command` for the CLI. The library adds no protocol runtime and defines no application error types.
-- Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application.
+- Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application. Authorization is the application's pre-handler hook, which the library runs but never writes.
 - `Testing` depends only on `effect`. `TestingClient` is the single module that loads the optional MCP client peer.
 - Docs: `README.md` is the pitch for humans. `docs/` is the reference for agents, one card per module. `skills/effect-actions` is a copy of `docs/`, with this vocabulary included. `CONTRIBUTING.md` and `AGENTS.md` are for maintainers.

package/docs/README.md

@@ -17,9 +17,9 @@ Package facts that apply everywhere:
 | Read                                     | When you need to                                                                       |
 | ---------------------------------------- | -------------------------------------------------------------------------------------- |
 | [setup.md](setup.md)                     | install, pin versions, pick entry points, know what the package does not do            |
-| [Action.md](Action.md)                   | define one contract: input, success, errors, HTTP and MCP flags, tool hints            |
-| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, set a schema-error policy, bind handlers       |
-| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, publish OpenAPI, call the API with `HttpApiClient`             |
+| [Action.md](Action.md)                   | define one contract: input, success, errors, read/write access, HTTP and MCP flags     |
+| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, run one check before every handler, bind them  |
+| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, declare the surface's own errors, publish OpenAPI, call it     |
 | [ActionMcp.md](ActionMcp.md)             | serve MCP tools over Streamable HTTP or stdio                                          |
 | [ActionToolkit.md](ActionToolkit.md)     | use actions as a native Effect AI `Toolkit` without a server                           |
 | [ActionCli.md](ActionCli.md)             | run handlers in-process from a terminal command                                        |
@@ -54,7 +54,7 @@ const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: Schema.Struct({ name: Schema.String }),
   success: Schema.String,
-  mcp: { readOnly: true },
+  access: "read",
 });
 
 export const Actions = ActionGroup.make({ name: "greetings" }, Greet);

package/docs/guarantees.md

@@ -5,10 +5,12 @@ Rules that hold across every adapter. Module pages link here rather than repeati
 ## Dependency lifetimes
 
 - Handlers receive decoded input, return decoded results, and may fail only with declared errors. Anything else is a defect.
+- A group's pre-handler hook (`implement(handlers, { before })`) runs once per invocation on every surface, before the selected handler, inside that handler's span. It may fail only with the group's own errors, and its services are request-time requirements like a handler's. No adapter can skip it; only calling `build` directly does, and that is not dispatch.
 - Build-time services are those yielded in the `implement` builder Effect. They resolve once per adapter layer, in that layer's scope. An implementation served by two adapters is built twice. Share state through a Layer provided to the adapters, never through the builder.
 - Request-time services are those yielded inside a handler. For HTTP-hosted adapters (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request.From<"Requires", R>` and are supplied by router middleware, `HttpRouter.provideRequest`, or request context. For `ActionToolkit`, `ActionCli`, and `ActionMcp.layerStdio` the host supplies them at invocation.
 - Use distinct tags for build-time capabilities and request-scoped identity. Never provide an identity or tenant tag in a startup layer or root context. The adapters use native Effect context capture and merging: a startup value under a tag can shadow a request value or satisfy a missing one. Types verify presence, not provenance.
-- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization.
+- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization; the `before` hook is the one place the library guarantees runs first, so put the check there rather than in each handler.
+- `access` is contract metadata. Nothing in the library reads it: adapters ignore it and the catalog only reports it. An action defaults to `access: "write"` so a hook that fails closed does so without a list of exceptions.
 - `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.layer` acquires it once for the layer's lifetime.
 
 ## Wire behavior
@@ -20,6 +22,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
 | Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: { value: <encoded> }`                                                              |
 | Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
+| Pre-handler hook failure    | the same, using the hook's error schema; the handler never runs                                       | the same `isError` result; the handler never runs                                                      |
 | Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
 | Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                  |
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
@@ -27,7 +30,8 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
-- Object schemas strip excess fields unless configured to reject them.
+- `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are HTTP-only, produced by middleware rather than by the library, and never returnable by a handler. MCP is unaffected.
+- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP is not strict, and cannot be made strict without a hack: Effect merges one `HttpApi.ParseOptions` per endpoint and uses it for payload decoding _and_ error encoding, so `onExcessProperty: "error"` also rejects a `TaggedError` instance's own `message` and `stack`, turning a declared 409 into an empty 500. Making the payload schema itself strict would require wrapping it in an open schema, which erases its OpenAPI shape. Declare the fields you accept and treat extra HTTP fields as ignored.
 
 ## Namespaces
 
@@ -51,5 +55,5 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 - HTTP is JSON `POST` on `HttpApi`, not Effect RPC. MCP is native `McpServer`, no SDK runtime dependency.
 - Actions are unary: no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting; the package supplies shapes for the first two only.
+- Authentication and authorization are the application's. The library supplies the seams: `Authentication.middleware` for identity, `implement({ before })` for one authorization rule per group, `access` for what a rule reads, and `ActionHttp.make`'s `errors` for what a client can decode. It defines no error types, no scopes and no verifier. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting.
 - The catalog is descriptive. Presence in it grants nothing.

package/docs/setup.md

@@ -54,7 +54,7 @@ What the package does, and nothing else:
 - HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
 - MCP means one native `McpServer` `Tool` per action. There is no MCP SDK runtime dependency.
 - Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. The library provides a middleware shape and discovery metadata, not a token verifier. Tool discovery is never filtered by actor.
+- Authentication and authorization are the application's. The library provides the seams — `Authentication.middleware` for identity, `implement({ before })` for one authorization rule per group, `access` for what that rule reads, `ActionHttp.make`'s `errors` for what a client can decode — and no token verifier, error types or scopes of its own. Tool discovery is never filtered by actor.
 
 ## Failure modes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {