libar-dev · darko-mijic · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,17 +9,63 @@ Categories per release: **Added**, **Changed**, **Deprecated**, **Removed**, **F
 
 ---
 
-## [0.1.0] - 2026-06-24
+## [Unreleased]
+
+### Fixed
+
+- Canonicalized existing hook-event working directories before project-root
+  filtering so symlinked paths still reach an open project's endpoint.
+- Exercised the actual esbuild-bundled forwarder in subprocess tests, including
+  its exit-zero, empty-output behavior for malformed stdin.
+
+## [0.2.0] - 2026-07-12
 
-First public release of `@libar-dev/agent-harness-kit`.
+### Added
+
+- Added a validated endpoint-discovery file contract and helpers for process
+  liveness, project-root filtering, and hook URL construction.
+- Added a standalone, esbuild-bundled command-hook forwarder that silently
+  opts out when its endpoint is absent, stale, unrelated, or unreachable.
+- Added the managed POSIX wrapper asset for consumers that install the
+  forwarder at a stable user path.
+
+- Added the per-call `allowedMarkerRoots` tail option (`TailOptions`) so
+  library consumers can validate a custom `markerDir` without mutating the
+  process-global `CLAUDE_TAIL_MARKER_ROOTS` env var. When set (even empty) it
+  takes precedence over the env var; when unset the env var remains the
+  fallback, so the `claude-session-tail` CLI behavior is unchanged.
+- Exported `getMarkerPath`, `readMarker`, and `writeMarker` from
+  `@libar-dev/agent-harness-kit/processing` so consumers that pre-seed or
+  inspect tail markers share the kit's marker file format instead of
+  re-implementing it.
+
+### Changed
 
-This is the first release under the new `agent-harness-kit` identity.
+- ExitPlanMode summaries use the plan's first Markdown heading so collapsed
+  transcript rows remain meaningful.
+
+- Published Claude Code API parity notes now cover `Setup` and `MessageDisplay`.
+- Documented `SessionStart` input/output parity updates.
+- Documented `Notification` and `StopFailure` enum expansions.
+- Documented support for `CommandHookHandler.args`, `PostToolUseOutput.updatedToolOutput`, `PostToolUseInput.duration_ms`, `PostToolUseFailureInput.duration_ms`, `BaseHookInput.effort`, and `BaseHookOutput.terminalSequence`.
+- Documented `PostToolUseOutput.updatedMCPToolOutput` widening to `unknown`.
+
+## [0.1.0] - 2026-06-24
+
+This is the first release candidate under the new `agent-harness-kit` identity.
 The package was renamed from `@libar-dev/claude-code-hooks` to
 `@libar-dev/agent-harness-kit`.
 
+### Added
+
+- Added support for image content blocks in transcript processing.
+
 ### Changed
 
 - Package name changed from `@libar-dev/claude-code-hooks` to `@libar-dev/agent-harness-kit`.
+- Normalized npm bin paths in package metadata.
+- Updated the repository URL to the public GitHub location.
+- Added `publishConfig.access: public` for npm publishing.
 
 ---
 
@@ -31,7 +77,7 @@ The package was renamed from `@libar-dev/claude-code-hooks` to
 > pre-publication development milestone under the old `@libar-dev/claude-code-hooks`
 > package name.
 
-Pre-publication development milestone for `@libar-dev/claude-code-hooks` before the first public npm release.
+Development milestone for `@libar-dev/claude-code-hooks` before the first public npm release.
 
 ### Added
 
@@ -89,4 +135,3 @@ Pre-publication development milestone for `@libar-dev/claude-code-hooks` before
   `--unsafe-raw-unredacted` opt-in; without it, raw records are redacted.
 
 [0.1.0]: https://github.com/libar-dev/agent-harness-kit/releases/tag/v0.1.0
-[1.0.0]: https://github.com/libar-dev/claude-code-hooks/releases/tag/v1.0.0
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,10 +1,10 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code (claude.ai/code) when working in this repository.
 
 ## What This Is
 
-A standalone TypeScript hooks library (`@libar-dev/agent-harness-kit`) for Claude Code. Hooks are command, HTTP, MCP tool, prompt, or agent handlers that execute at lifecycle points to provide deterministic control over Claude's behavior. The library covers all 28 hook events in the current official docs.
+A standalone TypeScript hooks library (`@libar-dev/agent-harness-kit`) for Claude Code. Hooks are command, HTTP, MCP tool, prompt, or agent handlers that run at lifecycle points. The library covers all 30 hook events in the current official docs.
 
 Official docs (mirrored upstream): `docs/upstream/hooks-guide.md`, `docs/upstream/hooks-reference.md`
 
@@ -30,7 +30,7 @@ pnpm run hook:test:session      # Session start
 
 ## Absolute Rule: No `any` Types
 
-`any` is forbidden everywhere. Use `unknown` with validation/type assertions instead. `noImplicitAny: true` is set in all tsconfig files. Do not weaken this.
+`any` is forbidden. Use `unknown` with validation/type assertions instead. `noImplicitAny: true` is set in all tsconfig files. Do not weaken this.
 
 ```typescript
 // WRONG
@@ -44,10 +44,10 @@ const bashInput = validateBashToolInput(input); // Returns typed BashToolInput
 
 **Hook I/O protocol**: JSON in via stdin, JSON out via stdout. Exit codes: 0 (success), 1 (non-blocking error), 2 (blocking error). `WorktreeCreate` treats any non-zero exit as a creation failure.
 
-**28 hook events**: SessionStart, UserPromptSubmit, UserPromptExpansion, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, SessionEnd.
+**30 hook events**: Setup, SessionStart, UserPromptSubmit, UserPromptExpansion, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, MessageDisplay, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, SessionEnd.
 
 **Key modules**:
-- `src/types/index.ts` — All type definitions: hook I/O interfaces, tool input types, hook config types (`HookHandler`, `MatcherGroup`, `HooksConfig`), and `HookEnvironmentVars`
+- `src/types/index.ts` — Type definitions: hook I/O interfaces, tool input types, hook config types (`HookHandler`, `MatcherGroup`, `HooksConfig`), and `HookEnvironmentVars`
 - `src/utils/index.ts` — Core I/O (`readStdinJson`, `outputJson`, `executeHook`), logging, config (`getConfig()` reads `CLAUDE_*` env vars)
 - `src/utils/output-builder.ts` — `HookOutputBuilder` with methods for all output patterns
 - `src/validation/` — Zod schemas (`schemas.ts`), validators (`validators.ts`), and re-exports (`index.ts`). Schema-first: define Zod schema -> infer types with `z.infer` -> validate at boundaries
@@ -79,7 +79,7 @@ const bashInput = validateBashToolInput(input); // Returns typed BashToolInput
 
 ## Hook Handler Types
 
-Settings validation supports all current official handler types:
+Settings validation supports these handler types:
 
 ```json
 {
@@ -181,7 +181,7 @@ import { validateHooksConfig } from '../validation/index.js';
 const config = validateHooksConfig(parsed); // validates full settings hooks structure
 ```
 
-Config supports handler common fields `if`, `timeout`, `statusMessage`, and `once`. Command handlers additionally support `async`, `asyncRewake`, and `shell`. Settings-root restriction fields include `allowManagedHooksOnly`, `allowedHttpHookUrls`, and `httpHookAllowedEnvVars`.
+Config supports common handler fields `if`, `timeout`, `statusMessage`, and `once`. Command handlers also support `async`, `asyncRewake`, and `shell`. Settings-root restriction fields include `allowManagedHooksOnly`, `allowedHttpHookUrls`, and `httpHookAllowedEnvVars`.
 
 ## Build System
 
@@ -193,14 +193,14 @@ Config supports handler common fields `if`, `timeout`, `statusMessage`, and `onc
 
 ## Testing
 
-- Tests live in `tests/` and run directly against `.ts` source files via Vitest.
+- Tests live in `tests/` and run against `.ts` source files via Vitest.
 - Use test helpers from `tests/test-utils.ts` (`createPreToolUseInput`, `expectValidationError`, etc.).
 - All test inputs should go through Zod validation.
 - `tests/docs-round-trip.test.ts` validates parseable JSON hook examples from the mirrored official docs. It explicitly skips known pseudocode/commented JSON blocks and the generic official PreToolUse snippet that omits required `tool_use_id`.
 
 ## Config
 
-All hook behavior is configurable through environment variables. The library reads:
+Hook behavior is configurable through environment variables. The library reads:
 
 - Core/runtime: `CLAUDE_PROJECT_DIR`, `CLAUDE_ENV_FILE`, `CLAUDE_CODE_DEBUG_LOG_LEVEL`, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`, `CLAUDE_CODE_SYNC_PLUGIN_INSTALL`, `CLAUDE_HOOK_DEBUG`, `CLAUDE_HOOK_TIMEOUT`
 - Protection and command policy: `CLAUDE_HOOK_PROTECTED_FILES`, `CLAUDE_HOOK_DANGEROUS_COMMANDS`, `CLAUDE_HOOK_STRICT_PROTECTION`, `CLAUDE_HOOK_EXTRA_PROTECTED`, `CLAUDE_HOOK_READ_ONLY`, `CLAUDE_HOOK_AUTO_APPROVE_READS`
@@ -213,10 +213,23 @@ All hook behavior is configurable through environment variables. The library rea
 Processing CLIs have a small separate env surface that is not loaded through
 `getConfig()`. Today that includes `CLAUDE_TAIL_MARKER_ROOTS` for
 `claude-session-tail --marker-dir`. Keep hook env-var docs and processing CLI
-docs separate.
+docs separate. Library consumers of the tail APIs should pass the per-call
+`allowedMarkerRoots` option instead of relying on that env var.
 
 Set `CLAUDE_HOOK_DEBUG=true` or `CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose` for verbose logging. The default hook timeout is 60 seconds. `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` defaults to 1500 ms and is capped at 60000 ms.
 
+## Public Repository Hygiene
+
+Planning and context files created for agent workflows are ephemeral and must not be committed to the public repo. Examples include `prometheus-implementation-context.md` and `.omo/notepads/*` scratch files. Delete them before merging. Persistent guidance belongs in user-facing docs or ADRs, not in agent-context scratchpads.
+
+## Comment Style
+
+- Preserve API-contract JSDoc on every exported type, interface, function, class, and method. Keep parameter, return, thrown-error, and behavior notes that public consumers rely on.
+- Strip temporal, AI-workflow, migration, provenance, and marketing phrasing from comments. Avoid examples such as `Following ... pattern`, `incremental`, `Phase`, `recently`, `parent project`, `ported from`, `moved to`, `will`, `currently`, `now`, `new`, `modern`, `legacy`, `comprehensive`, and `designed for`.
+- Treat filler wording as noise. Avoid `automatically` when it adds no technical detail, and avoid `supports` when the code, type, or API name already makes that clear.
+- Keep comments that explain regression rationale, compatibility constraints, security-sensitive behavior, invariants, or non-obvious edge cases.
+- Avoid heavy visual banners such as `// =====`, `// ----`, or long dashed separator lines. Prefer a single blank line between logical blocks.
+
 ## Compatibility Notes
 
 `PermissionRequest` now uses nested `hookSpecificOutput.decision` with `behavior: "allow" | "deny"` and optional permission updates. The old top-level allow/deny style should not be used for new code.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing
 
-Thank you for your interest in contributing to `@libar-dev/agent-harness-kit`.
+Thanks for contributing to `@libar-dev/agent-harness-kit`.
 
 ## Getting Started
 
@@ -21,7 +21,7 @@ pnpm run build          # Compile src/ → dist/ (only needed before publishing)
 
 ## Code Rules
 
-**No `any` types — ever.** This is an absolute rule enforced by `noImplicitAny: true`. Use `unknown` with a validator instead:
+**No `any` types.** This is enforced by `noImplicitAny: true`. Use `unknown` with a validator instead:
 
 ```typescript
 // Wrong
@@ -52,7 +52,7 @@ if (import.meta.url === `file://${process.argv[1]}`) {
 
 ## Commit Style
 
-Follow the existing convention:
+Use the existing convention:
 
 ```
 fix: short description of the bug fixed
@@ -66,7 +66,7 @@ Keep the subject line under 72 characters. Reference issues in the body if appli
 
 ## Pull Request Checklist
 
-Before opening a PR, confirm:
+Before opening a PR:
 
 - [ ] `pnpm run check` passes with no errors or warnings
 - [ ] `pnpm run test:run` passes
@@ -76,4 +76,4 @@ Before opening a PR, confirm:
 
 ## Architecture Notes
 
-The high-level structure and the reasoning behind it lives in [docs/architecture/overview.md](docs/architecture/overview.md). The maintainer API-update checklist for tracking Claude Code API changes is in [docs/internal/api-update-checklist.md](docs/internal/api-update-checklist.md).
+The high-level structure and the reasoning behind it lives in [docs/README.md](docs/README.md). The maintainer API-update checklist for tracking Claude Code API changes is in [docs/internal/api-update-checklist.md](docs/internal/api-update-checklist.md).
diff --git a/README.md b/README.md
@@ -2,22 +2,22 @@
 
 > **Today: a Claude Code toolkit. Future: harness-agnostic.**
 >
-> This library currently targets [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) — all 28 events, strict types, Zod-validated inputs, and a fluent output builder. The long-term goal is to generalize the harness layer so the same validators, builders, and session tooling work across multiple agent platforms. Claude-specific names in the API (event names, CLI binaries) will remain stable; the package itself is being repositioned to reflect that broader ambition.
+> This library currently targets [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). The long-term goal is to generalize the harness layer so the same validators, builders, and session tooling work across multiple agent platforms. Claude-specific API names (event names, CLI binaries) will remain stable.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/libar-dev/agent-harness-kit/releases)
 [![Node ≥22](https://img.shields.io/badge/node-%3E%3D22-green)](package.json)
 
-TypeScript library for [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) with strict types, Zod-validated inputs, and a fluent output builder for all 28 hook events.
+TypeScript library for [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) with strict types, Zod-validated inputs, and a fluent output builder for all 30 hook events.
 
 **Why use this instead of raw shell scripts?**  
-Writing hook output JSON by hand is error-prone — field names, nesting, and event-specific shapes vary across 28 event types. This library validates your inputs at the boundary and produces the right output shapes via `HookOutputBuilder`, so you write logic, not plumbing.
+Writing hook output JSON by hand is error-prone: field names, nesting, and event-specific shapes vary across 30 event types. This library validates inputs at the boundary and produces the right output shapes via `HookOutputBuilder`, so you write logic, not plumbing.
 
 It also ships session-processing CLIs: export sessions to clean markdown/JSONL, and tail a live session JSONL as structured blocks for downstream ingestion. Retained tool-result bodies are secret-redacted by default (API keys, tokens, passwords, URL credentials).
 
 ## Install
 
-Runtime support targets Node.js 22 and newer. The library is developed, type-checked, and CI-tested on a Node 24 baseline so maintainers and contributors see the current typings/tooling surface without overstating the consumer runtime floor.
+Runtime support targets Node.js 22 and newer. Development, type-checking, and CI use a Node 24 baseline without raising the consumer runtime floor.
 
 ```bash
 pnpm add @libar-dev/agent-harness-kit
@@ -74,23 +74,25 @@ echo '{"hook_event_name":"PreToolUse","session_id":"s1","transcript_path":"/tmp/
 
 | Module | Contents |
 |--------|----------|
-| `@libar-dev/agent-harness-kit/types` | TypeScript types for all 28 events + `HookOutputBuilder` |
+| `@libar-dev/agent-harness-kit/types` | TypeScript types for all 30 events + `HookOutputBuilder` |
 | `@libar-dev/agent-harness-kit/utils` | `executeHook`, `outputJson`, `isProtectedFile`, `isDangerousCommand`, logging |
 | `@libar-dev/agent-harness-kit/validation` | Zod schemas, per-event validators, 15 tool-input validators, `validateHooksConfig` |
 | `@libar-dev/agent-harness-kit/pre-tool-use` | Reference handlers: bash validator, file protector, ESLint-disable blocker |
 | `@libar-dev/agent-harness-kit/post-tool-use` | Reference handlers: Prettier formatter, TypeScript checker |
-| `@libar-dev/agent-harness-kit/lifecycle` | Reference handlers: session start/end, notifications, stop, subagents, elicitation |
+| `@libar-dev/agent-harness-kit/lifecycle` | Reference handlers: setup, session start/end, notifications, message display, stop, subagents, elicitation |
+| `@libar-dev/agent-harness-kit/processing` | Session parsing, full-history reads, structured exports, and multi-source raw transcript tailing |
 
 ## Documentation
 
 - **[Getting Started](docs/guides/getting-started.md)** — install, sub-path imports, 5-minute walkthrough
 - **[Writing Your First Hook](docs/guides/writing-your-first-hook.md)** — `executeHook` skeleton, validators, `permission()`, testing
 - **[Configuring settings.json](docs/guides/configuring-settings-json.md)** — 5 handler types, matcher syntax, `if`/`timeout`/`async`
 - **[Cookbook](docs/guides/cookbook.md)** — 10 copy-pasteable recipes
-- **[Hook Events Reference](docs/reference/hook-events.md)** — all 28 events with input/output shapes
+- **[Hook Events Reference](docs/reference/hook-events.md)** — all 30 events with input/output shapes
 - **[HookOutputBuilder Reference](docs/reference/output-builder.md)** — every method with examples
 - **[Validators Reference](docs/reference/validators.md)** — tool-input validators, type guards, config validators
 - **[Environment Variables](docs/reference/environment-variables.md)** — all `CLAUDE_HOOK_*` vars
+- **[Session tailing](docs/internal/tail-session.md)** — CLI and public library APIs for live transcript ingestion
 - **[Full docs index](docs/README.md)**
 
 ## Development
@@ -109,7 +111,7 @@ pnpm run build        # compile src/ → dist/ (publish only)
 
 ## Status
 
-Version `0.1.0` is not yet published to npm. The public API is stable but may change before the first published release. Pin to a commit hash if you depend on this from another project.
+Version `0.1.0` is the initial npm release candidate. The public API is stable but may change before the first published release. Pin to a commit hash if you depend on this from another project.
 
 ## Contributing