skills.rest
cajias
cajiasCOMMUNITY
Explore all skills by this author →
GitHub

cc-hooks-main-vs-subagent

Detect Claude Code hook invocations from main threads versus subagents.

Updated Nov 18, 2025
Search Tags:#claude code#hooks#permissions#subagent#headless testing#main thread
One-click install
npx skills add https://github.com/cajias/claude-skills --skill cc-hooks-main-vs-subagent
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cc-hooks-main-vs-subagent
Source: https://github.com/cajias/claude-skills/tree/main/plugins/cc-authoring/skills/cc-hooks-main-vs-subagent
Command: npx skills add https://github.com/cajias/claude-skills --skill cc-hooks-main-vs-subagent

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill explains how to tell whether a Claude Code hook was triggered by the main conversation thread or by a subagent, so you can enforce different behaviors without blocking the wrong tool calls.

Core Features & Use Cases

  • Main-vs-Subagent Detection: Identifies the undocumented hook input fields that distinguish subagent calls from main-thread calls.
  • Interactive vs Headless Handling: Shows how to exempt headless claude -p sessions from interactive enforcement when needed.
  • Reliable Hook Testing: Documents the common testing pitfalls that can hide hook denials behind permission-gate errors.
  • Use Case: Build an orchestrator-only hook that denies file edits in the main thread while allowing delegated subagents to proceed.

Quick Start

Use this skill to determine whether your Claude Code hook should treat a tool call as coming from the main thread or a subagent and apply the right permission logic.

Frequently Asked Questions about cc-hooks-main-vs-subagent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a Claude Code hook was triggered by the main thread or a subagent?▼

You can distinguish main thread from subagent Claude Code hooks by inspecting undocumented agent_id and agent_type input fields, enabling orchestrator-only enforcement without blocking delegated subagent tool calls.

Can I exempt headless Claude Code sessions from interactive hook enforcement?▼

Yes, you can exempt headless Claude Code sessions by checking the CLAUDE_CODE_ENTRYPOINT variable, allowing automated claude -p runs to bypass interactive enforcement logic designed for standard conversations.

How do I build an orchestrator-only hook that denies file edits in the main thread?▼

Build an orchestrator-only hook by detecting the main thread via agent_type, then denying file edits there while allowing subagents to proceed, ensuring delegated tasks are not blocked by main thread restrictions.

Why are my Claude Code hook denials hidden behind permission-gate errors during testing?▼

Claude Code hook denials are often masked by permission-gate errors during testing because the validation logic overlaps, requiring careful test design to avoid hiding actual hook denial behavior behind standard permission failures.

What is the best way to audit subagent tool calls without affecting main thread behavior?▼

The best way to audit subagent tool calls independently is to target hook logic specifically at subagent invocations using the agent_id field, leaving main thread orchestrator behavior completely unaffected.

Related Skills

Explore More Software Engineering Skills→
twiced-technology-gmbhtwiced-technology-gmbh

agent-creator

Guide creation and configuration of Claude Code agents with frontmatter fields.

Official
Intermediate
phant-appphant-app

subagent-driven-development

Dispatch subagents to implement plan tasks with mandatory review gates.

Official
Advanced
AreteDriverAreteDriver
4

cicd-pipeline

Implements CI/CD pipelines using Batcomputer for automated code review and deployment gating.

Community
Advanced
jpoutrinjpoutrin
14

agent-tools

Configure Claude Code agent tool permissions with path and command restrictions.

Community
Basic