# Contributor handoff — anthropics/claude-code

> Canonical page: https://codevetter.com/unpack/claude-code/agent-handoff

# Contributor handoff — anthropics/claude-code

Scanned commit b486776a2eef0d3f39abaebaa3c03e378c7480b8 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Edit one mod or one plugin at a time. Read that mod's README and register.ts before its leaves; the leaves are tiny single-export files. Do not hand-edit mods/types/claude-code.d.ts. Typecheck with tsc -p mods/tsconfig.json and test with claude plugin test if the CLI supports it. Never treat plugins/ and mods/ as the same system. Issue scripts share scripts/issue-lifecycle.ts and must keep the gh.sh allowlist. The hook API is early access.
- Read first, in this order, for any mod change: mods/README.md (test kit and noun contracts), mods/types/claude-code.d.ts header (host rules), the mod's README.md, hooks/hooks.json, hooks/register.ts, and its plugin.json. For a plugin change: plugins/README.md, .claude-plugin/marketplace.json, the plugin README, and its hooks.json or commands/*.md. For issue bots: scripts/issue-lifecycle.ts, scripts/gh.sh, and the workflow that invokes them. — [mods/README.md](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/README.md) [mods/types/claude-code.d.ts#L1-L21](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/types/claude-code.d.ts#L1-L21) [plugins/README.md](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/README.md) [.claude-plugin/marketplace.json](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.claude-plugin/marketplace.json) [scripts/issue-lifecycle.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/scripts/issue-lifecycle.ts) [scripts/gh.sh](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/scripts/gh.sh)
- Safe edit boundary for mods: files under that mod's hooks/ and tests/, plus a one-line export in an index.ts that already re-exports the folder. Do not add the mod to marketplace.json. Do not change EngineInterface except by editing the owning mod's types/index.d.ts (today only telemetry has one). Do not edit claude-code.d.ts; regenerate with /plugin-types. — [mods/README.md#L15-L20](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/README.md#L15-L20) [mods/README.md#L84-L114](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/README.md#L84-L114) [mods/types/claude-code.d.ts#L1-L8](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/types/claude-code.d.ts#L1-L8) [mods/telemetry/types/index.d.ts#L1-L9](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/types/index.d.ts#L1-L9)
- Style in mods is one concept per file, re-exported through index.ts (often with a .js specifier in the export path, for example export * from './has-mcp-allowlist.js'). Tests import the folder default (import Hooks from '../hooks', import Fixtures from './fixtures'). Match that. JSX, when present under diff views, uses the h factory from tsconfig, not React. — [mods/tsconfig.json](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/tsconfig.json) [mods/sec-default/hooks/policy/index.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/sec-default/hooks/policy/index.ts) [mods/telemetry/tests/register.test.ts#L1-L4](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/tests/register.test.ts#L1-L4) [mods/diff/hooks/names/index.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/hooks/names/index.ts)
- Tests to run after a mod edit: npx or global tsc -p mods/tsconfig.json, then CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test mods/<name>. Diff's suite is large; a register change needs mods/diff/tests/register.test.ts plus the pure tests for the helper you touched. Telemetry changes need register.test.ts and gate.test.ts. sec-default changes need tests/register.test.ts. If plugin test is missing, say so; CI will skip rather than fail. — [.github/workflows/mod-tests.yml#L24-L40](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.github/workflows/mod-tests.yml#L24-L40) [mods/README.md#L22-L26](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/README.md#L22-L26) [mods/telemetry/tests/gate.test.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/tests/gate.test.ts) [mods/diff/tests/register.test.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/tests/register.test.ts)
- Trap: $.telemetry may be absent. agents-md wraps calls in Telemetry.quietly and diff's recorder drops rows when the noun is missing. A new mod must do the same. Calling $.telemetry from tier user or prepend is refused by Gate.served (SERVED_TIERS is only builtin and core). A test that calls it must seat a provider plugin or on('telemetry.log'). — [mods/agents-md/README.md#L107-L111](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/agents-md/README.md#L107-L111) [mods/diff/README.md#L92-L93](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/README.md#L92-L93) [mods/telemetry/hooks/gate/served/served.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/hooks/gate/served/served.ts) [mods/telemetry/hooks/gate/served-tiers/served-tiers.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/hooks/gate/served-tiers/served-tiers.ts) [mods/README.md#L102-L107](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/README.md#L102-L107)
- Trap: diff command registration fails soft when the built-in still owns /diff (BUILTIN_HOLDS_PATTERN). The plugin then has host === null and command.run calls next(e). Auto-open also no-ops without host. Do not assume register throwing means the pane works. Git must stay pinned with pinnedLeadOf; do not spawn git with a bare argv after the first rev-parse. — [mods/diff/hooks/register.ts#L628-L641](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/hooks/register.ts#L628-L641) [mods/diff/hooks/register.ts#L744-L747](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/hooks/register.ts#L744-L747) [mods/diff/hooks/git/git-backend-of.ts#L26-L37](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/hooks/git/git-backend-of.ts#L26-L37) [mods/diff/hooks/git/argv/pinned-lead-of/pinned-lead-of.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/hooks/git/argv/pinned-lead-of/pinned-lead-of.ts)
- Trap: agents-md option migration. instructionFiles set to the default cannot be told from unset, so a stored projectInstructions value still applies (isLegacyRead). Setting instructionFiles to anything else ignores the legacy key and logs that it should be removed. Project .claude/settings.json is not read for plugin options. --bare sets CLAUDE_CODE_SIMPLE and disables nested Read attachments, but the walk itself finds nothing when the engine loads no instruction files. — [mods/agents-md/hooks/register.ts#L40-L48](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/agents-md/hooks/register.ts#L40-L48) [mods/agents-md/hooks/register.ts#L271-L279](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/agents-md/hooks/register.ts#L271-L279) [mods/agents-md/README.md#L63-L74](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/agents-md/README.md#L63-L74)
- Trap: sec-default next.to is refused outside a managed tier, so claude --plugin-dir mods/sec-default does not exercise the security property. Tests must tier('prepend'). Policy source is exactly {source:'policy'}. Empty allowedMcpServers still counts as an allowlist because hasMcpAllowlist only checks Array.isArray. — [mods/sec-default/README.md#L45-L54](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/sec-default/README.md#L45-L54) [mods/sec-default/tests/register.test.ts#L6](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/sec-default/tests/register.test.ts#L6) [mods/sec-default/hooks/policy/source.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/sec-default/hooks/policy/source.ts) [mods/sec-default/hooks/policy/has-mcp-allowlist.ts](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/sec-default/hooks/policy/has-mcp-allowlist.ts)
- Trap: security-guidance Bash routing. hooks.json fires the script once per matching if, so git commit && git push starts two processes with the same tool_use_id. main() must keep the commit check first and _claim_bash_hook_once must keep the second spawn on bash_hook_dedup. Reversing the order drops commit review. Plans under ~/.claude/plans are skipped. SECURITY_GUIDANCE_DISABLE must still emit metrics or asyncRewake Stop hooks hang. — [plugins/security-guidance/hooks/security_reminder_hook.py#L2023-L2108](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/security-guidance/hooks/security_reminder_hook.py#L2023-L2108) [plugins/security-guidance/hooks/security_reminder_hook.py#L2116-L2120](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/security-guidance/hooks/security_reminder_hook.py#L2116-L2120) [plugins/security-guidance/hooks/hooks.json#L35-L68](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/security-guidance/hooks/hooks.json#L35-L68)
- Trap: issue automation. Do not call gh directly from triage or dedupe prompts; scripts/gh.sh exits on any other subcommand or flag. Do not duplicate timeout numbers; import lifecycle. comment-on-duplicates.sh only works when GITHUB_EVENT_PATH is set and the repo is anthropics/claude-code. CLAUDE_CODE_SCRIPT_CAPS in the workflow must name any new script or the action will refuse it. Sweep and lifecycle comments need GITHUB_TOKEN. — [scripts/gh.sh#L29-L36](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/scripts/gh.sh#L29-L36) [.claude/commands/triage-issue.md#L14-L23](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.claude/commands/triage-issue.md#L14-L23) [scripts/comment-on-duplicates.sh#L11-L19](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/scripts/comment-on-duplicates.sh#L11-L19) [.github/workflows/claude-issue-triage.yml#L33-L34](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.github/workflows/claude-issue-triage.yml#L33-L34) [scripts/issue-lifecycle.ts#L1-L3](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/scripts/issue-lifecycle.ts#L1-L3)
- There is no root lint, format, or unit-test script. Prettier and ESLint appear only as VS Code settings inside .devcontainer. Python files have no pyproject.toml or requirements.txt in the reviewed tree; security-guidance vendors its interpreter selection in sg-python.sh and ensure_agent_sdk.py. Do not npm install inside the repo; CI installs the CLI globally. — [.devcontainer/devcontainer.json#L24-L29](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.devcontainer/devcontainer.json#L24-L29) [.github/workflows/mod-tests.yml#L21-L23](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/.github/workflows/mod-tests.yml#L21-L23) [plugins/security-guidance/hooks/hooks.json#L9](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/security-guidance/hooks/hooks.json#L9) [plugins/security-guidance/README.md#L19-L23](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/security-guidance/README.md#L19-L23)
- Docs to keep consistent when behaviour changes: the mod's own README (it is the contract for which events are hooked and which $ nouns are called), plugins/README.md table if a marketplace plugin's commands change, and marketplace.json description fields. CHANGELOG.md in the repo root records CLI releases and is not a substitute for those local READMEs. SECURITY.md only points at HackerOne. — [mods/diff/README.md#L68-L90](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/diff/README.md#L68-L90) [mods/telemetry/README.md#L58-L73](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/mods/telemetry/README.md#L58-L73) [plugins/README.md#L11-L27](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/plugins/README.md#L11-L27) [SECURITY.md](https://github.com/anthropics/claude-code/blob/b486776a2eef0d3f39abaebaa3c03e378c7480b8/SECURITY.md)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)