Release Claude lifecycle hooks 0.3.4

[TerminallyLazy]

Ship Claude plugin 0.3.4 with native SessionStart/SubagentStart recall and Stop/SubagentStop capture checkpoints. These hooks use CLI 0.15.7 to recall project guidance and the agent's durable memories across sessions, and resolve the project-local runtime from nested working directories. Managed project hooks take precedence to prevent duplicate checkpoints.

Update the marketplace version, shared skill, privacy disclosures, and submission materials. CI uses the checksum-pinned 0.15.7 release.

Validation: package contract, all lifecycle event forwarders, duplicate suppression, and real CLI smoke pass. Claude Code 2.1.241 strict manifest validation passes.

High-level PR Summary

This PR ships version 0.3.4 of the Tree Ring Memory Claude Code plugin, introducing native lifecycle hooks for automatic session startup context recall and bounded stop-event memory checkpoints. The plugin now registers SessionStart, SubagentStart, Stop, and SubagentStop hooks that forward events to the Tree Ring Memory CLI (version 0.15.7), which handles project guidance recall and agent-mediated memory capture. The hooks implement duplicate suppression to prevent conflicts when project-level managed hooks are already installed. All documentation, validation scripts, privacy disclosures, security policies, and submission materials have been updated to reflect the new lifecycle integration pattern and clarify that hooks never persist transcripts or sensitive content directly.

⏱️ Estimated Review Time: 30-90 minutes

💡 Review Order Suggestion

Order	File Path
1	README.md
2	.claude-plugin/plugin.json
3	.claude-plugin/marketplace.json
4	SUBMISSION.md
5	hooks/claude-hooks.json
6	hooks/claude-hook.sh
7	commands/tree-ring-capture.md
8	skills/tree-ring-memory/SKILL.md
9	PRIVACY.md
10	SECURITY.md
11	TERMS.md
12	scripts/validate-lifecycle.py
13	scripts/validate.py
14	scripts/smoke_v015.sh
15	.github/workflows/validate.yml

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ef6c8ab3-50c5-40d5-8015-4d51469bfcdc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Release Claude lifecycle hooks in plugin 0.3.4

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Add native start recall and stop checkpoints through the local Tree Ring CLI.
• Suppress plugin hooks when managed project lifecycle ownership is detected.
• Release 0.3.4 with pinned CLI validation and expanded privacy guidance.

Diagram

graph TD
  A["Lifecycle Events"] --> B["Hook Manifest"] --> C["Hook Wrapper"] --> D{"Managed Hook?"}
  D -->|Yes| E["Exit Quietly"]
  D -->|No| F["Resolve CLI"] --> G["CLI Hook Handler"] --> H["Recall or Checkpoint"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use project-managed hooks only

• ➕ Guarantees a single lifecycle owner without runtime marker detection.
• ➕ Keeps marketplace installations instructions-only.
• ➖ Plugin-only users receive no automatic recall or stop checkpoints.
• ➖ Requires explicit project activation and host trust before lifecycle behavior works.

2. Implement lifecycle parsing in plugin scripts

• ➕ Could reduce dependence on newer CLI lifecycle commands.
• ➕ Allows plugin-specific behavior without CLI delegation.
• ➖ Duplicates identity, privacy, capture, and receipt logic from the CLI.
• ➖ Expands the plugin security boundary and increases behavior drift across integrations.

Recommendation: Keep the PR’s thin wrapper and shared CLI lifecycle handler. It provides native plugin behavior while centralizing privacy-sensitive parsing and capture policy in the CLI; exact managed-hook marker suppression is a reasonable compatibility mechanism for avoiding duplicate execution.

Files changed (15) +456 / -70

Enhancement (4) +123 / -2

plugin.jsonRegister lifecycle hooks in plugin 0.3.4 +3/-2

Register lifecycle hooks in plugin 0.3.4

• Bumps the plugin version and declares the packaged Claude hook manifest.

.claude-plugin/plugin.json

tree-ring-capture.mdAdd strict lifecycle checkpoint capture guidance +37/-0

Add strict lifecycle checkpoint capture guidance

• Defines candidate eligibility, identity-bound capture arguments, a three-candidate limit, ring selection, and prohibited transcript-derived alternatives.

commands/tree-ring-capture.md

claude-hook.shAdd project-aware Claude lifecycle wrapper +26/-0

Add project-aware Claude lifecycle wrapper

• Resolves the Git root, suppresses execution for managed lifecycle versions 2–4, prefers the project-local CLI, and forwards stdin to the Claude integration handler.

hooks/claude-hook.sh

claude-hooks.jsonRegister four bounded Claude lifecycle events +57/-0

Register four bounded Claude lifecycle events

• Adds synchronous ten-second handlers for session and subagent start and stop events, all delegated through the shared wrapper.

hooks/claude-hooks.json

Tests (3) +157 / -6

smoke_v015.shRun smoke validation against CLI 0.15.7 +1/-1

Run smoke validation against CLI 0.15.7

• Updates the expected CLI version used by the existing integration smoke test.

scripts/smoke_v015.sh

validate-lifecycle.pyAdd lifecycle package contract validation +151/-0

Add lifecycle package contract validation

• Verifies exact event registration, bounded synchronous handlers, project-local runtime selection, byte-for-byte stdin forwarding, CLI output forwarding, and managed-hook duplicate suppression.

scripts/validate-lifecycle.py

validate.pyAlign release validation with plugin and CLI versions +5/-5

Align release validation with plugin and CLI versions

• Updates expected wrapper, submission, workflow checksum, and smoke-test markers for plugin 0.3.4 and CLI 0.15.7.

scripts/validate.py

Documentation (6) +170 / -58

PRIVACY.mdDisclose lifecycle hook data handling and capture boundaries +29/-11

Disclose lifecycle hook data handling and capture boundaries

• Documents synchronous event forwarding, excluded transcript fields, strict capture gates, local SQLite storage, and the absence of background collection.

PRIVACY.md

README.mdDocument automatic recall and stop checkpoints +61/-3

Document automatic recall and stop checkpoints

• Explains registered events, runtime resolution, managed-hook precedence, receipt semantics, privacy boundaries, and CLI onboarding requirements.

README.md

SECURITY.mdDefine hook security boundaries and vulnerability reporting +38/-29

Define hook security boundaries and vulnerability reporting

• Reorganizes supported-version and reporting guidance while documenting bounded execution, excluded data, and strict automatic-capture requirements.

SECURITY.md

SUBMISSION.mdUpdate marketplace submission for release 0.3.4 +4/-2

Update marketplace submission for release 0.3.4

• Advertises the four native lifecycle hooks and adds lifecycle validation to the release verification commands.

SUBMISSION.md

TERMS.mdExtend operational terms to lifecycle hooks +9/-9

Extend operational terms to lifecycle hooks

• Clarifies differences between the repository plugin and skills-only artifact and assigns responsibility for reviewing hook trust and local storage.

TERMS.md

SKILL.mdTeach agents lifecycle recall and checkpoint behavior +29/-4

Teach agents lifecycle recall and checkpoint behavior

• Adds CLI compatibility guidance, receipt interpretation, stop-checkpoint eligibility, strict capture requirements, and privacy constraints to the shared skill.

skills/tree-ring-memory/SKILL.md

Other (2) +6 / -4

marketplace.jsonBump marketplace package to version 0.3.4 +1/-1

Bump marketplace package to version 0.3.4

• Updates the marketplace release metadata for the lifecycle-hook release.

.claude-plugin/marketplace.json

validate.ymlValidate lifecycle hooks against pinned CLI 0.15.7 +5/-3

Validate lifecycle hooks against pinned CLI 0.15.7

• Updates the checksum-pinned Tree Ring CLI release and runs the new lifecycle package validator before strict Claude manifest validation.

.github/workflows/validate.yml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. CI validation never starts ✓ Resolved 🐞 Bug ≡ Correctness

Description

load_json annotates its return type with Any, but scripts/validate-lifecycle.py neither
imports that name nor postpones annotation evaluation, causing module initialization to fail when
annotations are evaluated eagerly. The required python3 scripts/validate-lifecycle.py workflow
command reaches this failure before any lifecycle package checks execute.

Code

scripts/validate-lifecycle.py[8]

+def load_json(path: Path) -> dict[str, Any]:

Evidence

The script imports only json, os, subprocess, tempfile, and Path, while line 8 uses the
otherwise undefined Any in dict[str, Any] without a future-annotations import. Because the
validation workflow directly invokes this new script as a required command, the annotation is
evaluated during function definition and prevents the lifecycle checks from starting on Python
versions that eagerly evaluate annotations.

scripts/validate-lifecycle.py[3-8]
.github/workflows/validate.yml[58-61]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description

`validate-lifecycle.py` references `Any` in a runtime-evaluated function annotation without defining or importing it, causing the script to fail during module initialization on Python versions that eagerly evaluate annotations.

## Issue Context

CI invokes this script directly as part of the required plugin lifecycle validation, so the initialization failure prevents all lifecycle package checks from running. Import `Any` from `typing`, replace the annotation with a type that requires no missing import, or otherwise ensure annotations are not eagerly evaluated.

## Fix Focus Areas

- scripts/validate-lifecycle.py[3-8]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Some projects lose automatic recall 🐞 Bug ☼ Reliability

Description

claude-hook.sh treats any occurrence of a managed-lifecycle description substring anywhere in
.claude/settings.json as proof that a managed hook is installed and exits before invoking the CLI.
A project with that text in an unrelated setting but no managed lifecycle definition therefore loses
all four marketplace lifecycle events, despite the documented ownership rule applying only after
project activation installs that definition.

Code

hooks/claude-hook.sh[R13-18]

+if [ -f .claude/settings.json ] && {
+    grep -Fq 'Tree Ring Memory managed lifecycle v2"' .claude/settings.json ||
+        grep -Fq 'Tree Ring Memory managed lifecycle v3"' .claude/settings.json ||
+        grep -Fq 'Tree Ring Memory managed lifecycle v4"' .claude/settings.json
+}; then
+    exit 0

Evidence

The wrapper checks only file existence and marker text, then exits before the CLI invocation; it
does not parse the JSON or verify a hook registration. The documented behavior explicitly limits
this bypass to projects where activation installed the managed lifecycle definition.

hooks/claude-hook.sh[13-26]
README.md[195-200]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The duplicate-suppression check uses an unscoped text search over the whole Claude settings file, so unrelated data containing the marker disables the marketplace hook.

## Issue Context
Suppression should occur only when a project-managed lifecycle hook is actually installed, not when the marker appears in arbitrary settings content.

## Fix Focus Areas
- hooks/claude-hook.sh[13-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: 🧠 Deep: This release introduces security- and privacy-sensitive lifecycle hook behavior across multiple independent paths, including CLI resolution, stdin forwarding, duplicate suppression, manifests, and CI validation, making independent review passes materially valuable.

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

2. Some projects lose automatic recall 🐞 Bug ☼ Reliability

claude-hook.sh treats any occurrence of a managed-lifecycle description substring anywhere in
.claude/settings.json as proof that a managed hook is installed and exits before invoking the CLI.
A project with that text in an unrelated setting but no managed lifecycle definition therefore loses
all four marketplace lifecycle events, despite the documented ownership rule applying only after
project activation installs that definition.

Agent Prompt

## Issue description
The duplicate-suppression check uses an unscoped text search over the whole Claude settings file, so unrelated data containing the marker disables the marketplace hook.

## Issue Context
Suppression should occur only when a project-managed lifecycle hook is actually installed, not when the marker appears in arbitrary settings content.

## Fix Focus Areas
- hooks/claude-hook.sh[13-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools