feat: extract shared hook types into tokf-hook-types crate (#314)

## Summary
- Extract `ExternalEngineConfig`, `ErrorFallback`, `HookFormat`,
`PermissionVerdict`, `RewriteConfig`, `PermissionsConfig`, and related
types into a new `tokf-hook-types` crate
- Enables external tools to share the config format without duplicating
type definitions or risking format drift
- Adds `Serialize` derives for round-trip TOML support,
`skip_serializing_if` for clean output, and `Default` impl for
`ExternalEngineConfig`
- `tokf-cli` re-exports all types from the new crate for full backward
compatibility

## Test plan
- [x] `cargo fmt && cargo clippy --all-targets -- -D warnings` passes
- [x] All 1359 tokf tests pass (0 failures)
- [x] `tokf-hook-types` builds with only `serde` dependency
- [x] Verify tokf-cli re-exports work correctly (no API breakage)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mpecan

.github/workflows/release.yml

@@ -43,6 +43,18 @@ jobs:
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
 
+      - name: Publish tokf-hook-types
+        run: |
+          LOCAL=$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.name == "tokf-hook-types") | .version')
+          PUBLISHED=$(cargo search tokf-hook-types --limit 1 --color never | sed -n 's/^tokf-hook-types = "\([^"]*\)".*/\1/p')
+          if [ "$LOCAL" = "$PUBLISHED" ]; then
+            echo "::notice::tokf-hook-types@$LOCAL already published, skipping"
+          else
+            cargo publish -p tokf-hook-types
+          fi
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
       - name: Publish tokf-filter
         run: |
           LOCAL=$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.name == "tokf-filter") | .version')

.release-please-config.json

@@ -18,6 +18,7 @@
   ],
   "packages": {
     "crates/tokf-common": {},
+    "crates/tokf-hook-types": {},
     "crates/tokf-filter": {},
     "crates/tokf-cli": { "component": "tokf" },
     "crates/tokf-server": {},
@@ -34,7 +35,7 @@
     {
       "type": "linked-versions",
       "groupName": "workspace",
-      "components": ["tokf-common", "tokf-filter", "tokf", "tokf-server", "catalog-types"]
+      "components": ["tokf-common", "tokf-hook-types", "tokf-filter", "tokf", "tokf-server", "catalog-types"]
     }
   ]
 }

.release-please-manifest.json

@@ -4,5 +4,6 @@
   "crates/tokf-cli": "0.2.38",
   "crates/tokf-server": "0.2.38",
   "crates/tokf-server/generated": "0.2.38",
+  "crates/tokf-hook-types": "0.2.38",
   "crates/e2e-tests": "0.1.26"
 }

Cargo.lock

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/tokf-cli", "crates/tokf-common", "crates/tokf-filter", "crates/tokf-server", "crates/crdb-test-macro", "crates/e2e-tests"]
+members = ["crates/tokf-cli", "crates/tokf-common", "crates/tokf-filter", "crates/tokf-hook-types", "crates/tokf-server", "crates/crdb-test-macro", "crates/e2e-tests"]
 resolver = "2"
 
 [workspace.package]

Cargo.toml

@@ -16,6 +16,7 @@ path = "src/main.rs"
 [dependencies]
 tokf-common = { path = "../tokf-common", version = "0.2.38", features = ["validation"] }
 tokf-filter = { path = "../tokf-filter", version = "0.2.38" }
+tokf-hook-types = { path = "../tokf-hook-types", version = "0.2.38" }
 clap = { version = "4", features = ["derive", "env"] }
 toml = "1.0"
 serde = { version = "1", features = ["derive"] }

crates/tokf-cli/Cargo.toml

@@ -10,69 +10,12 @@ use std::io::Write;
 use std::process::{Command, Stdio};
 use std::time::Duration;
 
-use serde::Deserialize;
 use serde_json::Value;
 
 use super::permissions::PermissionVerdict;
 use super::types::HookFormat;
 
-/// Configuration for an external permission engine.
-#[derive(Debug, Clone, Deserialize)]
-pub struct ExternalEngineConfig {
-    /// Path to the external engine binary (resolved via PATH if not absolute).
-    pub command: String,
-
-    /// Arguments passed to the engine. Use `{format}` as a placeholder for the
-    /// tool format (e.g. `["hook", "handle", "--mode", "{format}"]`).
-    /// The placeholder is replaced with the resolved format string before spawning.
-    #[serde(default)]
-    pub args: Vec<String>,
-
-    /// Timeout in milliseconds. Default: 5000 (5 seconds).
-    #[serde(default = "default_timeout")]
-    pub timeout_ms: u64,
-
-    /// What to do when the engine fails (crash, timeout, bad output).
-    #[serde(default)]
-    pub on_error: ErrorFallback,
-
-    /// Override the default format strings used for `{format}` substitution.
-    /// Keys are the default names (`claude-code`, `gemini`, `cursor`);
-    /// values are the replacements the engine expects.
-    ///
-    /// Example: `{ "claude-code" = "claude", "gemini" = "google" }`
-    #[serde(default)]
-    pub format_map: std::collections::HashMap<String, String>,
-}
-
-impl ExternalEngineConfig {
-    /// Resolve the format string for a given hook format,
-    /// applying `format_map` overrides if present.
-    pub fn resolve_format(&self, format: HookFormat) -> String {
-        let default = format.as_str();
-        self.format_map
-            .get(default)
-            .cloned()
-            .unwrap_or_else(|| default.to_string())
-    }
-}
-
-/// Behaviour when the external engine fails.
-#[derive(Debug, Clone, Deserialize, Default, PartialEq, Eq)]
-#[serde(rename_all = "lowercase")]
-pub enum ErrorFallback {
-    /// Fail closed — prompt user for permission (default).
-    #[default]
-    Ask,
-    /// Fail open — auto-allow.
-    Allow,
-    /// Fall back to built-in rule matching.
-    Builtin,
-}
-
-const fn default_timeout() -> u64 {
-    5000
-}
+pub use tokf_hook_types::{ErrorFallback, ExternalEngineConfig};
 
 /// Error from the external permission engine.
 #[derive(Debug)]

crates/tokf-cli/src/hook/permission_engine.rs

@@ -9,16 +9,7 @@
 use serde_json::Value;
 use std::path::PathBuf;
 
-/// Verdict from checking a command against Claude Code's permission rules.
-#[derive(Debug, PartialEq, Eq, Clone)]
-pub enum PermissionVerdict {
-    /// No deny/ask rules matched — safe to auto-allow.
-    Allow,
-    /// A deny rule matched — pass through to Claude Code's native deny handling.
-    Deny,
-    /// An ask rule matched — rewrite the command but let the tool prompt the user.
-    Ask,
-}
+pub use tokf_hook_types::PermissionVerdict;
 
 /// Check `cmd` against Claude Code's deny/ask permission rules.
 ///

crates/tokf-cli/src/hook/permissions.rs

@@ -1,29 +1,6 @@
 use serde::{Deserialize, Serialize};
 
-/// Which hook format is being processed — determines response shape
-/// and which JSON field carries the permission decision.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum HookFormat {
-    /// Claude Code: `hookSpecificOutput.permissionDecision`
-    ClaudeCode,
-    /// Gemini CLI: `decision`
-    Gemini,
-    /// Cursor: `permission`
-    Cursor,
-}
-
-impl HookFormat {
-    /// Default string identifier for this format.
-    ///
-    /// Used as the default `{format}` template value in external engine args.
-    pub const fn as_str(self) -> &'static str {
-        match self {
-            Self::ClaudeCode => "claude-code",
-            Self::Gemini => "gemini",
-            Self::Cursor => "cursor",
-        }
-    }
-}
+pub use tokf_hook_types::HookFormat;
 
 /// Claude Code `PreToolUse` hook input (read from stdin).
 #[derive(Debug, Clone, Deserialize)]

crates/tokf-cli/src/hook/types.rs

@@ -1,70 +1,6 @@
-use serde::Deserialize;
-
-const fn default_true() -> bool {
-    true
-}
-
-/// User-provided overrides loaded from `rewrites.toml`.
-#[derive(Debug, Clone, Default, Deserialize)]
-pub struct RewriteConfig {
-    /// Additional skip patterns (commands matching these are never rewritten).
-    pub skip: Option<SkipConfig>,
-
-    /// Pipe stripping and prefer-less-context behaviour.
-    pub pipe: Option<PipeConfig>,
-
-    /// User-defined rewrite rules (checked before auto-generated filter rules).
-    #[serde(default)]
-    pub rewrite: Vec<RewriteRule>,
-
-    /// Permission engine configuration (external sub-hook delegation).
-    pub permissions: Option<PermissionsConfig>,
-}
-
-/// Configuration for the permission decision engine.
-#[derive(Debug, Clone, Deserialize)]
-pub struct PermissionsConfig {
-    /// Which engine to use: `"builtin"` (default) or `"external"`.
-    #[serde(default)]
-    pub engine: PermissionEngineType,
-
-    /// Configuration for the external engine (required when `engine = "external"`).
-    pub external: Option<crate::hook::permission_engine::ExternalEngineConfig>,
-}
-
-/// Which permission engine to use.
-#[derive(Debug, Clone, Deserialize, Default, PartialEq, Eq)]
-#[serde(rename_all = "lowercase")]
-pub enum PermissionEngineType {
-    /// Built-in deny/ask rule matching from Claude Code settings.json.
-    #[default]
-    Builtin,
-    /// Delegate to an external process (sub-hook).
-    External,
-}
-
-/// Controls how tokf handles piped commands during rewriting.
-#[derive(Debug, Clone, Deserialize)]
-pub struct PipeConfig {
-    /// Whether to strip simple pipes (tail/head/grep) when a filter matches.
-    /// Default: true (current behaviour).
-    #[serde(default = "default_true")]
-    pub strip: bool,
-
-    /// When true and a pipe is stripped, inject `--prefer-less` so that at
-    /// runtime tokf compares filtered vs piped output and uses whichever is
-    /// smaller.
-    #[serde(default)]
-    pub prefer_less: bool,
-}
-
-/// Extra skip patterns from user config.
-#[derive(Debug, Clone, Default, Deserialize)]
-pub struct SkipConfig {
-    /// Regex patterns — if any matches the command, rewriting is skipped.
-    #[serde(default)]
-    pub patterns: Vec<String>,
-}
+pub use tokf_hook_types::{
+    PermissionEngineType, PermissionsConfig, PipeConfig, RewriteConfig, RewriteRule, SkipConfig,
+};
 
 /// Options that control how the rewrite system generates `tokf run` commands.
 #[derive(Debug, Clone, Default)]
@@ -74,17 +10,6 @@ pub struct RewriteOptions {
     pub no_mask_exit_code: bool,
 }
 
-/// A single rewrite rule: match a command and replace it.
-#[derive(Debug, Clone, Deserialize)]
-pub struct RewriteRule {
-    /// Regex pattern to match against the command string.
-    #[serde(rename = "match")]
-    pub match_pattern: String,
-
-    /// Replacement template. Supports `{0}` (full match), `{1}`, `{2}`, etc.
-    pub replace: String,
-}
-
 #[cfg(test)]
 #[allow(clippy::unwrap_used, clippy::expect_used)]
 mod tests {