Release Claude lifecycle hooks 0.3.4

.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/TerminallyLazy"
   },
   "description": "Claude Code marketplace for Tree Ring Memory v0.15 verified bootstrap, local-first recall, and receipt-backed harness readiness.",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "plugins": [
     {
       "name": "tree-ring-memory",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tree-ring-memory",
   "displayName": "Tree Ring Memory",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Local-first memory lifecycle, project bootstrap, and receipt-backed harness guidance for Claude Code using Tree Ring Memory v0.15+.",
   "author": {
     "name": "TerminallyLazy",
@@ -22,5 +22,6 @@
     "sqlite",
     "skills"
   ],
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "hooks": "./hooks/claude-hooks.json"
 }

.github/workflows/validate.yml

@@ -10,8 +10,8 @@ permissions:
   contents: read
 
 env:
-  TREE_RING_VERSION: "0.15.0"
-  TREE_RING_LINUX_X86_64_SHA256: "9b47873268dbb94712a49b02bd785cc69507facee1e879e46e6922778b4afbe6"
+  TREE_RING_VERSION: "0.15.7"
+  TREE_RING_LINUX_X86_64_SHA256: "5c9da887e212b1a7222205d2a661910276171a927d7677f09ec097f2cddd26b7"
 
 jobs:
   validate:
@@ -56,7 +56,9 @@ jobs:
           printf 'TREE_RING_BIN=%s\n' "${binary_path}" >> "${GITHUB_ENV}"
 
       - name: Validate plugin guidance
-        run: python3 scripts/validate.py
+        run: |
+          python3 scripts/validate.py
+          python3 scripts/validate-lifecycle.py
 
       - name: Validate with Claude Code 2.1.241
         run: |

PRIVACY.md

@@ -2,22 +2,40 @@
 
 Effective August 23, 2026
 
-The Tree Ring Memory Claude Code plugin is an instruction package. It does not
-operate a hosted service, create a user account, collect analytics, send
-telemetry, install hooks, or include a remote MCP server.
+The Tree Ring Memory repository plugin packages instructions and local
+lifecycle-hook registrations for AI coding agents. It does not operate a hosted
+service, create a user account, collect analytics, send telemetry, or include a
+remote MCP server.
 
-When Claude Code runs the separately installed Tree Ring Memory CLI, the CLI
-stores the memory content the user chooses in a local SQLite database under the
-configured Tree Ring root. The project does not receive that database or its
-contents. Data leaves the local environment only when the user or another tool
-explicitly exports, syncs, publishes, or otherwise transmits it.
+The repository hooks run only when a session or subagent starts or stops. They
+forward the host's lifecycle JSON through standard input to the separately
+installed Tree Ring Memory CLI and wait synchronously for at most 10 seconds.
+They do not register for user prompts, tool calls, or `SessionEnd`; persist hook
+input; capture prompts or transcripts; or run in the background. The lifecycle
+parser never inspects or persists `transcript_path`, `last_assistant_message`,
+prompts, or transcript content.
+
+Each stop event enforces one agent-mediated memory checkpoint. It asks the
+active agent to evaluate already-grounded work rather than deriving a summary
+from hook input. Only a concise, durable candidate classified as normal
+sensitivity may be written automatically with strict `tree-ring capture`.
+That command fixes agent scope, requires identity and provenance, tags the
+memory as automatic capture, and rejects sensitive content. If no candidate
+passes, no durable memory is created.
+
+When an agent runs an explicit command in the separately installed Tree Ring
+Memory CLI, including an identity-bound strict capture approved by the
+checkpoint gates, the CLI stores accepted memory content in a local SQLite
+database under the configured Tree Ring root. The project does not receive that
+database or its contents. Data leaves the local environment only when the user
+or another tool explicitly exports, syncs, publishes, or otherwise transmits it.
 
 The plugin instructs agents to avoid transcripts, credentials, secrets, private
 keys, raw chain-of-thought, and unnecessary sensitive personal data. It also
 provides explicit redaction, deletion, supersession, audit, and consolidation
-workflows. These safeguards do not replace the privacy and data-use terms of
-Claude Code, the operating system, source-control provider, or another tool the
-user chooses to invoke.
+workflows. These safeguards do not replace the privacy and data-use terms of the
+AI host, operating system, source-control provider, or any other tool the user
+chooses to invoke.
 
 Support and privacy questions may be filed at
 <https://github.com/TerminallyLazy/Tree-Ring-Memory/issues>.

README.md

@@ -8,9 +8,10 @@ that teach agents when to recall, write, audit, consolidate, and forget project
 memory using the open-source
 [Tree Ring Memory](https://github.com/TerminallyLazy/Tree-Ring-Memory) CLI.
 
-It does not run a background service, scrape chats, capture transcripts, install
-hooks, or ship a networked MCP server. The active agent chooses when a memory
-action is useful, source-linked, and privacy-safe.
+The plugin registers native startup recall and bounded stop checkpoints.
+Automatic lifecycle hooks require CLI `0.15.6` or newer. It does not run a
+background service, scrape chats, capture transcripts, or ship a networked MCP
+server. The active agent evaluates durable outcomes before any capture.
 
 ## What It Adds
 
@@ -153,3 +154,60 @@ memory, logs, source references, and ordinary worker environments.
 
 See [PRIVACY.md](PRIVACY.md), [TERMS.md](TERMS.md), and
 [SECURITY.md](SECURITY.md) for data handling, use terms, and disclosures.
+
+## Automatic Lifecycle Hooks
+
+The repository plugin registers exactly `SessionStart`, `SubagentStart`,
+`Stop`, and `SubagentStop`. Each hook forwards its event JSON directly to the
+local CLI and waits synchronously for at most 10 seconds. It does not register
+prompt, tool, compaction, or `SessionEnd` hooks; run a background service;
+scrape chats; or ship an MCP server.
+
+Session start covers startup, resume, and compaction rehydration when the host
+reports those sources. Subagent start gives each worker an independent,
+receipt-backed preflight. Codex requires review and trust of the installed hook
+definition before it runs. Claude Code loads the hook with the enabled plugin.
+
+Startup recall loads a bounded brief of shared project guidance and this
+agent's durable memories, including captures from earlier sessions. Workflow
+and session memories remain limited to their matching scope. It does not
+depend on memories containing special startup keywords. Use targeted recall
+when the task changes; the startup brief is not an exhaustive search.
+
+Stop and subagent-stop enforce one agent-mediated memory checkpoint. The
+lifecycle parser uses only stable harness identity and project fields; it never
+inspects or persists `transcript_path`, `last_assistant_message`, prompts, or
+transcript content. The checkpoint asks the active agent to evaluate its
+already-grounded work. If and only if that evaluation yields a concise,
+durable, normal-sensitivity candidate, the agent automatically runs the exact
+strict `tree-ring capture` command template returned by the lifecycle handler.
+Strict capture fixes agent scope, requires identity and provenance, adds an
+automatic-capture tag, and rejects sensitive candidates. No candidate means no
+memory write. This is one bounded checkpoint, not a recorder or automatic
+summary of every turn.
+
+The hook wrapper resolves the Git project root when available, prefers that
+project's `.tree-ring/bin/tree-ring`, and otherwise uses `tree-ring` from
+`PATH`. It then invokes the shared lifecycle entry point with the project-local
+`.tree-ring` root. An unavailable or incompatible CLI is not active-harness
+proof and cannot be reported as a successful checkpoint or capture.
+
+When project activation has already installed the managed lifecycle definition
+in `.codex/hooks.json` or `.claude/settings.json`, that project definition owns
+recall and stop checkpoints. The marketplace wrapper detects the exact managed
+marker and exits without invoking the CLI, preventing duplicate context,
+receipts, checkpoint continuations, or capture attempts when the host merges
+project and plugin hooks.
+
+`integrations status --verbose` reports the last validated recall's result
+count and query class. A zero-result receipt proves the check ran; it does not
+prove that useful context was found. A skills-only plugin installation has no
+automatic lifecycle hooks; enable the repository plugin or configure the
+project with the CLI to obtain them. A newly configured Codex hook still needs
+the host's trust flow and a new session before automatic execution can be
+verified.
+
+Installer onboarding requires CLI 0.15.7 or newer to create the activation
+manifest and native project hooks in the same install action. On earlier 0.15
+CLIs, run `tree-ring init` explicitly after the installer. Onboarding readiness
+is configuration; a fresh host receipt is required to prove automatic recall.

SECURITY.md

@@ -1,26 +1,48 @@
 # Security Policy
 
-Tree Ring Memory Claude Code Plugin is an instructions-only wrapper around the
-open-source Tree Ring Memory CLI.
+## Supported Versions
 
-## What This Plugin Does Not Do
+The `main` branch is the supported version of this agent plugin package.
 
-- It does not run background services.
-- It does not define Claude Code hooks.
-- It does not ship a networked MCP server.
-- It does not collect analytics.
-- It does not ask for credentials, tokens, or API keys.
-- It does not store raw chat transcripts.
+The Tree Ring Memory framework and CLI are maintained in the canonical
+repository:
 
-## Privacy Guidance
+<https://github.com/TerminallyLazy/Tree-Ring-Memory>
 
-Only store concise, useful memory. Do not store secrets, credentials, tokens,
-private keys, raw chain-of-thought, temporary scratchpad notes, unverified claims
-as durable truth, or private health, financial, legal, or personal identifier
-details without explicit user instruction.
+## Reporting A Vulnerability
+
+Report vulnerabilities privately through the canonical repository's GitHub
+security advisory form:
+
+<https://github.com/TerminallyLazy/Tree-Ring-Memory/security/advisories/new>
+
+Use the canonical issue tracker only for non-sensitive support:
+
+<https://github.com/TerminallyLazy/Tree-Ring-Memory/issues>
+
+Never include vulnerability details, secrets, tokens, private memory contents,
+or personal data in a public issue.
+
+## Data Handling
+
+This wrapper plugin contains guidance files and bounded local lifecycle-hook
+registrations. It does not run a background service, include remote MCP
+servers, collect telemetry, or store credentials. The hooks run only at
+`SessionStart`, `SubagentStart`, `Stop`, and `SubagentStop`, forward standard
+input directly to the local Tree Ring CLI, and do not persist prompts,
+transcripts, `last_assistant_message`, or hook input. They are synchronous,
+bounded to 10 seconds, and never run as a `SessionEnd` or background recorder.
 
-Use `tree-ring audit`, `tree-ring forget`, redaction, and supersession when
-memory is wrong, sensitive, stale, or replaced by newer evidence.
+Stop hooks enforce one agent-mediated checkpoint. They may supply an exact
+strict `tree-ring capture` template only for concise durable candidates. Strict
+capture fixes agent scope, requires harness identity and provenance, accepts
+only normal sensitivity, and tags the result as automatic capture. A missing,
+sensitive, ambiguous, or ungrounded candidate must not be stored.
+
+Tree Ring Memory is designed for explicit agent-mediated memory actions. Store
+only concise decisions, lessons, warnings, and evidence references that are
+useful, source-linked, and privacy-safe. Do not store raw transcripts, secrets,
+private keys, tokens, or raw chain-of-thought.
 
 ## Coordinated Mode
 
@@ -41,16 +63,3 @@ Tree Ring Memory v0.15 reports harness readiness from project-local
 configuration plus privacy-safe preflight receipts. Configuration alone is not
 activation. The plugin does not manufacture receipts, alter global trust, or
 hand-author Agent Zero activation capability descriptors.
-
-## Reporting A Vulnerability
-
-Open a private vulnerability report on the canonical framework repository:
-
-<https://github.com/TerminallyLazy/Tree-Ring-Memory/security/advisories/new>
-
-Use the canonical issue tracker only for non-sensitive support:
-
-<https://github.com/TerminallyLazy/Tree-Ring-Memory/issues>
-
-Never include vulnerability details, secrets, tokens, private memory contents,
-or personal data in a public issue.

SUBMISSION.md

@@ -5,7 +5,7 @@
 - Name: Tree Ring Memory
 - Plugin identifier: `tree-ring-memory`
 - Source: <https://github.com/TerminallyLazy/tree-ring-memory-claude-plugin>
-- Release: `v0.3.2`
+- Release: `v0.3.4`
 - Category: Developer Tools / Workflow Orchestration
 - License: MIT
 - Homepage: <https://terminallylazy.github.io/Tree-Ring-Memory/>
@@ -24,7 +24,8 @@ Description:
 - One provider-neutral Tree Ring Memory skill.
 - Slash commands for recall, capture, read-only audit, and receipt-backed
   harness status.
-- No hooks, remote MCP server, background service, analytics, credentials, or
+- Native SessionStart, SubagentStart, Stop, and SubagentStop hooks; CLI >=0.15.6.
+- No remote MCP server, background service, analytics, credentials, or
   installation-time scripts.
 
 ## Validation
@@ -34,6 +35,7 @@ claude plugin validate . --strict
 claude plugin validate .claude-plugin/plugin.json --strict
 claude plugin validate .claude-plugin/marketplace.json --strict
 python3 scripts/validate.py
+python3 scripts/validate-lifecycle.py
 bash scripts/smoke_v015.sh
 ```
 

TERMS.md

@@ -2,16 +2,16 @@
 
 Effective August 23, 2026
 
-The Tree Ring Memory Claude Code plugin is open-source software distributed
-under the MIT License. By using it, you agree to the license and these
-operational terms.
+The Tree Ring Memory plugin is open-source software distributed under the MIT
+License. By using it, you agree to the license and these operational terms.
 
-The plugin provides agent instructions only. It is not a hosted memory service,
-backup service, access-control system, medical or legal record system, or
-guarantee that an AI host will follow every instruction. The user is responsible
-for choosing what to store, maintaining backups, controlling local filesystem
-access, reviewing agent actions, and complying with applicable policies and
-law.
+The repository plugin provides agent instructions and local lifecycle-hook
+registrations. The separate OpenAI upload artifact is skills-only. Neither is a
+hosted memory service, backup service, access-control system, medical or legal
+record system, or guarantee that an AI host will follow every instruction. The
+user is responsible for choosing what to store, maintaining backups, controlling
+local filesystem access, reviewing agent actions and hook trust, and complying
+with applicable policies and law.
 
 Tree Ring Memory is provided without warranty, including warranties of fitness,
 availability, accuracy, non-infringement, or data durability, to the maximum

commands/tree-ring-capture.md

@@ -9,6 +9,43 @@ allowed-tools: ["Bash"]
 Capture only durable, useful memory. Do not store transcripts, secrets,
 credentials, raw chain-of-thought, or unverified claims as truth.
 
+## Lifecycle Stop Checkpoint
+
+`Stop` and `SubagentStop` hooks enforce one agent-mediated checkpoint. The hook
+never inspects or persists `transcript_path`, `last_assistant_message`, prompts,
+or transcript content. Evaluate the grounded work already in the active agent's
+context. If there is no durable, normal-sensitivity candidate, do not write a
+memory.
+
+For each qualifying candidate, use the exact identity-bound template returned
+by the lifecycle handler. Its strict shape is:
+
+```bash
+tree-ring --root .tree-ring capture "<concise summary>" \
+  --event-type <preference|decision|lesson|warning|correction|seed> \
+  --ring <cambium|scar|seed> \
+  --project <project> \
+  --agent-profile <profile> \
+  --workflow-id <workflow> \
+  --session-id <session> \
+  --operation-id auto-<checkpoint>-<1..3> \
+  --source-ref agent-checkpoint:<checkpoint> \
+  [--tag <tag>]
+```
+
+Do not invent or edit the supplied identity, checkpoint, operation, or source
+values. Strict capture fixes `scope=agent`, requires identity and provenance,
+adds the automatic-capture tag, and accepts normal sensitivity only. Use no more
+than three candidates in the single checkpoint. Never replace this with a raw
+transcript summary, `remember`, `evidence`, or an import.
+
+Use `cambium` for preferences, decisions, lessons, and corrections; `scar` for
+warnings; and `seed` for future work. A candidate still must be durable and
+grounded regardless of its ring.
+
+The manual command flow below remains available for an explicit user-directed
+capture outside a lifecycle checkpoint.
+
 Read project-local `.tree-ring/SKILL.md` and `.tree-ring/CLI.md` first when
 present. Follow the skill's Runtime Bootstrap And Updates procedure and confirm
 the selected project-local or global binary reports 0.15.0 or newer. Bootstrap

hooks/claude-hook.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+set -eu
+
+if command -v git >/dev/null 2>&1; then
+    project_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+    if [ -n "$project_root" ]; then
+        cd "$project_root"
+    fi
+fi
+
+# Project activation owns lifecycle recall and checkpoints when its managed hook
+# is present. The marketplace hook stands down to prevent duplicate handling.
+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
+fi
+
+tree_ring=tree-ring
+if [ -x .tree-ring/bin/tree-ring ]; then
+    tree_ring=.tree-ring/bin/tree-ring
+fi
+
+exec "$tree_ring" --root .tree-ring integrations hook --harness claude-code --input-json-stdin