Evaluate: Typed tool hooks (beforeToolCall/afterToolCall) for terraphim-skills

[AlexMikhalev]

Parent Epic

#682 -- Evaluate Pi architectural patterns

Pattern

Pi's agent-core provides typed hooks at the tool execution boundary:

beforeToolCall: async ({ toolCall, args, context }) => {
  if (toolCall.name === "bash" && args.command.includes("rm -rf")) {
    return { block: true, reason: "Destructive command blocked" };
  }
}

afterToolCall: async ({ toolCall, result, isError, context }) => {
  return { details: { ...result.details, audited: true } };
}

These hooks:

• Run after argument validation but before execution (beforeToolCall)
• Can block execution with a typed reason
• Can modify tool results before they reach the LLM (afterToolCall)
• Are in-process callbacks with full type safety (not JSON over shell)

Current State

terraphim-skills hooks system:

• PreToolUse (~/.claude/hooks/pre_tool_use.sh): git safety guard + KG text replacement. Shell script, receives JSON on stdin, returns JSON on stdout.
• PostToolUse (~/.claude/hooks/post_tool_use.sh): learning capture for failed commands. Shell script.
• Both are shell commands -- no type safety, JSON parsing overhead, subprocess spawn cost.

Claude Code hooks:

• 22 lifecycle events
• Shell command, HTTP POST, or prompt/agent types
• JSON-based input/output contract
• Exit code 2 for blocking

Claude Agent SDK hooks:

• Callback functions (Python/TypeScript) -- closer to Pi's model
• Typed input objects, structured output
• permissionDecision: "deny" for blocking

Evaluation Questions

1. Should terraphim-skills adopt typed Rust hooks? Current shell hooks have subprocess overhead (~50ms per invocation). A Rust-native hook system would be sub-millisecond.
2. What's the right abstraction? Pi uses { block: true, reason }. Claude uses { permissionDecision: "deny", permissionDecisionReason }. terraphim could use a trait: fn before_tool_call(&self, tool: &ToolCall, args: &Value) -> HookResult.
3. Does this replace or complement shell hooks? Shell hooks are user-facing (CLAUDE.md configurable). Rust hooks would be for skill/extension developers.
4. Integration with terraphim-skills Markdown format: Skills are currently Markdown files. Typed hooks would require a Rust module alongside the Markdown. Is this acceptable complexity?

Acceptance Criteria

• Design a Rust hook trait compatible with terraphim-skills
• Benchmark: shell hook invocation time vs Rust trait dispatch
• Prototype: port git-safety-guard from shell to Rust hook
• Decision: adopt Rust hooks, keep shell-only, or hybrid approach

References

• Pi beforeToolCall/afterToolCall: https://github.com/badlogic/pi-mono/tree/main/packages/agent
• Current shell hooks: ~/.claude/hooks/pre_tool_use.sh, ~/.claude/hooks/post_tool_use.sh
• terraphim-skills: https://github.com/terraphim/terraphim-skills
• Claude Agent SDK hooks: knowledge/claude-agent-sdk-reference.md