harness-hooks 0.1.0__tar.gz

harness_hooks-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+dist/

harness_hooks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Pertsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harness_hooks-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: harness-hooks
+Version: 0.1.0
+Summary: Installs the hooks that a config file lists into Claude Code and Codex, and removes them
+Project-URL: Homepage, https://github.com/a-pertsev/harness-hooks
+Author: Alexei Pertsev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,hooks
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# harness-hooks
+
+Installs the hooks that a config file lists into Claude Code and Codex, and removes them.
+Works on macOS and Linux.
+
+Run it with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx harness-hooks install path/to/harness-hooks.json
+uvx harness-hooks remove path/to/harness-hooks.json
+```
+
+Or install it once, which puts `harness-hooks` on your `PATH`:
+
+```sh
+uv tool install harness-hooks
+```
+
+## Config
+
+```json
+{
+  "name": "notify",
+  "files": ["notify.py"],
+  "hooks": {
+    "Stop": [{"command": "python3 {dir}/notify.py {agent}", "timeout": 5}]
+  },
+  "claude": {
+    "Notification": [{"matcher": "idle_prompt", "command": "python3 {dir}/notify.py claude"}]
+  },
+  "codex": {
+    "PreToolUse": [{"matcher": "^request_user_input", "command": "python3 {dir}/notify.py codex"}]
+  }
+}
+```
+
+- `hooks` go to both agents, `claude` and `codex` only to that agent.
+- `{dir}` becomes the folder with the hooks' files, so hooks can call scripts there.
+  `{agent}` becomes `claude` or `codex`.
+- `matcher` and `command` mean what they mean in each agent's own hook files. Other
+  fields, such as `timeout`, are copied as they are.
+- `files`, if given, lists the files the hooks need, as paths inside the config's folder.
+
+## Copies
+
+With `files` in the config, `install` copies those files to `~/.claude/harness-hooks/<name>/`
+and `~/.codex/harness-hooks/<name>/`, and `{dir}` points there. The hooks keep working when
+the config's folder moves or is deleted. Run `install` again to bring in changed files;
+`remove` deletes the copies.
+
+Without `files`, or with `--editable`, `{dir}` is the config's folder, so an edit takes
+effect at once. `--editable` also deletes copies left by an earlier `install`. `--project`
+never copies.
+
+## Where hooks go
+
+By default into `~/.claude/settings.json` and `~/.codex/hooks.json`, so they run in every
+project. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` move these files, as they do for the agents.
+
+With `--project`, into `.claude/settings.json` and `.codex/hooks.json` of the git repository
+that holds the config. Commit them, and everyone who clones the repository gets the hooks.
+`{dir}` is then found from the repository root, so the hooks work in any clone.
+Claude reads them only in sessions started at the repository root. Codex reads them only
+after you trust the project.
+
+`--agent claude` or `--agent codex` touches only that agent.
+
+## How it finds its hooks
+
+Each installed command ends with `# harness-hooks: <name>`. `install` replaces the commands
+with that mark and `remove` deletes them, so a hook dropped from the config disappears on
+the next run. Keep `name` the same once installed. It is also the copies' folder name, so it
+can't hold `/`. Hooks without the mark, such as ones you added by hand, are left alone, and
+the rest of each file is kept.
+
+Codex asks you to review new or changed hooks at its next start. It remembers approvals
+by a hook's place in the file, so removing hooks can make it ask again about the hooks
+after them.
+
+## Development
+
+From a clone, `uv tool install --editable .` runs the code in the clone, so an edit takes
+effect at once.
+
+```sh
+python3 -m unittest
+```

harness_hooks-0.1.0/README.md

@@ -0,0 +1,87 @@
+# harness-hooks
+
+Installs the hooks that a config file lists into Claude Code and Codex, and removes them.
+Works on macOS and Linux.
+
+Run it with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx harness-hooks install path/to/harness-hooks.json
+uvx harness-hooks remove path/to/harness-hooks.json
+```
+
+Or install it once, which puts `harness-hooks` on your `PATH`:
+
+```sh
+uv tool install harness-hooks
+```
+
+## Config
+
+```json
+{
+  "name": "notify",
+  "files": ["notify.py"],
+  "hooks": {
+    "Stop": [{"command": "python3 {dir}/notify.py {agent}", "timeout": 5}]
+  },
+  "claude": {
+    "Notification": [{"matcher": "idle_prompt", "command": "python3 {dir}/notify.py claude"}]
+  },
+  "codex": {
+    "PreToolUse": [{"matcher": "^request_user_input", "command": "python3 {dir}/notify.py codex"}]
+  }
+}
+```
+
+- `hooks` go to both agents, `claude` and `codex` only to that agent.
+- `{dir}` becomes the folder with the hooks' files, so hooks can call scripts there.
+  `{agent}` becomes `claude` or `codex`.
+- `matcher` and `command` mean what they mean in each agent's own hook files. Other
+  fields, such as `timeout`, are copied as they are.
+- `files`, if given, lists the files the hooks need, as paths inside the config's folder.
+
+## Copies
+
+With `files` in the config, `install` copies those files to `~/.claude/harness-hooks/<name>/`
+and `~/.codex/harness-hooks/<name>/`, and `{dir}` points there. The hooks keep working when
+the config's folder moves or is deleted. Run `install` again to bring in changed files;
+`remove` deletes the copies.
+
+Without `files`, or with `--editable`, `{dir}` is the config's folder, so an edit takes
+effect at once. `--editable` also deletes copies left by an earlier `install`. `--project`
+never copies.
+
+## Where hooks go
+
+By default into `~/.claude/settings.json` and `~/.codex/hooks.json`, so they run in every
+project. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` move these files, as they do for the agents.
+
+With `--project`, into `.claude/settings.json` and `.codex/hooks.json` of the git repository
+that holds the config. Commit them, and everyone who clones the repository gets the hooks.
+`{dir}` is then found from the repository root, so the hooks work in any clone.
+Claude reads them only in sessions started at the repository root. Codex reads them only
+after you trust the project.
+
+`--agent claude` or `--agent codex` touches only that agent.
+
+## How it finds its hooks
+
+Each installed command ends with `# harness-hooks: <name>`. `install` replaces the commands
+with that mark and `remove` deletes them, so a hook dropped from the config disappears on
+the next run. Keep `name` the same once installed. It is also the copies' folder name, so it
+can't hold `/`. Hooks without the mark, such as ones you added by hand, are left alone, and
+the rest of each file is kept.
+
+Codex asks you to review new or changed hooks at its next start. It remembers approvals
+by a hook's place in the file, so removing hooks can make it ask again about the hooks
+after them.
+
+## Development
+
+From a clone, `uv tool install --editable .` runs the code in the clone, so an edit takes
+effect at once.
+
+```sh
+python3 -m unittest
+```

harness_hooks-0.1.0/harness_hooks.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Installs the hooks that a config file lists into Claude Code and Codex, and removes them.
+
+Usage: harness-hooks install|remove CONFIG [--project] [--editable] [--agent claude|codex]
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+
+AGENTS = ("claude", "codex")
+PROJECT_FILES = {"claude": ".claude/settings.json", "codex": ".codex/hooks.json"}
+# Codex runs a hook in the folder the session started in, which can be below the project root.
+PROJECT_ROOT = '"$(git rev-parse --show-toplevel)"'
+
+
+def hook_file(agent, project):
+    if project:
+        return project / PROJECT_FILES[agent]
+    if agent == "claude":
+        return Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")) / "settings.json"
+    return Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")) / "hooks.json"
+
+
+def git_root(folder):
+    result = subprocess.run(["git", "-C", str(folder), "rev-parse", "--show-toplevel"], capture_output=True, text=True)
+    if result.returncode:
+        sys.exit(f"--project needs the config inside a git repository: {result.stderr.strip()}")
+    return Path(result.stdout.strip())
+
+
+def config_dir(folder, project):
+    if not project:
+        return shlex.quote(str(folder))
+    rel = folder.relative_to(project)
+    return PROJECT_ROOT + ("" if rel == Path() else "/" + shlex.quote(str(rel)))
+
+
+def build(config, agent, folder, tag):
+    events = {}
+    for block in (config.get("hooks", {}), config.get(agent, {})):
+        for event, entries in block.items():
+            for entry in entries:
+                handler = {"type": "command", **entry}
+                matcher = handler.pop("matcher", None)
+                handler["command"] = handler["command"].replace("{dir}", folder).replace("{agent}", agent) + tag
+                group = {} if matcher is None else {"matcher": matcher}
+                group["hooks"] = [handler]
+                events.setdefault(event, []).append(group)
+    return events
+
+
+def strip(hooks, tag):
+    kept = {}
+    for event, groups in hooks.items():
+        groups = [{**g, "hooks": [h for h in g["hooks"] if not h.get("command", "").endswith(tag)]} for g in groups]
+        groups = [g for g in groups if g["hooks"]]
+        if groups:
+            kept[event] = groups
+    return kept
+
+
+def write(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    with os.fdopen(fd, "w") as f:
+        f.write(text)
+    if path.exists():
+        shutil.copymode(path, tmp)
+    os.replace(tmp, path)
+
+
+def copy(folder, files, target):
+    """Builds the copy aside and swaps it in, so a hook never runs from a half-copied folder."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fresh = Path(tempfile.mkdtemp(dir=target.parent))
+    for name in files:
+        (fresh / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(folder / name, fresh / name)
+    old = fresh.with_suffix(".old")
+    if target.exists():
+        os.rename(target, old)
+    os.rename(fresh, target)
+    shutil.rmtree(old, ignore_errors=True)
+
+
+def update(path, tag, new):
+    """Replaces the hooks carrying the tag with the new ones; returns whether the file changed."""
+    # Writing through a symlink keeps a settings file that lives elsewhere, such as in dotfiles.
+    path = path.resolve()
+    data = json.loads(path.read_text()) if path.exists() else {}
+    old = data.get("hooks", {})
+    hooks = strip(old, tag)
+    for event, groups in new.items():
+        hooks.setdefault(event, []).extend(groups)
+    if hooks == old:
+        return False
+    if hooks:
+        data["hooks"] = hooks
+    else:
+        data.pop("hooks", None)
+    write(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Installs the hooks a config file lists into Claude Code and Codex, and removes them.")
+    parser.add_argument("action", choices=["install", "remove"])
+    parser.add_argument("config", type=Path)
+    parser.add_argument("--project", action="store_true", help="use the hook files of the git repository that holds the config, for everyone who clones it")
+    parser.add_argument("--editable", action="store_true", help="run hooks from the config's folder instead of a copy of its files, so edits take effect at once")
+    parser.add_argument("--agent", choices=AGENTS, help="only this agent")
+    args = parser.parse_args()
+
+    path = args.config.resolve()
+    config = json.loads(path.read_text())
+    if "name" not in config or set(config) - {"name", "files", "hooks", *AGENTS}:
+        sys.exit(f"{path}: needs a name, and allows only files, hooks, claude and codex besides it")
+    name = config["name"]
+    # The name is also a folder that remove deletes, so it must not lead out of its parent.
+    if name in ("", ".", "..") or "/" in name:
+        sys.exit(f"{path}: name must be a plain folder name")
+    files = config.get("files", [])
+    if args.action == "install":
+        for file in files:
+            if Path(file).is_absolute() or ".." in Path(file).parts or not (path.parent / file).is_file():
+                sys.exit(f"{path}: {file} is not a file in {path.parent}")
+    project = git_root(path.parent) if args.project else None
+    copying = args.action == "install" and bool(files) and not args.editable and not project
+    # Marks every installed command, so remove finds it even after the config changed.
+    tag = f" # harness-hooks: {name}"
+    folder = config_dir(path.parent, project)
+    for agent in [args.agent] if args.agent else AGENTS:
+        target = hook_file(agent, project)
+        # Next to the agent's own settings, so the hooks keep working after the config's folder moves.
+        copy_dir = target.parent / "harness-hooks" / name
+        if copying:
+            copy(path.parent, files, copy_dir)
+            print(f"{agent}: copied {', '.join(files)} to {copy_dir}")
+        hooks = build(config, agent, shlex.quote(str(copy_dir)) if copying else folder, tag) if args.action == "install" else {}
+        changed = update(target, tag, hooks)
+        print(f"{agent}: {'updated' if changed else 'unchanged'} {target}")
+        if not copying and not project and copy_dir.exists():
+            shutil.rmtree(copy_dir)
+            print(f"{agent}: removed {copy_dir}")
+        if agent == "codex" and changed and hooks:
+            print("codex: asks you to review the new hooks at its next start")
+
+
+if __name__ == "__main__":
+    main()

harness_hooks-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "harness-hooks"
+version = "0.1.0"
+description = "Installs the hooks that a config file lists into Claude Code and Codex, and removes them"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Alexei Pertsev"}]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["claude-code", "codex", "hooks"]
+classifiers = [
+  "Environment :: Console",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/a-pertsev/harness-hooks"
+
+[project.scripts]
+harness-hooks = "harness_hooks:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["harness_hooks.py"]

harness_hooks-0.1.0/test_harness_hooks.py

@@ -0,0 +1,222 @@
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+TOOL = Path(__file__).with_name("harness_hooks.py")
+
+
+class HarnessHooksTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = root = Path(self.tmp.name).resolve()
+        self.repo = root / "repo"
+        self.tools = self.repo / "tools"
+        self.tools.mkdir(parents=True)
+        # Stands in for a hook script: records how it was called next to itself.
+        script = self.tools / "log.sh"
+        script.write_text('#!/bin/sh\necho "$@" >> "$(dirname "$0")/log"\n')
+        script.chmod(0o755)
+        self.config = self.tools / "harness-hooks.json"
+        self.write_config({
+            "name": "demo",
+            "hooks": {"Stop": [{"command": "{dir}/log.sh {agent} Stop", "timeout": 5}]},
+            "claude": {"PreToolUse": [{"matcher": "AskUserQuestion", "command": "{dir}/log.sh claude ask"}]},
+            "codex": {"PreToolUse": [{"matcher": "^request_user_input", "command": "{dir}/log.sh codex ask"}]},
+        })
+        self.claude_file = root / "claude" / "settings.json"
+        self.codex_file = root / "codex" / "hooks.json"
+        self.env = {**os.environ, "CLAUDE_CONFIG_DIR": str(root / "claude"), "CODEX_HOME": str(root / "codex")}
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def write_config(self, config):
+        self.config.write_text(json.dumps(config))
+
+    def run_tool(self, *args, check=True):
+        return subprocess.run([sys.executable, TOOL, *args], text=True, capture_output=True, env=self.env, check=check)
+
+    def commands(self, path):
+        hooks = json.loads(path.read_text())["hooks"]
+        return {event: [(g.get("matcher"), h["command"]) for g in groups for h in g["hooks"]] for event, groups in hooks.items()}
+
+    def run_hook(self, command, cwd, log, env=None):
+        subprocess.run(["/bin/sh", "-c", command], cwd=cwd, env={**os.environ, **(env or {})}, check=True)
+        return log.read_text().splitlines()[-1]
+
+    def copy_dir(self, agent):
+        return self.root / agent / "harness-hooks" / "demo"
+
+    def write_copied_config(self, files):
+        self.write_config({"name": "demo", "files": files, "hooks": {"Stop": [{"command": "{dir}/log.sh {agent} Stop"}]}})
+
+    def test_install_adds_shared_and_harness_hooks_that_run(self):
+        self.run_tool("install", str(self.config))
+
+        log = self.tools / "log"
+        for path, agent, matcher in [(self.claude_file, "claude", "AskUserQuestion"), (self.codex_file, "codex", "^request_user_input")]:
+            [(stop_matcher, stop)] = self.commands(path)["Stop"]
+            [(ask_matcher, ask)] = self.commands(path)["PreToolUse"]
+            self.assertIsNone(stop_matcher)
+            self.assertEqual(ask_matcher, matcher)
+            self.assertEqual(self.run_hook(stop, "/", log), f"{agent} Stop")
+            self.assertEqual(self.run_hook(ask, "/", log), f"{agent} ask")
+        self.assertEqual(json.loads(self.claude_file.read_text())["hooks"]["Stop"][0]["hooks"][0]["timeout"], 5)
+
+    def test_install_keeps_other_settings_and_hooks_and_repeats_without_changes(self):
+        foreign = {"hooks": [{"type": "command", "command": "notify.sh"}]}
+        self.claude_file.parent.mkdir()
+        self.claude_file.write_text(json.dumps({"model": "opus", "hooks": {"Stop": [foreign]}}))
+
+        self.run_tool("install", str(self.config))
+        first = self.claude_file.read_text()
+        out = self.run_tool("install", str(self.config)).stdout
+
+        self.assertEqual(self.claude_file.read_text(), first)
+        self.assertIn("claude: unchanged", out)
+        settings = json.loads(first)
+        self.assertEqual(settings["model"], "opus")
+        self.assertEqual(settings["hooks"]["Stop"][0], foreign)
+        self.assertEqual(len(settings["hooks"]["Stop"]), 2)
+
+    def test_install_replaces_hooks_of_an_earlier_config(self):
+        self.run_tool("install", str(self.config))
+        self.write_config({"name": "demo", "hooks": {"Stop": [{"command": "{dir}/log.sh new"}]}})
+
+        self.run_tool("install", str(self.config))
+
+        commands = self.commands(self.claude_file)
+        self.assertEqual(list(commands), ["Stop"])
+        [(_, stop)] = commands["Stop"]
+        self.assertEqual(self.run_hook(stop, "/", self.tools / "log"), "new")
+
+    def test_remove_takes_out_only_installed_hooks(self):
+        settings = {"model": "opus", "hooks": {"Stop": [{"hooks": [{"type": "command", "command": "notify.sh"}]}]}}
+        self.claude_file.parent.mkdir()
+        self.claude_file.write_text(json.dumps(settings))
+        self.run_tool("install", str(self.config))
+        self.write_config({"name": "demo"})
+
+        self.run_tool("remove", str(self.config))
+
+        self.assertEqual(json.loads(self.claude_file.read_text()), settings)
+        self.assertEqual(json.loads(self.codex_file.read_text()), {})
+
+    def test_remove_without_install_writes_nothing(self):
+        out = self.run_tool("remove", str(self.config)).stdout
+
+        self.assertIn("claude: unchanged", out)
+        self.assertFalse(self.claude_file.exists())
+        self.assertFalse(self.codex_file.exists())
+
+    def test_install_copies_listed_files_so_hooks_survive_the_config_folder(self):
+        self.write_copied_config(["log.sh"])
+
+        self.run_tool("install", str(self.config))
+        shutil.rmtree(self.repo)
+
+        for path, agent in [(self.claude_file, "claude"), (self.codex_file, "codex")]:
+            [(_, stop)] = self.commands(path)["Stop"]
+            self.assertEqual(self.run_hook(stop, "/", self.copy_dir(agent) / "log"), f"{agent} Stop")
+
+    def test_install_again_replaces_the_copy(self):
+        (self.tools / "notes.txt").write_text("old")
+        self.write_copied_config(["log.sh", "notes.txt"])
+        self.run_tool("install", str(self.config))
+        (self.tools / "log.sh").write_text('#!/bin/sh\necho new "$@" >> "$(dirname "$0")/log"\n')
+        self.write_copied_config(["log.sh"])
+
+        self.run_tool("install", str(self.config))
+
+        [(_, stop)] = self.commands(self.claude_file)["Stop"]
+        self.assertEqual(self.run_hook(stop, "/", self.copy_dir("claude") / "log"), "new claude Stop")
+        self.assertEqual(sorted(p.name for p in self.copy_dir("claude").parent.iterdir()), ["demo"])
+        self.assertFalse((self.copy_dir("claude") / "notes.txt").exists())
+
+    def test_remove_deletes_the_copy(self):
+        self.write_copied_config(["log.sh"])
+        self.run_tool("install", str(self.config))
+
+        self.run_tool("remove", str(self.config))
+
+        self.assertEqual(json.loads(self.claude_file.read_text()), {})
+        self.assertFalse(self.copy_dir("claude").exists())
+        self.assertFalse(self.copy_dir("codex").exists())
+
+    def test_editable_install_runs_from_the_config_folder_and_drops_an_earlier_copy(self):
+        self.write_copied_config(["log.sh"])
+        self.run_tool("install", str(self.config))
+
+        self.run_tool("install", str(self.config), "--editable")
+
+        self.assertFalse(self.copy_dir("claude").exists())
+        [(_, stop)] = self.commands(self.claude_file)["Stop"]
+        self.assertEqual(self.run_hook(stop, "/", self.tools / "log"), "claude Stop")
+
+    def test_file_that_is_not_in_the_config_folder_is_refused(self):
+        for file in ["missing.sh", "../tools/log.sh", str(self.tools / "log.sh")]:
+            with self.subTest(file=file):
+                self.write_copied_config([file])
+
+                result = self.run_tool("install", str(self.config), check=False)
+
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn("is not a file", result.stderr)
+                self.assertFalse(self.claude_file.exists())
+
+    def test_name_that_leads_out_of_its_folder_is_refused(self):
+        # With this folder present, the copy folder of a name ".." is the agent's whole home.
+        (self.root / "claude" / "harness-hooks").mkdir(parents=True)
+        self.claude_file.write_text("{}")
+        self.write_config({"name": ".."})
+
+        result = self.run_tool("remove", str(self.config), check=False)
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertTrue(self.claude_file.exists())
+
+    def test_project_install_runs_scripts_in_a_clone_from_any_of_its_folders(self):
+        subprocess.run(["git", "init", "-q", str(self.repo)], check=True)
+        self.write_config({**json.loads(self.config.read_text()), "files": ["log.sh"]})
+
+        self.run_tool("install", str(self.config), "--project")
+
+        self.assertFalse(self.claude_file.parent.exists())
+        self.assertFalse(self.codex_file.parent.exists())
+        clone = Path(self.tmp.name).resolve() / "clone"
+        shutil.copytree(self.repo, clone)
+        (clone / "sub").mkdir()
+        log = clone / "tools" / "log"
+        [(_, claude_stop)] = self.commands(clone / ".claude/settings.json")["Stop"]
+        [(_, codex_stop)] = self.commands(clone / ".codex/hooks.json")["Stop"]
+        self.assertEqual(self.run_hook(claude_stop, clone / "sub", log), "claude Stop")
+        self.assertEqual(self.run_hook(codex_stop, clone / "sub", log), "codex Stop")
+
+    def test_project_install_outside_git_is_refused(self):
+        result = self.run_tool("install", str(self.config), "--project", check=False)
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("git repository", result.stderr)
+
+    def test_agent_option_installs_into_that_agent_only(self):
+        self.run_tool("install", str(self.config), "--agent", "codex")
+
+        self.assertFalse(self.claude_file.exists())
+        self.assertIn("Stop", self.commands(self.codex_file))
+
+    def test_config_without_name_is_refused(self):
+        self.write_config({"hooks": {"Stop": [{"command": "x"}]}})
+
+        result = self.run_tool("install", str(self.config), check=False)
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse(self.claude_file.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()