libar-dev · darko-mijic · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.omo/plans/comment-consistency-cleanup.md b/.omo/plans/comment-consistency-cleanup.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,17 +9,32 @@ Categories per release: **Added**, **Changed**, **Deprecated**, **Removed**, **F
 
 ---
 
-## [0.1.0] - 2026-06-24
+## [Unreleased]
+
+### Changed
+
+- 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`.
 
-First public release of `@libar-dev/agent-harness-kit`.
+## [0.1.0] - 2026-06-24
 
-This is the first release under the new `agent-harness-kit` identity.
+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 +46,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 +104,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`
@@ -217,6 +217,18 @@ docs separate.
 
 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,20 +74,20 @@ 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 |
 
 ## 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
@@ -109,7 +109,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
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -2,8 +2,8 @@
 
 ## Supported Versions
 
-This library is pre-1.0-stable in practice and published from the `main` branch. Security
-fixes are applied to the latest released version. Older versions are not maintained.
+This library is a pre-1.0 release candidate published from the `main` branch. Security
+fixes apply to the latest released version. Older versions are not maintained.
 
 | Version | Supported          |
 | ------- | ------------------ |
@@ -27,19 +27,19 @@ public disclosure.
 ## Scope
 
 This is a TypeScript library that processes Claude Code hook I/O and session transcripts.
-Particularly relevant areas:
+Relevant areas:
 
 - **Untrusted transcript content** parsed by the `processing/` and tail subsystems
   (JSONL validation, secret redaction, regex safety).
 - **Hook input validation** in `validation/` (Zod schemas at trust boundaries).
 
 **Known limitation — secret redaction scope.** Redaction covers tool-**result**
-bodies and error strings (Bash stdout, file contents, diffs, and the like). It
+bodies and error strings (Bash stdout, file contents, diffs, etc.). It
 does **not** redact tool-**call inputs** — for example a Bash command such as
 `export API_KEY=...`, or a URL with embedded credentials passed as a tool
 argument — nor the one-line tool-call summaries derived from those inputs.
 Consumers should treat tool-call inputs as potentially containing secrets and
 handle them accordingly. The `--format raw-records` path is unredacted by
 design and is gated behind an explicit `--unsafe-raw-unredacted` opt-in.
 
-When reporting, noting which subsystem is involved helps us triage quickly.
+When reporting, include the subsystem involved if known.
diff --git a/docs/README.md b/docs/README.md
@@ -2,8 +2,6 @@
 
 `@libar-dev/agent-harness-kit` developer documentation.
 
----
-
 ## Guides — Start Here
 
 | Guide | What it covers |
@@ -14,20 +12,16 @@
 | [Cookbook](guides/cookbook.md) | 10 copy-pasteable recipes for common hook patterns |
 | [Troubleshooting](guides/troubleshooting.md) | Hook not firing, exit codes, debug logging, Zod errors |
 
----
-
 ## API Reference
 
 | Reference | What it covers |
 |-----------|----------------|
-| [Hook Events](reference/hook-events.md) | All 28 events — input fields, output shape, builder method |
+| [Hook Events](reference/hook-events.md) | All 30 events — input fields, output shape, builder method |
 | [HookOutputBuilder](reference/output-builder.md) | Every method with signature and examples |
 | [Validators](reference/validators.md) | Tool-input validators, type guards, content validators, config validators |
 | [Types](reference/types.md) | Full type catalogue — inputs, outputs, tools, config |
 | [Environment Variables](reference/environment-variables.md) | Every `CLAUDE_HOOK_*` variable with type, default, and description |
 
----
-
 ## Architecture & Internal
 
 | Doc | Audience |
@@ -36,11 +30,9 @@
 | [Export Sessions Script](internal/export-sessions.md) | How the export-sessions utility works |
 | [Tail Sessions Script](internal/tail-session.md) | How the tail-session CLI works (modes, flags, marker offsets) |
 
----
-
 ## Upstream Reference (Mirrored)
 
-Official Anthropic documentation mirrored for offline development use. Always check the [official docs](https://docs.anthropic.com/en/docs/claude-code/hooks) for the canonical, up-to-date version.
+Official Claude Code documentation mirrored for offline development use. Always check the [official docs](https://code.claude.com/docs/en/overview) for the canonical, up-to-date version.
 
 | Doc | Source |
 |-----|--------|