task: plan hook api hardening
This commit is contained in:
parent
fb172b6049
commit
21b6848e21
|
|
@ -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<Item>)` or `TurnEndAction::ContinueWithMessages(Vec<Item>)`.
|
||||
- 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<PreToolCall>` 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
|
||||
|
|
@ -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
|
||||
---
|
||||
|
|
|
|||
|
|
@ -4,4 +4,96 @@
|
|||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: plan author: hare at: 2026-06-03T16:36:57Z -->
|
||||
|
||||
## 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<Item>)` or `TurnEndAction::ContinueWithMessages(Vec<Item>)`.
|
||||
- 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<PreToolCall>` 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
|
||||
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user