[Feature]: Project-scoped hooks (.augment/settings.json checked into the repo) #130

What would you like to be added?

Summary

Support reading hook configuration from a project-local file checked into the repository — e.g. .augment/settings.json (and optionally .augment/settings.local.json for personal/gitignored overrides) — in addition to the existing ~/.augment/settings.json and /etc/augment/settings.json locations. This should apply to all surfaces that already honor hooks: Auggie CLI, the VSCode extension, and the JetBrains/IntelliJ plugin.

Problem

Per the current hooks docs, the only locations Augment loads hook configuration from are:

There is no way for a repository to ship a hook configuration that:

1. Applies only to that repository.
2. Is version-controlled and reviewed alongside the code it governs.
3. Is automatically picked up by every contributor without each of them editing files in their home directory.

This is a real blocker for several use cases:

• Repo-scoped policy enforcement. A repository wants to require that certain commands (e.g. terraform apply, kubectl delete) be blocked by a PreToolUse hook only within that repo, without globally affecting the developer's other projects.
• AI provenance / commit attribution. We're rolling out a tool (devx-ai-standards) that tags AI-assisted commits with a verifiable trailer. The reliable way to wire this up for the IDE surfaces is a PreToolUse hook on launch-process matching git commit, since neither the VSCode extension nor the JetBrains plugin reliably exports an environment variable a git hook could detect. Without project-scoped hook config, every contributor on every machine has to manually merge a snippet into ~/.augment/settings.json — and even then it leaks across all of their other projects.
• Onboarding & reproducibility. New contributors get the project's hooks the moment they git clone, instead of via a side-channel doc that says "please go edit your home directory".

Claude Code already supports exactly this pattern with .claude/settings.json and .claude/settings.local.json (see their docs), and it's been a major reason teams have been able to standardize Claude Code hooks across a repo. The same model would solve the equivalent problem for Augment.

Proposed Solution

1. Add two new hook config locations, in this precedence order (highest to lowest)

Project discovery should walk up from the current working directory looking for .augment/ (mirroring how Claude Code does it), so it works in monorepo subdirectories and worktrees.

2. Apply across all surfaces that already support hooks

The docs already list CLI, VSCode, and IntelliJ as supporting the existing hook locations — the new ones should be honored in all three. For the IDE surfaces, the discovery root is the workspace/project root.

3. Merge semantics

Following the existing precedence note in the docs (system overrides user), the new layers should compose: hooks from all applicable layers run, with later layers able to override matchers from earlier ones. This matches Claude Code's behavior and avoids surprising users when a repo hook silently disables their personal one (or vice versa).

4. Auto-gitignore the local file

When .augment/settings.local.json is created, append it to .gitignore (Claude Code does this) so personal/experimental hook config doesn't accidentally get committed.

5. Security guardrails

Project-scoped hooks execute arbitrary commands on contributor machines, so this needs the same treatment Claude Code applies:

• On first encounter of a .augment/settings.json from a freshly cloned repo, prompt the user to review and approve before any hook executes.
• Provide a clear way to inspect what hooks would run (e.g. auggie hooks list).
• Document the trust model loudly.

Why is this needed?

Without project-scoped hooks, there is no way for a repository to ship a hook recipe that contributors get automatically and that is scoped to that repository. This forces every team that wants policy enforcement, AI provenance, or any other repo-level hook behavior to either:

• give up on hooks for the IDE surfaces and rely only on git hooks (which can't see Augment's tool-execution lifecycle), or
• ask every contributor to manually merge a snippet into their global ~/.augment/settings.json (which then leaks into all of their other projects).

The ~/.augment/settings.json model is the right one for personal preferences, but it is the wrong shape for repo-defined policy.

Possible solution or alternatives

• Mirror Claude Code's .claude/settings.json model (preferred, described above).
• Allow ~/.augment/settings.json to include external files by path, so a repo could ship a config and ask the user to add "include": ["./.augment/settings.json"] to their global config. This is strictly worse than option 1 — still requires per-user setup, still leaks across worktrees, no automatic discovery — but easier to implement.
• Honor an AUGMENT_SETTINGS_FILE environment variable pointing at an additional settings file. Also worse than option 1; doesn't solve the IDE surface case where there's no shell at all.

Additional context

Reference implementations of project-scoped hook config:

• Claude Code: Settings docs, Hooks guide. Project hooks live in .claude/settings.json, personal-overrides in .claude/settings.local.json (auto-gitignored).

Filed by a team building an AI-provenance commit-attribution standard (@clari/devx-ai-standards) that needs to support repository-defined hooks for both Augment (CLI + VSCode + IntelliJ) and Claude Code consumers.