@onlooker-community/ecosystem 0.8.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "ecosystem",
       "source": "./",
       "description": "Fill this out",
-      "version": "0.8.0",
+      "version": "0.10.0",
       "author": {
         "name": "Onlooker Community"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "TODO fill this out",
   "author": {
     "name": "Onlooker Community",

package/.github/workflows/release.yml

@@ -15,7 +15,6 @@ jobs:
       - uses: googleapis/release-please-action@v4
         id: release
         with:
-          release-type: node
           token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
           
       - uses: actions/checkout@v4

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.10.0"
 }

package/CHANGELOG.md

@@ -7,6 +7,47 @@
 
 # Changelog
 
+## [0.10.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.9.0...ecosystem-v0.10.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** enrich tool.file.read with read chunking observability ([#25](https://github.com/onlooker-community/ecosystem/issues/25)) ([8eb23c8](https://github.com/onlooker-community/ecosystem/commit/8eb23c8f4f03dfbeb701a30de1fa50c1c8ee48ac))
+
+## [0.9.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.8.0...ecosystem-v0.9.0) (2026-05-22)
+
+
+### Features
+
+* add configuration and hooks for agent spawn tracking ([3ef4590](https://github.com/onlooker-community/ecosystem/commit/3ef459006bbbda246604bdd1ffaf9af0a59f9740))
+* add settings.json for plugin configuration ([67fbdfe](https://github.com/onlooker-community/ecosystem/commit/67fbdfe37f067a45801e7d0355c4a533b687f6b2))
+* **hooks:** add PreCompact and PostCompact context compaction trackers ([#15](https://github.com/onlooker-community/ecosystem/issues/15)) ([1ec5632](https://github.com/onlooker-community/ecosystem/commit/1ec5632404676ed8b35d324b79ad71a2e9093505))
+* **hooks:** add SessionStart and SessionEnd session trackers ([#10](https://github.com/onlooker-community/ecosystem/issues/10)) ([a48d680](https://github.com/onlooker-community/ecosystem/commit/a48d680dd24c98e79ef1c0401b07483ecebf9e8b))
+* **hooks:** add TaskCreated and TaskCompleted task lifecycle trackers ([#21](https://github.com/onlooker-community/ecosystem/issues/21)) ([986ffa8](https://github.com/onlooker-community/ecosystem/commit/986ffa84bdd857a464ca0d556671628190ed27bc))
+* **hooks:** add UserPromptSubmit turn and session duration trackers ([#12](https://github.com/onlooker-community/ecosystem/issues/12)) ([cbb7657](https://github.com/onlooker-community/ecosystem/commit/cbb7657979ed144efce506e6b487e037679b9462))
+* **hooks:** add WorktreeCreate and WorktreeRemove lifecycle trackers ([#24](https://github.com/onlooker-community/ecosystem/issues/24)) ([ff55e39](https://github.com/onlooker-community/ecosystem/commit/ff55e397a0c0adc3e76f66aba12c6b237149ad17))
+* **hooks:** emit canonical schema events for tool history :sparkles: ([1e49a24](https://github.com/onlooker-community/ecosystem/commit/1e49a24bfb930942fa477b594395ef352618f574))
+* **hooks:** track skill usage via skill.invoked events ([23fff0f](https://github.com/onlooker-community/ecosystem/commit/23fff0f0bfad8ab91788d8c45a0457d099d2e870))
+* **hooks:** track tool call sequence on every PreToolUse :sparkles: ([0ad9546](https://github.com/onlooker-community/ecosystem/commit/0ad95465cc22a237e26115a67814a6e7b2951b1d))
+
+
+### Bug Fixes
+
+* **ci:** apply release-please extra-files for Claude plugin manifests ([#17](https://github.com/onlooker-community/ecosystem/issues/17)) ([da9913c](https://github.com/onlooker-community/ecosystem/commit/da9913ca4f7497280edc34f8c64baa903c1e6754))
+* **ci:** checkout release tag before npm publish :relieved: ([bc7bbdc](https://github.com/onlooker-community/ecosystem/commit/bc7bbdc7a886a55ba8f04fe09bfa60043648c766))
+* **ci:** grant id-token write for npm provenance on publish ([c78c9f0](https://github.com/onlooker-community/ecosystem/commit/c78c9f054c1d48ca8a83d0d26b76ce991fffe51b))
+* **ci:** parse release-please paths_released JSON for npm publish ([749e1a0](https://github.com/onlooker-community/ecosystem/commit/749e1a02b563f37f81a8da21fc3f6e10e179314a))
+* **ci:** stop upgrading npm globally before publish ([a7c7a0e](https://github.com/onlooker-community/ecosystem/commit/a7c7a0e1f25aee1bbb75bdd2af130dbc276480a6))
+* **ci:** use HTTPS repository URL for npm provenance ([a7e8927](https://github.com/onlooker-community/ecosystem/commit/a7e89275c5a025a8afee009853265b717091f6ca))
+* **package:** update repository URL format in package.json ([591ce9f](https://github.com/onlooker-community/ecosystem/commit/591ce9f54dd605ec04ceb77b9dcca40b3e08621e))
+
+## [0.8.0](https://github.com/onlooker-community/ecosystem/compare/v0.7.2...v0.8.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** add TaskCreated and TaskCompleted task lifecycle trackers ([#21](https://github.com/onlooker-community/ecosystem/issues/21)) ([986ffa8](https://github.com/onlooker-community/ecosystem/commit/986ffa84bdd857a464ca0d556671628190ed27bc))
+
 ## [0.7.2](https://github.com/onlooker-community/ecosystem/compare/v0.7.1...v0.7.2) (2026-05-22)
 
 

package/hooks/hooks.json

@@ -157,6 +157,26 @@
           }
         ]
       }
+    ],
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/worktree-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/worktree-tracker.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -9,7 +9,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/onlooker-community/ecosystem"
+    "url": "git+https://github.com/onlooker-community/ecosystem.git"
   },
   "homepage": "https://github.com/onlooker-community/ecosystem#readme",
   "bugs": {
@@ -19,7 +19,7 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^1.4.0"
+    "@onlooker-community/schema": "^1.4.1"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",

package/scripts/hooks/worktree-tracker.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Onlooker Worktree Tracker
+# Invoked by WorktreeCreate and WorktreeRemove for isolated agent/git worktree sessions.
+#
+# WorktreeCreate replaces default git behavior: this hook creates the worktree, records
+# telemetry, and prints the absolute worktree path on stdout (stderr for diagnostics).
+# WorktreeRemove records telemetry and removes the git worktree when present.
+#
+# Records canonical tool.shell.exec events (interim until worktree.* schema types exist) to:
+#   ~/.onlooker/session-history/<session_id>.jsonl
+#   ~/.onlooker/logs/onlooker-events.jsonl
+#
+# Usage:
+#   echo "$INPUT" | worktree-tracker.sh
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/worktree-tracker.sh"
+
+hook_register "worktree-tracker" "Worktree Tracker" "Creates/removes git worktrees and records lifecycle telemetry"
+
+INPUT=$(cat)
+
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""')
+hook_set_context "$INPUT" "$HOOK_EVENT"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+
+turn_state_export "$SESSION_ID"
+
+worktree_tracker_emit() {
+	local enriched_input="${1:-}"
+	local record
+	record=$(worktree_tracker_build_record "$enriched_input")
+	if [[ -n "$record" ]]; then
+		worktree_tracker_append "$SESSION_ID" "$record" || hook_failure "Failed to append session history"
+		onlooker_append_event "$record" || hook_failure "Failed to append global event log"
+	fi
+}
+
+case "$HOOK_EVENT" in
+WorktreeCreate)
+	NAME=$(echo "$INPUT" | jq -r '.name // ""')
+	if [[ -z "$NAME" ]]; then
+		echo "WorktreeCreate requires a worktree name" >&2
+		exit 1
+	fi
+
+	REPO_ROOT=$(worktree_tracker_repo_root "$CWD")
+	if [[ -z "$REPO_ROOT" ]]; then
+		echo "WorktreeCreate requires a git repository (cwd: ${CWD:-unknown})" >&2
+		exit 1
+	fi
+
+	START_MS=$(session_tracker_now_ms)
+	WORKTREE_PATH=$(worktree_tracker_git_create "$REPO_ROOT" "$NAME")
+	if [[ -z "$WORKTREE_PATH" ]]; then
+		echo "Failed to create git worktree for name: $NAME" >&2
+		exit 1
+	fi
+
+	BRANCH="worktree-${NAME}"
+	worktree_tracker_record_created "$SESSION_ID" "$NAME" "$WORKTREE_PATH" "$BRANCH" \
+		|| hook_failure "Failed to record worktree start time"
+
+	END_MS=$(session_tracker_now_ms)
+	export ONLOOKER_WORKTREE_DURATION_MS="$((END_MS - START_MS))"
+
+	ENRICHED=$(echo "$INPUT" | jq \
+		--arg path "$WORKTREE_PATH" \
+		--arg branch "$BRANCH" \
+		--arg repo "$REPO_ROOT" \
+		'. + {worktree_path: $path, branch_name: $branch, repo_root: $repo}')
+	RECORD=$(worktree_tracker_build_record "$ENRICHED")
+	if [[ -n "$RECORD" ]]; then
+		worktree_tracker_append "$SESSION_ID" "$RECORD" \
+			|| hook_failure "Failed to append session history"
+		onlooker_append_event "$RECORD" \
+			|| hook_failure "Failed to append global event log"
+	fi
+
+	# stdout must be only the absolute worktree path for Claude Code
+	printf '%s' "$WORKTREE_PATH"
+	exit 0
+	;;
+WorktreeRemove)
+	WORKTREE_PATH=$(echo "$INPUT" | jq -r '.worktree_path // ""')
+	if [[ -z "$WORKTREE_PATH" ]]; then
+		hook_success
+		exit 0
+	fi
+
+	REPO_ROOT=$(worktree_tracker_repo_root "$CWD")
+	DURATION_MS=$(worktree_tracker_duration_ms "$SESSION_ID" "$WORKTREE_PATH")
+	if [[ -n "$DURATION_MS" ]]; then
+		export ONLOOKER_WORKTREE_DURATION_MS="$DURATION_MS"
+	fi
+
+	ENRICHED=$(echo "$INPUT" | jq --arg repo "${REPO_ROOT:-}"} '. + {repo_root: $repo}')
+	worktree_tracker_emit "$ENRICHED"
+
+	if [[ -n "$REPO_ROOT" ]]; then
+		worktree_tracker_git_remove "$REPO_ROOT" "$WORKTREE_PATH"
+	fi
+
+	worktree_tracker_clear_by_path "$SESSION_ID" "$WORKTREE_PATH"
+
+	hook_success
+	exit 0
+	;;
+*)
+	hook_success
+	exit 0
+	;;
+esac

package/scripts/lib/onlooker-event.mjs

@@ -4,7 +4,7 @@
  * Uses @onlooker-community/schema for envelope shape and validation.
  */
 import { randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   createEvent,
@@ -81,6 +81,85 @@ function extractPath(toolInput, toolResponse) {
   return toolInput?.file_path ?? toolInput?.path ?? toolResponse?.filePath ?? toolResponse?.path ?? undefined;
 }
 
+/** Bytes on disk above which a full read is flagged as large_file_full_read. */
+export const LARGE_FILE_BYTES_ON_DISK = 100_000;
+
+const MAX_FILE_LINES_STAT_BYTES = 512 * 1024;
+
+function parseNonNegativeInt(value) {
+  if (value == null || value === '') return undefined;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+function parsePositiveInt(value, min = 1) {
+  if (value == null || value === '') return undefined;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) && n >= min ? n : undefined;
+}
+
+/**
+ * Derive read_mode and line range from Read tool_input (supports common field aliases).
+ */
+export function extractReadRange(toolInput) {
+  const input = toolInput ?? {};
+  const offset = parseNonNegativeInt(
+    input.offset ?? input.start_line ?? input.start_line_one_indexed ?? input.line_offset,
+  );
+  const limit = parsePositiveInt(input.limit ?? input.line_limit ?? input.num_lines ?? input.line_count);
+  const read_mode = offset != null || limit != null ? 'partial' : 'full';
+  return stripUndefined({ read_mode, offset, limit });
+}
+
+/**
+ * Stat file on disk for chunking analytics (line count omitted for very large files).
+ */
+export function measureFileOnDisk(filePath) {
+  try {
+    if (!filePath || !existsSync(filePath)) return {};
+    const st = statSync(filePath);
+    if (!st.isFile()) return {};
+    const file_bytes_on_disk = st.size;
+    let file_lines_on_disk;
+    if (st.size <= MAX_FILE_LINES_STAT_BYTES) {
+      const text = readFileSync(filePath, 'utf8');
+      file_lines_on_disk = text.split('\n').length;
+    }
+    return stripUndefined({ file_bytes_on_disk, file_lines_on_disk });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Build tool.file.read payload from Read tool hook fields.
+ */
+export function buildToolFileReadPayload(toolInput, toolResponse, options = {}) {
+  const path = extractPath(toolInput, toolResponse);
+  if (!path) return null;
+
+  const payload = { path, ...extractReadRange(toolInput) };
+  const content = toolResponse?.content;
+  if (typeof content === 'string') {
+    payload.lines_read = content.split('\n').length;
+    payload.file_size_bytes = content.length;
+  }
+
+  if (options.measureOnDisk !== false) {
+    Object.assign(payload, measureFileOnDisk(path));
+  }
+
+  if (
+    payload.read_mode === 'full' &&
+    payload.file_bytes_on_disk != null &&
+    payload.file_bytes_on_disk >= LARGE_FILE_BYTES_ON_DISK
+  ) {
+    payload.large_file_full_read = true;
+  }
+
+  return stripUndefined(payload);
+}
+
 function stripUndefined(obj) {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null && v !== ''));
 }
@@ -197,6 +276,59 @@ export function mapTaskHookInput(hookInput, options) {
   return { valid: true, event: result.event };
 }
 
+/**
+ * Map WorktreeCreate / WorktreeRemove hook input to tool.shell.exec (interim until
+ * worktree.* event types exist in @onlooker-community/schema).
+ */
+export function mapWorktreeHookInput(hookInput, options) {
+  const { onlookerDir, plugin, runtime = 'claude-code', adapter_id = 'ecosystem.hooks' } = options;
+  const hookEvent = hookInput?.hook_event_name;
+  const sessionId = hookInput?.session_id ?? 'unknown';
+  const cwd = hookInput?.cwd;
+
+  let command;
+  let worktreePath = hookInput?.worktree_path;
+
+  if (hookEvent === 'WorktreeCreate') {
+    const name = hookInput?.name;
+    if (!name) return null;
+    const branch = hookInput?.branch_name ?? `worktree-${name}`;
+    worktreePath = hookInput?.worktree_path;
+    command = `worktree:create name=${name} branch=${branch}${worktreePath ? ` path=${worktreePath}` : ''}`;
+  } else if (hookEvent === 'WorktreeRemove') {
+    if (!worktreePath) return null;
+    command = `worktree:remove path=${worktreePath}`;
+  } else {
+    return null;
+  }
+
+  const durationRaw = process.env.ONLOOKER_WORKTREE_DURATION_MS;
+  const durationMs = durationRaw != null && durationRaw !== '' ? Number.parseInt(String(durationRaw), 10) : undefined;
+
+  const payload = stripUndefined({
+    command,
+    exit_code: 0,
+    duration_ms: Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : undefined,
+    working_directory: cwd,
+  });
+
+  const event = buildCanonicalEvent({
+    onlookerDir,
+    runtime,
+    adapter_id,
+    plugin,
+    session_id: sessionId,
+    event_type: TOOL_SHELL_EXEC,
+    payload,
+  });
+
+  const result = validate(event);
+  if (!result.valid) {
+    return { valid: false, errors: result.errors, event_type: TOOL_SHELL_EXEC };
+  }
+  return { valid: true, event: result.event };
+}
+
 /**
  * Map Claude Code hook input to a canonical event.
  * Returns null when the hook input is not mapped to a schema event type.
@@ -208,6 +340,9 @@ export function mapHookInputToCanonical(hookInput, options) {
   const taskMapped = mapTaskHookInput(hookInput, options);
   if (taskMapped) return taskMapped;
 
+  const worktreeMapped = mapWorktreeHookInput(hookInput, options);
+  if (worktreeMapped) return worktreeMapped;
+
   const { onlookerDir, plugin, runtime = 'claude-code', adapter_id = 'ecosystem.hooks' } = options;
 
   const toolName = hookInput?.tool_name;
@@ -223,16 +358,9 @@ export function mapHookInputToCanonical(hookInput, options) {
 
   switch (toolName) {
     case 'Read': {
-      const path = extractPath(toolInput, toolResponse);
-      if (!path) return null;
+      payload = buildToolFileReadPayload(toolInput, toolResponse);
+      if (!payload) return null;
       eventType = TOOL_FILE_READ;
-      payload = { path };
-      const content = toolResponse?.content;
-      if (typeof content === 'string') {
-        const lines = content.split('\n').length;
-        payload.lines_read = lines;
-        payload.file_size_bytes = content.length;
-      }
       break;
     }
     case 'Write': {

package/scripts/lib/onlooker-schema.sh

@@ -27,6 +27,7 @@ onlooker_event_from_hook() {
 	printf '%s' "$hook_input" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
 		ONLOOKER_TURN_NUMBER="${ONLOOKER_TURN_NUMBER:-}" \
 		ONLOOKER_TASK_DURATION_MS="${ONLOOKER_TASK_DURATION_MS:-}" \
+		ONLOOKER_WORKTREE_DURATION_MS="${ONLOOKER_WORKTREE_DURATION_MS:-}" \
 		node "$_ONLOOKER_EVENT_JS" emit-from-hook 2>/dev/null
 }
 

package/scripts/lib/worktree-tracker.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Worktree lifecycle helpers — git worktree create/remove and telemetry state.
+#
+# Source after validate-path.sh, onlooker-schema.sh, session-tracker.sh, and tool-history.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/worktree-tracker.sh"
+
+# Resolve repository root from hook cwd (must be inside a git work tree).
+# Usage: repo_root=$(worktree_tracker_repo_root "$CWD")
+worktree_tracker_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && return 1
+	git -C "$cwd" rev-parse --show-toplevel 2>/dev/null
+}
+
+# Create a Claude-style git worktree; prints absolute path on stdout, diagnostics on stderr.
+# Usage: path=$(worktree_tracker_git_create "$REPO_ROOT" "$NAME")
+worktree_tracker_git_create() {
+	local repo_root="${1:-}"
+	local name="${2:-}"
+	[[ -z "$repo_root" || -z "$name" ]] && return 1
+
+	local worktree_dir="${repo_root}/.claude/worktrees/${name}"
+	local branch="worktree-${name}"
+
+	mkdir -p "${repo_root}/.claude/worktrees"
+
+	if [[ -d "$worktree_dir" ]]; then
+		(cd "$worktree_dir" && pwd -P)
+		return 0
+	fi
+
+	local base_ref="HEAD"
+	if git -C "$repo_root" rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+		base_ref=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD)
+	fi
+
+	if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" 2>/dev/null; then
+		git -C "$repo_root" worktree add "$worktree_dir" "$branch" >&2 || return 1
+	else
+		git -C "$repo_root" worktree add -b "$branch" "$worktree_dir" "$base_ref" >&2 || return 1
+	fi
+
+	(cd "$worktree_dir" && pwd -P)
+}
+
+# Remove a git worktree when it is registered for the repo (best-effort).
+# Usage: worktree_tracker_git_remove "$REPO_ROOT" "$WORKTREE_PATH"
+worktree_tracker_git_remove() {
+	local repo_root="${1:-}"
+	local worktree_path="${2:-}"
+	[[ -z "$repo_root" || -z "$worktree_path" ]] && return 0
+
+	local resolved_path="$worktree_path"
+	if [[ -d "$worktree_path" ]]; then
+		resolved_path=$(cd "$worktree_path" && pwd -P)
+	fi
+
+	if git -C "$repo_root" worktree list --porcelain 2>/dev/null | grep -Fq "worktree ${resolved_path}"; then
+		git -C "$repo_root" worktree remove --force "$resolved_path" >&2 || true
+	fi
+}
+
+# Record worktree creation in the per-session tracker for duration on remove.
+# Usage: worktree_tracker_record_created "$SESSION_ID" "$NAME" "$PATH" "$BRANCH"
+worktree_tracker_record_created() {
+	local session_id="${1:-}"
+	local name="${2:-}"
+	local worktree_path="${3:-}"
+	local branch="${4:-}"
+	[[ -z "$session_id" || -z "$name" || -z "$worktree_path" ]] && return 0
+
+	turn_state_ensure_session "$session_id" || return 1
+
+	local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+	local now_ms
+	now_ms=$(session_tracker_now_ms)
+
+	local temp_file
+	temp_file=$(mktemp)
+	if jq --arg name "$name" --arg path "$worktree_path" --arg branch "$branch" --argjson ms "$now_ms" \
+		'.worktrees[$name] = {path: $path, branch: $branch, start_time_ms: $ms}' \
+		"$tracker_file" >"$temp_file" 2>/dev/null; then
+		mv "$temp_file" "$tracker_file"
+	else
+		rm -f "$temp_file"
+		return 1
+	fi
+}
+
+# Compute duration for a worktree path; prints empty when unknown.
+# Usage: duration_ms=$(worktree_tracker_duration_ms "$SESSION_ID" "$WORKTREE_PATH")
+worktree_tracker_duration_ms() {
+	local session_id="${1:-}"
+	local worktree_path="${2:-}"
+	[[ -z "$session_id" || -z "$worktree_path" ]] && return 0
+
+	local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+	[[ ! -f "$tracker_file" ]] && return 0
+
+	local start_ms
+	start_ms=$(
+		jq -r --arg path "$worktree_path" '
+			[.worktrees // {} | to_entries[] | select(.value.path == $path) | .value.start_time_ms] | first // empty
+		' "$tracker_file" 2>/dev/null
+	)
+	[[ -z "$start_ms" || "$start_ms" == "null" ]] && return 0
+
+	local now_ms elapsed
+	now_ms=$(session_tracker_now_ms)
+	elapsed=$((now_ms - start_ms))
+	if [[ "$elapsed" -ge 0 ]]; then
+		printf '%s' "$elapsed"
+	fi
+}
+
+# Remove worktree timing entry after removal telemetry is recorded.
+# Usage: worktree_tracker_clear_by_path "$SESSION_ID" "$WORKTREE_PATH"
+worktree_tracker_clear_by_path() {
+	local session_id="${1:-}"
+	local worktree_path="${2:-}"
+	[[ -z "$session_id" || -z "$worktree_path" ]] && return 0
+
+	local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+	[[ ! -f "$tracker_file" ]] && return 0
+
+	local temp_file
+	temp_file=$(mktemp)
+	if jq --arg path "$worktree_path" '
+			.worktrees |= with_entries(select(.value.path != $path))
+		' "$tracker_file" >"$temp_file" 2>/dev/null; then
+		mv "$temp_file" "$tracker_file"
+	else
+		rm -f "$temp_file"
+	fi
+}
+
+# Build a canonical event from hook stdin (empty when unmapped).
+# Usage: record=$(worktree_tracker_build_record "$INPUT")
+worktree_tracker_build_record() {
+	local input_json="${1:-}"
+	onlooker_event_from_hook "$input_json"
+}
+
+# Append a canonical worktree event to session history.
+# Usage: worktree_tracker_append "$SESSION_ID" "$event_json"
+worktree_tracker_append() {
+	tool_history_append "$1" "$2"
+}

package/test/bats/config.bats

@@ -197,6 +197,28 @@ setup_file() {
   [ "$status" -eq 0 ]
 }
 
+@test "hooks.json WorktreeCreate references worktree-tracker" {
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.WorktreeCreate[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *worktree-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
+@test "hooks.json WorktreeRemove references worktree-tracker" {
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.WorktreeRemove[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *worktree-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
 @test "plugin.json is valid JSON" {
   run jq -e '.name and .version' "${REPO_ROOT}/.claude-plugin/plugin.json"
   [ "$status" -eq 0 ]

package/test/bats/read-chunk-tracking.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  # shellcheck source=../../scripts/lib/onlooker-schema.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  # shellcheck source=../../scripts/lib/tool-history.sh
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+
+  LARGE_FILE="${BATS_TEST_TMPDIR}/large-source.ts"
+  # > LARGE_FILE_BYTES_ON_DISK (100_000) for large_file_full_read
+  printf '%*s\n' 120000 "" >"$LARGE_FILE"
+}
+
+@test "tool_history maps full Read to read_mode full" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read.json"
+  local record
+  record=$(tool_history_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "full"
+     and .payload.path == "/project/src/main.ts"
+     and (.payload.large_file_full_read | not)' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool_history maps chunked Read to read_mode partial with offset and limit" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read-chunked.json"
+  local record
+  record=$(tool_history_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "partial"
+     and .payload.offset == 400
+     and .payload.limit == 80
+     and .payload.lines_read == 3' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool_history flags large_file_full_read for full read of large on-disk file" {
+  local input
+  input=$(jq -n \
+    --arg path "$LARGE_FILE" \
+    --arg content "peek\n" \
+    '{
+      session_id: "history-session-002",
+      hook_event_name: "PostToolUse",
+      tool_name: "Read",
+      tool_input: {file_path: $path},
+      tool_response: {content: $content}
+    }')
+  local record
+  record=$(tool_history_build_record "$input")
+  echo "$record" | jq -e \
+    '.payload.read_mode == "full"
+     and .payload.large_file_full_read == true
+     and .payload.file_bytes_on_disk > 100000' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "tool-history-tracker appends chunked read to session JSONL" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/post-tool-use-read-chunked.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/history-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  cat "$fixture" | "${REPO_ROOT}/scripts/hooks/tool-history-tracker.sh" >/dev/null 2>&1
+
+  tail -n 1 "$history_file" | jq -e '.payload.read_mode == "partial"' >/dev/null
+}

package/test/bats/tool-history-tracker.bats

@@ -19,6 +19,7 @@ setup() {
     '.schema_version == "1.0"
      and .event_type == "tool.file.read"
      and .payload.path == "/project/src/main.ts"
+     and .payload.read_mode == "full"
      and .session_id == "history-session-001"' \
     >/dev/null
   echo "$record" | onlooker_validate_event

package/test/bats/validate-path.bats

@@ -96,7 +96,7 @@ setup() {
   export _HOOK_SESSION_ID="emit-session"
   export ONLOOKER_HOOK_TYPE="PreToolUse"
   export ONLOOKER_TOOL_NAME="Read"
-  local payload='{"path":"/tmp/example.txt"}'
+  local payload='{"path":"/tmp/example.txt","read_mode":"full"}'
   safe_emit "tool.file.read" "$payload"
   [ "$?" -eq 0 ]
   [ -f "$ONLOOKER_EVENTS_LOG" ]

package/test/bats/worktree-tracker.bats

@@ -0,0 +1,129 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  # shellcheck source=../../scripts/lib/onlooker-schema.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  # shellcheck source=../../scripts/lib/session-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/session-tracker.sh"
+  # shellcheck source=../../scripts/lib/tool-history.sh
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  # shellcheck source=../../scripts/lib/worktree-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/worktree-tracker.sh"
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+
+  GIT_REPO="${BATS_TEST_TMPDIR}/git-repo"
+  rm -rf "$GIT_REPO"
+  mkdir -p "$GIT_REPO"
+  git -C "$GIT_REPO" init -q
+  git -C "$GIT_REPO" config user.email "test@example.com"
+  git -C "$GIT_REPO" config user.name "Test User"
+  echo "hello" >"$GIT_REPO/README.md"
+  git -C "$GIT_REPO" add README.md
+  git -C "$GIT_REPO" commit -q -m "init"
+}
+
+@test "worktree_tracker_build_record maps WorktreeCreate to tool.shell.exec" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/worktree-create.json"
+  local enriched
+  enriched=$(jq \
+    --arg path "${GIT_REPO}/.claude/worktrees/feature-auth" \
+    --arg branch "worktree-feature-auth" \
+    '. + {worktree_path: $path, branch_name: $branch}' \
+    "$fixture")
+  export ONLOOKER_WORKTREE_DURATION_MS=42
+  local record
+  record=$(worktree_tracker_build_record "$enriched")
+  echo "$record" | jq -e \
+    '.event_type == "tool.shell.exec"
+     and .payload.exit_code == 0
+     and .payload.duration_ms == 42
+     and (.payload.command | test("worktree:create"))
+     and .payload.working_directory == "/project/repo"' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "worktree_tracker_build_record maps WorktreeRemove to tool.shell.exec" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/worktree-remove.json"
+  export ONLOOKER_WORKTREE_DURATION_MS=9000
+  local record
+  record=$(worktree_tracker_build_record "$(cat "$fixture")")
+  echo "$record" | jq -e \
+    '.event_type == "tool.shell.exec"
+     and (.payload.command | test("worktree:remove"))
+     and .payload.duration_ms == 9000' \
+    >/dev/null
+  echo "$record" | onlooker_validate_event
+}
+
+@test "worktree-tracker WorktreeCreate prints absolute path on stdout" {
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/worktree-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/worktree-session-001"
+
+  local input_file="${BATS_TEST_TMPDIR}/worktree-create-input.json"
+  jq \
+    --arg cwd "$GIT_REPO" \
+    --arg sid "worktree-session-001" \
+    '.cwd = $cwd | .session_id = $sid' \
+    "${REPO_ROOT}/test/fixtures/hook-inputs/worktree-create.json" >"$input_file"
+
+  local worktree_path
+  worktree_path=$(cat "$input_file" | "${REPO_ROOT}/scripts/hooks/worktree-tracker.sh")
+  [ -d "$worktree_path" ]
+  [[ "$worktree_path" == "$(cd "$worktree_path" && pwd -P)" ]]
+  [ -f "$history_file" ]
+  tail -n 1 "$history_file" | jq -e '.event_type == "tool.shell.exec"' >/dev/null
+}
+
+@test "worktree-tracker WorktreeRemove records telemetry and removes worktree" {
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/worktree-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/worktree-session-001"
+
+  local create_input_file="${BATS_TEST_TMPDIR}/worktree-create-input.json"
+  local remove_input_file="${BATS_TEST_TMPDIR}/worktree-remove-input.json"
+  jq \
+    --arg cwd "$GIT_REPO" \
+    --arg sid "worktree-session-001" \
+    '.cwd = $cwd | .session_id = $sid' \
+    "${REPO_ROOT}/test/fixtures/hook-inputs/worktree-create.json" >"$create_input_file"
+
+  local worktree_path
+  worktree_path=$(cat "$create_input_file" | "${REPO_ROOT}/scripts/hooks/worktree-tracker.sh")
+
+  jq \
+    --arg cwd "$GIT_REPO" \
+    --arg path "$worktree_path" \
+    --arg sid "worktree-session-001" \
+    '.cwd = $cwd | .worktree_path = $path | .session_id = $sid' \
+    "${REPO_ROOT}/test/fixtures/hook-inputs/worktree-remove.json" >"$remove_input_file"
+
+  run bash -c "cat '${remove_input_file}' | '${REPO_ROOT}/scripts/hooks/worktree-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+  [ ! -d "$worktree_path" ]
+
+  tail -n 1 "$history_file" | jq -e \
+    '.event_type == "tool.shell.exec"
+     and (.payload.command | test("worktree:remove"))' \
+    >/dev/null
+}
+
+@test "worktree-tracker mirrors worktree events to global events log" {
+  local input
+  input=$(jq \
+    --arg cwd "$GIT_REPO" \
+    '.cwd = $cwd' \
+    "${REPO_ROOT}/test/fixtures/hook-inputs/worktree-create.json")
+  : >"$ONLOOKER_EVENTS_LOG"
+
+  printf '%s' "$input" | "${REPO_ROOT}/scripts/hooks/worktree-tracker.sh" >/dev/null
+
+  tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -e \
+    '.event_type == "tool.shell.exec"
+     and (.payload.command | test("worktree:create"))' \
+    >/dev/null
+}

package/test/fixtures/hook-inputs/post-tool-use-read-chunked.json

@@ -0,0 +1,15 @@
+{
+  "session_id": "history-session-001",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Read",
+  "tool_use_id": "toolu_read_002",
+  "duration_ms": 18,
+  "tool_input": {
+    "file_path": "/project/src/large-module.ts",
+    "offset": 400,
+    "limit": 80
+  },
+  "tool_response": {
+    "content": "// chunk line 1\n// chunk line 2\n"
+  }
+}

package/test/fixtures/hook-inputs/worktree-create.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "worktree-session-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "permission_mode": "default",
+  "hook_event_name": "WorktreeCreate",
+  "name": "feature-auth"
+}

package/test/fixtures/hook-inputs/worktree-remove.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "worktree-session-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "permission_mode": "default",
+  "hook_event_name": "WorktreeRemove",
+  "worktree_path": "/project/repo/.claude/worktrees/feature-auth"
+}

package/test/node/schema-events.test.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
@@ -7,9 +7,13 @@ import { fileURLToPath } from 'node:url';
 import { validate } from '@onlooker-community/schema';
 import {
   buildCanonicalEvent,
+  buildToolFileReadPayload,
+  extractReadRange,
+  LARGE_FILE_BYTES_ON_DISK,
   mapHookInputToCanonical,
   mapSkillHookInput,
   mapTaskHookInput,
+  mapWorktreeHookInput,
 } from '../../scripts/lib/onlooker-event.mjs';
 
 const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
@@ -31,6 +35,43 @@ test('mapHookInputToCanonical maps PostToolUse Read to tool.file.read', () => {
   assert.equal(mapped.event.event_type, 'tool.file.read');
   assert.equal(mapped.event.schema_version, '1.0');
   assert.equal(mapped.event.payload.path, '/project/src/main.ts');
+  assert.equal(mapped.event.payload.read_mode, 'full');
+  assert.equal(validate(mapped.event).valid, true);
+});
+
+test('extractReadRange detects partial reads from offset and limit', () => {
+  const range = extractReadRange({ offset: 10, limit: 50 });
+  assert.equal(range.read_mode, 'partial');
+  assert.equal(range.offset, 10);
+  assert.equal(range.limit, 50);
+});
+
+test('buildToolFileReadPayload flags large_file_full_read', () => {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'onlooker-read-chunk-'));
+  const filePath = join(tmpDir, 'big.txt');
+  const bytes = LARGE_FILE_BYTES_ON_DISK + 1;
+  writeFileSync(filePath, 'x'.repeat(bytes), 'utf8');
+
+  const payload = buildToolFileReadPayload({ file_path: filePath }, { content: 'x\n' });
+  assert.equal(payload.read_mode, 'full');
+  assert.equal(payload.large_file_full_read, true);
+  assert.equal(payload.file_bytes_on_disk, bytes);
+
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('mapHookInputToCanonical maps chunked Read to partial read_mode', () => {
+  const hookInput = loadFixture('post-tool-use-read-chunked.json');
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const mapped = mapHookInputToCanonical(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.payload.read_mode, 'partial');
+  assert.equal(mapped.event.payload.offset, 400);
+  assert.equal(mapped.event.payload.limit, 80);
   assert.equal(validate(mapped.event).valid, true);
 });
 
@@ -111,6 +152,43 @@ test('mapTaskHookInput maps TaskCompleted to task.complete', () => {
   assert.equal(validate(mapped.event).valid, true);
 });
 
+test('mapWorktreeHookInput maps WorktreeCreate to tool.shell.exec', () => {
+  const hookInput = {
+    ...loadFixture('worktree-create.json'),
+    worktree_path: '/project/repo/.claude/worktrees/feature-auth',
+    branch_name: 'worktree-feature-auth',
+  };
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const prev = process.env.ONLOOKER_WORKTREE_DURATION_MS;
+  process.env.ONLOOKER_WORKTREE_DURATION_MS = '15';
+  const mapped = mapWorktreeHookInput(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+  if (prev === undefined) delete process.env.ONLOOKER_WORKTREE_DURATION_MS;
+  else process.env.ONLOOKER_WORKTREE_DURATION_MS = prev;
+
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.event_type, 'tool.shell.exec');
+  assert.equal(mapped.event.payload.exit_code, 0);
+  assert.equal(mapped.event.payload.duration_ms, 15);
+  assert.match(mapped.event.payload.command, /worktree:create/);
+  assert.equal(validate(mapped.event).valid, true);
+});
+
+test('mapWorktreeHookInput maps WorktreeRemove to tool.shell.exec', () => {
+  const hookInput = loadFixture('worktree-remove.json');
+  const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');
+  const mapped = mapWorktreeHookInput(hookInput, {
+    onlookerDir: tmpDir,
+    plugin: 'onlooker',
+  });
+
+  assert.equal(mapped.valid, true);
+  assert.match(mapped.event.payload.command, /worktree:remove/);
+  assert.equal(validate(mapped.event).valid, true);
+});
+
 test('mapHookInputToCanonical routes TaskCreated through task mapping', () => {
   const hookInput = loadFixture('task-created.json');
   const tmpDir = join(REPO_ROOT, 'test/tmp-schema-events');

package/.claude/settings.local.json

@@ -1,5 +0,0 @@
-{
-  "enabledPlugins": {
-    "ecosystem@onlooker-community": true
-  }
-}