@theokit/sdk 4.2.7 → 4.2.9

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.2.9
+
+### Patch Changes
+
+- d12634e: fix(a2a): register the `Agent` facade on a process-global `Symbol.for` slot so `SubAgent` works across build entries (#142). Each public entry (`.`, `./a2a`, `./cron`, `./eval`, …) is bundled with `tsup splitting: false`, which inlines its own copy of the internal `agent-factory-registry` — a module-level `let` gave each copy a private registration slot, so a subagent invoked through `@theokit/sdk/a2a` read a slot the `.` entry (via `agent.ts`'s `setAgentFacade`) never set, throwing `internal: Agent facade not registered` even when the main entry was loaded first. The registry now stores the facade on `globalThis[Symbol.for("theokit.internal.runtime.agentFacade")]`, so all duplicated copies share ONE registration. Adds regression tests. No public API change.
+
+## 4.2.8
+
+### Patch Changes
+
+- feat(init-claude): the scaffolded `.claude/` template now covers **every public `@theokit/sdk` subpath**. Added 16 per-module skills — models, subagents (`/a2a` + tool-scope), retry, task-store, sandbox, compaction, messages, auth (`/server/auth` + errors-envelope), sanitize, skills, path-safety, concurrency, persistence, client, filesystem, project — each authored against the shipped type declarations (verified signatures: `Retry.create` executor, `Semaphore.create`, `SubAgent.create`, `Auth.create`, `sanitizeToolInput`, …). The `claude-template-no-drift` gate covers the expanded set.
+
 ## 4.2.7
 
 ### Patch Changes

package/claude-template/CLAUDE.md

@@ -24,6 +24,22 @@ These skills inject TheoKit knowledge automatically when you edit files matching
 | `theokit-config` | `.theokit/**`, `config.*`, `theo.config.*` |
 | `theokit-streaming` | `*stream*`, `*Stream*`, `*SDKMessage*` |
 | `theokit-budget` | `*budget*`, `*Budget*`, `*cost*`, `*token*` |
+| `theokit-models` | `*model*`, `*Model*` |
+| `theokit-subagents` | `*subagent*`, `*a2a*`, `*delegat*` |
+| `theokit-retry` | `*retry*`, `*Retry*` |
+| `theokit-task-store` | `*task-store*`, `*taskstore*`, `*TaskStore*` |
+| `theokit-sandbox` | `*sandbox*`, `*Sandbox*` |
+| `theokit-compaction` | `*compact*`, `*Compact*` |
+| `theokit-messages` | `*message*`, `*Message*` |
+| `theokit-auth` | `*auth*`, `*Auth*`, `*envelope*` |
+| `theokit-sanitize` | `*sanitize*`, `*Sanitize*` |
+| `theokit-skills` | `*skill*`, `*Skill*` |
+| `theokit-path-safety` | `*path-safety*`, `*pathsafety*` |
+| `theokit-concurrency` | `*concurren*`, `*semaphore*`, `*Semaphore*` |
+| `theokit-persistence` | `*persist*`, `*Persist*` |
+| `theokit-client` | `*client*`, `*Client*` |
+| `theokit-filesystem` | `*filesystem*`, `*Filesystem*` |
+| `theokit-project` | `*project*`, `*Project*` |
 
 ### Settings
 

package/claude-template/dot-claude/skills/theokit-auth/SKILL.md

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*auth*"
+  - "**/*Auth*"
+  - "**/*envelope*"
+description: TheoKit SDK server auth — Auth.create orchestrator, validateReturnTo, and the cross-layer error envelope
+---
+
+# TheoKit Server Auth
+
+Server-side auth orchestrator and the cross-layer error envelope. These live
+under the `@theokit/sdk/server/*` sub-paths (not the main barrel). Concrete
+OAuth/email providers ship in opt-in `@theokit/auth-*` packages — the SDK only
+defines the orchestrator contract.
+
+## `Auth.create` — session + provider orchestrator
+
+```typescript
+import {
+  Auth,
+  validateReturnTo,
+  AuthConfigError,
+  AuthProviderNotFoundError,
+  AuthCallbackError,
+  AuthCancelledError,
+  AuthSecretTooShortError,
+} from "@theokit/sdk/server/auth";
+import type {
+  AuthProvider,
+  SessionManager,
+  AuthOrchestrator,
+} from "@theokit/sdk/server/auth";
+```
+
+`Auth.create(opts)` returns an `AuthOrchestrator<TSession>` with 5 methods.
+`providers` is optional — an empty list is the manual-`signIn`-only escape hatch.
+
+```typescript
+const auth: AuthOrchestrator<Session> = Auth.create<Session>({
+  session,                 // your SessionManager<Session> implementation
+  providers: [githubProvider], // AuthProvider<Profile>[] from a @theokit/auth-* package
+  onSignIn: async ({ profile, provider }) => {
+    return toSession(profile, provider); // returns the TSession to persist
+  },
+  onSignOut: async (session) => {
+    /* revoke, audit, etc. */
+  },
+});
+
+// OAuth flow (node:http req/res):
+const redirect = await auth.startSignIn("github", req, { returnTo: "/dashboard" });
+const { session, returnTo } = await auth.finishSignIn("github", req, res); // rotates session id (OWASP A07)
+const current = await auth.getSession(req);
+await auth.signOut(res);
+
+// Escape hatch — persist a session directly, skipping the OAuth flow:
+const s = await auth.signIn(externalProfile, "github", req, res);
+```
+
+## `validateReturnTo` — open-redirect guard (OWASP A01)
+
+Returns a safe same-origin path. Cross-origin, protocol-relative (`//evil.com`),
+empty, and defensive cases all collapse to `"/"`.
+
+```typescript
+const safe = validateReturnTo(returnTo, new URL("https://app.example.com"));
+// "/dashboard" -> kept; "https://evil.com" -> "/"; undefined -> "/"
+```
+
+Typed errors: `AuthConfigError`, `AuthProviderNotFoundError`, `AuthCallbackError`,
+`AuthCancelledError`, `AuthSecretTooShortError`.
+
+## Error envelope — cross-layer boundary translation
+
+```typescript
+import {
+  toEnvelope,
+  fromEnvelope,
+  MemoryAdapterError,
+} from "@theokit/sdk/server/errors-envelope";
+import type {
+  TheokitErrorEnvelope,
+  TheokitErrorCode,
+} from "@theokit/sdk/server/errors-envelope";
+```
+
+`toEnvelope` translates any SDK error (or arbitrary thrown value) into the wire
+envelope at egress; `fromEnvelope` reconstructs SDK class identity at ingress so
+`instanceof` checks keep working across an IPC/serialization boundary.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  const envelope: TheokitErrorEnvelope = toEnvelope(err); // { code, message, meta?, ext? }
+  send(envelope); // code is a TheokitErrorCode, e.g. "RATE_LIMITED"
+}
+
+// Inbound edge (e.g. worker receiving the envelope):
+const restored = fromEnvelope(envelope); // a TheokitAgentError subclass
+```

package/claude-template/dot-claude/skills/theokit-client/SKILL.md

@@ -0,0 +1,58 @@
+---
+user-invocable: false
+paths:
+  - "**/*client*"
+  - "**/*Client*"
+description: TheoKit SDK low-level HTTP client — TheoKitClient (DEPRECATED; prefer the Agent façade)
+---
+
+# TheoKit Client
+
+`TheoKitClient` is a browser-safe, zero-Node-dependency HTTP client (native
+`fetch` + manual SSE parsing) for a legacy server-adapter contract.
+
+> DEPRECATED since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
+> server-adapter HTTP contract (`POST /agent/send`, `GET /agent/stream`) that the
+> ecosystem no longer produces, and will be removed in the next major. For
+> in-process runs use the `Agent` façade (`@theokit/sdk`); for HTTP, use the
+> framework's typed `POST /api/agents/<name>` client. Reach for this only when
+> maintaining an existing integration against the old contract.
+
+```ts
+import { TheoKitClient } from "@theokit/sdk/client";
+import type { ClientOptions, SendResponse, StreamEvent } from "@theokit/sdk/client";
+```
+
+## Construct
+
+The constructor takes `ClientOptions` — `baseUrl` (required), optional `basePath`
+and `headers`.
+
+```ts
+const client = new TheoKitClient({
+  baseUrl: "https://adapter.example.com",
+  basePath: "/agent",                      // optional
+  headers: { authorization: "Bearer …" },  // optional
+});
+```
+
+## Send (one-shot)
+
+`send(input)` POSTs and resolves a `SendResponse` (`{ status, output?, error? }`).
+
+```ts
+const res: SendResponse = await client.send("summarize the repo");
+if (res.error) throw new Error(res.error);
+console.log(res.status, res.output);
+```
+
+## Stream (SSE)
+
+`stream(input)` returns an `AsyncGenerator<StreamEvent>`; each `StreamEvent` has a
+`type` and an optional `text` (plus arbitrary extra fields).
+
+```ts
+for await (const event of client.stream("build the changelog")) {
+  if (event.type === "text" && event.text) process.stdout.write(event.text);
+}
+```

package/claude-template/dot-claude/skills/theokit-compaction/SKILL.md

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*compact*"
+  - "**/*Compact*"
+description: TheoKit SDK compaction reference — compactTranscript, shouldCompact, checkpoints, context-overflow
+---
+
+# TheoKit Compaction
+
+Public context-management helpers. Every function is pure and never mutates its
+input. A `CompressibleMessage` is `{ role: "user" | "assistant" | "system"; content: string }`.
+
+```typescript
+import {
+  compactTranscript,
+  shouldCompact,
+  estimateTokens,
+  buildCheckpoint,
+  filterFromLatestCheckpoint,
+  isContextOverflowError,
+  CHECKPOINT_MARKER,
+  SUMMARY_TEMPLATE,
+  type CompactTranscriptOptions,
+  type ShouldCompactInput,
+  type CompressibleMessage,
+} from "@theokit/sdk/compaction";
+```
+
+## Pre-call gate — `estimateTokens` + `shouldCompact`
+
+`estimateTokens` is a tokenizer-free `ceil(text.length / 4)` heuristic — a cheap
+gate, NOT exact tokenization. `shouldCompact` is pure: the caller supplies the
+model's window.
+
+```typescript
+const estimated = estimateTokens(transcript.map((m) => m.content).join("\n"));
+
+const input: ShouldCompactInput = {
+  estimated,
+  contextWindow: 200_000,
+  buffer: 8_000,     // headroom to reserve (output + safety margin)
+  maxOutput: 4_000,  // optional; separate response reservation (default 0)
+};
+
+if (shouldCompact(input)) {
+  // compact before sending — see below
+}
+```
+
+## `compactTranscript` — summarize the older window
+
+Default `keepRecent` mode keeps the last N turns verbatim (default 6) and
+preserves leading system prompts. The older window is summarized via the
+caller-supplied `summarize` callback (or dropped if omitted). With `failSafe`, a
+thrown summarizer returns the ORIGINAL transcript instead of propagating.
+
+```typescript
+const opts: CompactTranscriptOptions = {
+  keepRecent: 6,        // OR keepTokens: 40_000 (token-budget mode, takes precedence)
+  failSafe: true,
+  summarize: async (older: CompressibleMessage[], template: string) => {
+    // template is SUMMARY_TEMPLATE unless overridden via summaryTemplate
+    const summary = await callYourModel(template, older);
+    return { role: "system", content: summary };
+  },
+};
+
+const compacted = await compactTranscript(transcript, opts);
+```
+
+## Checkpoints — mark and filter
+
+`buildCheckpoint` produces a `system` turn whose content starts with
+`CHECKPOINT_MARKER`. `filterFromLatestCheckpoint` returns turns relative to the
+most recent marker (`include: "after"` excludes it — the default; `"from"`
+includes it).
+
+```typescript
+const marked = [...transcript, buildCheckpoint("milestone: tests green")];
+
+const recent = filterFromLatestCheckpoint(marked);              // after (exclusive)
+const withHead = filterFromLatestCheckpoint(marked, { include: "from" });
+```
+
+## Context-overflow detection
+
+`isContextOverflowError` is `true` only for a `TheokitAgentError` reporting the
+typed `context_too_long` code — never a brittle message regex.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  if (isContextOverflowError(err)) {
+    const compacted = await compactTranscript(transcript, { keepRecent: 4 });
+    // retry with the compacted transcript
+  } else {
+    throw err;
+  }
+}
+```

package/claude-template/dot-claude/skills/theokit-concurrency/SKILL.md

@@ -0,0 +1,68 @@
+---
+user-invocable: false
+description: Bound in-process parallelism with Semaphore.create and mapWithConcurrency from @theokit/sdk/concurrency.
+paths:
+  - "**/*concurren*"
+  - "**/*semaphore*"
+  - "**/*Semaphore*"
+---
+
+# TheoKit SDK -- Concurrency
+
+In-house concurrency helpers (no `p-limit`/`p-map` dependency). `Semaphore.create(permits)` builds an N-permit async counting gate; `mapWithConcurrency` runs an async mapper over items with bounded parallelism while preserving input order.
+
+## Import
+
+```typescript
+import { Semaphore, mapWithConcurrency } from "@theokit/sdk/concurrency";
+import type { AsyncSemaphore } from "@theokit/sdk/concurrency";
+```
+
+## Signatures
+
+```typescript
+class Semaphore {
+  static create(permits: number): AsyncSemaphore; // canonical factory (ADR 0015)
+}
+
+interface AsyncSemaphore {
+  acquire(): Promise<() => void>; // returns a release fn; call it exactly once
+  inFlight(): number;             // permits currently held
+  pending(): number;              // in-flight + queued waiters
+}
+
+function mapWithConcurrency<T, R>(
+  items: ReadonlyArray<T>,
+  concurrency: number,                                     // positive integer; validated
+  fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,
+  options?: { signal?: AbortSignal },
+): Promise<R[]>; // ordered; fail-fast; throws ConfigurationError on bad concurrency
+```
+
+## Semaphore -- release in a finally
+
+```typescript
+const sem = Semaphore.create(4); // at most 4 in flight
+
+async function guarded<T>(task: () => Promise<T>): Promise<T> {
+  const release = await sem.acquire();
+  try {
+    return await task();
+  } finally {
+    release(); // release exactly once (idempotent, but leaking it consumes a permit)
+  }
+}
+```
+
+## mapWithConcurrency -- ordered bounded map
+
+```typescript
+const controller = new AbortController();
+const results = await mapWithConcurrency(
+  ["a", "b", "c"],
+  2, // max 2 concurrent fetches
+  async (url, _index, signal) => (await fetch(url, { signal })).json(),
+  { signal: controller.signal },
+);
+// results align with input order; rejects on the first task error
+```

package/claude-template/dot-claude/skills/theokit-filesystem/SKILL.md

@@ -0,0 +1,74 @@
+---
+user-invocable: false
+paths:
+  - "**/*filesystem*"
+  - "**/*Filesystem*"
+description: TheoKit SDK filesystem seam — FilesystemBackend, LocalFilesystem, boundary-enforced storage with read-before-write safety
+---
+
+# TheoKit Filesystem
+
+A pluggable, boundary-enforced file *storage* provider for agent file tools —
+the storage-side twin of the sandbox seam. Ship a `FilesystemBackend` (default
+`LocalFilesystem`) with an optional `readOnly` flag and a per-request resolver.
+
+```ts
+import {
+  LocalFilesystem, FilesystemBackend, resolveFilesystem,
+} from "@theokit/sdk/filesystem";
+import type {
+  FilesystemProvider, FilesystemConfig, FileStat, WriteFileOptions,
+} from "@theokit/sdk/filesystem";
+import {
+  FileNotFoundError, FilesystemError,
+  FilesystemReadOnlyError, FilesystemSecurityError, StaleFileError,
+} from "@theokit/sdk/filesystem";
+```
+
+## LocalFilesystem
+
+Boundary-enforced over `node:fs/promises`. Every path resolves within `basePath`;
+traversal / symlink escapes are rejected with `FilesystemSecurityError`. NOT an
+isolation boundary — run untrusted code inside a container/VM.
+
+```ts
+const fs = new LocalFilesystem({ basePath: "/workspace", readOnly: false });
+
+const stat: FileStat = await fs.writeFile("notes.md", "# hello"); // returns FileStat
+const text = await fs.readFile("notes.md");
+const names = await fs.list(".");            // entry names, not recursive
+if (await fs.exists("notes.md")) { /* … */ }
+```
+
+## Read-before-write safety (SE32)
+
+`stat().mtimeMs` is the oracle. Pass `expectedMtime` so a concurrent change makes
+the write fail with `StaleFileError` instead of silently clobbering.
+
+```ts
+const before = await fs.stat("notes.md");
+try {
+  await fs.writeFile("notes.md", updated, { expectedMtime: before.mtimeMs });
+} catch (err) {
+  if (err instanceof StaleFileError) { /* someone changed it — re-read + merge */ }
+}
+```
+
+## Per-request provider (multi-tenant)
+
+A `FilesystemProvider` is a backend OR a resolver `(ctx) => backend` run at
+tool-execution time, giving each request its own root. `resolveFilesystem`
+collapses either form to a concrete backend.
+
+```ts
+const provider: FilesystemProvider<{ tenant: string }> = (ctx) =>
+  new LocalFilesystem({ basePath: `/data/${ctx.tenant}` });
+
+const backend = await resolveFilesystem(provider, { tenant: "acme" });
+```
+
+## Custom backend
+
+Extend `FilesystemBackend` and implement `readFile` / `writeFile` / `stat` /
+`list`; `exists()`, `readOnly`, and `basePath` derive on the base class. Map raw
+Node errors to the typed errors above (`FileNotFoundError`, `FilesystemError`).

package/claude-template/dot-claude/skills/theokit-messages/SKILL.md

@@ -0,0 +1,58 @@
+---
+user-invocable: false
+paths:
+  - "**/*message*"
+  - "**/*Message*"
+description: TheoKit SDK message readers — assistantText, extractToolUses, costAmountUsd over the SDKMessage stream
+---
+
+# TheoKit Messages
+
+Pure readers over the `SDKMessage` stream — no I/O, no mutation, deterministic.
+Use these instead of re-implementing a wire-event mapper.
+
+```typescript
+import { assistantText, extractToolUses, costAmountUsd } from "@theokit/sdk/messages";
+import type { SDKMessage, ToolUseBlock } from "@theokit/sdk";
+import type { CostBreakdown } from "@theokit/sdk";
+```
+
+## `assistantText(msg)` — concatenate assistant text blocks
+
+Returns `""` for any non-assistant message (or an assistant with no text
+blocks). `tool_use` blocks are ignored — only `text` blocks contribute.
+
+```typescript
+for await (const event of run.stream()) {
+  // event is an SDKMessage; assistantText is safe on any variant
+  const text = assistantText(event);
+  if (text) process.stdout.write(text);
+}
+```
+
+## `extractToolUses(msg)` — read assistant `ToolUseBlock`s
+
+Returns `[]` for any non-assistant message. This reads the assistant message's
+content blocks — NOT the separate `tool_call` lifecycle event (a different
+stream). Tool `input` is `unknown`; parse it defensively.
+
+```typescript
+const uses: ToolUseBlock[] = extractToolUses(event);
+for (const use of uses) {
+  console.log(use.name, use.id); // use.input is `unknown` — validate before use
+}
+```
+
+## `costAmountUsd(cost)` — honesty-preserving cost read
+
+Returns `number | undefined`. `undefined` means "cost unknown" — distinct from a
+real `$0` (e.g. a subscription-included route). NEVER coerced to 0.
+
+```typescript
+const amount = costAmountUsd(cost); // cost: CostBreakdown | undefined
+if (amount === undefined) {
+  console.log("cost unknown");
+} else {
+  console.log(`$${amount.toFixed(4)}`);
+}
+```

package/claude-template/dot-claude/skills/theokit-models/SKILL.md

@@ -0,0 +1,79 @@
+---
+user-invocable: false
+paths:
+  - "**/*model*"
+  - "**/*Model*"
+description: TheoKit SDK model helpers — @theokit/sdk/models (parseModelId, resolveModelCapabilities, toModelOption, humanizeModelName); API catalog via Theokit.models.list()
+---
+
+# TheoKit Models
+
+Pure, sync, offline helpers for model ids. No network — these read a static catalog
+and parse strings. For the live API-backed catalog, use `Theokit.models.list()` from
+the main `@theokit/sdk` barrel.
+
+```typescript
+import {
+  parseModelId,
+  resolveModelCapabilities,
+  toModelOption,
+  humanizeModelName,
+  type ModelCapabilities,
+  type ModelOption,
+  type ParsedModelId,
+} from "@theokit/sdk/models";
+```
+
+## Parse a model id
+
+`parseModelId` splits on the first `/` into `{ provider, name }`. No `/` means
+`provider` is `undefined` (so callers can fall back to env-var detection). Tag
+suffixes like `:3b` / `:latest` stay part of `name`.
+
+```typescript
+const a: ParsedModelId = parseModelId("anthropic/claude-3-5-sonnet");
+// { provider: "anthropic", name: "claude-3-5-sonnet" }
+
+const b = parseModelId("openrouter/meta-llama/llama-3");
+// { provider: "openrouter", name: "meta-llama/llama-3" }  (embedded slash kept)
+
+const c = parseModelId("claude-sonnet-4-6");
+// { provider: undefined, name: "claude-sonnet-4-6" }
+```
+
+## Gate features by capability
+
+`resolveModelCapabilities` returns typed flags + token limits from an OFFLINE
+catalog. It strips routing prefixes (`openrouter/`/`vertex/`/`bedrock/`) and the
+OpenRouter `:variant` suffix before lookup; unknown models get conservative defaults.
+
+```typescript
+const caps: ModelCapabilities = resolveModelCapabilities("anthropic/claude-3-5-sonnet");
+// { supportsVision, supportsStructuredOutput, supportsToolUse,
+//   supportsCacheControl, maxContextTokens, maxOutputTokens }
+
+if (!caps.supportsVision) {
+  throw new Error("This model cannot accept images");
+}
+```
+
+## Build dropdown options
+
+`humanizeModelName` produces a best-effort label; `toModelOption` composes it with
+`parseModelId` into `{ value, label, provider }`.
+
+```typescript
+humanizeModelName("anthropic/claude-3-5-sonnet"); // "Claude 3 5 Sonnet"
+
+const opt: ModelOption = toModelOption("openrouter/meta-llama/llama-3");
+// { value: "openrouter/meta-llama/llama-3", label: "...", provider: "openrouter" }
+```
+
+## Live catalog (API-backed)
+
+```typescript
+import { Theokit } from "@theokit/sdk";
+
+const models = await Theokit.models.list({ apiKey: process.env.THEOKIT_API_KEY });
+const options: ModelOption[] = models.map((m) => toModelOption(m.id));
+```

package/claude-template/dot-claude/skills/theokit-path-safety/SKILL.md

@@ -0,0 +1,60 @@
+---
+user-invocable: false
+description: Path-traversal, symlink-escape, and forbidden-path guards from @theokit/sdk/path-safety for agent file I/O.
+paths:
+  - "**/*path-safety*"
+  - "**/*pathsafety*"
+---
+
+# TheoKit SDK -- Path Safety
+
+TOCTOU-safe path primitives to wire wherever user input becomes a filesystem path in a custom tool. `safePathJoin` resolves then prefix-checks; `assertNoSymlinkEscape` resolves the whole symlink chain via `realpathSync`; `isForbiddenPath` blocks sensitive files even when they are lexically inside the project.
+
+## Import
+
+```typescript
+import {
+  safePathJoin,
+  assertNoSymlinkEscape,
+  isForbiddenPath,
+  safeFilenameForId,
+  sanitizeIdentifier,
+  PathTraversalError,
+  ForbiddenPathError,
+} from "@theokit/sdk/path-safety";
+```
+
+## Signatures
+
+```typescript
+function safePathJoin(base: string, ...parts: string[]): string;   // throws PathTraversalError on escape
+function assertNoSymlinkEscape(path: string, base: string): void;  // throws PathTraversalError on symlink escape
+function isForbiddenPath(input: string): boolean;                  // true for .env*, .git/, node_modules/, .theo/, lock files
+function safeFilenameForId(id: string, options?: { maxLen?: number }): string; // total: passthrough or h-<16hex>
+function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string; // grammar ^[a-z0-9][a-z0-9-_]*$
+
+class PathTraversalError extends ConfigurationError { constructor(input: string, resolvedPath: string); } // code "path_traversal"
+class ForbiddenPathError extends ConfigurationError { constructor(path: string); }                         // code "forbidden_path"
+```
+
+## Guard a tool's file read
+
+```typescript
+const projectRoot = process.cwd();
+
+function resolveUserPath(userPath: string): string {
+  if (isForbiddenPath(userPath)) throw new ForbiddenPathError(userPath);
+  const safe = safePathJoin(projectRoot, userPath); // throws PathTraversalError on "../" escape
+  assertNoSymlinkEscape(safe, projectRoot);          // throws PathTraversalError on symlink escape
+  return safe;
+}
+```
+
+## Derive a safe filename from an opaque id
+
+`safeFilenameForId` never throws on a non-empty string: it returns the id verbatim when it already matches the safe grammar, otherwise a deterministic `h-<16 hex>` sha256 token.
+
+```typescript
+safeFilenameForId("550e8400-e29b-41d4-a716-446655440000"); // passthrough
+safeFilenameForId("user@example.com");                       // "h-<16hex>"
+```