expandai 0.0.0 → 0.0.2

package/src/Commands/Search.ts

@@ -0,0 +1,92 @@
+import { Args, Command, Options } from '@effect/cli'
+import { Console, Effect, Layer, Match, Schema } from 'effect'
+import { ApiClient } from '../ApiClient.js'
+import { ConfigManager } from '../Config.js'
+import { renderSnippets } from '../Snippets.js'
+
+export class SnapshotSnippetsUnavailable extends Schema.TaggedError<SnapshotSnippetsUnavailable>()(
+	'SnapshotSnippetsUnavailable',
+	{
+		snapshotId: Schema.String,
+		query: Schema.String,
+	},
+) {
+	get message() {
+		return `No snippets in snapshot ${this.snapshotId} matched '${this.query}'`
+	}
+}
+
+const snapshotId = Args.text({ name: 'snapshotId' }).pipe(
+	Args.withDescription('Snapshot handle from a previous fetch (meta.snapshotId, or the WebFetch hook note)'),
+)
+
+const query = Args.text({ name: 'query' }).pipe(Args.withDescription('Semantic search query'))
+
+const format = Options.text('format').pipe(
+	Options.withDefault('text'),
+	Options.withDescription('Output format (text or json)'),
+	Options.withSchema(Schema.Literal('text', 'json')),
+)
+
+const maxResults = Options.integer('max-results').pipe(
+	Options.withDefault(5),
+	Options.withDescription('Maximum snippets to return (default: 5)'),
+	Options.withSchema(Schema.Int.pipe(Schema.greaterThanOrEqualTo(1), Schema.lessThanOrEqualTo(50))),
+)
+
+const minScore = Options.float('min-score').pipe(
+	Options.withDefault(0.6),
+	Options.withDescription('Minimum snippet relevance score from 0 to 1 (default: 0.6)'),
+	Options.withSchema(Schema.Number.pipe(Schema.greaterThanOrEqualTo(0), Schema.lessThanOrEqualTo(1))),
+)
+
+const searchConfig = {
+	snapshotId,
+	query,
+	format,
+	maxResults,
+	minScore,
+}
+
+interface SearchCommandConfig {
+	readonly snapshotId: string
+	readonly query: string
+	readonly format: 'text' | 'json'
+	readonly maxResults: number
+	readonly minScore: number
+}
+
+export const SearchCommand: Command.Command<'search', never, unknown, SearchCommandConfig> = Command.make(
+	'search',
+	searchConfig,
+).pipe(
+	Command.withDescription('Search a previously fetched page by its snapshot handle — no new capture'),
+	Command.withHandler(
+		Effect.fnUntraced(
+			function* ({ format, maxResults, minScore, query, snapshotId }) {
+				const client = yield* ApiClient
+				const configManager = yield* ConfigManager
+				const host = yield* configManager.getPlaygroundHost()
+				const result = yield* client.fetchFetchSearch({
+					snapshotId,
+					search: { query, maxResults, minScore },
+					include: { markdown: true, json: true },
+				})
+
+				const output = yield* Match.value(format).pipe(
+					Match.when('text', () => {
+						const snippets = result.search.snippets
+						return snippets.length === 0
+							? Effect.fail(new SnapshotSnippetsUnavailable({ snapshotId, query }))
+							: Effect.succeed(renderSnippets(snapshotId, host, snippets))
+					}),
+					Match.when('json', () => Schema.encode(Schema.parseJson(Schema.Unknown, { space: 2 }))(result)),
+					Match.exhaustive,
+				)
+
+				yield* Console.log(output)
+			},
+			Effect.provide(Layer.mergeAll(ApiClient.Default, ConfigManager.Default)),
+		),
+	),
+)

package/src/Commands/Skill.ts

@@ -0,0 +1,30 @@
+import { Args, Command } from '@effect/cli'
+import { Effect } from 'effect'
+import { Skill } from '../Install/Skill.js'
+
+const hostArg = Args.choice([
+	['claude-code', 'claude-code' as const],
+	['cursor', 'cursor' as const],
+	['opencode', 'opencode' as const],
+	['codex', 'codex' as const],
+])
+
+const scopeArg = Args.choice([
+	['global', 'global' as const],
+	['project', 'project' as const],
+])
+
+const InstallCommand = Command.make('install', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Install the expandai skill into the chosen host + scope'),
+	Command.withHandler(({ host, scope }) => Effect.flatMap(Skill, (skill) => skill.install(host, scope))),
+)
+
+const UninstallCommand = Command.make('uninstall', { host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription('Remove the expandai skill from the chosen host + scope'),
+	Command.withHandler(({ host, scope }) => Effect.flatMap(Skill, (skill) => skill.uninstall(host, scope))),
+)
+
+export const SkillCommand = Command.make('skill').pipe(
+	Command.withDescription('Manage the expandai agent skill'),
+	Command.withSubcommands([InstallCommand, UninstallCommand]),
+)

package/src/Commands/Uninstall.ts

@@ -0,0 +1,38 @@
+import { Args, Command } from '@effect/cli'
+import { Effect, Option } from 'effect'
+import { Uninstall } from '../Install/Uninstall.js'
+
+const targetArg = Args.choice([
+	['all', 'all' as const],
+	['hook', 'hook' as const],
+	['skill', 'skill' as const],
+	['mcp', 'mcp' as const],
+]).pipe(Args.optional)
+
+const hostArg = Args.choice([
+	['claude-code', 'claude-code' as const],
+	['cursor', 'cursor' as const],
+	['opencode', 'opencode' as const],
+	['codex', 'codex' as const],
+]).pipe(Args.optional)
+
+const scopeArg = Args.choice([
+	['global', 'global' as const],
+	['project', 'project' as const],
+]).pipe(Args.optional)
+
+export const UninstallCommand = Command.make('uninstall', { target: targetArg, host: hostArg, scope: scopeArg }).pipe(
+	Command.withDescription(
+		'Remove expandai hooks, skills, and MCP server entries. Defaults to `all` across every host and scope when target/host/scope are omitted.',
+	),
+	Command.withHandler(
+		Effect.fnUntraced(function* ({ target, host, scope }) {
+			const uninstall = yield* Uninstall
+			yield* uninstall.uninstall({
+				target: Option.getOrUndefined(target),
+				host: Option.getOrUndefined(host),
+				scope: Option.getOrUndefined(scope),
+			})
+		}),
+	),
+)

package/src/Config.ts

@@ -0,0 +1,195 @@
+/**
+ * CLI configuration. Persisted at `$XDG_CONFIG_HOME/expandai/config.json`
+ * (default `~/.config/expandai/config.json`). The `EXPAND_API_KEY` and
+ * `EXPAND_API_URL` environment variables override the file.
+ */
+import { homedir } from 'node:os'
+import { FileSystem, Path } from '@effect/platform'
+import { NodeFileSystem, NodePath } from '@effect/platform-node'
+import { DEFAULT_PLAYGROUND_HOST } from '@expandai/sdk/Playground'
+import { Config, DateTime, Effect, Option, Schema } from 'effect'
+
+/** Production API endpoint used when neither `EXPAND_API_URL` nor the config file overrides it. */
+export const DEFAULT_API_URL = 'https://api.expand.ai'
+
+export const ApiKey = Schema.Redacted(Schema.NonEmptyTrimmedString.pipe(Schema.brand('ApiKey')))
+
+export const ApiKeyConfig = Schema.TaggedStruct('ApiKey', { apiKey: ApiKey })
+export const OAuthConfig = Schema.TaggedStruct('OAuth', {
+	accessToken: Schema.Redacted(Schema.String),
+	refreshToken: Schema.optional(Schema.Redacted(Schema.String)),
+	expiresAt: Schema.DateTimeUtc,
+})
+
+export class ExpandCliConfig extends Schema.Class<ExpandCliConfig>('ExpandCliConfig')({
+	apiUrl: Schema.optional(Schema.URL),
+	authMethod: Schema.optional(Schema.Union(ApiKeyConfig, OAuthConfig)),
+}) {
+	static readonly Json = Schema.parseJson(ExpandCliConfig)
+}
+
+export class ConfigNotWritable extends Schema.TaggedError<ConfigNotWritable>()('ConfigNotWritable', {
+	path: Schema.String,
+}) {
+	get message() {
+		return `Cannot write to ${this.path}. Check filesystem permissions on the config directory.`
+	}
+}
+
+export class ConfigParseError extends Schema.TaggedError<ConfigParseError>()('ConfigParseError', {
+	path: Schema.String,
+	error: Schema.Defect,
+}) {
+	get message() {
+		return `Could not parse ${this.path}. Delete the file and run \`expandai login\` to recreate it.`
+	}
+}
+
+export class NotAuthenticated extends Schema.TaggedError<NotAuthenticated>()('NotAuthenticated', {}) {
+	get message() {
+		return 'Not authenticated. Run `expandai login` to authenticate.'
+	}
+}
+
+export class OAuthTokenExpired extends Schema.TaggedError<OAuthTokenExpired>()('OAuthTokenExpired', {
+	expiredAt: Schema.DateTimeUtc,
+}) {
+	get message() {
+		return `Your OAuth token expired at ${DateTime.formatIso(this.expiredAt)}. Run \`expandai login\` to re-authenticate.`
+	}
+}
+
+const Environment = Effect.gen(function* () {
+	const apiKey = yield* Schema.Config('EXPAND_API_KEY', ApiKey).pipe(Config.option)
+	const apiUrl = yield* Config.url('EXPAND_API_URL').pipe(Config.option)
+
+	return ExpandCliConfig.make({
+		apiUrl: Option.getOrUndefined(apiUrl),
+		authMethod: Option.getOrUndefined(Option.map(apiKey, (apiKey) => ({ _tag: 'ApiKey' as const, apiKey }))),
+	})
+})
+
+export class ConfigManager extends Effect.Service<ConfigManager>()('@expandai/cli/Config/ConfigManager', {
+	dependencies: [NodeFileSystem.layer, NodePath.layer],
+	effect: Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem
+		const path = yield* Path.Path
+
+		const configPath = yield* Config.string('XDG_CONFIG_HOME').pipe(
+			Config.withDefault(path.join(homedir(), '.config')),
+			Config.map((dir) => path.join(dir, 'expandai', 'config.json')),
+		)
+
+		const EnvironmentFromConfigFile = Effect.gen(function* () {
+			const exists = yield* fs.exists(configPath)
+			if (!exists) {
+				return ExpandCliConfig.make({})
+			}
+
+			const string = yield* fs.readFileString(configPath)
+			return yield* Schema.decode(ExpandCliConfig.Json)(string).pipe(
+				Effect.mapError((error) => new ConfigParseError({ path: configPath, error })),
+			)
+		})
+
+		const loadConfig = Effect.fn('loadConfig')(function* () {
+			const env = yield* Environment
+			const file = yield* EnvironmentFromConfigFile
+
+			const apiUrl = {
+				env: Option.fromNullable(env.apiUrl),
+				file: Option.fromNullable(file.apiUrl),
+			}
+			const authMethod = {
+				env: Option.fromNullable(env.authMethod),
+				file: Option.fromNullable(file.authMethod),
+			}
+
+			yield* Effect.logWarning(`EXPAND_API_URL overrides apiUrl from ${configPath}`).pipe(
+				Effect.when(() =>
+					Option.zipWith(apiUrl.env, apiUrl.file, (env, file) => env.toString() !== file.toString()).pipe(
+						Option.getOrElse(() => false),
+					),
+				),
+			)
+			yield* Effect.logWarning(`EXPAND_API_KEY overrides the auth method stored in ${configPath}`).pipe(
+				Effect.when(() => Option.isSome(authMethod.env) && Option.isSome(authMethod.file)),
+			)
+
+			return yield* Option.match(
+				Option.orElse(authMethod.env, () => authMethod.file),
+				{
+					onNone: () => Effect.fail(new NotAuthenticated()),
+					onSome: (authMethod) =>
+						Effect.succeed({
+							apiUrl: Option.firstSomeOf([apiUrl.env, apiUrl.file]).pipe(
+								Option.getOrElse(() => new URL(DEFAULT_API_URL)),
+							),
+							authMethod,
+						}),
+				},
+			)
+		})
+
+		const saveConfig = Effect.fn('saveConfig')(function* (config: ExpandCliConfig) {
+			yield* fs
+				.makeDirectory(path.dirname(configPath), { recursive: true })
+				.pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })))
+			const encoded = yield* Schema.encode(ExpandCliConfig.Json)(config)
+			yield* fs
+				.writeFileString(configPath, encoded, { mode: 0o600 })
+				.pipe(Effect.mapError(() => new ConfigNotWritable({ path: configPath })))
+			// `mode` only applies on creation; chmod handles a pre-existing file.
+			// Failures are non-fatal (e.g. chmod is a no-op on Windows, or the file
+			// is owned by another user) but surfaced at debug level so they're
+			// inspectable when DEBUG=true.
+			yield* fs.chmod(configPath, 0o600).pipe(
+				Effect.tapErrorCause((cause) =>
+					Effect.logDebug(`chmod 0o600 ${configPath} failed (file mode may not enforce 0600)`).pipe(
+						Effect.annotateLogs({ cause }),
+					),
+				),
+				Effect.ignore,
+			)
+		})
+
+		const updateConfig = Effect.fn('updateConfig')(function* (patch: Partial<ExpandCliConfig>) {
+			const existing = yield* EnvironmentFromConfigFile.pipe(Effect.orElseSucceed(() => ExpandCliConfig.make({})))
+			yield* saveConfig(ExpandCliConfig.make({ ...existing, ...patch }))
+		})
+
+		const clearConfig = Effect.fn('clearConfig')(function* () {
+			yield* saveConfig(ExpandCliConfig.make({}))
+		})
+
+		const getApiUrl = Effect.fn('getApiUrl')(function* () {
+			const env = yield* Environment
+			const file = yield* EnvironmentFromConfigFile
+
+			const apiUrl = {
+				env: Option.fromNullable(env.apiUrl),
+				file: Option.fromNullable(file.apiUrl),
+			}
+
+			return Option.firstSomeOf([apiUrl.env, apiUrl.file]).pipe(Option.getOrElse(() => new URL(DEFAULT_API_URL)))
+		})
+
+		// Public playground host for citation links. Reads `EXPAND_PLAYGROUND_HOST` — the same env
+		// var the API / cdp-server bake into `meta.playground` — so local/staging set one host for
+		// both server and CLI. The fetch path prefers the server-resolved `meta.playground` origin;
+		// only the snapshot-search path (no `meta.playground`) falls back to this.
+		const getPlaygroundHost = Effect.fn('getPlaygroundHost')(function* () {
+			return yield* Config.string('EXPAND_PLAYGROUND_HOST').pipe(Config.withDefault(DEFAULT_PLAYGROUND_HOST))
+		})
+
+		return {
+			configPath,
+			loadConfig,
+			saveConfig,
+			updateConfig,
+			clearConfig,
+			getApiUrl,
+			getPlaygroundHost,
+		} as const
+	}),
+}) {}

package/src/DeviceAuth.ts

@@ -0,0 +1,193 @@
+import { HttpClient, HttpClientRequest, HttpClientResponse } from '@effect/platform'
+import { NodeHttpClient } from '@effect/platform-node'
+import { DateTime, Duration, Effect, Inspectable, Match, Option, Redacted, Ref, Schema, String } from 'effect'
+import { ConfigManager, OAuthConfig } from './Config.js'
+
+const FormattedUserCode = Schema.transform(Schema.String, Schema.String, {
+	strict: true,
+	decode: (raw) => {
+		const upper = String.toUpperCase(raw)
+		return upper.length > 4 ? `${String.takeLeft(upper, 4)}-${String.takeRight(upper, upper.length - 4)}` : upper
+	},
+	encode: (formatted) => formatted.replace('-', ''),
+})
+
+const DurationFromSeconds = Schema.transform(Schema.Number, Schema.DurationFromSelf, {
+	strict: true,
+	decode: Duration.seconds,
+	encode: Duration.toSeconds,
+})
+
+export class DeviceCodeResponse extends Schema.Class<DeviceCodeResponse>('DeviceCodeResponse')({
+	device_code: Schema.String,
+	user_code: FormattedUserCode,
+	verification_uri: Schema.String,
+	verification_uri_complete: Schema.String,
+	expires_in: DurationFromSeconds,
+	interval: DurationFromSeconds,
+}) {}
+
+export class TokenResponse extends Schema.Class<TokenResponse>('TokenResponse')({
+	access_token: Schema.String,
+	expires_in: DurationFromSeconds,
+	token_type: Schema.String,
+	scope: Schema.optional(Schema.String),
+}) {}
+
+export class DeviceAuthRequestFailed extends Schema.TaggedError<DeviceAuthRequestFailed>()('DeviceAuthRequestFailed', {
+	endpoint: Schema.String,
+	error: Schema.Defect,
+	status: Schema.optional(Schema.Number),
+}) {
+	get message() {
+		return `Device auth request to ${this.endpoint} failed${this.status ? ` (${this.status})` : ''}: ${Inspectable.format(this.error)}`
+	}
+}
+
+export class DeviceAuthorizationDenied extends Schema.TaggedError<DeviceAuthorizationDenied>()(
+	'DeviceAuthorizationDenied',
+	{},
+) {
+	get message() {
+		return 'Authorization was denied by the user'
+	}
+}
+
+export class DeviceAuthorizationExpired extends Schema.TaggedError<DeviceAuthorizationExpired>()(
+	'DeviceAuthorizationExpired',
+	{},
+) {
+	get message() {
+		return 'Device authorization code expired'
+	}
+}
+
+const CLIENT_ID = 'expandai-cli'
+
+export class DeviceAuthService extends Effect.Service<DeviceAuthService>()('@expandai/cli/DeviceAuthService', {
+	dependencies: [NodeHttpClient.layer, ConfigManager.Default],
+	effect: Effect.gen(function* () {
+		const httpClient = yield* HttpClient.HttpClient
+		const configManager = yield* ConfigManager
+		const apiUrl = yield* configManager.getApiUrl()
+
+		const requestDeviceCode = Effect.fn('DeviceAuthService.requestDeviceCode')(function* () {
+			const DEVICE_AUTH_CODE_ENDPOINT = '/api/auth/device/code'
+
+			const request = yield* HttpClientRequest.post(new URL(DEVICE_AUTH_CODE_ENDPOINT, apiUrl)).pipe(
+				HttpClientRequest.bodyJson({ client_id: CLIENT_ID }),
+			)
+
+			return yield* httpClient.execute(request).pipe(
+				Effect.flatMap(HttpClientResponse.schemaBodyJson(DeviceCodeResponse)),
+				Effect.mapError(
+					(error) =>
+						new DeviceAuthRequestFailed({
+							endpoint: DEVICE_AUTH_CODE_ENDPOINT,
+							error,
+						}),
+				),
+			)
+		})
+
+		const pollForToken = Effect.fn('DeviceAuthService.pollForToken')(function* (
+			deviceCode: string,
+			interval: Duration.Duration,
+			expiresIn: Duration.Duration,
+		) {
+			const DEVICE_AUTH_TOKEN_ENDPOINT = '/api/auth/device/token'
+			// RFC 8628 §3.5: on `slow_down`, the polling interval MUST be increased by 5
+			// seconds for this and all subsequent requests.
+			const SLOW_DOWN_BUMP = Duration.seconds(5)
+			const intervalRef = yield* Ref.make(interval)
+
+			const PollErrorBody = Schema.Struct({
+				error: Schema.String,
+				error_description: Schema.optional(Schema.String),
+			})
+
+			// better-auth's `deviceAuthorization` plugin accepts JSON; RFC 8628 §3.4
+			// would normally require `application/x-www-form-urlencoded`. If we ever
+			// target a non-better-auth server, switch to `HttpClientRequest.bodyUrlParams`.
+			const singlePoll = HttpClientRequest.post(new URL(DEVICE_AUTH_TOKEN_ENDPOINT, apiUrl)).pipe(
+				HttpClientRequest.bodyJson({
+					grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+					device_code: deviceCode,
+					client_id: CLIENT_ID,
+				}),
+				Effect.flatMap(httpClient.execute),
+				Effect.flatMap(
+					HttpClientResponse.matchStatus({
+						'200': (response) =>
+							HttpClientResponse.schemaBodyJson(TokenResponse)(response).pipe(Effect.map(Option.some)),
+						orElse: (response) =>
+							HttpClientResponse.schemaBodyJson(PollErrorBody)(response).pipe(
+								Effect.flatMap(({ error, error_description }) =>
+									Match.value(error).pipe(
+										Match.when('authorization_pending', () =>
+											Ref.get(intervalRef).pipe(Effect.flatMap(Effect.sleep), Effect.as(Option.none<TokenResponse>())),
+										),
+										Match.when('slow_down', () =>
+											Ref.updateAndGet(intervalRef, (current) => Duration.sum(current, SLOW_DOWN_BUMP)).pipe(
+												Effect.flatMap(Effect.sleep),
+												Effect.as(Option.none<TokenResponse>()),
+											),
+										),
+										Match.when('access_denied', () => Effect.fail(new DeviceAuthorizationDenied())),
+										Match.when('expired_token', () => Effect.fail(new DeviceAuthorizationExpired())),
+										Match.orElse(() =>
+											Effect.fail(
+												new DeviceAuthRequestFailed({
+													endpoint: DEVICE_AUTH_TOKEN_ENDPOINT,
+													status: response.status,
+													error: error_description ?? error,
+												}),
+											),
+										),
+									),
+								),
+							),
+					}),
+				),
+				Effect.catchTags({
+					RequestError: (error) => new DeviceAuthRequestFailed({ endpoint: DEVICE_AUTH_TOKEN_ENDPOINT, error }),
+					ResponseError: (error) => new DeviceAuthRequestFailed({ endpoint: DEVICE_AUTH_TOKEN_ENDPOINT, error }),
+					HttpBodyError: (error) => new DeviceAuthRequestFailed({ endpoint: DEVICE_AUTH_TOKEN_ENDPOINT, error }),
+					ParseError: (error) => new DeviceAuthRequestFailed({ endpoint: DEVICE_AUTH_TOKEN_ENDPOINT, error }),
+				}),
+			)
+
+			const result = yield* Effect.repeat(singlePoll, { until: Option.isSome }).pipe(
+				Effect.timeoutFail({
+					duration: expiresIn,
+					onTimeout: () => new DeviceAuthorizationExpired(),
+				}),
+			)
+
+			return yield* Option.match(result, {
+				onNone: () => new DeviceAuthorizationExpired(),
+				onSome: Effect.succeed,
+			})
+		})
+
+		// INFO: better-auth's `deviceAuthorization` plugin issues access tokens
+		// with no refresh flow — `/api/auth/device/token` only accepts
+		// `grant_type=urn:ietf:params:oauth:grant-type:device_code`. Refresh is
+		// not part of the auth surface we're using, so we don't persist the
+		// refresh_token at all; ApiClient pre-empts the post-expiry 401 with
+		// `OAuthTokenExpired` and asks the user to re-login.
+		const saveToken = Effect.fn('DeviceAuthService.saveToken')(function* (tokenResponse: TokenResponse) {
+			const now = yield* DateTime.now
+			const expiresAt = DateTime.addDuration(now, tokenResponse.expires_in)
+
+			yield* configManager.updateConfig({
+				authMethod: OAuthConfig.make({
+					accessToken: Redacted.make(tokenResponse.access_token),
+					expiresAt,
+				}),
+			})
+		})
+
+		return { requestDeviceCode, pollForToken, saveToken } as const
+	}),
+}) {}

package/src/Hook/Claude.ts

@@ -0,0 +1,81 @@
+import { NodeStream } from '@effect/platform-node'
+import { Console, Effect, Schema, String } from 'effect'
+import { ApiClient } from '../ApiClient.js'
+import { MarkdownUnavailable } from '../Commands/Fetch.js'
+import { HookProtocolFailed, StdinReadError } from './Errors.js'
+import { withSnapshotNote } from './SnapshotNote.js'
+
+/**
+ * Runner for `expandai hook claude-code`. Reads a Claude Code PreToolUse
+ * payload from stdin, fetches the requested URL via expand.ai, and writes
+ * a `hookSpecificOutput` payload that substitutes the markdown for what
+ * WebFetch would have produced.
+ *
+ * Substitution mechanism: `permissionDecision: "deny"` blocks the WebFetch,
+ * and the page markdown is delivered via `additionalContext` (the documented
+ * channel for injecting page content). `permissionDecisionReason` carries
+ * a short label only — the agent SDK has no documented cap on it, but
+ * `additionalContext` is the semantically correct field for the body.
+ */
+
+const WEBFETCH_TOOL_NAME = 'WebFetch'
+
+class WebFetchToolInput extends Schema.Class<WebFetchToolInput>('WebFetchToolInput')({
+	url: Schema.String,
+	prompt: Schema.optional(Schema.String),
+}) {}
+
+class PreToolUseHookPayload extends Schema.Class<PreToolUseHookPayload>('PreToolUseHookPayload')({
+	hook_event_name: Schema.Literal('PreToolUse'),
+	tool_name: Schema.String,
+	tool_input: WebFetchToolInput,
+}) {}
+
+const decodeHookPayload = Schema.decode(Schema.parseJson(PreToolUseHookPayload))
+const encodeHookOutput = Schema.encode(Schema.parseJson(Schema.Unknown))
+
+const readStdin = NodeStream.toString(() => process.stdin, {
+	onFailure: (error) => new StdinReadError({ error }),
+	encoding: 'utf8',
+})
+
+export class ClaudeHook extends Effect.Service<ClaudeHook>()('@expandai/cli/Hook/Claude', {
+	dependencies: [ApiClient.Default],
+	effect: Effect.gen(function* () {
+		const apiClient = yield* ApiClient
+
+		const runProtocol = Effect.fn('ClaudeHook.runProtocol')(function* () {
+			const raw = yield* readStdin.pipe(Effect.mapError((error) => new HookProtocolFailed({ error })))
+			const payload = yield* decodeHookPayload(raw).pipe(Effect.mapError((error) => new HookProtocolFailed({ error })))
+
+			// Defensive — settings.json matcher already scopes us to WebFetch.
+			if (payload.tool_name !== WEBFETCH_TOOL_NAME) return
+
+			const url = payload.tool_input.url
+			yield* Effect.gen(function* () {
+				// Object mode (`/v1/fetch/json`) over markdown mode so the response carries
+				// `meta.snapshotId` — the handle the agent uses to search this same capture
+				// via `fetch_search` instead of fetching the URL again.
+				const result = yield* apiClient.fetchFetchResult({
+					params: {},
+					payload: { url, include: { markdown: true } },
+				})
+				if (String.isEmpty(result.markdown)) {
+					return yield* new MarkdownUnavailable({ url })
+				}
+
+				const output = {
+					hookSpecificOutput: {
+						hookEventName: 'PreToolUse',
+						permissionDecision: 'deny',
+						permissionDecisionReason: `Fetched via expand.ai — page markdown injected as additionalContext.`,
+						additionalContext: withSnapshotNote(result.markdown, result.meta.snapshotId, result.meta.playground),
+					},
+				}
+				yield* Console.log(yield* encodeHookOutput(output))
+			}).pipe(Effect.mapError((error) => new HookProtocolFailed({ error, url })))
+		})
+
+		return { runProtocol } as const
+	}),
+}) {}

package/src/Hook/Errors.ts

@@ -0,0 +1,19 @@
+import { Schema } from 'effect'
+
+export class StdinReadError extends Schema.TaggedError<StdinReadError>()('StdinReadError', {
+	error: Schema.Defect,
+}) {
+	get message() {
+		return 'Failed to read hook payload from stdin.'
+	}
+}
+
+export class HookProtocolFailed extends Schema.TaggedError<HookProtocolFailed>()('HookProtocolFailed', {
+	error: Schema.Defect,
+	url: Schema.optional(Schema.String),
+}) {
+	get message() {
+		const inner = this.error instanceof Error ? this.error.message : 'Hook protocol failed.'
+		return this.url ? `${inner} (url: ${this.url})` : inner
+	}
+}