feat: add env vars to terminal hooks and fix on_worktree_close branch

Terminal hooks (on_create, shell_wrapper) previously received zero
environment variables. Now they export OKENA_PROJECT_ID, OKENA_PROJECT_NAME,
OKENA_PROJECT_PATH, and OKENA_BRANCH (for worktree projects) into the
shell session so they persist after the hook command runs.

Also adds OKENA_TERMINAL_NAME and OKENA_BRANCH to terminal.on_close,
and fixes on_worktree_close being the only worktree hook missing
OKENA_BRANCH.

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

Author: neumie

crates/okena-views-terminal/src/layout/terminal_pane/mod.rs

@@ -359,7 +359,8 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             &settings.default_shell,
         );
 
-        let (project_path, _project_name, project_hooks, parent_hooks) = {
+        // Read fresh path and project info from workspace state
+        let (project_path, project_name, project_hooks, parent_hooks, is_worktree) = {
             let project = ws.project(&self.project_id);
             let path = project.map(|p| p.path.clone())
                 .unwrap_or_else(|| self.project_path.clone());
@@ -369,19 +370,21 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
                 .and_then(|p| p.worktree_info.as_ref())
                 .and_then(|wt| ws.project(&wt.parent_project_id))
                 .map(|p| p.hooks.clone());
-            (path, name, hooks_cfg, parent)
+            let is_wt = project.map(|p| p.worktree_info.is_some()).unwrap_or(false);
+            (path, name, hooks_cfg, parent, is_wt)
         };
 
-        // Apply shell_wrapper if configured - need global hooks from settings
-        // This requires accessing the main app's settings which we don't have directly.
-        // The hooks are resolved through okena_workspace which reads from workspace state.
+        let env = hooks::terminal_hook_env(&self.project_id, &project_name, &project_path, is_worktree);
+
+        // Apply shell_wrapper if configured
         let global_hooks = settings.hooks;
         if let Some(wrapper) = hooks::resolve_shell_wrapper(&project_hooks, parent_hooks.as_ref(), &global_hooks) {
-            shell = hooks::apply_shell_wrapper(&shell, &wrapper);
+            shell = hooks::apply_shell_wrapper(&shell, &wrapper, &env);
         }
 
+        // Apply on_create: wrap shell to run command first, then exec into shell
         if let Some(cmd) = hooks::resolve_terminal_on_create_simple(&project_hooks, parent_hooks.as_ref(), &global_hooks) {
-            shell = hooks::apply_on_create(&shell, &cmd);
+            shell = hooks::apply_on_create(&shell, &cmd, &env);
         }
 
         match self

crates/okena-workspace/src/actions/project.rs

@@ -644,14 +644,17 @@ impl Workspace {
         // for backwards compatibility with worktrees created before monorepo support
         let worktree_path = std::path::PathBuf::from(&project_path);
 
+        // Resolve branch BEFORE removal (git worktree remove deletes the checkout)
+        let branch = okena_git::get_current_branch(&worktree_path).unwrap_or_default();
+
         // Remove the git worktree
         okena_git::remove_worktree(&worktree_path, force)?;
 
         // Delete the project from workspace (this also fires on_project_close)
         self.delete_project(project_id, global_hooks, cx);
 
         // Fire worktree-specific hook (runs headlessly since project is deleted)
-        hooks::fire_on_worktree_close(&project_hooks, project_id, &project_name, &project_path, global_hooks, cx);
+        hooks::fire_on_worktree_close(&project_hooks, project_id, &project_name, &project_path, &branch, global_hooks, cx);
 
         Ok(())
     }

crates/okena-workspace/src/hooks.rs

@@ -160,6 +160,67 @@ fn is_valid_env_key(key: &str) -> bool {
     bytes[1..].iter().all(|&b| b.is_ascii_alphanumeric() || b == b'_')
 }
 
+/// Build shell export statements from a HashMap of env vars.
+/// POSIX: `export KEY='value'; ` with single-quote escaping.
+/// Windows: `set "KEY=value" && ` with cmd.exe escaping.
+fn build_export_prefix(env_vars: &HashMap<String, String>) -> String {
+    let safe_env: Vec<_> = env_vars
+        .iter()
+        .filter(|(k, _)| is_valid_env_key(k))
+        .collect();
+
+    if safe_env.is_empty() {
+        return String::new();
+    }
+
+    if cfg!(windows) {
+        let parts: Vec<_> = safe_env
+            .iter()
+            .map(|(k, v)| {
+                let escaped = v
+                    .replace('^', "^^")
+                    .replace('%', "%%")
+                    .replace('"', "\\\"")
+                    .replace('&', "^&")
+                    .replace('|', "^|")
+                    .replace('<', "^<")
+                    .replace('>', "^>")
+                    .replace('(', "^(")
+                    .replace(')', "^)");
+                format!("set \"{}={}\"", k, escaped)
+            })
+            .collect();
+        format!("{} && ", parts.join(" && "))
+    } else {
+        let parts: Vec<_> = safe_env
+            .iter()
+            .map(|(k, v)| format!("export {}='{}'; ", k, v.replace('\'', "'\\''")))
+            .collect();
+        parts.join("")
+    }
+}
+
+/// Build environment variables for terminal hooks.
+/// Includes base project vars and, for worktree projects, OKENA_BRANCH.
+pub fn terminal_hook_env(
+    project_id: &str,
+    project_name: &str,
+    project_path: &str,
+    is_worktree: bool,
+) -> HashMap<String, String> {
+    let mut env = project_env(project_id, project_name, project_path);
+    if is_worktree {
+        let path = std::path::Path::new(project_path);
+        let branch = okena_git::get_git_status(path)
+            .and_then(|s| s.branch)
+            .or_else(|| okena_git::get_current_branch(path));
+        if let Some(branch) = branch {
+            env.insert("OKENA_BRANCH".into(), branch);
+        }
+    }
+    env
+}
+
 /// Build a `std::process::Command` for headless hook execution.
 /// Handles platform dispatch (sh -c / cmd /C), env vars, and cwd.
 fn build_headless_command(command: &str, env_vars: &HashMap<String, String>) -> std::process::Command {
@@ -558,12 +619,14 @@ pub fn fire_on_worktree_close(
     project_id: &str,
     project_name: &str,
     project_path: &str,
+    branch: &str,
     global_hooks: &HooksConfig,
     cx: &App,
 ) {
     if let Some(cmd) = resolve_hook(project_hooks, global_hooks, |h| &h.worktree.on_close) {
-        let env = project_env(project_id, project_name, project_path);
-        log::info!("Running on_worktree_close hook for project '{}'", project_name);
+        let mut env = project_env(project_id, project_name, project_path);
+        env.insert("OKENA_BRANCH".into(), branch.into());
+        log::info!("Running on_worktree_close hook for project '{}' (branch: {})", project_name, branch);
         let monitor = try_monitor(cx);
         run_hook(cmd, env, monitor.as_ref(), "on_worktree_close", project_name, None, project_id, true);
     }
@@ -777,10 +840,12 @@ pub fn resolve_terminal_on_create_simple(
 
 /// Apply the `terminal.on_create` command by wrapping the shell to run
 /// the command first, then `exec` into the original shell.
-/// Produces: `sh -c '<on_create_cmd>; exec <shell_cmd>'`
-pub fn apply_on_create(shell: &ShellType, on_create_cmd: &str) -> ShellType {
+/// Environment variables are exported so they persist in the shell session.
+/// Produces: `sh -c 'export K=V; ...; <on_create_cmd>; exec <shell_cmd>'`
+pub fn apply_on_create(shell: &ShellType, on_create_cmd: &str, env_vars: &HashMap<String, String>) -> ShellType {
     let shell_cmd = shell.to_command_string();
-    let script = format!("{}; exec {}", on_create_cmd, shell_cmd);
+    let prefix = build_export_prefix(env_vars);
+    let script = format!("{}{}; exec {}", prefix, on_create_cmd, shell_cmd);
     ShellType::for_command(script)
 }
 
@@ -793,16 +858,30 @@ pub fn fire_terminal_on_close(
     project_name: &str,
     project_path: &str,
     terminal_id: &str,
+    terminal_name: Option<&str>,
+    is_worktree: bool,
     exit_code: Option<u32>,
     global_hooks: &HooksConfig,
     cx: &App,
 ) {
     if let Some(cmd) = resolve_hook_with_parent(project_hooks, parent_hooks, global_hooks, |h| &h.terminal.on_close) {
         let mut env = project_env(project_id, project_name, project_path);
         env.insert("OKENA_TERMINAL_ID".into(), terminal_id.into());
+        if let Some(name) = terminal_name {
+            env.insert("OKENA_TERMINAL_NAME".into(), name.into());
+        }
         if let Some(code) = exit_code {
             env.insert("OKENA_EXIT_CODE".into(), code.to_string());
         }
+        if is_worktree {
+            let path = std::path::Path::new(project_path);
+            let branch = okena_git::get_git_status(path)
+                .and_then(|s| s.branch)
+                .or_else(|| okena_git::get_current_branch(path));
+            if let Some(branch) = branch {
+                env.insert("OKENA_BRANCH".into(), branch);
+            }
+        }
         log::info!("Running terminal.on_close hook for terminal '{}'", terminal_id);
         let monitor = try_monitor(cx);
         run_hook(cmd, env, monitor.as_ref(), "terminal.on_close", project_name, None, project_id, true);
@@ -821,20 +900,22 @@ pub fn resolve_shell_wrapper(
 
 /// Apply shell_wrapper to a ShellType, producing a new ShellType.
 /// The wrapper template uses `{shell}` as a placeholder for the resolved shell command.
+/// Environment variables are exported so they persist in the shell session.
 ///
 /// If the result contains shell metacharacters (`&&`, `||`, `;`, `|`), it is wrapped
 /// in `sh -c` for proper execution. Otherwise, it is split into executable + args directly,
 /// avoiding an extra `sh` process layer (important for session backends like dtach/tmux).
 ///
 /// The shell is expected to be already resolved (not `ShellType::Default`).
-pub fn apply_shell_wrapper(shell: &ShellType, wrapper: &str) -> ShellType {
+pub fn apply_shell_wrapper(shell: &ShellType, wrapper: &str, env_vars: &HashMap<String, String>) -> ShellType {
     let shell_cmd = shell.to_command_string();
     // Replace {shell} with `exec <shell>` so the shell replaces the wrapper process.
     // This is critical for session backends (dtach/tmux) that monitor the top-level process.
     let wrapped = wrapper.replace("{shell}", &format!("exec {}", shell_cmd));
+    let prefix = build_export_prefix(env_vars);
     // Always use for_command (sh -c '...') so that build_terminal_command can extract
     // the inner command for session backend integration (dtach/tmux/screen).
-    ShellType::for_command(wrapped)
+    ShellType::for_command(format!("{}{}", prefix, wrapped))
 }
 
 #[cfg(test)]
@@ -1003,7 +1084,7 @@ mod tests {
             args: vec!["--login".to_string()],
         };
         let wrapper = "devcontainer exec -- {shell}";
-        let wrapped = apply_shell_wrapper(&shell, wrapper);
+        let wrapped = apply_shell_wrapper(&shell, wrapper, &HashMap::new());
         match &wrapped {
             ShellType::Custom { path: _, args } => {
                 // for_command uses $SHELL -ic on Unix
@@ -1022,7 +1103,7 @@ mod tests {
             args: vec![],
         };
         let wrapper = "echo hello && {shell}";
-        let wrapped = apply_shell_wrapper(&shell, wrapper);
+        let wrapped = apply_shell_wrapper(&shell, wrapper, &HashMap::new());
         match &wrapped {
             ShellType::Custom { path: _, args } => {
                 // for_command uses $SHELL -ic on Unix
@@ -1041,4 +1122,85 @@ mod tests {
         };
         assert_eq!(shell.to_command_string(), "/usr/bin/fish");
     }
+
+    #[test]
+    fn build_export_prefix_empty() {
+        assert_eq!(build_export_prefix(&HashMap::new()), "");
+    }
+
+    #[test]
+    fn build_export_prefix_single_var() {
+        let mut env = HashMap::new();
+        env.insert("MY_VAR".into(), "hello".into());
+        let prefix = build_export_prefix(&env);
+        assert!(prefix.contains("MY_VAR"), "got: {}", prefix);
+        assert!(prefix.contains("hello"), "got: {}", prefix);
+        if cfg!(windows) {
+            assert!(prefix.contains("set"), "got: {}", prefix);
+        } else {
+            assert!(prefix.contains("export"), "got: {}", prefix);
+        }
+    }
+
+    #[test]
+    fn build_export_prefix_escapes_single_quotes() {
+        let mut env = HashMap::new();
+        env.insert("VAR".into(), "it's a test".into());
+        let prefix = build_export_prefix(&env);
+        if !cfg!(windows) {
+            // POSIX: single quotes with '\'' escaping
+            assert!(prefix.contains("'\\''"), "Expected single-quote escape in: {}", prefix);
+        }
+    }
+
+    #[test]
+    fn build_export_prefix_filters_invalid_keys() {
+        let mut env = HashMap::new();
+        env.insert("GOOD_KEY".into(), "val".into());
+        env.insert("BAD;KEY".into(), "val".into());
+        env.insert("123BAD".into(), "val".into());
+        let prefix = build_export_prefix(&env);
+        assert!(prefix.contains("GOOD_KEY"), "got: {}", prefix);
+        assert!(!prefix.contains("BAD;KEY"), "got: {}", prefix);
+        assert!(!prefix.contains("123BAD"), "got: {}", prefix);
+    }
+
+    #[test]
+    fn apply_on_create_with_env_vars() {
+        let shell = ShellType::Custom {
+            path: "/bin/bash".to_string(),
+            args: vec![],
+        };
+        let mut env = HashMap::new();
+        env.insert("OKENA_PROJECT_ID".into(), "proj-123".into());
+        let result = apply_on_create(&shell, "echo hello", &env);
+        match &result {
+            ShellType::Custom { path: _, args } => {
+                let cmd = &args[1];
+                assert!(cmd.contains("export OKENA_PROJECT_ID="), "got: {}", cmd);
+                assert!(cmd.contains("echo hello"), "got: {}", cmd);
+                assert!(cmd.contains("exec /bin/bash"), "got: {}", cmd);
+            }
+            other => panic!("Expected ShellType::Custom, got: {:?}", other),
+        }
+    }
+
+    #[test]
+    fn apply_shell_wrapper_with_env_vars() {
+        let shell = ShellType::Custom {
+            path: "/bin/zsh".to_string(),
+            args: vec![],
+        };
+        let mut env = HashMap::new();
+        env.insert("OKENA_PROJECT_NAME".into(), "my-project".into());
+        let result = apply_shell_wrapper(&shell, "wrapper {shell}", &env);
+        match &result {
+            ShellType::Custom { path: _, args } => {
+                let cmd = &args[1];
+                assert!(cmd.contains("export OKENA_PROJECT_NAME="), "got: {}", cmd);
+                assert!(cmd.contains("wrapper exec /bin/zsh"), "got: {}", cmd);
+            }
+            other => panic!("Expected ShellType::Custom, got: {:?}", other),
+        }
+    }
 }

docs/hooks.md

@@ -91,6 +91,14 @@ Available on worktree and merge hooks.
 | `OKENA_TARGET_BRANCH` | Target branch for merge operations (`pre_merge`, `post_merge`, `on_rebase_conflict`) |
 | `OKENA_MAIN_REPO_PATH` | Path to the main repository (merge and worktree-remove hooks) |
 
+### Terminal variables
+
+| Variable | Description |
+|----------|-------------|
+| `OKENA_TERMINAL_ID` | Unique ID of the terminal (`terminal.on_close` only) |
+| `OKENA_TERMINAL_NAME` | Custom name of the terminal, if set (`terminal.on_close` only) |
+| `OKENA_EXIT_CODE` | Exit code of the terminal process (`terminal.on_close` only) |
+
 ### Conflict variables
 
 | Variable | Description |
@@ -99,18 +107,23 @@ Available on worktree and merge hooks.
 
 ### Variable availability by hook
 
-| Hook | `BRANCH` | `TARGET_BRANCH` | `MAIN_REPO_PATH` | `REBASE_ERROR` |
-|------|----------|-----------------|-------------------|----------------|
-| `on_project_open` | | | | |
-| `on_project_close` | | | | |
-| `on_worktree_create` | yes | | | |
-| `on_worktree_close` | | | | |
-| `pre_merge` | yes | yes | yes | |
-| `post_merge` | yes | yes | yes | |
-| `before_worktree_remove` | yes | | yes | |
-| `worktree_removed` | yes | | yes | |
-| `on_rebase_conflict` | yes | yes | yes | yes |
-| `on_dirty_worktree_close` | yes | | | |
+| Hook | `PROJECT_*` | `BRANCH` | `TARGET_BRANCH` | `MAIN_REPO_PATH` | `REBASE_ERROR` | `TERMINAL_ID` | `TERMINAL_NAME` | `EXIT_CODE` |
+|------|-------------|----------|-----------------|-------------------|----------------|---------------|-----------------|-------------|
+| `on_project_open` | yes | | | | | | | |
+| `on_project_close` | yes | | | | | | | |
+| `on_worktree_create` | yes | yes | | | | | | |
+| `on_worktree_close` | yes | yes | | | | | | |
+| `pre_merge` | yes | yes | yes | yes | | | | |
+| `post_merge` | yes | yes | yes | yes | | | | |
+| `before_worktree_remove` | yes | yes | | yes | | | | |
+| `worktree_removed` | yes | yes | | yes | | | | |
+| `on_rebase_conflict` | yes | yes | yes | yes | yes | | | |
+| `on_dirty_worktree_close` | yes | yes | | | | | | |
+| `terminal.on_create` | yes | worktree | | | | | | |
+| `terminal.shell_wrapper` | yes | worktree | | | | | | |
+| `terminal.on_close` | yes | worktree | | | | yes | if set | yes |
+
+For `terminal.on_create` and `terminal.shell_wrapper`, environment variables are exported into the shell session so they persist after the hook command runs. For worktree projects, `OKENA_BRANCH` is included automatically.
 
 ## Hook Monitor