@onlooker-community/ecosystem 0.0.2 → 0.2.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "TODO fill this out",
   "author": {
     "name": "Onlooker Community",
@@ -9,9 +9,6 @@
   "homepage": "https://onlooker.dev",
   "repository": "https://github.com/onlooker-community/ecosystem",
   "license": "MIT",
-  "skills": [
-    "./skills/",
-    "./commands/"
-  ],
+  "skills": [],
   "agents": []
 }

package/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mise
+        uses: jdx/mise-action@v2
+
+      - name: Install tools
+        run: mise install
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Run CI test suite
+        run: npm run test:ci

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.0.2"
+  ".": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/v0.1.0...v0.2.0) (2026-05-21)
+
+
+### Features
+
+* **hooks:** emit canonical schema events for tool history :sparkles: ([1e49a24](https://github.com/onlooker-community/ecosystem/commit/1e49a24bfb930942fa477b594395ef352618f574))
+* **hooks:** track tool call sequence on every PreToolUse :sparkles: ([0ad9546](https://github.com/onlooker-community/ecosystem/commit/0ad95465cc22a237e26115a67814a6e7b2951b1d))
+
+
+### Chores
+
+* **deps:** use published @onlooker-community/schema from npm :relieved: ([efc92d8](https://github.com/onlooker-community/ecosystem/commit/efc92d8171592aa5a5f1c27853387e810fee612f))
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/v0.0.3...v0.1.0) (2026-05-21)
+
+
+### Features
+
+* add configuration and hooks for agent spawn tracking ([3ef4590](https://github.com/onlooker-community/ecosystem/commit/3ef459006bbbda246604bdd1ffaf9af0a59f9740))
+
+
+### Chores
+
+* clean up README.md by removing outdated badge links ([42d47d6](https://github.com/onlooker-community/ecosystem/commit/42d47d602aa7b68db719874a1cf4193433d1bd68))
+* remove skills from plugin.json to streamline configuration ([fdfd8eb](https://github.com/onlooker-community/ecosystem/commit/fdfd8eb4faa0c807eff97feb1a20961de1fe154d))
+
+## [0.0.3](https://github.com/onlooker-community/ecosystem/compare/v0.0.2...v0.0.3) (2026-05-21)
+
+
+### Chores
+
+* update release-please configuration to include custom pull request title pattern ([e860f1c](https://github.com/onlooker-community/ecosystem/commit/e860f1c5a7b58909a53ec38a3b3da89f22f0434c))
+
 ## [0.0.2](https://github.com/onlooker-community/ecosystem/compare/v0.0.1...v0.0.2) (2026-05-21)
 
 

package/README.md

@@ -1,21 +1,23 @@
 # Onlooker Ecosystem
 
-[![Stars](https://img.shields.io/github/stars/onlooker-community/ecosystem?style=flat)](https://github.com/onlooker-community/ecosystem/stargazers)
-[![Forks](https://img.shields.io/github/forks/onlooker-community/ecosysem?style=flat)](https://github.com/onlooker-community/ecosystem/network/members)
-[![Contributors](https://img.shields.io/github/contributors/onlooker-community/ecosysetm?style=flat)](https://github.com/onlooker-community/ecosystem/graphs/contributors)
-[![License](https://img.shields.io/badge/license-BlueOak-blue.svg)](LICENSE)
-![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white)
-![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
-![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
-![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white)
-![Ruby](https://img.shields.io/badge/-Ruby-ED8B00?logo=openjdk&logoColor=white)
-![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white)
+Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev).
 
 ---
 
-Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev).
+## Development
 
----
+Install tools with [mise](https://mise.jdx.dev/) (`mise install`), then install dependencies (includes [`@onlooker-community/schema`](https://www.npmjs.com/package/@onlooker-community/schema) from npm):
+
+```bash
+npm ci
+npm test              # bats + schema validation tests
+npm run test:shellcheck
+npm run test:ci       # shellcheck + bats + schema + lint
+```
+
+Hooks emit [canonical Onlooker events](https://github.com/onlooker-community/schema) via `scripts/lib/onlooker-event.mjs`. Bash helpers live in `scripts/lib/onlooker-schema.sh`.
+
+Tests live under `test/bats/` and `test/node/` and use an isolated temp home so nothing writes to your real `~/.onlooker`.
 
 ## Quick Start
 

package/config.json

@@ -0,0 +1,4 @@
+{
+  "plugin_name": "onlooker",
+  "storage_path": "~/.onlooker"
+}

package/hooks/hooks.json

@@ -0,0 +1,46 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/tool-sequence-tracker.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/agent-spawn-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/tool-history-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/tool-history-tracker.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mise.toml

@@ -1,2 +1,13 @@
 [tools]
 node = "26.1.0"
+bats = "1.13.0"
+shellcheck = "0.10.0"
+jq = "1.7.1"
+
+[tasks.test]
+description = "Run bats test suite"
+run = "bats test/bats"
+
+[tasks."test:shellcheck"]
+description = "Run shellcheck on shell scripts"
+run = "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -18,9 +18,17 @@
   "bin": {
     "onlooker-install": "install.sh"
   },
+  "dependencies": {
+    "@onlooker-community/schema": "^1.3.0"
+  },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
-    "lint:check": "biome check . && markdownlint '**/*.md' --ignore node_modules",
+    "test": "npm run test:bats && npm run test:schema",
+    "test:bats": "bats test/bats",
+    "test:schema": "node --test test/node/*.test.mjs",
+    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh",
+    "test:ci": "npm run test:shellcheck && npm run test:bats && npm run test:schema && npm run lint:check",
+    "lint:check": "biome check . && markdownlint '**/*.md' --ignore node_modules --ignore CHANGELOG.md",
     "lint": "biome lint --write",
     "format": "biome format --write",
     "format:check": "biome format",

package/scripts/common.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Shared helpers for Onlooker hook scripts.
+# Requires validate-path.sh and onlooker-schema.sh.
+
+# Emit canonical tool.agent.spawn telemetry event (schema payload).
+# Usage: onlooker_emit_tool_agent_spawn SESSION_ID SUBAGENT_TYPE DESCRIPTION MODEL RUN_IN_BACKGROUND ISOLATION
+onlooker_emit_tool_agent_spawn() {
+	local session_id="$1"
+	local subagent_type="$2"
+	local description="$3"
+	local _model="$4"
+	local _run_in_background="$5"
+	local _isolation="$6"
+
+	local subagent_id="${session_id}-$(date +%s)"
+
+	local params
+	params=$(jq -n \
+		--arg plugin "${ONLOOKER_PLUGIN_NAME:-onlooker}" \
+		--arg sid "$session_id" \
+		--arg subagent_id "$subagent_id" \
+		--arg agent_name "$subagent_type" \
+		--arg task_summary "$description" \
+		'{
+			plugin: $plugin,
+			session_id: $sid,
+			event_type: "tool.agent.spawn",
+			payload: {
+				subagent_id: $subagent_id,
+				agent_name: $agent_name,
+				task_summary: $task_summary
+			}
+		}')
+
+	local event
+	event=$(printf '%s' "$params" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
+		node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/onlooker-event.mjs" emit 2>/dev/null) || return 1
+
+	onlooker_append_event "$event"
+}

package/scripts/hooks/agent-spawn-tracker.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# Onlooker Agent Spawn Tracker Script
+# Invoked by the PreToolUse hook (via command) when an Agent tool is used.
+#
+# Usage:
+#   echo "$INPUT" | agent-spawn-tracker.sh
+#
+# Input:
+#   {
+#     "session_id": "123",
+#     "tool_name": "Agent",
+#     "tool_input": {
+#       "agent_id": "456"
+#     }
+#   }
+
+set -uo pipefail # No -e: we must never exit non-zero and block the hook
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "${CLAUDE_PLUGIN_ROOT:-$SCRIPT_DIR/../..}/scripts/common.sh"
+
+hook_register "agent-spawn-tracker" "Agent Spawn Tracker" "Tracks when an agent is spawned"
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "Unknown"')
+
+hook_set_context "$INPUT" "PreToolUse"
+
+json_response() {
+	jq -n --arg decision "$1" --arg reason "$2" '{ "decision": $decision, "reason": $reason }'
+}
+
+# Only process Agent tool calls
+if [[ "$TOOL_NAME" != "Agent" ]]; then
+	json_response "approve" "Not an Agent tool call"
+	hook_success
+	exit 0
+fi
+
+# Extract agent parameters
+SUBAGENT_TYPE=$(jq -r '.tool_input.subagent_type // "general-purpose"' <<<"$INPUT")
+DESCRIPTION=$(jq -r '.tool_input.description // ""' <<<"$INPUT")
+RUN_IN_BACKGROUND=$(jq -r '.tool_input.run_in_background // false' <<<"$INPUT")
+ISOLATION=$(jq -r '.tool_input.isolation // "worktree"' <<<"$INPUT")
+MODEL=$(jq -r '.tool_input.model // "sonnet"' <<<"$INPUT")
+MAX_TURNS=$(jq -r '.tool_input.max_turns // 10' <<<"$INPUT")
+TOOLS=$(jq -r '.tool_input.tools // []' <<<"$INPUT")
+DISALLOWED_TOOLS=$(jq -r '.tool_input.disallowed_tools // []' <<<"$INPUT")
+SKILLS=$(jq -r '.tool_input.skills // []' <<<"$INPUT")
+MEMORY=$(jq -r '.tool_input.memory // false' <<<"$INPUT")
+BACKGROUND=$(jq -r '.tool_input.background // false' <<<"$INPUT")
+ISOLATION=$(jq -r '.tool_input.isolation // "worktree"' <<<"$INPUT")
+MODEL=$(jq -r '.tool_input.model // "sonnet"' <<<"$INPUT")
+MAX_TURNS=$(jq -r '.tool_input.max_turns // 10' <<<"$INPUT")
+TOOLS=$(jq -r '.tool_input.tools // []' <<<"$INPUT")
+DISALLOWED_TOOLS=$(jq -r '.tool_input.disallowed_tools // []' <<<"$INPUT")
+SKILLS=$(jq -r '.tool_input.skills // []' <<<"$INPUT")
+MEMORY=$(jq -r '.tool_input.memory // false' <<<"$INPUT")
+BACKGROUND=$(jq -r '.tool_input.background // false' <<<"$INPUT")
+
+# Track agent spawns in telemetry log
+STATE_FILE="$ONLOOKER_DIR/agent-spawn-trackers.json"
+LOCKFILE="$STATE_FILE.lock"
+
+# Use flock for exclusive access
+exec 200>"$LOCKFILE"
+flock -w 5 200 || {
+	json_response "deny" "Failed to acquire lock"
+	hook_failure
+	exit 0
+}
+
+# Load or initialize state
+if [[ -f "$STATE_FILE" ]]; then
+	STATE=$(jq '.' "$STATE_FILE" 2>/dev/null) || STATE='{}'
+else
+	STATE='{}'
+fi
+
+# Get Session ID for tracking
+SESSION_ID=$(jq -r '.session_id // "unknown"' <<<"$INPUT") || SESSION_ID="unknown"
+
+# Export turn state so envelope and payload include parent lineage
+turn_state_export "$SESSION_ID"
+
+# Initialize session tracking if needed
+STATE=$(jq --arg sid "$SESSION_ID" '
+	if .sessions[$sid] == null then
+		.sessions[$sid] = {
+			spawns: 0,
+			background_spawns: 0,
+			types: {},
+			first_spawn: now | strftime("%Y-%m-%dT%H:%M:%SZ"),
+			last_spawn: null
+		}
+	else .
+	end
+' <<<"$STATE")
+
+# Save state
+echo "$STATE" > "$STATE_FILE" 2>/dev/null || true
+
+# Release lock
+flock -u 200
+
+# Get current session stats
+SPAWN_COUNT=$(jq -r --arg sid "$SESSION_ID" '.sessions[$sid].spawns' <<<"$STATE")
+BG_SPAWN_COUNT=$(jq -r --arg sid "$SESSION_ID" '.sessions[$sid].background_spawns' <<<"$STATE")
+
+## Warn on potential issues
+WARNING=""
+
+# High spawn count warning
+if (( SPAWN_COUNT > 10 )); then
+  WARNING="Note: $SPAWN_COUNT agents spawned this session. Consider if tasks could be consolidated."
+fi
+
+# Many background agents warning (cumulative this session)
+if (( BG_SPAWN_COUNT > 5 )); then
+  WARNING="${WARNING:+$WARNING\n}Note: $BG_SPAWN_COUNT background agents spawned this session. Consider tracking completion."
+fi
+
+# Worktree isolation note (informational)
+if [[ "$ISOLATION" == "worktree" ]]; then
+  WARNING="${WARNING:+$WARNING\n}Info: Agent using worktree isolation - changes will be in separate branch."
+fi
+
+if [[ -n "$WARNING" ]]; then
+  json_response "approve" "$WARNING"
+else
+  json_response "approve" "Agent spawn tracked (#$SPAWN_COUNT: $SUBAGENT_TYPE)"
+fi
+
+PAYLOAD=$(jq -n \
+  --arg type "$SUBAGENT_TYPE" \
+  --arg desc "$DESCRIPTION" \
+  --argjson bg "$RUN_IN_BACKGROUND" \
+  --arg isolation "$ISOLATION" \
+  --arg model "$MODEL" \
+  --argjson spawn_num "$SPAWN_COUNT" \
+  --arg parent_sid "$SESSION_ID" \
+  --arg parent_turn "${ONLOOKER_TURN_NUMBER:-}" \
+  '{
+    subagent_type: $type,
+    description: $desc,
+    run_in_background: $bg,
+    isolation: $isolation,
+    model: $model,
+    session_spawn_number: $spawn_num,
+    parent_session_id: $parent_sid
+  }
+  + (if $parent_turn != "" then {parent_turn: ($parent_turn | tonumber)} else {} end)
+  ')
+
+# Canonical event: tool.agent.spawn (@onlooker-community/schema)
+onlooker_emit_tool_agent_spawn "$SESSION_ID" "$SUBAGENT_TYPE" "$DESCRIPTION" "$MODEL" "$RUN_IN_BACKGROUND" "$ISOLATION" 2>/dev/null && hook_success || hook_failure "Failed to emit tool.agent.spawn event"
+
+exit 0

package/scripts/hooks/tool-history-tracker.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Onlooker Tool History Tracker
+# Invoked by PostToolUse and PostToolUseFailure (matcher: *) after each tool call.
+#
+# Appends canonical OnlookerEvent records to:
+#   ~/.onlooker/session-history/<session_id>.jsonl  (per-session analysis)
+#   ~/.onlooker/logs/onlooker-events.jsonl           (global telemetry)
+#
+# Usage:
+#   echo "$INPUT" | tool-history-tracker.sh
+
+set -uo pipefail # No -e: never block or alter tool results
+
+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/tool-history.sh"
+
+hook_register "tool-history-tracker" "Tool History Tracker" "Records canonical tool events to session JSONL"
+
+INPUT=$(cat)
+
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "PostToolUse"')
+hook_set_context "$INPUT" "$HOOK_EVENT"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+turn_state_export "$SESSION_ID"
+
+RECORD=$(tool_history_build_record "$INPUT")
+if [[ -n "$RECORD" ]]; then
+	tool_history_append "$SESSION_ID" "$RECORD" || hook_failure "Failed to append session history"
+	onlooker_append_event "$RECORD" || hook_failure "Failed to append global event log"
+fi
+
+hook_success
+exit 0

package/scripts/hooks/tool-sequence-tracker.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Onlooker Tool Sequence Tracker
+# Invoked by PreToolUse (matcher: *) before every tool call.
+#
+# Increments turn_tool_seq in the session tracker so downstream hooks and
+# event emission can stamp tool_call_seq on the current turn.
+#
+# Usage:
+#   echo "$INPUT" | tool-sequence-tracker.sh
+
+set -uo pipefail # No -e: never block the tool call
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+
+hook_register "tool-sequence-tracker" "Tool Sequence Tracker" "Increments tool call sequence within the current turn"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "PreToolUse"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+
+json_response() {
+  jq -n --arg decision "$1" --arg reason "$2" '{ "decision": $decision, "reason": $reason }'
+}
+
+turn_state_next_tool "$SESSION_ID"
+turn_state_export "$SESSION_ID"
+
+json_response "approve" "Tool sequence #${ONLOOKER_TURN_TOOL_SEQ:-0} (turn ${ONLOOKER_TURN_NUMBER:-1})"
+hook_success
+exit 0

package/scripts/lib/onlooker-emit.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# onlooker-emit.sh - Legacy shim: emit canonical events via @onlooker-community/schema.
+#
+# Prefer onlooker_emit_from_hook / onlooker_append_event from onlooker-schema.sh.
+#
+# Usage:
+#   onlooker-emit.sh "tool.agent.spawn" '{"subagent_id":"x",...}'
+#
+# The first argument is treated as event_type; payload must match schema for that type.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=validate-path.sh
+source "$SCRIPT_DIR/validate-path.sh"
+# shellcheck source=onlooker-schema.sh
+source "$SCRIPT_DIR/onlooker-schema.sh"
+
+EVENT_TYPE="$1"
+PAYLOAD_JSON="$2"
+
+SESSION_ID="${_HOOK_SESSION_ID:-}"
+if [[ -z "$SESSION_ID" ]]; then
+	SESSION_ID=$(echo "$PAYLOAD_JSON" | jq -r '.session_id // "unknown"' 2>/dev/null) || SESSION_ID="unknown"
+fi
+
+PARAMS=$(jq -n \
+	--arg plugin "${ONLOOKER_PLUGIN_NAME:-onlooker}" \
+	--arg sid "$SESSION_ID" \
+	--arg type "$EVENT_TYPE" \
+	--argjson payload "$PAYLOAD_JSON" \
+	'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}')
+
+EVENT=$(printf '%s' "$PARAMS" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
+	node "$_ONLOOKER_EVENT_JS" emit 2>/dev/null) || {
+	hook_failure "Failed to build canonical event"
+	exit 0
+}
+
+onlooker_append_event "$EVENT"
+hook_success
+exit 0