docs: align Claude hook redesign plan

Author: ScriptedAlchemy

docs/plans/tracedecay-v2/00-plan-set-index.md

@@ -39,7 +39,7 @@ Core product surfaces:
 | [`11-dashboard-frontend.md`](11-dashboard-frontend.md) | Concept-led Evidence Cartography product; stable profile atlas, linked Atlas/Trace/Compare/Lab/Triage compositions, complete memory/skill/automation navigation in Brain and Explorer, Loom replay player, composable lenses, hermetic experiment cockpit, visual ontology/renderers/charts, accessibility/mobile/export, perceptual and comprehension gates. |
 | [`12-root-compatibility-migration.md`](12-root-compatibility-migration.md) | Root binary/daemon/CLI/MCP composition and deployment/probe/config/service effect adapters; application-owned integration lifecycle execution; V1 data migration, cutover/rollback/retirement. |
 | [`13-research-provenance-and-context-anchors.md`](13-research-provenance-and-context-anchors.md) | Research manifest, durable retrieval anchors, subagent context, corpus hashes/cutoff, source recovery, future implementation handoff. |
-| [`14-historical-failure-regression-matrix.md`](14-historical-failure-regression-matrix.md) | Historical problem -> prevention owner -> visible detection/recovery -> cutover regression gate; 148 stable rows (`FM-001` through `FM-148`) with no gaps. |
+| [`14-historical-failure-regression-matrix.md`](14-historical-failure-regression-matrix.md) | Historical problem -> prevention owner -> visible detection/recovery -> cutover regression gate; 150 stable rows (`FM-001` through `FM-150`) with no gaps. |
 | [`15-search-quality-evaluation-and-retrieval-research.md`](15-search-quality-evaluation-and-retrieval-research.md) | Real local precision corpus, primary retrieval research, hybrid pipeline, qrels/metrics/holdouts, shadow/online evaluation, Search Quality Lab. |
 | [`16-cross-project-repository-worktree-scope.md`](16-cross-project-repository-worktree-scope.md) | Exceptional multi-repo/project/worktree/ref/store behavior, `ScopeSelectorV2`, routed retrieval, graph federation, CLI/MCP UX, Rspack/Rsbuild/React Router corpus. |
 | [`17-official-public-api-and-sdks.md`](17-official-public-api-and-sdks.md) | Official direct-agent/public API, contract IR/OpenAPI/JSON Schema, stable IDs/errors/cursors/batch/SSE, Rust/TS/Python SDKs, docs/sandbox/conformance. |

docs/plans/tracedecay-v2/01-domain-crate.md

@@ -481,9 +481,9 @@ pub struct HostCapabilitySnapshotV1 {
     pub fresh_until: UtcMicros,
     pub snapshot_digest: ManifestDigest, // canonical subject/capabilities/times only; excludes this field
 }
-pub enum HookInvocationScopeV1 { ThreadStart, SubagentStart, Turn }
-pub enum HookDefinitionRepresentationV1 { JsonFile, InlineToml, PluginDefaultFile, PluginManifestPath, PluginManifestPathArray, PluginManifestInline, PluginManifestInlineArray, ManagedInline }
-pub enum HostConfigLayerV1 { System, Cloud, Mdm, ManagedRequirements, User, Project, Session, Plugin }
+pub enum HookInvocationScopeV1 { SessionLifecycle, Setup, Turn, ToolCall, ToolBatch, SubagentLifecycle, TaskLifecycle, TeamLifecycle, WorktreeLifecycle, ComponentLifecycle, Elicitation, AsyncObservation, DisplayStream }
+pub enum HookDefinitionRepresentationV1 { JsonFile, JsonSettings, InlineToml, PluginDefaultFile, PluginManifestPath, PluginManifestPathArray, PluginManifestInline, PluginManifestInlineArray, SkillFrontmatter, AgentFrontmatter, ManagedInline, SessionMemory, BuiltIn }
+pub enum HostConfigLayerV1 { System, Cloud, Mdm, ManagedRequirements, ManagedPolicy, User, Project, Local, Session, Plugin, Skill, Agent, BuiltIn }
 pub struct HostConfigSourceV1 {
     pub source_id: EntityId,
     pub layer: HostConfigLayerV1,
@@ -512,11 +512,32 @@ pub struct HookInvocationGroupRefV1 { pub group_id: EntityId, pub host_event_ide
 pub enum PermissionBehaviorV1 { Allow, Deny, NoDecision }
 pub enum HookContinuationTargetV1 { Turn, Subagent }
 pub enum HookHandlerResultV1 { Succeeded, TimedOut, Exited { code: i32 }, InvalidOutput { reason: RegistryEntryId }, SkippedUnsupported, SkippedTrust }
-pub enum HostHookTrustStateV1 { NeedsReview, Trusted, ManagedTrusted, Unknown }
+pub enum ClaudePermissionDestinationV1 { Session, LocalSettings, ProjectSettings, UserSettings }
+pub enum ClaudePermissionUpdateV1 {
+    AddRules { behavior: RegistryEntryId, rules: PayloadRef, destination: ClaudePermissionDestinationV1 },
+    ReplaceRules { behavior: RegistryEntryId, rules: PayloadRef, destination: ClaudePermissionDestinationV1 },
+    RemoveRules { behavior: RegistryEntryId, rules: PayloadRef, destination: ClaudePermissionDestinationV1 },
+    SetMode { mode: RegistryEntryId, destination: ClaudePermissionDestinationV1 },
+    AddDirectories { directories: PayloadRef, destination: ClaudePermissionDestinationV1 },
+    RemoveDirectories { directories: PayloadRef, destination: ClaudePermissionDestinationV1 },
+}
+pub struct ClaudePermissionRequestDecisionV1 { pub behavior: PermissionBehaviorV1, pub updated_input: Option<PayloadRef>, pub updates: BoundedVec<ClaudePermissionUpdateV1, 32>, pub message: Option<LogSafeText>, pub interrupt: bool }
+pub struct ProtectedHostLocatorHandleV1 { pub handle_id: EntityId, pub access_digest: AccessPolicyDigest, pub expires_at: UtcMicros }
+pub struct ProtectedHostLocatorRefV1 { pub handle: ProtectedHostLocatorHandleV1, pub locator_digest: PrivacyDomainBoundLocatorDigest }
+pub struct ValidatedHostDirectoryV1 { pub locator: ProtectedHostLocatorRefV1, pub validation_receipt: EntityRef }
+pub struct WatchPathSetV1 { pub paths: BoundedVec<ProtectedHostLocatorRefV1, 64>, pub coverage: CoverageReportV1 }
+pub enum ClaudeElicitationActionV1 { Accept, Decline, Cancel }
+pub struct ClaudeElicitationDecisionV1 { pub action: ClaudeElicitationActionV1, pub form_content: Option<PayloadRef>, pub sanitization_receipt: SanitizationReceiptId }
+pub struct ClaudeSessionBootstrapV1 { pub initial_user_message: Option<PayloadRef>, pub session_title: Option<PromptEligibleText>, pub watch_paths: Option<WatchPathSetV1>, pub reload_skills: bool }
+pub enum HostHookTrustStateV1 { NeedsReview, Trusted, ManagedTrusted, NotApplicable, Unknown }
 pub enum HostHookEligibilityStateV1 { Eligible, DisabledByUser, SkippedUntrustedProject, SkippedManagedOnly, SkippedFeatureDisabled }
-pub enum HostHookHandlerSupportV1 { SupportedCommand, UnsupportedPrompt, UnsupportedAgent, UnsupportedAsync }
+pub enum HostHookControlStateV1 { Enabled, DisabledAll, SuppressedManagedOnly, ManagedExempt, ComponentInactive }
+pub enum HostHookHandlerKindV1 { Command, Http, McpTool, Prompt, Agent }
+pub enum HostHookHandlerSupportV1 { Supported, VersionGated, Unsupported, Experimental }
+pub enum HostHookExecutionModeV1 { Synchronous, Async, AsyncRewake }
+pub enum HostHookHostDedupeV1 { NotApplicable, Executed, DedupedIdentical, Unobservable }
 pub enum HostHookDefinitionFreshnessV1 { Current, ChangedSinceReview }
-pub enum HostHookTrustRequirementV1 { ExactHashUserReview, ManagedPolicy }
+pub enum HostHookTrustRequirementV1 { ExactHashUserReview, ManagedPolicy, NotApplicable }
 pub enum HostHookRunVisibilityV1 { TraceDecayOwned, HostObserved, Unobservable }
 pub struct HostHookTrustReceiptRefV1 {
     pub receipt_id: EntityId,
@@ -528,12 +549,16 @@ pub struct HostHookTrustReceiptRefV1 {
 }
 pub struct HostHookDefinitionObservationV1 {
     pub definition: HookDefinitionRefV1,
+    pub handler_kind: HostHookHandlerKindV1,
+    pub execution_mode: HostHookExecutionModeV1,
     pub trust: HostHookTrustStateV1,
+    pub control: HostHookControlStateV1,
     pub eligibility: HostHookEligibilityStateV1,
     pub handler_support: HostHookHandlerSupportV1,
     pub freshness: HostHookDefinitionFreshnessV1,
     pub trust_receipt: Option<HostHookTrustReceiptRefV1>,
     pub run_visibility: HostHookRunVisibilityV1,
+    pub host_dedupe: HostHookHostDedupeV1,
 }
 pub struct SkillVersionRef {
     pub skill_id: SkillId,

docs/plans/tracedecay-v2/03-capture-crate.md

@@ -318,27 +318,47 @@ pub struct WorkClaimDraft {
 
 pub enum HookEventV1 {
     SessionStarted { source: NativeKindCode },
-    PromptSubmitted { turn_id: AliasRef, content: ProviderFieldValue },
+    SetupStarted { trigger: NativeKindCode },
+    InstructionsLoaded { load_reason: NativeKindCode, metadata: ProviderFieldValue },
+    PromptSubmitted { prompt_id: Option<AliasRef>, content: ProviderFieldValue },
+    PromptExpanded { prompt_id: Option<AliasRef>, expansion: ProviderFieldValue },
+    AssistantMessageDisplayed { turn_id: AliasRef, message_id: AliasRef, index: u32, final_chunk: bool, delta: ProviderFieldValue },
     AgentSpawned { child: NativeAgentId, task: ProviderFieldValue },
-    AgentStopped { child: NativeAgentId, stop_hook_active: bool, last_message: Option<ProviderFieldValue> },
+    AgentStopped { child: NativeAgentId, stop_hook_active: bool, last_message: Option<ProviderFieldValue>, background_tasks: Option<ProviderFieldValue>, session_crons: Option<ProviderFieldValue>, terminal_coverage: CoverageReportV1 },
     AgentMessage { recipient: NativeAgentId, content: ProviderFieldValue },
     AgentHandoff { recipient: NativeAgentId, state: ProviderFieldValue },
     AgentPresenceHeartbeat { status: PresenceStatus },
     WorkClaimDeclared { claim: WorkClaimDraft },
     WorkClaimScopeChanged { claim_id: String, scope: WorkClaimScopeDraft },
     WorkClaimAcknowledged { claim_id: String, redundancy: RedundancyMode },
     CoordinationOutcomeObserved { claim_id: String, outcome: CoordinationOutcome },
-    PermissionRequested { turn_id: AliasRef, native_request_id: Option<AliasRef>, tool: String, input: ProviderFieldValue },
+    PermissionRequested { prompt_id: Option<AliasRef>, native_request_id: Option<AliasRef>, tool: String, input: ProviderFieldValue },
     PermissionDecisionObserved { permission_request: AliasRef, behavior: PermissionBehaviorV1 },
+    PermissionDenied { prompt_id: Option<AliasRef>, tool_use_id: Option<AliasRef>, tool: String, input: ProviderFieldValue, reason: ProviderFieldValue },
     ToolStarted { call_id: String, tool: String, input: ProviderFieldValue },
-    ToolFinished { call_id: String, outcome: ToolOutcome, output: ProviderFieldValue },
-    CompactStarted { trigger: NativeKindCode },
-    CompactFinished { trigger: NativeKindCode },
-    TurnStopRequested { turn_id: AliasRef, stop_hook_active: bool, last_message: Option<ProviderFieldValue> },
+    ToolFinished { call_id: String, outcome: ToolOutcome, output: ProviderFieldValue, duration_ms: Option<u64> },
+    ToolFailed { call_id: String, tool: String, error: ProviderFieldValue, is_interrupt: Option<bool>, duration_ms: Option<u64> },
+    ToolBatchFinished { prompt_id: Option<AliasRef>, results: ProviderFieldValue },
+    NotificationObserved { kind: NativeKindCode, message: ProviderFieldValue },
+    TaskCreated { task: ProviderFieldValue },
+    TaskCompleted { task: ProviderFieldValue },
+    TeammateIdle { teammate: ProviderFieldValue },
+    ConfigurationChanged { source: NativeKindCode, change: ProviderFieldValue },
+    CwdChanged { previous: ProviderFieldValue, current: ProviderFieldValue },
+    FileChanged { file: ProviderFieldValue, change: ProviderFieldValue },
+    WorktreeCreateRequested { request: ProviderFieldValue },
+    WorktreeCreated { worktree: ProviderFieldValue },
+    WorktreeRemoved { worktree: ProviderFieldValue },
+    CompactStarted { trigger: NativeKindCode, custom_instructions: Option<ProviderFieldValue> },
+    CompactFinished { trigger: NativeKindCode, compact_summary: Option<ProviderFieldValue> },
+    TurnStopRequested { prompt_id: Option<AliasRef>, stop_hook_active: bool, last_message: Option<ProviderFieldValue>, background_tasks: Option<ProviderFieldValue>, session_crons: Option<ProviderFieldValue>, terminal_coverage: CoverageReportV1 },
+    TurnStopFailed { prompt_id: Option<AliasRef>, error_type: NativeKindCode, error: ProviderFieldValue },
+    ElicitationRequested { server: AliasRef, request: ProviderFieldValue },
+    ElicitationAnswered { server: AliasRef, response: ProviderFieldValue },
     ContinuationDecisionObserved { target: HookContinuationTargetV1, continued: bool, reason: Option<ProviderFieldValue> },
     HookHandlerRunObserved { definition: HookDefinitionRefV1, run: HookHandlerRunRefV1, result: HookHandlerResultV1 },
     HintTerminal { hint_id: String, terminal: HintTerminalState },
-    SessionStopped { outcome: Option<String> },
+    SessionStopped { outcome: Option<String>, reason: Option<NativeKindCode> },
 }
 
 pub struct HookSpool;
@@ -358,6 +378,8 @@ Every TraceDecay-owned source adapter and hook draft carries the originating `Tr
 
 Codex lowering preserves the exact parent-session `session_id`, Turn, agent, tool-use, hook-definition binding, matcher-group, handler, run/attempt, bundle, trust/source-layer evidence, producer-build, and optional collector-build identities available at that surface. `PermissionRequest` has no mandatory native call ID: capture accepts an optional native alias, while application persists a deterministic request identity over session/Turn/tool/sanitized-input digest and source generation. It appends every concurrently launched observable TraceDecay handler run; an invocation-group projection relates them and records host aggregation evidence separately. Shared definition/run/result/trust/source refs are owned by `tracedecay-domain`; capture imports them and never depends on root hook/config composition. `transcript_path`, `agent_transcript_path`, cwd, prompt, tool input/response, and last assistant message remain transient unclassified inputs and may persist only as sanitized payload refs or privacy-domain locator fingerprints. Stop/SubagentStop terminal observations asynchronously dirty only their exact thread/subagent automation scope; the hook never waits for reflection/curation, and unchanged terminal inputs remain fenced by plans 09/26.
 
+Claude lowering preserves the native 30-event identity, only the native correlation fields actually supplied (`prompt_id`, `tool_use_id`, MessageDisplay `turn_id`, and event-specific IDs), conditional effort, session/agent/task/team/tool/batch/worktree/MCP identities, event-specific duration/failure/interrupt/continuation fields, handler kind/execution mode, configured-definition versus host-deduped versus actual-run evidence, and produced-at versus later-delivered context time. It never manufactures a Turn ID from session/timing/text. `transcript_path` is explicitly lagging and never used to infer current-turn completeness. `MessageDisplay` is metadata-only by default—delta text is discarded after sanitizer classification unless a versioned bounded capture purpose passes privacy/performance evaluation. Version-gated background-task/session-cron fields are optional with coverage; missing/unreachable evidence cannot satisfy the Stop/SubagentStop terminal predicate. `StopFailure` remains a distinct non-controllable event.
+
 Capture owns the one hook spool and its drainer. There is exactly one spool implementation, one hash-chained frame format (below), and one always-spool ingress protocol; the store exposes only append transactions and never runs a handoff-first or fallback ingress spool of its own ([`02-store-crate.md`](02-store-crate.md) drains capture's spool through `ObservationJournal` appends). Plan [`07-hooks-crate.md`](07-hooks-crate.md) hook hosts write exclusively through capture's spool client (`spool/client.rs`) and receive durability acks carrying the domain `SpoolReceipt` from [`01-domain-crate.md`](01-domain-crate.md); no crate mints a spool-receipt variant.
 
 Under dedicated-service isolation, that client is an authenticated connect-only call to a socket-activated, service-owned capture-ingress helper that sanitizes/validates and `fdatasync`s the canonical capture spool without opening an application store. It stays available while the main daemon is stopped or draining and hands segments to the normal daemon drainer after restart. Client hooks never receive spool paths or keys and never create a second user-owned spool; if the ingress service itself is unavailable, the hook reports a non-content degraded receipt and never claims durability. Remote-authority mode uses the same local service-owned ingress spool until a verified remote commit receipt retires the frame.