feat(specialist): add lifecycle metadata

[anandh8x]

Summary:

• adds specialistStart/specialistStop hook events and parser coverage
• adds session tag/depth metadata for specialist child runs
• persists tag/depth through exec session preparation and child session lineage
• surfaces tag/depth in session snapshots and session list output

Scope:

• lifecycle/session groundwork only
• does not add Task runtime, background manager, or specialist execution yet
• independent of draft PR Runtime-core: multi-model tool tolerance, failure guard, rich TUI, subagents, plugins/skills #101

Tests:

• GOCACHE=/tmp/zero-go-cache go test ./internal/hooks ./internal/sessions ./internal/cli ./internal/zerocommands
• GOCACHE=/tmp/zero-go-cache go test ./...
• git diff --check

Summary by CodeRabbit

Release Notes

• New Features
  • Sessions now support Tag and Depth metadata, configurable via --tag and --depth command-line options.
  • Tag and depth fields now display in session list output.
  • Added new hook event types for specialist workflow lifecycle events.

[github-actions]

Zero automated PR review

Verdict: No blockers found

Blockers

• None found.

Validation

• [pass] Diff hygiene: git diff --check
• [pass] Tests: go test ./...
• [pass] Build: go run ./cmd/zero-release build
• [pass] Smoke build: go run ./cmd/zero-release smoke

Scope

Head: 92b35ed3dbdb
Changed files (12): internal/cli/exec.go, internal/cli/exec_test.go, internal/cli/sessions.go, internal/cli/sessions_test.go, internal/hooks/hooks.go, internal/hooks/hooks_test.go, internal/sessions/exec_session.go, internal/sessions/lineage.go, internal/sessions/store.go, internal/sessions/store_test.go, internal/zerocommands/contracts.go, internal/zerocommands/contracts_test.go

This deterministic review checks validation status and basic diff hygiene. A human reviewer still owns product judgment and design quality.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3796312e-b655-4459-a286-711d73006a73

📥 Commits

Reviewing files that changed from the base of the PR and between ae6c959 and 92b35ed.

📒 Files selected for processing (12)

• internal/cli/exec.go
• internal/cli/exec_test.go
• internal/cli/sessions.go
• internal/cli/sessions_test.go
• internal/hooks/hooks.go
• internal/hooks/hooks_test.go
• internal/sessions/exec_session.go
• internal/sessions/lineage.go
• internal/sessions/store.go
• internal/sessions/store_test.go
• internal/zerocommands/contracts.go
• internal/zerocommands/contracts_test.go

---

Walkthrough

This PR extends the session system to track specialist execution metadata via Tag (identifier string) and Depth (nesting level integer). The fields thread through session creation, CLI flags, lineage, hooks, and API contracts with matching test updates throughout.

Changes

Specialist Metadata (Tag and Depth) Support

Layer / File(s)	Summary
Session metadata schema and validation internal/sessions/store.go, internal/sessions/store_test.go	Metadata, CreateInput, and ChildInput now include Tag and Depth fields. Store.Create validates that Depth is non-negative, trims whitespace from Tag, and persists both into session records.
Session creation and child lineage internal/sessions/exec_session.go, internal/sessions/lineage.go	PrepareExecOptions carries Tag and Depth through to PrepareExec, which passes them to session creation. Child sessions receive and propagate the metadata; lineage events include tag and depth in parent–child linking payloads.
Hook system events for specialists internal/hooks/hooks.go, internal/hooks/hooks_test.go	New EventSpecialistStart and EventSpecialistStop constants; eventSupportsMatcher helper restricts matcher validation to tool-related events; parseEvent recognizes specialist events and updates error messages.
CLI flags and session display internal/cli/exec.go, internal/cli/sessions.go, internal/cli/exec_test.go, internal/cli/sessions_test.go	--tag and --depth flags flow from CLI into PrepareExecOptions; formatSessionSnapshotLine conditionally renders tag=<value> in session list output when Tag is non-empty.
API contract and snapshot serialization internal/zerocommands/contracts.go, internal/zerocommands/contracts_test.go	SessionSnapshot adds optional JSON fields Tag and Depth; SessionSnapshotFromMetadata populates them from persisted session metadata for API responses.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Gitlawb/zero#104: Introduces specialist execution metadata (--tag and --depth flags) that flow through internal/cli/exec.go session preparation into the data model.
• Gitlawb/zero#68: Builds on session lineage backend (CreateChild, childLinkPayload) to propagate new metadata fields through child session creation and lineage events.

Suggested reviewers

• gnanam1990
• Vasanthdev2004

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(specialist): add lifecycle metadata' directly and accurately summarizes the main change: adding lifecycle-related metadata (tag and depth) for specialist sessions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/specialist-hook-events

---

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

[gnanam1990]

Review — clean, approving

Tidy, well-scoped metadata groundwork, and nicely tested. Highlights:

• Hooks: specialistStart/specialistStop events added consistently — parseEvent accepts them with an updated error message, and the matcher check is refactored to a positive eventSupportsMatcher (beforeTool/afterTool only) so the new lifecycle events correctly reject matchers too. Covered by TestLoadConfigRejectsMatchersOnLifecycleHooks + TestSpecialistHookEventsLoadAndSelect.
• Sessions: Tag/Depth flow through Metadata / CreateInput / ChildInput, and CreateChild routes through Create(), so the Depth < 0 guard and Tag trimming apply to child sessions too (verified). omitempty keeps existing JSON stable. Covered by TestStoreRejectsNegativeSessionDepth + TestPrepareExecPersistsSpecialistMetadataForNewSession.
• CLI/contracts: tag/depth surfaced in zero sessions output and the SessionSnapshot contract.

go build/vet/go test ./... all green. Approving.

Non-blocking notes

1. depth semantics coordination (continuing the thread from #104): depth now spans exec flags (#104), agent.Options.Depth (#104), and session Metadata.Depth (here). Worth making sure they all carry the same "specialist nesting level" meaning and converge cleanly with the upcoming task-runtime depth — so a child run's session depth == its agent nesting depth.
2. childLinkPayload calls strings.TrimSpace(input.Tag) while Create() also trims Tag for the stored metadata — harmless redundancy, just noting.
3. As stated in the PR, Tag/Depth are persisted/surfaced but not yet consumed by any runtime — fine as groundwork; flagging so it's a conscious staging step.

Nice incremental slice. 👍

_{🤖 Verified review via Claude Code.}