You ask the agent to add a timeout, and it patches bookshelf.gen.go, the file oapi-codegen
wrote. The tests pass and the change merges. The next go generate rewrites all 633 lines of the
file and drops the timeout without a warning, because nothing records that the file was edited.
What you get
You will end up with one list of generated paths, a hook that refuses agent edits to them, and a CI job that fails when one slips through. This is for you if a generated SDK lives in a repository an agent works in.
Short answer
Mark the generated paths linguist-generated in .gitattributes, then enforce that list twice.
A Claude Code PreToolUse hook asks git check-attr and exits 2 on an edit to a marked file,
while reads stay allowed. A CI job regenerates and runs git diff --exit-code, which catches
edits from any agent or shell command. Per-agent ignore files differ per tool and also hide
the types.
You will need
Node 22 or later, git, and a generated SDK checked into the repository. Verified 2026-11-20 against Node 22.23.5. The sample repository holds a file sdkgen generated, the client oapi-codegen generated, and the Bookshelf document both came from.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
.cursorignore, .aiderignore, .geminiignore and .clineignore | One agent, and you accept a hint the tool may not honor | Four formats with four meanings, and most hide the files from reading too | You need a refusal, or the agent must read the types |
| Claude Code deny rules and PreToolUse hook | Claude Code is the agent, and you want edits refused at the tool call | Claude Code only, and a script that opens files itself gets past both | Several agents work in the repository |
| linguist-generated plus a CI regeneration check | Any agent and any person, with the generator runnable in CI | The edit is caught at pull request time, after the agent’s work is done | Feedback must reach the agent while it works |
| oapi-codegen go generate and its DO NOT EDIT header | A Go client, where tools already read the generated-code header | The header is a convention, so nothing stops an edit without a CI check | You need the refusal at edit time |
swift-openapi-generator build plugin | A Swift package, where generated code need not be committed at all | Generated code is out of the source tree, so review and audit read nothing | You must commit the generated code |
| voxgig-sdkgen doctor and JOSTRACA_PROTECT | An sdkgen project, where .sdk/ is the place for changes | doctor checks .sdk/ only, so edits under ts/ pass it with exit 0 | The edit to guard is in the generated output |
Voxgig maintains sdkgen. It is one of six options here, not the recommendation.
The ignore files are the cheapest and differ the most from tool to tool. The hook refuses at edit time but only in
Claude Code. The CI check works for every agent and arrives last. Each generator offers something
different. The Swift plugin keeps the output out of the repository, oapi-codegen labels it, and
sdkgen guards its own .sdk/ tree.
Mark the generated paths once
.gitattributes
is the one list every tool here can read. GitHub collapses linguist-generated files in diffs and
leaves them out of language counts; the hook and the CI job read the same lines.
ts/** linguist-generated
bookshelf/*.gen.go linguist-generated
Refuse the edit at the tool call
A PreToolUse hook receives the tool call as JSON on
stdin. Exit code 2 blocks the call, and stderr goes back to Claude as the reason. This hook asks git
whether the target is marked, so it never keeps a second list. It first resolves the path from the
repository root, following any symlink in it:
const rel = relative(root, real(resolve(cwd, target)))
if (rel === '' || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) process.exit(0) // outside this repository
// Any .gitattributes, at any depth, and .git/info/attributes can unset the mark.
if (basename(rel) === '.gitattributes' || rel === '.git' || rel.startsWith('.git' + sep)) {
block(`guard-generated: ${rel} decides what is generated; ask a person to change it`)
}
let attr
try {
attr = execFileSync('git', ['check-attr', 'linguist-generated', '--', rel], { cwd: root, encoding: 'utf8' })
} catch {
block(`guard-generated: git check-attr failed for ${rel}, so the edit is refused`)
}
// git prints "<path>: linguist-generated: <set|unset|unspecified|value>"
const value = attr.trim().split(': ').pop()
if (value === 'set' || value === 'true') {
block(`guard-generated: ${rel} is generated. Change api.json or the generator config and regenerate.`)
}
process.exit(0)
project/claude-settings.json registers it for Edit|Write|MultiEdit|NotebookEdit and adds
Edit(/ts/**) and Edit(/bookshelf/*.gen.go) as
deny rules. The demo feeds the hook six tool calls in
the documented input shape:
node hook-demo.mjs
Edit ts/src/BookshelfError.ts blocked
guard-generated: ts/src/BookshelfError.ts is generated. Change api.json or the generator config and regenerate.
Write bookshelf/bookshelf.gen.go blocked
guard-generated: bookshelf/bookshelf.gen.go is generated. Change api.json or the generator config and regenerate.
Edit docs/../ts/src/BookshelfError.ts blocked
guard-generated: ts/src/BookshelfError.ts is generated. Change api.json or the generator config and regenerate.
Read ts/src/BookshelfError.ts allowed
Edit api.json allowed
Edit .gitattributes blocked
guard-generated: .gitattributes decides what is generated; ask a person to change it
The path is resolved before git sees it, so docs/../ts is caught, and so are a symlink into ts/
and a session whose working directory is a subdirectory. The Read passes, which keeps the SDK’s
types visible. The hook also refuses an edit to any .gitattributes file and to anything under
.git/, since an attributes file anywhere could unset the mark.
Catch what the hook cannot see
Claude Code’s permissions page says Edit deny rules do not apply to a Node or Python script
that opens files itself. A CI job that regenerates and compares catches those, and edits from
every other agent. ci-demo.mjs commits an agent’s patch to both files, regenerates, and runs the
check.
node ci-demo.mjs
ts/src/BookshelfError.ts: linguist-generated: set
bookshelf/bookshelf.gen.go: linguist-generated: set
api.json: linguist-generated: unspecified
git diff --exit-code: exit 1
bookshelf/bookshelf.gen.go | 1 -
ts/src/BookshelfError.ts | 1 -
2 files changed, 2 deletions(-)
Exit 1 fails the job, and the stat names each file the agent touched. In the demo, regenerating
copies the committed generator output back, because the gate cannot run sdkgen or Go. Your job
runs npm run generate in .sdk/, or go generate ./....
Find out what sdkgen guards and what it passes
sdkgen 4.44.3 writes the rule into the project’s AGENTS.md: ts/ is build output, never edited
by hand. To see what enforces it, make the agent’s edit in a scaffolded project, mark a second
file with JOSTRACA_PROTECT, and regenerate. generate.sh ran these steps once:
cd bookshelf-sdk
echo "// agent edit: retry patched here" >> ts/src/BookshelfError.ts
{ echo '// JOSTRACA_PROTECT'; cat ts/src/utility/FetcherUtility.ts; } > ../protected.ts
mv ../protected.ts ts/src/utility/FetcherUtility.ts
echo "// agent edit: kept" >> ts/src/utility/FetcherUtility.ts
(cd .sdk && npm run generate)
It then ran npx voxgig-sdkgen doctor in .sdk/ five times, after each change below, and kept
the files and the log in sdkgen-run/. sdkgen-run.mjs reads them:
node sdkgen-run.mjs
ts/src/BookshelfError.ts no marker edit overwritten
ts/src/utility/FetcherUtility.ts JOSTRACA_PROTECT on line 1 edit kept
doctor after appending a line to ts/src/BookshelfError.ts and ts/src/utility/FetcherUtility.ts
exit 0: .sdk matches the scaffold (0 additive, 0 customized)
doctor after appending a line to the component .sdk/src/cmp/ts/Config_ts.ts
CUSTOMIZED src/cmp/ts/Config_ts.ts
exit 0: .sdk matches the scaffold (0 additive, 1 customized)
doctor after also appending a line to the template master .sdk/tm/ts/src/Spec.ts
CUSTOMIZED src/cmp/ts/Config_ts.ts
CUSTOMIZED tm/ts/src/Spec.ts
exit 0: .sdk matches the scaffold (0 additive, 2 customized)
doctor with the same two edits and main: kit: copies: 'overwrite' in .sdk/model/project.aontu
FORKED src/cmp/ts/Config_ts.ts
EDITED tm/ts/src/Spec.ts
exit 1: .sdk has drifted: 1 forked, 1 edited, 0 stale, 0 missing, 0 outdated, 0 unresolved
doctor with both edits undone, after adding a file .sdk/tm/ts/src/Extra.ts that target add does not write
STALE tm/ts/src/Extra.ts
exit 1: .sdk has drifted: 0 forked, 0 edited, 1 stale, 0 missing, 0 outdated, 0 unresolved
Regeneration overwrote the unmarked edit. The file holding JOSTRACA_PROTECT kept its edit, which
is how to keep one file on purpose. doctor compares .sdk/src/cmp/, .sdk/tm/ and the target
model with the scaffold, as the CLI reference
says, so it passed both edits under ts/.
Its --help says it exits non-zero for a forked component or an edited template master. In the
default merge mode it filed both edits as CUSTOMIZED and exited 0, because the copy record in
.sdk/log/copies.jsonl shows the project made them. Only with copies: 'overwrite' set did it
report FORKED and EDITED and exit 1. A stale file failed it in the default mode.
Use oapi-codegen’s header and the Swift build plugin
oapi-codegen v2.8.2 writes // Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.8.2 DO NOT EDIT. on line 3. That matches the regular expression the
go generate documentation asks generated files to carry, so linters
and reviewers can tell. Its README drives generation from a //go:generate directive, which makes
the CI check one line. oapi-codegen beats sdkgen here for a Go-only team, because the Go
toolchain already knows which files are generated.
swift-openapi-generator was not run, since this sandbox has no Swift toolchain. Its documentation
recommends the package plugin, which generates at build time so the code is not committed to your
source repository. A file that is not in the tree cannot be edited by any agent. That beats
every other row for a Swift package, unless you must commit the code for auditing, where the
manual CLI applies and the CI check returns.
Check it worked
Six tests cover the hook both ways and the symlink, subdirectory, and attributes-file tricks. They
also cover a call the hook cannot check, the deny rules matching .gitattributes, the CI check, and
the five doctor exits.
node --test guard.test.mjs
# tests 6
# suites 0
# pass 6
# fail 0
# cancelled 0
# skipped 0
# todo 0
Then ask the agent to edit ts/src/BookshelfError.ts, and expect the hook’s message in its reply.
When it goes wrong
The agent stops using the SDK’s types and invents its own. The generated directory is in an
ignore file that also blocks reading. Cursor’s page says it blocks ignored files from Agent, Tab and
@ mentions. Prefer a rule that refuses writes only: the hook here, or Aider’s
--read option, which specifies a read-only file.
The hook passes an edit that CI then fails. The agent edited through Bash, with sed -i or a
script, which a file-tool hook does not see. Keep the CI check; the
Cline page says its own shell guard is a token
check that a sufficiently creative command could slip through.1
CI fails on a clean branch. The generator version in CI differs from the one that wrote the
committed files. Pin it, as go run ...@v2.8.2 does in generate.sh.
When not to do this
Do not rely on one ignore file for several agents. .geminiignore applies only to the tools that
support it. .clineignore filters what Cline loads automatically, is being deprecated, and does
not refuse an edit either.2
Do not treat voxgig-sdkgen doctor as the guard for generated output. It checks .sdk/, and in
the run shown earlier it passed two edits under ts/ with exit 0. In the default merge mode it
also passed edits inside .sdk/. Pair it with the CI regeneration check, and use
JOSTRACA_PROTECT only for a file you mean to own.
Do not commit generated Swift when the package plugin will do. swift-openapi-generator
generates at build time, and a file outside the repository needs no guard at all.
Do not deny reads of the generated tree to stop edits. An agent that cannot read the client writes a second one.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3
with jostraca 0.42.0, and oapi-codegen v2.8.2. Every output block is what the command preceding it
printed. sdkgen and oapi-codegen were run once and their output is committed. swift-openapi-generator
was not run; its behavior comes from its documentation. Claude Code was not run with these
settings; the hook was run on the input shape its hooks reference documents. Cursor, Aider, Gemini
CLI and Cline were not run.
Footnotes
-
The Cline page offers an enforced
PreToolUsehook beside the original file, and lists what each misses. The original does not stop reads through explicit @ mentions or shell commands. The hook does not catch a symlink that existed before it, and the command line turns hooks off in--yolomode. ↩︎ Back to text -
The Gemini CLI page adds that ignored paths stay visible to other services such as Git. Cursor’s page says the terminal and MCP server tools its Agent uses cannot block access to ignored code, and that complete protection is not guaranteed due to LLM unpredictability. ↩︎ Back to text