Claude Code hooks for subagents and teams

The hook for subagent and team by Claude Code they must be placed in the level that really represents the rule. Settings hooks also apply to subagent tool calls; hooks in the frontmatter of a supported agent are valid during its activity. For agents distributed in a plugin there is a decisive exception: the frontmatter field hooks is ignored and controls should be defined at the plugin level. Subagents and Plugin Components.

An end-response, an end-agent, and a completed marked task are different facts. The check must observe the fact that it matches the requirement, identify the role and read a relevant test. Recording the same script anywhere can produce duplicates or a verification at the wrong time. The Guide to the Claude Code Hooks introduces general contracts.

Verified Sources on 9 October 2026. Team configurations and cases are hypothetical proposals not executed, with synthetic names. The ability to certify all changes to a project is not attributed to an automatic proxy.

Where does a team rule have to live?

A common rule, such as a limit on modifiable paths, may belong to the project settings or the appropriate administrative level. A condition dedicated to a role can live in the definition of the agent when that form supports it. A component distributed within a plugin follows the plugin contract. Provenance is therefore part of behavior, not an organizational detail.

Decide first who should be subject to the rule: all agents, a specific role or just a task. A rule for all should not depend on each author remembering to copy it in the frontmatter. A rule of a role should not indiscriminately block agents who do not have the tools necessary to satisfy it.

The settings documentation describes policies and configuration sources. Settings by Claude Code. For group distribution, Team and Security Mods complete the path: authorizing a plugin does not guarantee that every process it starts is sandboxed.

What data makes it possible to identify the subagent?

Hook inputs may include agent_id and agent_type to identify the activity of the subagent. Events SubagentStart and SubagentStop It concerns its departure and conclusion, while tool events continue to describe individual calls. The role helps to filter; the identifier helps to attribute a proof to the single execution. Common input.

A role name is not enough to certify the work. An agent called a "verifier" may not have run the relevant suite. The control must read which command was executed, which state was verified, and which result was obtained. The name is a convention, the proof is a distinct fact.

Avoid using identity to expand privileges without reason. A role may need limited tools; its hook should restrict a liability, not grant a general authorization. For the preventive part consult PreToolUse for files and commands.

A starting event with a synthetic role

The following recording only shows how to filter SubagentStart on a hypothetical role project-checker. The command produces a line on stdout, captured in the debug log: it is a smoke test of the matcher, not a message added to the context of the subagent. It does not initialize services and does not initiate other agents. The role must exist in the real configuration; the snippet was not executed in this guide. SubagentStart.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "project-checker",
        "hooks": [
          {
            "type": "command",
            "command": "printf 'Ruolo di verifica avviato: leggere il contratto del task.\\n'"
          }
        ]
      }
    ]
  }
}

This output is used to observe the execution in the log, it does not orient the subagent. To add context with SubagentStart the reference requires hookSpecificOutput.additionalContext, along with hookEventName. If the role needs to verify a form, you also need a task document that indicates what evidence to collect and what files it can read or edit. Do not print in the project's log transcript or credentials.

For a test, use one included role and one excluded from the matcher. Check in the debug log that the line is only produced for the included role, without expecting an alert in the UI or a subagent instruction. If the name does not match, Hooks debugging helps to control actual event and identity before changing the logic.

What changes for hooks in the frontmatter?

For agents supporting this form, frontmatter hooks are active during the execution of the agent. Stop is converted to behavior related to SubagentStop, according to the documentation. The team must therefore understand which conclusion is verifying and not assume that it is the final response of the coordinator. Hooks for subagents.

The local duration to the role is useful for dedicated control, but does not replace a common tool policy. If the requirement must apply before each write, placing it only in the review role leaves out the rest of the workflow. The responsibility matrix must list who performs each class of operation.

The documentation also indicates rules of trust for project agents, changed from historical versions. Before copying an old example, check the behavior of the installed version. The official subagent page is the source of the current contract, not a testimony that that configuration has already worked on the reader's computer.

Why do plugin agents ignore hooks in the frontmatter?

The plugin components page lists agent definition fields that are not applied in that context, including hooks. It is an explicit boundary of the configuration. Copying the definition of a local agent inside a plugin can then keep the text of the field without maintaining its effect. Frontmatter fields in plugins agents.

The control must be moved to the plugin hooks, with the filter suitable for the role. The packaging must make this responsibility visible: manifest, agent definition, hook recording and synthetic tests must be read together. It is not enough to see the field in the file to conclude that it is executed.

To understand the packaging of a plugin, Mods by Claude: what are they It distinguishes its possible functions. Install Mods and Plugins helps to verify broom and loaded version. The actual location of the configuration matters more than the similarity of the source files.

TaskCompleted, SubagentStop and TeammateIdle: What do they verify?

SubagentStop It is about the end of the subagent. TaskCompleted concerns the time when a task is marked as completed. TeammateIdle is about an agent teammate who is about to become inactive. Control must be linked to the observed condition and contract of that event. TaskCompleted and TeammateIdle.

A small task can be concluded while the project remains open. A verifier can end by reporting a failure, which is still a useful result. The policy must preserve these differences, instead of using "finished" for everything.

How to define a verifiable proxy contract?

Each proxy should indicate target, file scopes, necessary tools, result criteria, and limit. For a review, the output can be a list of demonstrable problems with code references. For QA, it can be command, outcome, and blocks. For implementation, you also need to know which files belong to the role and which can be modified by others.

A hook can control the presence and consistency of these elements, but it doesn't have to rely solely on keywords. A phrase "tests performed" may be present without a result. A structured proof must refer to the form and version of the content. If the coordinator applies new edits after delegation, a new verification may be needed.

PostToolUse for formatting and testing describes the collection of feedback during work. SessionStart and compaction explains why the proxy status must live in upgradable files, as well as a message that could be synthesized.

How to design a dedicated validator without promising too much?

A validator can control a circumscribed input: path included in the scope, result of a command or structure of a document. You have to state what you don't control. An example on read-only queries must not become a promise that a regex will prevent any writing on a database. Real protection also requires privileges in the backend.

When the control calls an external tool, it checks availability and authentication before inserting it into the delegation. Hooks and MCP distinguishes the observed tool from the tool used as a handler. The role must not invent a scanner result when the connection is unavailable.

The verifier ends with an incomplete test

The task requires an integrated test, but local service is not available. The role must return the completed checks, the unexecuted one and the missing prerequisite. The coordinator retains the distinction and does not translate the end of the subagent into a positive validation of the task.

What is the risk of recursion between agents and hooks?

A hook that generates an agent can trigger other events; if the same rule still generates agents, an unintentional chain is born. Even a review can become endless if every reviewer asks for another reviewer. The SDK documentation reports this risk for callbacks that invoke additional agents. Agent SDK Hooks.

Define an explicit limit and control over the origin of the work. Don't just change the name of the new agent: the problem is the circular dependence of the process. For an end-response condition, Stop hook without loop describes stop_hook_active and requests for continuation are over.

The coordinator should be able to distinguish a verification required by the original task from an automatically generated verification. This helps to read latency, outputs and blocks without attributing to AI a need that only arises from configuration. A useful autonomous process also knows how to end with a well-described impediment.

Are settings hook and callback SDK interchangeable?

No. In the SDK hooks are callbacks configured in the program options. The settings hooks follow the Claude Code contract and the plugin components have another distribution path. Versions and languages of the SDK can expose different events; do not copy a Python or TypeScript snippet assuming it matches a JSON file of settings. SDK Hooks reference.

If you are building an application that orchestrates agents, the responsibility for callbacks also belongs to the orchestrator code. The program needs to know which settings it loads, how it treats the result, and what tools it makes available. A hook in the repository does not prove that the SDK loaded it.

Distinction also helps in diagnosis. A problem in a callback does not necessarily resolve with /hooks; a problem in a settings file does not resolve by changing the signature of an SDK function. Identify the layer first, then the suitable proof at that level.

Two Italian teams with separate responsibilities

Hypothetical, untested example: a software house in Trento delegation implementation and verification of a module to two distinct roles. The author edits only the assigned files; the verifier reads the diff and initiates the relevant controls. The task is not considered validated because the verifier ends: its outcome is needed. If the author changes the form again, the coordinator evaluates which tests to repeat.

Hypothetical, untested example: a technical practice in Pescara packages an analysis agent into an internal plugin. The author initially copies a frontmatter with hooks; documentation shows that field is ignored for plugin agents. The team then defines the registration in plugin hooks, prepares an included and an excluded case and verifies the version actually loaded, using only dummy documents.

Cases do not demonstrate quantitative advantages. They show two preventable errors: confusing agent term and successful proof, or confusing field presence and its application in packaging.

How to maintain the workflow when growing the team?

Preserve a matrix with role, files, tools, control event, and final test. Update it when an agent changes responsibility or when the plugin is distributed in another broom. Frequent errors are duplicate hooks, roles without prerequisites, tests referring to outdated files, and checks that invoke each other.

A test with synthetic data should include expected role, excluded role, positive result, failure and unavailable control. The team needs to know who reads the outcome and who decides the next action. Delegation does not erase this responsibility: it makes it more distributed and therefore more important to document.

The design of AI agents can start from a single role with verifiable output and only grow when the process requires it. A delegated workflow works well when each event has a precise meaning, each test belongs to a task and the overall conclusion is a decision based on those results.