Scope agent context: extract conventions, enforce git restrictions via hooks by KRRT7 · Pull Request #258 · microsoft/typeagent-py

KRRT7 · 2026-04-29T06:27:38Z

Summary

Extracts code generation conventions from AGENTS.md into .github/code-conventions.md — only loads when writing/generating code, not every interaction
Replaces text-based "NEVER COMMIT CODE" with a PreToolUse hook (scripts/block-git-mutations.sh) that actually blocks git mutations
Registers the hook for both Claude Code (.claude/settings.json) and VS Code Copilot (.vscode/settings.json)
AGENTS.md goes from 106 → 32 lines — only core workflow rules remain

Related discussion: #257

How it works

The hook script receives tool invocations as JSON on stdin, checks if it's a terminal command containing a git mutation (commit, add, push, reset, rebase, merge, cherry-pick, revert, stash, tag), and returns a deny decision. Read-only commands (status, diff, log, show, branch) pass through.

Verifying hooks

Tests: 39 pytest tests cover blocking mutations, allowing read-only commands, allowing non-git commands, and ignoring non-terminal tools:

uv run pytest tests/test_hooks.py -v

Live verification:

Claude Code: run /hooks to confirm the PreToolUse hook is registered
VS Code Copilot: check agent logs for hook execution

Docs

Claude Code hooks: https://docs.anthropic.com/en/docs/claude-code/hooks
VS Code Copilot hooks: https://code.visualstudio.com/docs/copilot/customization/hooks

Test plan

uv run pytest tests/test_hooks.py -v — 39/39 passing
Live test: trigger git commit in Claude Code session, verify it's blocked
Live test: trigger git commit in VS Code Copilot session, verify it's blocked

gvanrossum

Not bad for a first draft, but I have some issues about what goes where.

gvanrossum · 2026-04-29T17:02:33Z

@@ -0,0 +1,11 @@
+{
+  "github.copilot.chat.agent.hooks": {


This file varies per user. We can't replace it with this. At best we could move this to README.md for humans to manually add there. (Or possibly we can add it to AGENTS.md. :-)

gvanrossum · 2026-04-29T17:02:54Z

@@ -1,5 +1,6 @@
-# Editor settings
-.vscode
+# Editor settings (but .vscode/settings.json is tracked for Copilot hooks)


So I would be against this.

gvanrossum · 2026-04-29T17:04:24Z

@@ -0,0 +1,11 @@
+{
+  "hooks": {


Same objection as for .vscode

gvanrossum · 2026-04-29T17:06:28Z

@@ -0,0 +1,62 @@
+When generating Python code (e.g. when translating TypeScript to Python),


I don't like hiding things under .github either. If we want to go through with this (I'm still skeptical) we should collect all the agent instructions in a single top-level directory (not hidden) and explain in AGENTS.md how to use them.

gvanrossum · 2026-04-29T17:07:56Z

@@ -1 +1,3 @@
 Get your instructions from AGENTS.md in the repo root.
+
+For code generation and style conventions, see [code-conventions.md](code-conventions.md).


Move this into AGENTS.md

gvanrossum · 2026-04-29T17:18:56Z

-Never run git commands that make any changes. (`git status` and `git diff` are fine)
-
-**NEVER COMMIT CODE. Do not run `git commit` or any other git commands
-that make changes to the repository. Not even `git add`**
-


I would keep this and use the hook script as a second defense.

gvanrossum · 2026-04-29T17:20:26Z

-When I ask to update AGENTS.md (even if maybe) extract a general rule from what I said
-before and update AGENTS.md (unless it's already in there -- maybe reformulate since
-it apparently didn't work). Also, when it looks like I state a general rule, add it to
-AGENTS.md. In all cases show what you added to AGENTS.md.


Why delete this? I want it to learn from its mistakes. (Though it may have to point at a different file or files.)

KRRT7 · 2026-05-01T07:29:54Z

Pushed updates addressing your feedback. Here's what changed and where I disagree:

Tracked settings files (.vscode/settings.json, .claude/settings.json)

These aren't user-specific editor preferences — they're project-level hook registrations. Both tools explicitly distinguish shared vs personal config:

VS Code: "Workspace settings are specific to a project and can be shared across developers on a project... This makes it easy to share settings with others in a version-controlled (for example, Git) project." (docs)
Claude Code: .claude/settings.json is "checked into source control and shared with your team"; .claude/settings.local.json is "not checked in, useful for personal preferences" (docs)

The .gitignore uses !.vscode/settings.json to track only that file — everything else under .vscode/ stays ignored.

.github/ location

.github/copilot-instructions.md is GitHub's standard path — Copilot auto-loads it. Moving it elsewhere means Copilot won't find it. Similarly, .github/code-conventions.md is linked from both AGENTS.md and copilot-instructions.md so each tool follows its own standard discovery path.

The point of splitting is lazy loading. Three tools' own docs recommend this:

Claude Code: "Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." (docs)
GitHub Copilot: supports .github/instructions/NAME.instructions.md scoped to matching file paths (docs)
Cursor: "Keep rules under 500 lines" and "Split large rules into multiple, composable rules." (docs)

Hook rewritten in Python (fixes Windows, bypass, git branch)

Rewrote block-git-mutations.sh → block_git_mutations.py. Addresses all three concerns:

Cross-platform via uv run python. VS Code hooks natively support per-OS commands (windows/linux/osx keys) (docs)
Allowlist approach — only known-safe subcommands pass, everything else denied by default
shlex.split() for proper shell parsing, resolves git aliases via git config --get-regexp, handles &&/||/;/| chains
git branch -d/-D/-m, git tag -a/-d/-f, git stash (without list/show), git worktree (without list) all correctly blocked

92 tests, pure Python, no subprocess dependency.

AGENTS.md — trimmed, not restored

You said "use the hook script as a second defense" — I took that further. The hook is the first line of defense: deterministic, zero context cost, can't be talked out of it. That means AGENTS.md doesn't need to repeat the git rules in prose. It went from 106 → 35 lines. Everything that can be enforced by a hook should be, so the agent context budget is spent on things that actually need natural language (workflow, conventions, preferences).

…git restrictions - Extract code generation conventions from AGENTS.md into .github/code-conventions.md - Replace text-based "NEVER COMMIT" instruction with a PreToolUse hook that blocks git mutations - Register hook for Claude Code (.claude/settings.json) and VS Code Copilot (see PR notes) - Add 39 pytest tests verifying the hook blocks mutations and allows read-only commands - AGENTS.md reduced from 106 to 32 lines — only core workflow rules remain

Makes git-mutation enforcement work out-of-the-box for VS Code Copilot users instead of requiring manual setup.

- Replace bash hook with cross-platform Python script using allowlist approach, shlex parsing, git alias resolution, and chained command handling - Restore removed AGENTS.md sections (worktrees, debugging, self-learning) - Hook is first line of defense; AGENTS.md just references it - Update .claude/settings.json and .vscode/settings.json with Python invocation and Windows-specific command - Rewrite tests as pure Python unit tests (92 cases, no subprocess)

Remove restored worktrees, debugging, and self-learning sections. The hook handles git enforcement deterministically; AGENTS.md stays lean to minimize context consumption.

gvanrossum reviewed Apr 29, 2026

View reviewed changes

KRRT7 added 4 commits May 1, 2026 03:03

Track .vscode/settings.json for Copilot PreToolUse hooks

7a0614a

Makes git-mutation enforcement work out-of-the-box for VS Code Copilot users instead of requiring manual setup.

Trim AGENTS.md: let hooks enforce, not prose

87b3261

Remove restored worktrees, debugging, and self-learning sections. The hook handles git enforcement deterministically; AGENTS.md stays lean to minimize context consumption.

KRRT7 force-pushed the scoped-agent-context branch from 043c3f8 to 87b3261 Compare May 1, 2026 08:03

Fix Claude Code hooks schema: use matcher + hooks array

7db86c9

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Scope agent context: extract conventions, enforce git restrictions via hooks#258

Scope agent context: extract conventions, enforce git restrictions via hooks#258
KRRT7 wants to merge 5 commits intomicrosoft:mainfrom
KRRT7:scoped-agent-context

KRRT7 commented Apr 29, 2026 •

edited

Loading

Uh oh!

gvanrossum left a comment

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

gvanrossum Apr 29, 2026

Uh oh!

KRRT7 commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,62 @@
		When generating Python code (e.g. when translating TypeScript to Python),

		@@ -1 +1,3 @@
		Get your instructions from AGENTS.md in the repo root.

		For code generation and style conventions, see [code-conventions.md](code-conventions.md).

Conversation

KRRT7 commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Verifying hooks

Docs

Test plan

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

gvanrossum Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

KRRT7 commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

KRRT7 commented Apr 29, 2026 •

edited

Loading