rulereach-delegate
English · Русский · 简体中文 · Español · Português
A subagent definition is a promise about a fresh context window: this prompt, these tools,
these skills. Claude Code keeps part of that promise and quietly rewrites the rest. A
background subagent, which is the default, keeps only a fixed list of built-in tools, so
BashOutput in your tools list is dropped with no error. A tools list that survives
none of the filters makes the agent fail to launch. A skill named in the prompt but missing
from the skills field is not in the context at startup. A skill that forks into Explore
sees no CLAUDE.md at all. An agent: that does not resolve falls back to a general-purpose
agent with a wider tool pool than the one you asked for.
rulereach-delegate reads .claude/agents/, plugin agents/ directories and every
SKILL.md in a repository, applies the documented startup and tool-filter rules, and reports
what delegation drops. It runs offline and cites the documentation page behind every finding.
$ rulereach-delegate check
.claude/agents/narrowed.md
x skill-unreachable the prompt mentions the 'deep-research' skill, but it is not preloaded and the agent has no Skill tool
fix: add deep-research to the skills field, or add Skill to tools
docs: https://code.claude.com/docs/en/sub-agents#preload-skills-into-subagents
! tools-background-removed BashOutput is dropped for a background subagent, which is the default, and the removal reports no error
fix: keep the agent in the foreground for this work, or drop the tool from the list so the definition says what the agent really gets
docs: https://code.claude.com/docs/en/sub-agents#available-tools
.claude/agents/zero-tools.md
x tools-zero no entry in tools survives the documented filters, so the agent fails to launch
fix: list tools the agent can actually keep, such as Artifact, Bash, Edit, EnterWorktree
docs: https://code.claude.com/docs/en/errors#agent-would-be-spawned-with-zero-tools
.claude/skills/deep-research/SKILL.md
! fork-skips-memory agent: Explore skips the CLAUDE.md hierarchy, so 4 instruction line(s) in it, 3 of them prohibitions, do not reach this fork
fix: restate the rules this task depends on inside the skill, or fork into an agent that loads CLAUDE.md
docs: https://code.claude.com/docs/en/sub-agents#what-loads-at-startup
rulereach-delegate: 5 error(s), 5 warning(s), 2 note(s)
Install
pipx install rulereach-delegate # or: uv tool install rulereach-delegate
Nothing is sent anywhere: the tool reads files and exits. No API keys, no network calls.
Use
rulereach-delegate check # report what delegation loses, exit 1 on errors
rulereach-delegate check --strict # exit 1 on warnings and notes too
rulereach-delegate check --check tools-zero # one check at a time
rulereach-delegate check --exclude "tests/fixtures/**"
rulereach-delegate list # every subagent and forking skill
rulereach-delegate explain code-reviewer # what that agent starts with
explain is the answer to "why did the subagent ignore that":
$ rulereach-delegate explain deep-research
deep-research (.claude/skills/deep-research/SKILL.md, forking skill)
Reaches it at startup:
- its own system prompt: the skill content, injected as the task
Does not reach it:
- the CLAUDE.md hierarchy: 4 instruction line(s), 3 of them prohibitions, and the git status snapshot
- the parent conversation history and the files already read
- skills invoked in the parent session, unless named in the skills field
- the output style and the parent's auto memory
Tools: inherits every tool available to subagents.
Runs in the background (the default); a background subagent keeps only a fixed set of built-in tools, 19 of them, plus every MCP tool.
Add --json to any command for machine-readable output.
Checks
| ID | What it catches |
|---|---|
not-loaded |
agent file Claude Code skips: unparsable frontmatter, no name, a name with a colon or leading hyphen, or a name with no description |
unknown-field |
frontmatter key that is not a subagent field, such as a skill's allowed-tools, so it is ignored |
tools-removed |
tool removed from every subagent even when listed, such as AskUserQuestion or ExitPlanMode outside plan mode |
tools-background-removed |
built-in tool a background subagent does not keep, dropped without an error |
tools-zero |
no entry in tools survives the filters, so the agent fails to launch |
tools-denied-conflict |
tool in both tools and disallowedTools, so it is denied |
skill-missing |
skills names a skill that is not in the repository |
skill-not-preloadable |
skills names a skill with disable-model-invocation: true, which cannot be preloaded |
skill-unreachable |
prompt names a skill that is neither preloaded nor reachable, because the agent has no Skill tool |
skill-not-preloaded |
prompt names a skill the agent must discover itself instead of starting with its content |
fork-agent-unresolved |
agent: in a forking skill that resolves to nothing, so the fork runs general-purpose with a wider tool pool |
fork-skips-memory |
fork into Explore or Plan, which skip the CLAUDE.md hierarchy and git status |
fork-background-tools |
tool pre-approved in allowed-tools that a background fork does not have |
model-unknown |
model that is neither an alias nor a full model ID |
Severity is about consequence, not style. An error means the definition cannot do what it says: the agent does not load, does not launch, or loses a capability it names. A warning means it silently gets less than the file promises. A note is behaviour worth knowing that is not a mistake.
The documented sentences each check is built on are collected in docs/semantics.md, with the date they were read.
Scope
Claude Code only, and only what a repository can carry: .claude/agents/, plugin agents/
directories, .claude/skills/*/SKILL.md, the CLAUDE.md hierarchy with its imports, and
.claude/rules/. Subagents installed at user scope in ~/.claude/agents/ are outside a
repository, so they are outside a repository check. Runtime behaviour is out of scope too:
this is a static audit of definitions, not a transcript analyser.
Configuration
Optional. Put the flags you would otherwise repeat into pyproject.toml:
[tool.rulereach-delegate]
exclude = ["tests/fixtures/**"]
strict = false
Projects without a pyproject.toml can use a .rulereach-delegate.toml with the same keys at
the top level. If both exist, .rulereach-delegate.toml wins, and command line flags win over
both. An unreadable file, an unknown key or a value of the wrong type is reported on stderr
rather than ignored.
In CI
- name: rulereach-delegate
run: uvx rulereach-delegate check
check exits 1 when there is at least one error, 0 otherwise. Use --strict to fail on
warnings as well.
Alternatives
- skilldoctor, skillcheck,
claudelint and
claude-plugins-validation validate
the shape of skill,
CLAUDE.mdand subagent files: frontmatter schema, referenced paths, security patterns. Some of them check a subagent's frontmatter fields as well. They stop at the file; this tool continues into what the runtime does to it, which is where the tool filters and the startup composition live. - rule-trace answers the same question at runtime: it asks the agent to disclose which rules it applied, and counts those disclosures over time. That needs your rules migrated into its format and a hook wired up. This tool is static and needs nothing but the repository.
claude plugin validatefinds agent files whose frontmatter does not parse. It does not flag a file that parses but has noname, and it does not model the tool filters.
Related
- rulereach - whether an instruction file reaches the main agent at all: Codex, Claude Code, Cursor, Copilot.
- skillfrisk - scan agent skills and MCP servers for prompt injection and unsafe instructions.
- ciparity - find drift between pre-commit hooks and your CI pipeline.
License
MIT
Metadata
Release files for rulereach-delegate 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rulereach_delegate-0.1.1.tar.gz | 196.5 kB | With provenance | Details for rulereach_delegate-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rulereach_delegate-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for rulereach_delegate-0.1.1-py3-none-any.whl |
Total release size: 221.6 kB
Release files / rulereach_delegate-0.1.1.tar.gz
| Download URL | rulereach_delegate-0.1.1.tar.gz |
|---|---|
| Size | 196.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
594a2c5eb76ca10613af4752ef5b93d5f1252bafa14dd6d4a07deedcb67ed6a6
|
|
BLAKE2b-256 checksum How to use checksums |
9c1db72acfd3787f881b8eb5239d717039ea31717d9269d48bc9c2b17449eb26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / rulereach_delegate-0.1.1-py3-none-any.whl
| Download URL | rulereach_delegate-0.1.1-py3-none-any.whl |
|---|---|
| Size | 25.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a0980499d26fc433d12282a36b14d5aa65f9097040ba92398ba6db9dacba52b
|
|
BLAKE2b-256 checksum How to use checksums |
cd24fa41381ec87b5c58fcf66c7e255c6fbd7ba8bff73efbd45a91dfa1d113f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logSecurity for rulereach-delegate 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rulereach_delegate-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.