Skip to content

docs: document the agent hooks and their trust requirement - #38

Merged
mjun0812 merged 1 commit into
mainfrom
docs/agent-hooks-setup
Sep 8, 2026
Merged

mjun0812 merged 1 commit into
mainfrom
docs/agent-hooks-setup

Conversation

@mjun0812

@mjun0812 mjun0812 commented Sep 8, 2026

Copy link
Copy Markdown
Owner

Overview and Background

The generated project's README now describes the agent configuration shipped in #37 and states what a user must do before it takes effect. Verifying the Codex path end to end showed that Codex loads project hooks only when the .codex/ layer is trusted and the hook definition itself has been reviewed and trusted through /hooks; until then it skips the hook without printing an error. A first Codex run in a fresh generated project therefore left an unformatted file behind with no indication why. The generated README also did not mention the hook or the settings files at all.

Related Issues

None. Documents the configuration added in #37.

Implementation Approach

Documentation only. The generated README gains an "AI Coding Agents" section listing the three files and the trust requirement for each tool; the repository README gets the same trust note appended to its existing file list. No behavior changes, because the trust step is a deliberate safety mechanism in both tools and cannot be waived from the project side.

Changes

  • template/README.md: new "AI Coding Agents" section (files, .claude/settings.local.json for personal overrides, trust requirements for Claude Code and Codex).
  • README.md: trust note added to the existing AI Editor Support list.

Impact

  • User-facing: generated projects explain how to activate the hook. No code, dependency, or CI change.
  • Existing projects receive the README change through the normal copier update three-way merge.

Validation Results

Behavior that motivated the change, observed in a project generated from main:

# Untrusted project: Codex creates the file, hook never runs
codex exec -s workspace-write -c 'features.hooks=true' '<write a badly formatted .py>'
# hook: Stop only; file left unformatted; ruff check reports I001 and F401

# Trusted project and trusted hook: the hook runs and feeds diagnostics back
codex exec -s workspace-write -c 'features.hooks=true' \
  -c 'projects."<abs path>".trust_level="trusted"' --dangerously-bypass-hook-trust '<same prompt>'
# hook: PostToolUse -> apply_patch result replaced with "Script error: F401 `os` imported but unused"
# Codex then patched the file again; final state:
uv run --frozen ruff check src/test_copier/from_codex.py          # All checks passed!
uv run --frozen ruff format --check src/test_copier/from_codex.py  # 1 file already formatted

Rendered the README from this branch with copier copy and confirmed the new section appears with no unrendered Jinja.

- Describe the shared format-on-edit hook and the Claude Code and Codex
  configuration files in the generated project's README
- State that both tools apply the configuration only in a trusted
  project, and that Codex additionally needs the hook trusted through
  /hooks before it runs
@mjun0812 mjun0812 added the documentation Improvements or additions to documentation label Sep 8, 2026
@mjun0812 mjun0812 self-assigned this Sep 8, 2026
@mjun0812
mjun0812 merged commit 19ded9f into main Sep 8, 2026
7 checks passed
@mjun0812
mjun0812 deleted the docs/agent-hooks-setup branch September 8, 2026 11:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant