Skip to content

Adopt the shared agent docs and Claude Code guard hooks - #225

Merged
webknjaz merged 5 commits into
ansible:develfrom
webknjaz:maintenance/agents-ctx
Nov 14, 2026
Merged

webknjaz merged 5 commits into
ansible:develfrom
webknjaz:maintenance/agents-ctx

Conversation

@webknjaz

@webknjaz webknjaz commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

This brings over the agent context that ansible/awx_plugins.interfaces, ansible/pylibssh and the tox-dev plugins already use: the AGENTS.md/CLAUDE.md entry points, the .agents-ctx/ house rules, and two Claude Code PreToolUse hooks that make the agent ask before silencing checks or changing license terms.

The shared docs are first imported unchanged from ansible/pylibssh@5ff33f5d, so the next commit shows exactly what differs here. Two tool-config commits come first, so the imported files pass this repository's linters: ruff treats .claude/hooks/ as a namespace directory, and codespell accepts "faits accomplis".

🤖 Produced by a probabilistic agent with a token generator using an LLM to sound convincing.

Summary by CodeRabbit

  • Documentation
    • Added contributor guidance covering project orientation, automation, testing, coding conventions, reviews, and licensing.
  • Chores
    • Added safeguards that flag certain license changes and attempts to weaken checks or tests for review before proceeding.
    • Updated project guidance and configuration to support the new documentation and safeguards.

The Claude Code hooks are standalone scripts that share a helper
module. The directory is deliberately not a package, the same way
the other namespace directories listed here are not.

Assisted-by: LLM
The agent docs shared with ansible/pylibssh say that delegated
experiments come back as findings, not faits accomplis. codespell
reads "accomplis" as a typo. The exception and its dictionary
reference match the ones in ansible/awx_plugins.interfaces.

Assisted-by: LLM
AGENTS.md, CLAUDE.md and the shared .agents-ctx/ docs are copied
unchanged from ansible/pylibssh as of 5ff33f5d, so the next commit
shows exactly what differs here. The pylibssh-only
CYTHON_AND_LIBSSH.md is left out.

Assisted-by: LLM
The shared text stays as in ansible/pylibssh. Only the "Here:"
paragraphs, which state this project's facts, are rewritten, along
with the per-project NAMING_THE_DUCKS.md and WHERE_TO_LOOK_FIRST.md,
and the operator-local context file CLAUDE.md loads.

Where existing tests don't follow a shared rule yet, such as the
grouping class or the mocks patching the plugins' internals, the
paragraph names them as predating the rule rather than as
precedent.

Assisted-by: LLM
The agent docs make silencing checks and changing license terms
the operator's decision. These PreToolUse hooks, copied unchanged
from ansible/pylibssh as of 5ff33f5d, make Claude Code ask the
operator before edits or commands that look like either.

Assisted-by: LLM
@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Caution

Review failed

The pull request is closed.

Walkthrough

The pull request adds agent and contributor guidance across repository context documents. It also adds shared Claude Code hook utilities, hooks for selected license and check-suppression concerns, and configuration that runs those hooks before supported tools.

Changes: Agent Workflow

Layer / File(s) Summary
Repository context and operating rules
.agents-ctx/.gitignore, .agents-ctx/README.md, AGENTS.md, CLAUDE.md, .agents-ctx/HOUSE_RULES.md, .agents-ctx/NAMING_THE_DUCKS.md, .agents-ctx/WHERE_TO_LOOK_FIRST.md
Entry-point files direct readers to agent context. New guides describe operating expectations, project naming, and where to find repository information.
Contribution and review workflows
.agents-ctx/CONTRIB_WORKFLOW_INFRA_TOOLING.md, .agents-ctx/PR_HYGIENE.md, .agents-ctx/DONT_GHOST_THE_REVIEWER.md, .agents-ctx/HUMAN_IN_THE_LOOP.md
Guidance covers tox-based automation, contribution and PR practices, reviewer communication, and operator involvement in decisions.
Project practices and policy guidance
.agents-ctx/HOUSE_STYLE.md, .agents-ctx/TESTING.md, .agents-ctx/LICENSING.md, .agents-ctx/DONT_SHOOT_THE_MESSENGER.md
Guides document coding and testing conventions, licensing procedures, and operator approval for proposed suppressions or test changes.
Pre-tool checks and hook configuration
.claude/hooks/hook_utils.py, .claude/hooks/guard_silenced_checks.py, .claude/hooks/guard_license_changes.py, .claude/settings.json, .ruff.toml, .codespellrc
Shared utilities process Claude Code hook input and request operator approval when checks report concerns. Two hooks check selected edits and shell commands. Claude Code settings register them, and Ruff and codespell configuration is updated.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant ClaudeCode
  participant HookSettings
  participant GuardHooks
  participant HookUtils
  participant Operator
  ClaudeCode->>HookSettings: Match tool to configured PreToolUse hooks
  HookSettings->>GuardHooks: Run configured checks
  GuardHooks->>HookUtils: Pass concern callbacks to run_hook
  HookUtils->>HookUtils: Read tool input and evaluate concerns
  HookUtils->>Operator: Request approval when concerns are returned
Loading
Merge Risk: Low · up to 8b4cd

The new guard hooks can silently skip their approval prompt for test or tool-config edits made inside a nested git worktree. This affects only the agent-assistance tooling, not shipped plugin code. Swapping the path-resolution order in the hook helper before merging would close the gap.

@sonarqubecloud

Copy link
Copy Markdown

@webknjaz
webknjaz merged commit 4332fe3 into ansible:devel Nov 14, 2026
30 of 32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant