Restore .agents hook path compatibility for Claude prompt hooks (#158)

Claude/Codex settings invoke hook scripts via .agents/hooks, but this repo only tracked hook files under .codex and .claude. Adding a repo-root compatibility symlink preserves existing hook settings while making the configured path resolvable again.

Constraint: Existing hook settings already target .agents/hooks and should remain stable across clients
Rejected: Repoint all hook commands to .codex/hooks | would require touching generated settings surfaces for both Claude and Codex
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep .agents path contract intact unless hook settings are migrated in one atomic change
Tested: python3 .agents/hooks/skill_activation.py </dev/null; python3 .agents/hooks/skill_guard.py </dev/null; openspec validate agent-codex-restore-agents-hook-bridge-2026-04-20-08-45 --type change --strict; openspec validate --specs
Not-tested: end-to-end interactive Claude hook execution in UI

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

.agents

@@ -0,0 +1 @@
+.codex

openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-20

openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/proposal.md

@@ -0,0 +1,17 @@
+## Why
+
+- Claude/Codex hooks are configured to execute under `.agents/hooks/*`.
+- This repository ships hook implementations under `.codex/hooks` and `.claude/hooks`, but `.agents/` can be missing.
+- When `.agents/` is absent, `UserPromptSubmit` fails with `[Errno 2] No such file or directory` and blocks Claude prompt submission.
+
+## What Changes
+
+- Add a repository-root compatibility alias `.agents -> .codex`.
+- Keep existing hook settings unchanged so both Claude and Codex continue to resolve the same path contract.
+- Verify `skill_activation.py` and `skill_guard.py` execute successfully via the `.agents/hooks` path.
+
+## Impact
+
+- Affected surface is limited to hook path resolution in local agent sessions.
+- No runtime package behavior changes, no dependency changes.
+- Low risk: symlink is reversible and only routes existing files.

openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/specs/restore-agents-hook-bridge/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: restore-agents-hook-bridge behavior
+The repository SHALL provide a valid `.agents/hooks/*` resolution path for local hook execution.
+
+#### Scenario: Hook path compatibility is present
+- **WHEN** a local hook command invokes `python3 <repo>/.agents/hooks/skill_activation.py`
+- **THEN** the file path SHALL resolve without `ENOENT`
+- **AND** the hook process SHALL exit successfully for empty stdin.
+
+#### Scenario: Existing guard hook remains callable through `.agents`
+- **WHEN** a local hook command invokes `python3 <repo>/.agents/hooks/skill_guard.py`
+- **THEN** the file path SHALL resolve without `ENOENT`
+- **AND** the hook process SHALL exit successfully for empty stdin.

openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/tasks.md

@@ -0,0 +1,20 @@
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-restore-agents-hook-bridge-2026-04-20-08-45`.
+- [x] 1.2 Define normative requirements in `specs/restore-agents-hook-bridge/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes.
+- [x] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+- [x] 3.2 Run `openspec validate agent-codex-restore-agents-hook-bridge-2026-04-20-08-45 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup
+
+- [x] 4.1 Confirm branch is ready for finish.
+- [ ] 4.2 After successful merge, run `bash scripts/agent-worktree-prune.sh --base <base> --delete-branches --delete-remote-branches` so merged agent branch/worktree sandboxes are removed from local and `origin`.