diff --git a/work-items/open/20260603-122317-hook-public-surface-hardening/artifacts/delegation-intent.md b/work-items/open/20260603-122317-hook-public-surface-hardening/artifacts/delegation-intent.md new file mode 100644 index 00000000..c027ca5f --- /dev/null +++ b/work-items/open/20260603-122317-hook-public-surface-hardening/artifacts/delegation-intent.md @@ -0,0 +1,84 @@ +# Delegation intent: Hook public surface hardening + +## Intent + +Harden `pod::hook` so it can be safely used as the public Hook contribution boundary for the feature/plugin registry. Public Hooks must not expose internal `llm_worker::Interceptor` action types that can inject raw model-visible `Item` values into request/history paths. + +## Requirements + +- Audit the current public Hook API in `crates/pod/src/hook.rs` and its bridge in `crates/pod/src/ipc/interceptor.rs`. +- Replace or wrap public Hook outputs that currently reuse internal interceptor action types with safe public action subsets. + - `OnPromptSubmit` already uses `HookPromptAction`; use the same pattern for events that need public actions. + - Public Hook APIs must not expose raw `Item` vector injection such as `PreRequestAction::ContinueWith(Vec)` or `TurnEndAction::ContinueWithMessages(Vec)`. +- Preserve internal mechanisms that legitimately need richer `llm_worker::Interceptor` actions, but keep them internal and separate from public feature/plugin Hooks. +- Preserve current manifest permission policy behavior. + - `PreToolCall` deny/ask still fails closed through the existing synthetic tool result path. +- Preserve usage tracking behavior. +- Clarify through names/types/tests which Hook events are observation-only and which can cancel/abort/yield/deny. +- Add focused Pod-layer tests for public Hook behavior and short-circuit ordering. + +## Invariants + +- Do not add hidden prompt/context injection paths. +- Do not mutate session history from public Hooks except through already-approved durable host paths. +- Do not expose `llm_worker::Item` or raw history/message vectors through public plugin/feature Hook actions. +- Do not implement plugin runtime, feature registry, MCP, or WorkItem tools in this ticket. +- Do not weaken manifest permission enforcement. +- Keep `llm_worker::Interceptor` internal capabilities available where currently required by Pod internals. + +## Non-goals + +- Implementing `plugin-feature-contribution-registry`. +- Adding new Hook event kinds unless the audit finds a strict safety gap. +- Allowing Hooks to rewrite tool outputs or arbitrary model context. +- Broad refactors of Pod/Worker runtime unrelated to the Hook surface. + +## Suggested files to inspect + +- `crates/pod/src/hook.rs` +- `crates/pod/src/ipc/interceptor.rs` +- `crates/pod/src/permission.rs` +- `crates/pod/src/pod.rs` +- `crates/llm-worker/src/interceptor.rs` +- `crates/llm-worker/tests/parallel_execution_test.rs` + +## Known observations from pre-delegation investigation + +- Current production Hook use is light: + - `PermissionHook` implements `Hook` in `crates/pod/src/permission.rs`. + - `UsageTrackingHook` uses `PreLlmRequest` from `crates/pod/src/pod.rs`. +- `OnPromptSubmit` already has a safe public subset action: `HookPromptAction`. +- `PreLlmRequest` and `OnTurnEnd` currently expose internal action types with raw `Item` injection capability. +- `PostToolCall` is currently observation + abort only and does not rewrite tool output; keep that conservative unless a strictly bounded explicit transform is justified, which is not expected for this ticket. +- Existing `llm-worker` interceptor tests cover some lower-level behavior, but Pod-layer Hook coverage should be improved. +- `cargo test -p pod hook --lib` passed during investigation. +- Individual relevant `llm-worker` interceptor tests passed, but the full `parallel_execution_test` file had an unrelated timing-sensitive failure (`test_parallel_tool_execution` took ~1.37s instead of ~100ms). Do not treat that file-wide failure as a Hook blocker without confirming. + +## Validation + +Run at least: + +- `cargo test -p pod hook --lib` +- focused Pod Hook tests added/updated by this ticket +- `cargo test -p pod --lib` +- `cargo test -p llm-worker --lib` +- `cargo check --workspace --all-targets` +- `cargo fmt --check` +- `./tickets.sh doctor` +- `git diff --check` + +If broader validation fails due to pre-existing unrelated timing flakes, report exact command/output and run focused commands that isolate this change. + +## Completion report + +Report: + +- worktree path / branch +- commit hash +- changed files +- public Hook API changes +- internal mechanism separation +- tests added/updated +- validation commands and results +- unresolved risks or follow-up recommendations +- whether the work is ready for external review diff --git a/work-items/open/20260603-122317-hook-public-surface-hardening/item.md b/work-items/open/20260603-122317-hook-public-surface-hardening/item.md index 97e66d38..34c8c41e 100644 --- a/work-items/open/20260603-122317-hook-public-surface-hardening/item.md +++ b/work-items/open/20260603-122317-hook-public-surface-hardening/item.md @@ -7,7 +7,7 @@ kind: task priority: P1 labels: [hooks, plugin, safety, tests] created_at: 2026-06-03T12:23:17Z -updated_at: 2026-06-03T12:23:17Z +updated_at: 2026-06-03T16:36:57Z assignee: null legacy_ticket: null --- diff --git a/work-items/open/20260603-122317-hook-public-surface-hardening/thread.md b/work-items/open/20260603-122317-hook-public-surface-hardening/thread.md index 963ee2d7..83e96f13 100644 --- a/work-items/open/20260603-122317-hook-public-surface-hardening/thread.md +++ b/work-items/open/20260603-122317-hook-public-surface-hardening/thread.md @@ -4,4 +4,96 @@ Created by tickets.sh create. +--- + + + +## Plan + +# Delegation intent: Hook public surface hardening + +## Intent + +Harden `pod::hook` so it can be safely used as the public Hook contribution boundary for the feature/plugin registry. Public Hooks must not expose internal `llm_worker::Interceptor` action types that can inject raw model-visible `Item` values into request/history paths. + +## Requirements + +- Audit the current public Hook API in `crates/pod/src/hook.rs` and its bridge in `crates/pod/src/ipc/interceptor.rs`. +- Replace or wrap public Hook outputs that currently reuse internal interceptor action types with safe public action subsets. + - `OnPromptSubmit` already uses `HookPromptAction`; use the same pattern for events that need public actions. + - Public Hook APIs must not expose raw `Item` vector injection such as `PreRequestAction::ContinueWith(Vec)` or `TurnEndAction::ContinueWithMessages(Vec)`. +- Preserve internal mechanisms that legitimately need richer `llm_worker::Interceptor` actions, but keep them internal and separate from public feature/plugin Hooks. +- Preserve current manifest permission policy behavior. + - `PreToolCall` deny/ask still fails closed through the existing synthetic tool result path. +- Preserve usage tracking behavior. +- Clarify through names/types/tests which Hook events are observation-only and which can cancel/abort/yield/deny. +- Add focused Pod-layer tests for public Hook behavior and short-circuit ordering. + +## Invariants + +- Do not add hidden prompt/context injection paths. +- Do not mutate session history from public Hooks except through already-approved durable host paths. +- Do not expose `llm_worker::Item` or raw history/message vectors through public plugin/feature Hook actions. +- Do not implement plugin runtime, feature registry, MCP, or WorkItem tools in this ticket. +- Do not weaken manifest permission enforcement. +- Keep `llm_worker::Interceptor` internal capabilities available where currently required by Pod internals. + +## Non-goals + +- Implementing `plugin-feature-contribution-registry`. +- Adding new Hook event kinds unless the audit finds a strict safety gap. +- Allowing Hooks to rewrite tool outputs or arbitrary model context. +- Broad refactors of Pod/Worker runtime unrelated to the Hook surface. + +## Suggested files to inspect + +- `crates/pod/src/hook.rs` +- `crates/pod/src/ipc/interceptor.rs` +- `crates/pod/src/permission.rs` +- `crates/pod/src/pod.rs` +- `crates/llm-worker/src/interceptor.rs` +- `crates/llm-worker/tests/parallel_execution_test.rs` + +## Known observations from pre-delegation investigation + +- Current production Hook use is light: + - `PermissionHook` implements `Hook` in `crates/pod/src/permission.rs`. + - `UsageTrackingHook` uses `PreLlmRequest` from `crates/pod/src/pod.rs`. +- `OnPromptSubmit` already has a safe public subset action: `HookPromptAction`. +- `PreLlmRequest` and `OnTurnEnd` currently expose internal action types with raw `Item` injection capability. +- `PostToolCall` is currently observation + abort only and does not rewrite tool output; keep that conservative unless a strictly bounded explicit transform is justified, which is not expected for this ticket. +- Existing `llm-worker` interceptor tests cover some lower-level behavior, but Pod-layer Hook coverage should be improved. +- `cargo test -p pod hook --lib` passed during investigation. +- Individual relevant `llm-worker` interceptor tests passed, but the full `parallel_execution_test` file had an unrelated timing-sensitive failure (`test_parallel_tool_execution` took ~1.37s instead of ~100ms). Do not treat that file-wide failure as a Hook blocker without confirming. + +## Validation + +Run at least: + +- `cargo test -p pod hook --lib` +- focused Pod Hook tests added/updated by this ticket +- `cargo test -p pod --lib` +- `cargo test -p llm-worker --lib` +- `cargo check --workspace --all-targets` +- `cargo fmt --check` +- `./tickets.sh doctor` +- `git diff --check` + +If broader validation fails due to pre-existing unrelated timing flakes, report exact command/output and run focused commands that isolate this change. + +## Completion report + +Report: + +- worktree path / branch +- commit hash +- changed files +- public Hook API changes +- internal mechanism separation +- tests added/updated +- validation commands and results +- unresolved risks or follow-up recommendations +- whether the work is ready for external review + + ---