Assess Configured Agent for Claude Code safely

What a Configured Agent for Claude Code is and why it is used

A Configured Agent in Claude Code refers to a custom subagent, a specialized AI assistant with its own system prompt, its own tool access, and its own permissions, set up for a specific type of task. According to Anthropic's official Claude Code documentation at code.claude.com, subagents exist to take on work that would otherwise flood the main conversation with search results, logs, or file contents that won't be needed again. The subagent does that work in its own isolated context window and returns only a summary to the main session at the end. This matters because Claude Code, as a coding agent, quickly runs up against the limits of the available context window on complex, multi-step tasks; a well-configured subagent keeps the main session lean while simultaneously being restricted to a narrower set of tools and rules, which lowers cost and improves result quality for recurring, clearly scoped tasks.

Prerequisites

The prerequisite is an installed and working version of Claude Code, since subagents are purely a feature of that product. According to the documentation, a subagent is defined as a single file with YAML frontmatter in which at minimum the name and description fields must be set; all other fields such as tools, model, or permissionMode are optional. To reuse subagents across multiple projects, it is recommended to place them at the user level rather than the project level, which requires familiarity with Claude Code's directory structure. Anyone wanting to connect a subagent to its own MCP servers additionally needs a working MCP server configuration, and anyone wanting to use specific models like Haiku for cheaper subagents needs access to the corresponding Anthropic model quota.

Setting it up step by step

A new subagent is created by adding a file with YAML frontmatter in Claude Code's relevant skills or agents directory; according to the documentation, the filename does not have to match the name field, but it must not contain a colon, since that character is reserved for plugin-scoped identifiers. The first step is choosing the scope, i.e. whether the subagent should only be available for the current project or globally for the user. Next, a short, precise description is written, since Claude uses this description to decide when to delegate a task to the subagent; according to the provider, once the combined descriptions of all subagents exceed roughly 15,000 tokens, this noticeably consumes context and triggers a warning at startup. After that, the tool set can optionally be restricted via tools and disallowedTools, a model can be set via model, and a permission mode can be chosen via permissionMode if needed. Finally, the subagent can either be invoked automatically by Claude based on its description or addressed explicitly by the user.

Security and best practices

From a security standpoint, the most important lever is deliberately restricting tool access through the tools and disallowedTools fields, since a subagent inherits every tool available to subagents by default if nothing is specified. According to the documentation, an entry with a specifier, such as Bash(git push *), removes the entire associated tool rather than just the specified subcommand, which should be kept in mind when configuring one. The permissionMode field additionally lets a subagent run more strictly than the main session, for example in plan mode without execution rights. The provider also recommends limiting the maximum number of turns via maxTurns to avoid uncontrolled long runs, and using the omitClaudeMd field when a subagent should deliberately operate without project-specific CLAUDE.md rules because it already receives everything it needs through the delegation prompt.

A practical example and its limits

A typical example from the official documentation is a code-reviewer subagent that is given only read and analysis tools and automatically performs delegated reviews on every code change without having write access to the repository itself, or a database query validator that checks queries before they run. The limits are that subagents operate within a single session and are not suited to fully independent, parallel-running sessions; for that, the documentation points to separate concepts such as background agents or agent teams. In addition, every extra description consumes context right from Claude Code's startup, which means too large a number of subagents with lengthy descriptions can itself become a performance problem.