From 6f6590c6a56ef87e922c7e24f8cb76f3f6f4a1ce Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Mon, 20 Apr 2026 08:47:45 +0200
Subject: [PATCH] Restore .agents hook path compatibility for Claude prompt
 hooks

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
---
 .agents                                       |  1 +
 .../.openspec.yaml                            |  2 ++
 .../proposal.md                               | 17 ++++++++++++++++
 .../specs/restore-agents-hook-bridge/spec.md  | 14 +++++++++++++
 .../tasks.md                                  | 20 +++++++++++++++++++
 5 files changed, 54 insertions(+)
 create mode 120000 .agents
 create mode 100644 openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/.openspec.yaml
 create mode 100644 openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/proposal.md
 create mode 100644 openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/specs/restore-agents-hook-bridge/spec.md
 create mode 100644 openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/tasks.md

diff --git a/.agents b/.agents
new file mode 120000
index 00000000..43126bb1
--- /dev/null
+++ b/.agents
@@ -0,0 +1 @@
+.codex
\ No newline at end of file
diff --git a/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/.openspec.yaml b/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/.openspec.yaml
new file mode 100644
index 00000000..c4036b7c
--- /dev/null
+++ b/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
diff --git a/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/proposal.md b/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/proposal.md
new file mode 100644
index 00000000..6249bb1c
--- /dev/null
+++ b/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.
diff --git a/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/specs/restore-agents-hook-bridge/spec.md b/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/specs/restore-agents-hook-bridge/spec.md
new file mode 100644
index 00000000..ca791b8e
--- /dev/null
+++ b/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.
diff --git a/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/tasks.md b/openspec/changes/agent-codex-restore-agents-hook-bridge-2026-04-20-08-45/tasks.md
new file mode 100644
index 00000000..ea49cd8c
--- /dev/null
+++ b/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`.