#11169: fix(security): remove bundled soul-evil hook that enables silent agent hijacking
docs
stale
Cluster:
Soul Hooks Security Enhancements
## Summary
Remove the bundled `soul-evil` hook, which can silently replace the agent's core system prompt (`SOUL.md`) with an attacker-controlled alternate file (`SOUL_EVIL.md`) at runtime.
While disabled by default, shipping this code in every installation creates an unnecessary attack surface — a successful prompt injection could chain `write` + `config.patch` to enable the hook and achieve **persistent agent compromise** without user notification.
## Security Rationale
1. **No legitimate use case** — any persona-swapping can be done by editing `SOUL.md` directly
2. **"Disabled by default" is insufficient** — the attack surface exists in every installation
3. **Prompt injection chain risk** — `write(SOUL_EVIL.md)` → `config.patch(enable hook)` → `restart` = persistent hijack
4. **Compounds with token exposure** — an attacker who obtains a gateway token could enable this hook remotely
## What's Removed
| Category | Files |
|---|---|
| Core logic | `src/hooks/soul-evil.ts` |
| Core tests | `src/hooks/soul-evil.test.ts` |
| Bundled hook | `src/hooks/bundled/soul-evil/` (handler, tests, docs) |
| EN docs | `docs/hooks/soul-evil.md` |
| zh-CN docs | `docs/zh-CN/hooks/soul-evil.md` |
**References cleaned from:**
- `src/hooks/bundled/README.md`
- `docs/hooks.md` + `docs/zh-CN/hooks.md`
- `docs/cli/hooks.md` + `docs/zh-CN/cli/hooks.md`
- `docs/docs.json` (nav entries)
## Verification
```bash
grep -rn "soul-evil\|soul_evil\|soulEvil\|SOUL_EVIL" src/ docs/
# Returns zero matches
```
No dangling references remain. The hook loader (`src/hooks/loader.ts`) uses dynamic directory discovery — removing the `soul-evil` directory is sufficient; no loader code changes needed.
Users who want persona-swapping functionality can implement it via custom hooks, explicitly accepting the risk.
Closes #8776
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR removes the bundled `soul-evil` internal hook implementation, its tests, and associated documentation/navigation entries. The docs were updated to reflect one fewer bundled hook and to remove CLI/docs references to `soul-evil`, while `docs/docs.json` drops the nav pages.
The main risk is process-related: the PR also edits/removes `docs/zh-CN/**` content, which the repo guidelines state is generated via the i18n pipeline and typically should not be hand-edited. If that guidance is still current, these changes should be reverted and regenerated to avoid future churn.
<h3>Confidence Score: 4/5</h3>
- This PR is largely safe to merge, but it should be corrected to follow the docs i18n process for zh-CN content.
- The change is primarily deletions of an internal hook and documentation, and repository-wide search shows no remaining references. The only clear merge-blocking issue is that it manually modifies generated `docs/zh-CN/**` files, which will likely be overwritten and create churn unless handled via the i18n pipeline or the guideline is updated.
- docs/zh-CN/hooks.md; docs/zh-CN/cli/hooks.md; docs/zh-CN/hooks/soul-evil.md
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#7036: Fix evil soul hooks by enforcing env properties
by myberry2026 · 2026-02-02
81.8%
#9914: fix(hooks): resolve bundled hook dist paths and packaging checks
by zimmra · 2026-02-05
80.1%
#8716: fix(soul-evil): minimal simplification of env config merging
by myberry2026 · 2026-02-04
79.2%
#13029: fix(docs): add redirect from /hooks to /automation/hooks
by asklee-klawd · 2026-02-10
79.2%
#14222: core: add needsApproval to before_tool_call; move AgentShield to ex...
by Eventedge · 2026-02-11
79.2%
#3392: fix(hooks): remove debug console.log statements from session-memory...
by WinJayX · 2026-01-28
77.8%
#11048: fix: address repository issues (env, author, CI comments, security ...
by cavula · 2026-02-07
77.4%
#16461: feat: flexible soul injection and quiet TUI
by krry · 2026-02-14
76.2%
#11817: fix(build): compile bundled hook handlers into dist
by AnonO6 · 2026-02-08
76.2%
#7892: Claude/setup agent firewall ww xsv
by starwreckntx · 2026-02-03
75.9%