fix(hook): use bare tokf in generated hook scripts (#208)

## Summary

- Replace hardcoded absolute binary path (`std::env::current_exe()`)
with bare `tokf` in generated hook shim and OpenCode plugin scripts
- Remove `escape_for_js_string` helper and `{{TOKF_PATH}}` template
substitution from opencode.rs (no longer needed)
- Add `--path <binary>` flag to `tokf hook install` so users can opt
into a specific binary path when bare `tokf` isn't on PATH (e.g.
Linuxbrew, `cargo install` without PATH in `/bin/sh`)
- Custom paths are shell-escaped in the hook shim and JS-escaped (via
`serde_json`) in the OpenCode plugin template
- Update tests to assert on bare `tokf` instead of quoted full paths,
plus new tests for custom path and path-with-spaces escaping
- Add "Set up automatic filtering" section to getting-started docs so
users discover `tokf hook install --global` during onboarding
- Document the `--path` flag in integrations docs

Closes #191

## Test plan

- [x] `cargo test -p tokf -- hook` — all 81 tests pass
- [x] `cargo clippy --workspace --all-targets -- -D warnings` — clean
- [x] `cargo fmt -- --check` — clean
- [x] README.md regenerated via `scripts/generate-readme.sh`

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

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: mpecan

README.md

@@ -124,6 +124,25 @@ tokf looks up a filter for `git push`, runs the command, and applies the filter.
 
 ---
 
+## Set up automatic filtering
+
+If you use an AI coding tool, install the hook so every command is filtered automatically — no `tokf run` prefix needed:
+
+```sh
+# Claude Code (recommended: --global so it works in every project)
+tokf hook install --global
+
+# OpenCode
+tokf hook install --tool opencode --global
+
+# OpenAI Codex CLI
+tokf hook install --tool codex --global
+```
+
+Drop `--global` to install for the current project only. See [Claude Code hook](#claude-code-hook) for details on each tool, the `--path` flag, and optional extras like the filter-authoring skill.
+
+---
+
 ## Usage
 
 ### Run a command with filtering
@@ -709,6 +728,15 @@ tokf hook install --global # user-level (~/.config/tokf/)
 
 Once installed, every command Claude runs through the Bash tool is filtered transparently. Track cumulative savings with `tokf gain`.
 
+### Custom binary path
+
+By default the generated hook script calls bare `tokf`, relying on PATH at runtime. If `tokf` isn't on PATH in the hook's execution environment (common with Linuxbrew or `cargo install` when PATH is only set in interactive shell profiles), pass `--path` to embed a specific binary location:
+
+```sh
+tokf hook install --global --path ~/.cargo/bin/tokf
+tokf hook install --tool opencode --path /home/linuxbrew/.linuxbrew/bin/tokf
+```
+
 tokf also ships a filter-authoring skill that teaches Claude the complete filter schema:
 
 ```sh

crates/tokf-cli/src/commands.rs

@@ -361,11 +361,12 @@ pub fn cmd_hook_handle() -> i32 {
     0
 }
 
-pub fn cmd_hook_install(global: bool, tool: &HookTool) -> i32 {
+pub fn cmd_hook_install(global: bool, tool: &HookTool, path: Option<&Path>) -> i32 {
+    let tokf_bin = path.map_or_else(|| "tokf".to_string(), |p| p.display().to_string());
     let result = match tool {
-        HookTool::ClaudeCode => hook::install(global),
+        HookTool::ClaudeCode => hook::install(global, &tokf_bin),
         // R6: Updated variant name from Opencode to OpenCode.
-        HookTool::OpenCode => hook::opencode::install(global),
+        HookTool::OpenCode => hook::opencode::install(global, &tokf_bin),
         HookTool::Codex => hook::codex::install(global),
     };
     match result {

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

@@ -78,7 +78,7 @@ pub(crate) fn handle_json_with_config(
 /// # Errors
 ///
 /// Returns an error if file I/O fails.
-pub fn install(global: bool) -> anyhow::Result<()> {
+pub fn install(global: bool, tokf_bin: &str) -> anyhow::Result<()> {
     let (hook_dir, settings_path) = if global {
         let user = crate::paths::user_dir()
             .ok_or_else(|| anyhow::anyhow!("could not determine config directory"))?;
@@ -94,13 +94,17 @@ pub fn install(global: bool) -> anyhow::Result<()> {
         (hook_dir, settings_path)
     };
 
-    install_to(&hook_dir, &settings_path)
+    install_to(&hook_dir, &settings_path, tokf_bin)
 }
 
 /// Core install logic with explicit paths (testable).
-pub(crate) fn install_to(hook_dir: &Path, settings_path: &Path) -> anyhow::Result<()> {
+pub(crate) fn install_to(
+    hook_dir: &Path,
+    settings_path: &Path,
+    tokf_bin: &str,
+) -> anyhow::Result<()> {
     let hook_script = hook_dir.join("pre-tool-use.sh");
-    write_hook_shim(hook_dir, &hook_script)?;
+    write_hook_shim(hook_dir, &hook_script, tokf_bin)?;
     patch_settings(settings_path, &hook_script)?;
 
     eprintln!("[tokf] hook installed");
@@ -111,13 +115,16 @@ pub(crate) fn install_to(hook_dir: &Path, settings_path: &Path) -> anyhow::Resul
 }
 
 /// Write the hook shim script.
-fn write_hook_shim(hook_dir: &Path, hook_script: &Path) -> anyhow::Result<()> {
+fn write_hook_shim(hook_dir: &Path, hook_script: &Path, tokf_bin: &str) -> anyhow::Result<()> {
     std::fs::create_dir_all(hook_dir)?;
 
-    let tokf_path = std::env::current_exe()?;
-    let quoted = runner::shell_escape(&tokf_path.to_string_lossy());
-    let content = format!("#!/bin/sh\nexec {quoted} hook handle\n");
-    std::fs::write(hook_script, &content)?;
+    let escaped_bin = if tokf_bin == "tokf" {
+        tokf_bin.to_string()
+    } else {
+        runner::shell_escape(tokf_bin)
+    };
+    let content = format!("#!/bin/sh\nexec {escaped_bin} hook handle\n");
+    std::fs::write(hook_script, content)?;
 
     // Make executable on Unix
     #[cfg(unix)]

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

@@ -6,10 +6,11 @@ use anyhow::Context;
 // R7: Add 5000ms timeout to Bun.spawnSync.
 // R8: Check proc.stdout for null before decoding.
 // R9: Log errors in catch block with [tokf] prefix.
+// {{TOKF_BIN}} is replaced at install time with the configured tokf binary (command or path).
 const PLUGIN_TEMPLATE: &str = r#"// tokf-filter plugin for OpenCode
 // Generated by: tokf hook install --tool opencode
 // Docs: https://github.com/mpecan/tokf
-const TOKF_BIN = "{{TOKF_PATH}}";
+const TOKF_BIN = "{{TOKF_BIN}}";
 export default {
   "tool.execute.before": async (
     input: { tool: string },
@@ -39,17 +40,17 @@ export default {
 /// # Errors
 ///
 /// Returns an error if the plugin directory cannot be created or the plugin file cannot be written.
-pub fn install(global: bool) -> anyhow::Result<()> {
+pub fn install(global: bool, tokf_bin: &str) -> anyhow::Result<()> {
     let plugin_dir = if global {
         global_plugin_dir()?
     } else {
         PathBuf::from(".opencode/plugins")
     };
-    install_to(&plugin_dir)
+    install_to(&plugin_dir, tokf_bin)
 }
 
-pub(crate) fn install_to(plugin_dir: &Path) -> anyhow::Result<()> {
-    write_plugin_file(plugin_dir)?;
+pub(crate) fn install_to(plugin_dir: &Path, tokf_bin: &str) -> anyhow::Result<()> {
+    write_plugin_file(plugin_dir, tokf_bin)?;
     // R5: Standardize eprintln prefix to [tokf]
     eprintln!(
         "[tokf] OpenCode plugin installed to {}",
@@ -64,26 +65,19 @@ fn global_plugin_dir() -> anyhow::Result<PathBuf> {
     Ok(home.join(".config/opencode/plugins"))
 }
 
-// R10: Extract escaping logic into a small helper for testability.
-fn escape_for_js_string(s: &str) -> anyhow::Result<String> {
-    // serde_json::to_string gives us a JSON string with surrounding quotes; strip them.
-    let json = serde_json::to_string(s).context("failed to serialize tokf path")?;
-    // Strip surrounding quotes that to_string adds.
-    Ok(json[1..json.len() - 1].to_string())
-}
-
-fn write_plugin_file(plugin_dir: &Path) -> anyhow::Result<()> {
+fn write_plugin_file(plugin_dir: &Path, tokf_bin: &str) -> anyhow::Result<()> {
     std::fs::create_dir_all(plugin_dir)
         .with_context(|| format!("failed to create plugin dir: {}", plugin_dir.display()))?;
 
-    let tokf_path = std::env::current_exe().context("could not determine tokf executable path")?;
-    let tokf_path_str = tokf_path.to_string_lossy();
-    // R4: Use serde_json for proper JSON string escaping instead of manual replacement.
-    let escaped = escape_for_js_string(tokf_path_str.as_ref())?;
-    let content = PLUGIN_TEMPLATE.replace("{{TOKF_PATH}}", &escaped);
+    // Use serde_json for proper JS/JSON string escaping (handles \n, \r, \t, etc.).
+    // serde_json::to_string wraps in quotes — strip them for template substitution.
+    let json_str = serde_json::to_string(tokf_bin)
+        .with_context(|| format!("failed to JSON-escape tokf binary: {tokf_bin}"))?;
+    let js_escaped = &json_str[1..json_str.len() - 1];
+    let content = PLUGIN_TEMPLATE.replace("{{TOKF_BIN}}", js_escaped);
 
     let plugin_file = plugin_dir.join("tokf.ts");
-    std::fs::write(&plugin_file, &content)
+    std::fs::write(&plugin_file, content)
         .with_context(|| format!("failed to write plugin file: {}", plugin_file.display()))?;
 
     Ok(())
@@ -100,7 +94,7 @@ mod tests {
         let dir = TempDir::new().unwrap();
         let plugin_dir = dir.path().join("plugins");
 
-        install_to(&plugin_dir).unwrap();
+        install_to(&plugin_dir, "tokf").unwrap();
 
         assert!(plugin_dir.join("tokf.ts").exists());
     }
@@ -110,34 +104,62 @@ mod tests {
         let dir = TempDir::new().unwrap();
         let plugin_dir = dir.path().join("plugins");
 
-        install_to(&plugin_dir).unwrap();
-        install_to(&plugin_dir).unwrap();
+        install_to(&plugin_dir, "tokf").unwrap();
+        install_to(&plugin_dir, "tokf").unwrap();
 
         // Only one file exists, no errors
         let entries: Vec<_> = std::fs::read_dir(&plugin_dir).unwrap().collect();
         assert_eq!(entries.len(), 1);
     }
 
     #[test]
-    fn write_plugin_embeds_tokf_path() {
+    fn write_plugin_uses_bare_tokf() {
         let dir = TempDir::new().unwrap();
         let plugin_dir = dir.path().join("plugins");
 
-        write_plugin_file(&plugin_dir).unwrap();
+        write_plugin_file(&plugin_dir, "tokf").unwrap();
 
         let content = std::fs::read_to_string(plugin_dir.join("tokf.ts")).unwrap();
-        // Should not contain the template placeholder
-        assert!(!content.contains("{{TOKF_PATH}}"));
-        // Should contain something that looks like an executable path
-        assert!(content.contains("const TOKF_BIN"));
+        assert!(
+            content.contains(r#"const TOKF_BIN = "tokf";"#),
+            "should use bare tokf, got: {content}"
+        );
+    }
+
+    #[test]
+    fn write_plugin_custom_path() {
+        let dir = TempDir::new().unwrap();
+        let plugin_dir = dir.path().join("plugins");
+
+        write_plugin_file(&plugin_dir, "/opt/bin/tokf").unwrap();
+
+        let content = std::fs::read_to_string(plugin_dir.join("tokf.ts")).unwrap();
+        assert!(
+            content.contains(r#"const TOKF_BIN = "/opt/bin/tokf";"#),
+            "should use custom path, got: {content}"
+        );
+    }
+
+    #[test]
+    fn write_plugin_escapes_backslash_in_path() {
+        let dir = TempDir::new().unwrap();
+        let plugin_dir = dir.path().join("plugins");
+
+        write_plugin_file(&plugin_dir, r"C:\Users\me\tokf.exe").unwrap();
+
+        let content = std::fs::read_to_string(plugin_dir.join("tokf.ts")).unwrap();
+        assert!(
+            content.contains(r#"const TOKF_BIN = "C:\\Users\\me\\tokf.exe";"#),
+            "backslashes should be escaped for JS, got: {content}"
+        );
     }
 
     #[test]
     fn write_plugin_rewrites_bash_tool_name() {
         let dir = TempDir::new().unwrap();
         let plugin_dir = dir.path().join("plugins");
 
-        write_plugin_file(&plugin_dir).unwrap();
+        write_plugin_file(&plugin_dir, "tokf").unwrap();
 
         let content = std::fs::read_to_string(plugin_dir.join("tokf.ts")).unwrap();
         assert!(content.contains(r#"input.tool !== "bash""#));
@@ -169,41 +191,15 @@ mod tests {
         assert!(PLUGIN_TEMPLATE.contains("[tokf] plugin error:"));
     }
 
-    // R10: Test the path escaping helper handles special characters.
-    #[test]
-    fn escape_for_js_string_handles_special_chars() {
-        // Test that backslashes get escaped
-        assert!(
-            escape_for_js_string("C:\\Users\\foo\\tokf")
-                .unwrap()
-                .contains("\\\\")
-        );
-        // Test that quotes are escaped as \" (i.e. the result contains \" not a bare ").
-        // serde_json produces the JS-safe escape sequence.
-        let escaped = escape_for_js_string("path\"with\"quotes").unwrap();
-        assert!(
-            escaped.contains("\\\""),
-            "quotes should be backslash-escaped"
-        );
-        // The result must be safe to embed inside a JS double-quoted string:
-        // it should not contain an unescaped double quote (any " must be preceded by \).
-        let unescaped_quote = escaped
-            .chars()
-            .zip(std::iter::once(' ').chain(escaped.chars()))
-            .any(|(ch, prev)| ch == '"' && prev != '\\');
-        assert!(!unescaped_quote, "must not contain unescaped double quote");
-    }
-
-    // R10: Verify no placeholder remains after write.
     #[test]
     fn write_plugin_no_placeholder_remains() {
         let dir = TempDir::new().unwrap();
         let plugin_dir = dir.path().join("plugins");
 
-        write_plugin_file(&plugin_dir).unwrap();
+        write_plugin_file(&plugin_dir, "tokf").unwrap();
 
         let content = std::fs::read_to_string(plugin_dir.join("tokf.ts")).unwrap();
-        assert!(!content.contains("{{TOKF_PATH}}"));
+        assert!(!content.contains("{{TOKF_BIN}}"));
         assert!(content.contains("const TOKF_BIN"));
     }
 }

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

@@ -262,7 +262,7 @@ fn write_hook_shim_creates_executable_script() {
     let hook_dir = dir.path().join("hooks");
     let hook_script = hook_dir.join("pre-tool-use.sh");
 
-    write_hook_shim(&hook_dir, &hook_script).unwrap();
+    write_hook_shim(&hook_dir, &hook_script, "tokf").unwrap();
 
     let content = std::fs::read_to_string(&hook_script).unwrap();
     assert!(content.starts_with("#!/bin/sh\n"));
@@ -280,18 +280,47 @@ fn write_hook_shim_creates_executable_script() {
 }
 
 #[test]
-fn write_hook_shim_quotes_path() {
+fn write_hook_shim_uses_bare_tokf() {
     let dir = tempfile::TempDir::new().unwrap();
     let hook_dir = dir.path().join("hooks");
     let hook_script = hook_dir.join("pre-tool-use.sh");
 
-    write_hook_shim(&hook_dir, &hook_script).unwrap();
+    write_hook_shim(&hook_dir, &hook_script, "tokf").unwrap();
 
     let content = std::fs::read_to_string(&hook_script).unwrap();
-    // The exec line should contain single quotes around the path
     assert!(
-        content.contains("exec '"),
-        "expected quoted path in script, got: {content}"
+        content.contains("exec tokf hook handle"),
+        "expected bare tokf in script, got: {content}"
+    );
+}
+
+#[test]
+fn write_hook_shim_custom_path() {
+    let dir = tempfile::TempDir::new().unwrap();
+    let hook_dir = dir.path().join("hooks");
+    let hook_script = hook_dir.join("pre-tool-use.sh");
+
+    write_hook_shim(&hook_dir, &hook_script, "/opt/bin/tokf").unwrap();
+
+    let content = std::fs::read_to_string(&hook_script).unwrap();
+    assert!(
+        content.contains("exec '/opt/bin/tokf' hook handle"),
+        "expected shell-escaped custom path, got: {content}"
+    );
+}
+
+#[test]
+fn write_hook_shim_path_with_spaces() {
+    let dir = tempfile::TempDir::new().unwrap();
+    let hook_dir = dir.path().join("hooks");
+    let hook_script = hook_dir.join("pre-tool-use.sh");
+
+    write_hook_shim(&hook_dir, &hook_script, "/home/my user/bin/tokf").unwrap();
+
+    let content = std::fs::read_to_string(&hook_script).unwrap();
+    assert!(
+        content.contains("exec '/home/my user/bin/tokf' hook handle"),
+        "path with spaces should be shell-escaped, got: {content}"
     );
 }
 
@@ -303,7 +332,7 @@ fn install_to_creates_files() {
     let hook_dir = dir.path().join("global/tokf/hooks");
     let settings_path = dir.path().join("global/.claude/settings.json");
 
-    install_to(&hook_dir, &settings_path).unwrap();
+    install_to(&hook_dir, &settings_path, "tokf").unwrap();
 
     let hook_script = hook_dir.join("pre-tool-use.sh");
     assert!(hook_script.exists(), "hook script should exist");
@@ -321,8 +350,8 @@ fn install_to_idempotent() {
     let hook_dir = dir.path().join(".tokf/hooks");
     let settings_path = dir.path().join("settings.json");
 
-    install_to(&hook_dir, &settings_path).unwrap();
-    install_to(&hook_dir, &settings_path).unwrap();
+    install_to(&hook_dir, &settings_path, "tokf").unwrap();
+    install_to(&hook_dir, &settings_path, "tokf").unwrap();
 
     let content = std::fs::read_to_string(&settings_path).unwrap();
     let value: serde_json::Value = serde_json::from_str(&content).unwrap();