Plugins
Add Claude Code plugins, and what their hooks do.
A plugin adds skills, commands, agents, hooks, MCP servers and language servers. ngram reads Claude Code plugins as they are. Settings › Plugins lists each one with a switch, what it adds, and any problem loading it.
| Scope | Location |
|---|---|
| Global | ~/.ngram/plugins/<plugin>/ |
| Project | .ngram/plugins/<plugin>/. Loads only once the folder is trusted. |
Hooks
A hook runs when something happens in a thread. A plugin's hooks are in hooks/hooks.json, grouped by event:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/format.sh" }]
}
]
}
}| Type | Does |
|---|---|
command | Runs a program. |
http | Posts the hook's input to a URL. |
mcp_tool | Calls a tool on an MCP server. |
prompt | Asks a model a question. |
agent | Runs a read-only agent. |
All five run on tool events, UserPromptSubmit, Stop and SubagentStop. Session and lifecycle events take command, http and mcp_tool, and SessionStart takes command and mcp_tool. A hook its event does not take is skipped, and the plugin's row says so.
Events that run
| Group | Events |
|---|---|
| Tools | PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest |
| Messages and agents | UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, SubagentStart, SubagentStop |
| Thread | SessionStart, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, ConfigChange, FileChanged, PreModelSwitch, PostModelSwitch, MessageDisplay, Notification, TaskCreated, TaskCompleted |
Events that never fire
These load, and the plugin's row lists them as Never fires here.
| Event | Why |
|---|---|
Setup | It runs only for command line flags, and a thread has none. |
PermissionDenied | It runs only when auto mode's classifier denies a call, and ngram has no classifier. |
CwdChanged | Each shell call starts in the thread's folder, so a cd never carries over. |
DirectoryAdded | A thread has the one folder it opened, with no way to add another. |
TeammateIdle | It belongs to agent teams, which ngram does not have. |
WorktreeCreate, WorktreeRemove | ngram makes no worktrees. |
Elicitation, ElicitationResult | ngram's MCP client does not take input requests from a server. |
An event name ngram does not know loads with a warning.
What a hook is sent
A command hook gets Claude Code's hook JSON on stdin, and an http hook gets it as the request body. It holds the thread's session_id, the cwd, the hook_event_name and the event's own fields, such as tool_name and tool_input. Tools go by Claude Code's names: Bash, Read, Write, Edit, Grep, Glob and Agent.
What its answer can do
- Exit 0 succeeds, and JSON on stdout applies. Exit 2 blocks on an event that can block, and stderr is the reason the agent reads.
- Any other exit, a timeout or a bad answer shows a notice. The turn carries on.
systemMessageshows as the plugin's row in the thread. The model never sees it.additionalContextis added for the model.continue: falseends the turn after the hook.- A
PreToolUsehook can answerpermissionDecisionallow,denyorask, andupdatedInputto change the call.PostToolUsecan change the result withupdatedToolOutput.
allow skips the approval card the call would have raised. It never overrides a deny rule, a rule that asks, or the sandbox. A plugin from a project folder cannot allow.
Hooks run outside the sandbox
A hook runs as you, with the project folder as its working directory, and the sandbox does not apply to it. An http hook sends the hook's input, a prompt included, to its URL. Turn on only plugins you trust.