Summary

• Problem: Embedded tool handler emits after_tool_call hook context with sessionKey: undefined.
• Why it matters: Plugins that correlate tool spans by session lose deterministic linkage in embedded paths.
• What changed: Threaded sessionKey through embedded tool handler params and pass it into runAfterToolCall(...) context.
• What did NOT change (scope boundary): No hook contract expansion (toolCallId/runId) and no behavior changes outside embedded after_tool_call context propagation.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

• after_tool_call hook handlers now receive sessionKey in embedded execution paths when available.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: N/A (hook wiring)
• Integration/channel (if any): Embedded agent tool handlers
• Relevant config (redacted): N/A

Steps

1. Register an after_tool_call hook.
2. Execute an embedded tool call flow with sessionKey present in subscribe params.
3. Inspect hook invocation context.

Expected

• Hook context includes matching sessionKey.

Actual

• Before this change, context used sessionKey: undefined.
• After this change, context receives ctx.params.sessionKey.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm check
  • pnpm test -- src/agents/pi-embedded-subscribe.handlers.tools.test.ts
  • pnpm exec vitest run --config vitest.e2e.config.ts src/plugins/wired-hooks-after-tool-call.e2e.test.ts
• Edge cases checked:
  • Existing hook wiring test now asserts propagated sessionKey.
• What you did not verify:
  • Full pnpm test:e2e suite (current branch has unrelated pre-existing failures).

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Revert commits in this PR.
• Files/config to restore:
  • src/agents/pi-embedded-subscribe.handlers.types.ts
  • src/agents/pi-embedded-subscribe.handlers.tools.ts
  • src/plugins/wired-hooks-after-tool-call.e2e.test.ts
• Known bad symptoms reviewers should watch for:
  • Missing/undefined sessionKey in embedded after_tool_call hook context.

Risks and Mitigations

• Risk:
  • Plugins may now branch on sessionKey presence where they previously always saw undefined.
  • Mitigation:
  • Change is backward-compatible (optional field); no contract shape break.