Seven modules depend directly on Session Store, with no fallback: ClaudeSDKClient, the Internal Client, Package Exports, Session Mutations, Session Resume, Sessions and the Transcript Mirror Batcher. Both clients call validate_session_store_options, Session Resume and Session Mutations call _store_implements, and Package Exports re-exports InMemorySessionStore. Package Exports also depends on ClaudeSDKClient, so a failure reaches the public entry point twice.

Impact: A defect in Session Store breaks both the interactive and one-shot clients and every session read, write and resume, and shows up at the public package surface.

Session Store is the hub of session management: 12 of the 23 other elements in this package depend on it, directly or indirectly. Treat changes to session_store.py and session_store_validation.py as changes to the whole session feature, and cover them with tests that go through both clients.

Types defines the SessionStore protocol, whose optional methods have default bodies that raise NotImplementedError. Support is detected by checking whether the adapter's class overrides the default (_store_implements), and continue_conversation is refused up front when list_sessions is not overridden. That contract lives in types.py, which 13 of 23 modules on the board depend on, only 3 directly: Control Protocol Query, Session Store and ClaudeSDKClient.

Impact: Changing which SessionStore methods are required, or what their defaults do, silently changes the override check that session validation and resume rely on.

Treat the raising defaults in SessionStore as the definition of 'optional'. Add a new optional method as a raising default, and cover it in session_store_validation so unsupported combinations fail before the subprocess starts.

sanitizer.ts is imported by 8 files across 7 modules: the prompt builder, the context formatter, the tracking comment, the comment and inline comment MCP servers, post-run reporting and the run orchestrator. It is a list of regexes with no other layer behind it, so a regression silently reopens every inbound and outbound path at once.

Impact: A missed pattern, such as a new Unicode tag block or an HTML construct, lets hidden instructions reach Claude everywhere at once.

Recommendation (small effort): Add a shared fixture test of known hiding tricks that runs against sanitizeContent and against each caller's output, so a gap fails CI at every entry point.

Control Protocol Query routes control responses and conversation messages through one reader task. That task awaits a send into a 100-message buffer (query.py:229, 506), so when the caller is not iterating receive_messages and the buffer fills, the control_response for interrupt(), set_model() or get_mcp_status() is never routed and the call fails after 60 seconds with Control request timeout. Only an example script warns that interrupts require active consumption.

Impact: The escape hatch fails exactly when it is needed: a runaway turn with partial messages enabled fills the buffer in seconds, and interrupt() then times out instead of stopping it.

Recommendation (small effort): Route control_response frames before any await on the message buffer, or give control responses their own path that never waits on the consumer. Document the consumption requirement on interrupt() itself.

The Marketplace Catalog is the most connected part of the system. Claude Code installs from it, it lists every first-party, channel and integration plugin by source path or pinned git SHA, and three of the four CI jobs read or rewrite it. Reading .claude-plugin/marketplace.json first explains why the rest of the repo exists.

Look at one local entry (./plugins/...), one external entry (git-subdir with ref and sha), and the renames map. Those three shapes cover how every plugin reaches users.

The core flow is install and load: Claude Code reads the catalogue, fetches a plugin, then loads its commands, agents, skills and hooks. Pick one rich plugin such as Hookify or Code Modernization and trace one command to the agents and scripts it drives; the plugin-dev plugin documents the same structure as skills.

Every first-party plugin is self-contained, so understanding one deeply transfers to the rest; there is no shared framework to learn first.

Session Store holds the SessionStore protocol, the in-memory store and the option validation. Seven parts of the SDK depend on it: both clients and the package exports (public API and internal client), the session mutations, resume, listing and reading modules, and the transcript mirror batcher that appends entries. A change to the protocol or its validation lands in all three groups at once.

Impact: Changing a store method or the validation rules forces coordinated edits across the public API, session management and the one-shot query path.

Recommendation (medium effort): Treat the SessionStore protocol as a stable contract: add methods only with defaults, and keep validate_session_store_options and _store_implements as the single place that checks what a store supports.

The exception hierarchy in _errors.py (ClaudeSDKError, CLIConnectionError, CLINotFoundError, ProcessError, ResultError, CLIJSONDecodeError, MessageParseError) is imported directly by the CLI transport, ClaudeSDKClient, the control protocol query, the message parser and the package entry point. None has a fallback. A breaking change to this file reaches all five, and through the transport it reaches the internal client that drives one-shot queries.

Impact: Renaming or reshaping an exception breaks the public exports and every place that catches or raises it, so callers lose their error handling at once.

Recommendation (small effort): Treat _errors.py as a frozen public contract: add new exception classes as subclasses and keep existing names and constructor arguments stable. Cover the hierarchy with a test that imports every name the package entry point re-exports.

Every tool call the CLI wants approved arrives at Control Protocol Query as a can_use_tool request carrying tool name, input, tool_use_id, agent_id, blocked_path, decision_reason and suggested permission updates. The developer's callback can allow, rewrite the input, add permission rules, or deny with interrupt. Missing callbacks fail closed. Gaps: the context's abort signal is always None, and a CLI cancel kills the callback task without telling it.

Recommendation (small effort): Wire the CLI's control_cancel_request into ToolPermissionContext.signal and the hook context signal, so an approval waiting on a human can be withdrawn cleanly instead of being cancelled mid-await.

On pull requests run.ts calls restoreConfigFromBase, which replaces .claude, .mcp.json, .claude.json, CLAUDE.md, CLAUDE.local.md, .gitmodules, .ripgreprc and .husky with the base branch versions. A PR therefore cannot add hooks, MCP servers or instructions to the agent that reviews it.

SENSITIVE_PATHS in src/github/operations/restore-config.ts must grow whenever Claude Code starts reading a new file from the working directory at startup.

run.ts decides whether untrusted input reaches Claude at all. It checks the trigger, then the actor and write permission, then on PRs restores config from the base branch, and only then prepares tag or agent mode. Reading these calls in order explains most of the action's security model before any prompt code.

Learn the GitHubContext union in src/github/context.ts next: every gate branches on isEntityContext and the event type.

Issue and PR text arrives through the GitHub Data Fetcher, which keeps only comments from before the trigger time and applies the actor filters. The Context Formatter sanitizes every title, body, comment and diff hunk, and the Prompt Builder assembles the result with the trigger comment. This is the core path to understand before changing what Claude sees.

The trigger-time filter in fetcher.ts stops edits made after the trigger from being read; keep it in mind when changing how comments are fetched.

src/create-prompt/index.ts and base-action/src/run-claude-sdk.ts each declare their own USER_REQUEST_FILENAME constant and agree only by convention on claude-prompt.txt sitting beside it. The base action is published standalone, so renaming the file in either package silently drops the user's request, and the multi-block slash-command path along with it.

Recommendation (trivial effort): Export the prompt and user-request file names from base-action and import them in src, or pass the user-request path explicitly as an input.

Subprocess CLI Transport is used by query(), the Internal Client, ClaudeSDKClient, Package Exports and Control Protocol Query, and is the sole path to the Claude Code CLI. _build_command reads 39 distinct ClaudeAgentOptions fields from Types and maps each to a CLI flag, yet the transport-to-Types dependency is not drawn. The CLI version check only logs a warning below 2.0.0.

Impact: Every new option or renamed CLI flag lands in one 1,228-line file, and a bundled or user-installed CLI that rejects a flag fails only at spawn time, in every entry point at once.

Recommendation (medium effort): Extract command building into a pure options-to-argv function with table-driven contract tests per CLI version, and move flag-only settings into the initialize request where the CLI can report unknown fields.

query() reaches Control Protocol Query through the Internal Client and ClaudeSDKClient uses it directly; the engine in turn depends on the transport, Message Parser, SDK MCP Bridge, Transcript Mirror Batcher, Task Compat, Errors and Types. Its run-end logic (session state, in-flight task ledger, a 10-minute ceiling) decides when stdin closes for both.

Impact: A change to when stdin closes, or to how a control request is answered, alters hooks, permissions and in-process MCP tools for every SDK user at once.

The engine is well commented with issue references (#1088, #1190), and test_run_end_subprocess.py exercises the run-end paths against a subprocess; keep changes here behind those tests.

Start with claude-issue-triage.yml and claude-dedupe-issues.yml, which turn every issue event into a Claude run. Then read .claude/commands/triage-issue.md and dedupe.md, the actual instructions the agent follows. Then scripts/gh.sh and the two write scripts, and finally issue-lifecycle.ts with sweep.ts and auto-close-duplicates.ts, which turn labels and comments into closures.

Key vocabulary: triage, dedupe, lifecycle labels (invalid, needs-repro, needs-info, stale, autoclose), sweep, egress firewall, auto permission mode, workload identity federation.

Triage and dedupe prompts, the egress allow list and the workflow comments all assume scripts/gh.sh only exposes read subcommands and four flags. It is a 100-line shell script with no tests in the repo; one new allowed subcommand or flag silently widens what an agent fed untrusted issue text can do in both jobs.

Impact: A small, innocent-looking edit to the wrapper changes the blast radius of every Claude run on issues.

Recommendation (small effort): Add a test that asserts the wrapper rejects edit, comment, close, api and repo: queries, and route changes to scripts/gh.sh and the two write scripts through CODEOWNERS review.

Both Claude jobs authenticate with a short-lived token from workload identity federation instead of a stored key, hold only issues: write, run in auto permission mode with Write, Edit, WebFetch and WebSearch disallowed, call GitHub only through the wrapper scripts, and run on a runner whose egress is limited to an explicit host list.

Impact: A compromised run can at most mislabel or comment on the one issue that triggered it.

This is a strong template for any further agent in this repo: per-job token, script-mediated writes, explicit egress list and per-script call caps.

scripts/gh.sh allows only issue view, issue list, search issues and label list, rejects repo:, org: and user: qualifiers, and requires numeric issue numbers. Writes go through edit-issue-labels.sh and comment-on-duplicates.sh, which read the issue number from GITHUB_EVENT_PATH, drop unknown labels and cap duplicates at three existing issues. Write, Edit, WebFetch and WebSearch are disallowed and the runner egress is allow-listed.

Impact: A prompt-injected agent cannot touch other issues, other repositories, code, or arbitrary hosts.

CLAUDE_CODE_SCRIPT_CAPS further limits triage to two label edits and dedupe to one duplicate comment per run.

Most of the repo is prompt files. The channel servers are the exception: long-running Bun MCP processes that poll a chat platform, filter senders through an allowlist, push messages into the session and relay permission prompts back. Telegram is the most complete of the three, and Fakechat is a local harness for experimenting with the protocol safely.

Read the pairing and gate functions before anything else in these files; they decide who can drive a session.

Once the catalogue makes sense, the CI explains its upkeep. The SHA bumper moves pinned third-party plugins forward daily through the GitHub API, the scope guard limits what outside contributors may add, and the validation workflows lint manifests, frontmatter, licenses and MCP URLs.

Most of the review logic lives in the shared claude-plugins-community actions, not in this repo; read their inputs here and their code there.

Session Store, the SessionStore protocol and in-memory store with validation, is imported directly by the public API. ClaudeSDKClient calls validate_session_store_options, and the package exports file pulls in InMemorySessionStore and project_key_for_directory. Internal Client and Session Resume use the same validation. So the session boundary is crossed at the storage layer, not at one session-level entry point.

Impact: A change to store validation or to the in-memory store's signature has to be followed in the client and the package exports, not only inside session management.

Recommendation (small effort): Expose store validation and the in-memory store through one session-management entry point, and have ClaudeSDKClient and the package exports import from that instead of from Session Store.

The CLI streams transcript_mirror frames on stdout. The read loop in Control Protocol Query hides them from callers and hands them to the Transcript Mirror Batcher, which flushes to SessionStore.append before each result is yielded. A failed append is retried up to 3 times; a 60s timeout is not retried. Then the batch is dropped, and the only signal is a system message with subtype mirror_error. 7 parts of the system depend on Session Store, none with an alternative.

Impact: A custom store that fails persistently loses transcript entries silently unless the caller watches for mirror_error; the local-disk transcript stays intact and the session carries on.

Recommendation (small effort): Handle system messages with subtype mirror_error in your consumer and alert on them. Make custom SessionStore.append idempotent by deduplicating on entry uuid, since a retried batch may overlap an earlier partial write.

Each channel notification wraps the text in a channel tag naming the source and carries meta with chat_id, message_id, user, user_id and a timestamp (telegram/server.ts around line 974). The session can therefore tell chat input from terminal input, and tell one sender from another. It cannot yet tell a human sender from an automated one.

This covers the actor.id part of provenance. Adding an explicit actor type (human, bot or relay) and the pairing date to meta would complete it for audit.

Scan Plugins runs the Claude CLI through the community scan action to review changed external marketplace entries, and comments the result on the PR. When a scan of the automated SHA bump fails, Revert Failed Bumps rolls the offending entries back. That deterministic fallback is the escape hatch an agent gate needs. The scan runs the latest CLI, so its behaviour can change between runs without a code change here.

Pinning claude-cli-version for the scan would make a change in review behaviour show up as a reviewed diff rather than a silent drift.

Session listing reads the CLI's own ~/.claude/projects folders directly, so sessions.py ports the CLI's JavaScript path sanitising and 32-bit string hash (base36, used for long paths) to rebuild the same folder names. Six modules import from it: the package exports, session import, mutations, resume, and the store. 12 of the 23 elements on the board depend on it, directly or indirectly. If the CLI changes how it names those folders, listing and resume find nothing, and no error says why.

Impact: A silent CLI naming change would make listing, resume, rename and import look empty or fail to find sessions that exist on disk.

Recommendation (medium effort): Cover the sanitising and hash with tests against known CLI folder names, so a CLI bump that changes them fails loudly. Longer term, ask the CLI to expose the session directory instead of re-deriving it.

max_budget_usd, task_budget and max_turns are passed to the CLI as flags, and Control Protocol Query bounds how long stdin stays open between turns with a 10-minute ceiling (CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS), so a background agent that never reports idle cannot hold a session open indefinitely.

These limits are enforced by the CLI, so they hold even when the embedding code forgets to stop iterating. The SDK does not check them itself.

prepareTagMode allows only comment updates, git add, commit and rm, a push wrapper, and the GitHub MCP tools the installer registers. Edits run under acceptEdits, which allows files inside the workspace only, and there is no general Bash.

Impact: A prompt-injected run is limited to its own branch and Claude's own comments.

User-supplied claude_args can widen this list, so the narrow default holds only for workflows that do not pass extra allowedTools.

Post-run Reporting, Branch Operations, Git Auth and Signing, the Comment Image Downloader and the GitHub Actions Server touch GitHub heavily but sit outside the untrusted-input path. They decide where results land, not what Claude is allowed to read.

Come back to Post-run Reporting when working on inline review comments: it posts buffered comments after a Haiku check filters out test calls.

The transport passes resume, session_id, resume_session_at and resume_drops_turn as --flag=value so a dash-leading value cannot become a new flag, applies the same rule to extra_args, refuses .bat/.cmd CLIs on Windows (the BatBadBut class, CVE-2024-27980), rejects cmd.exe metacharacters in session values, and validates skill names before formatting them into --allowedTools rules.

Session titles and IDs are often taken from end users, so these guards are what keeps a hostile resume value from rewriting the CLI's permission flags. New options that take untrusted strings should use the same equals form.

Control Protocol Query answers a can_use_tool request with an error when no callback is registered, an unknown hook callback ID with an error, and any unsupported request subtype with an error, rather than a default allow. A callback that returns anything other than PermissionResultAllow or PermissionResultDeny is also turned into an error response.

_configure_can_use_tool also routes permission prompts to stdio and refuses to combine can_use_tool with permission_prompt_tool_name, so one gate decides each tool call.

Claude Code (host engine) is the most depended-on part of this repo, used by every plugin, mod and example, but issue automation never touches it: the workflows run the published Claude Code Action. Mods, the plugin marketplace and the gateway examples can wait.

The only shared piece is the Anthropic API, reached by both the workflows and the security-guidance plugin.

scripts/issue-lifecycle.ts declares itself the single source for lifecycle labels and timeouts and is used by sweep.ts and lifecycle-comment.ts. The triage prompt separately says needs-repro and needs-info time out after 7 days, and the dedupe comment and auto-close-duplicates.ts each hardcode 3 days.

Impact: Changing a timeout in issue-lifecycle.ts leaves the agent and the posted comments promising the old schedule.

Recommendation (small effort): Generate the timeout text in the prompt and comment from issue-lifecycle.ts, or move the duplicate window into it and import it in auto-close-duplicates.ts.

comment-on-duplicates.sh sets REPO to anthropics/claude-code, while gh.sh uses the workflow repository. In any fork or mirror running these workflows, dedupe searches the fork but validates and comments against upstream issues with the fork issue numbers.

Impact: Forks get failed runs or comments that point at unrelated upstream issues.

Recommendation (trivial effort): Read the repository from GH_REPO or GITHUB_REPOSITORY in comment-on-duplicates.sh, as gh.sh does.

Duplicate comments say the issue closes in 3 days, and auto-close-duplicates skips any issue whose author reacted thumbs-down. The sweep skips lifecycle closures when a human commented after the label, triage removes stale and autoclose on new human comments, and remove-autoclose-label clears autoclose on any comment.

Impact: Authors can stop a wrong closure with one reaction or comment.

The escape hatch depends on the author noticing within 3 to 7 days; it does not cover issues whose author has gone quiet.

Newcomers can safely ignore the MCP Integration Plugins (each is a few lines of .mcp.json), the shared community actions and the vendor servers, which live outside this repo. Of the 27 first-party plugins, 22 are prompt-only command or skill bundles with no code paths worth tracing.

Return to these only when touching that specific plugin or integration; none of them affects how the others work.

Six terms recur everywhere: a marketplace entry (one plugin's record in marketplace.json), a plugin (bundle of commands, agents, skills, hooks, MCP servers), a channel (an MCP server feeding chat into a session), pairing and the allowlist (how a chat sender is trusted), permission relay (approving tool calls from chat) and a SHA bump (moving an external plugin's pinned commit).

Hooks, skills and agents follow Claude Code's own plugin model; the plugin-dev plugin's skills are the best in-repo explanation of each.

No first-party plugin imports another; every import resolves within a plugin's own directory. Each plugin ships as its own marketplace entry, so any plugin can change, version and release without coordinating with the others.

The marketplace entry is the only shared contract. Keeping cross-plugin reuse out (or in an explicitly versioned package) preserves this.

Both pull_request_target workflows check out only the base repository and read the head marketplace.json as data through the GitHub API. External-pr-scope.js trusts the source repo rather than the submitter: a PR is in scope only if it adds entries pinned to a commit in a repo that already backs a live entry.

This avoids the classic pull_request_target pitfall of checking out and running head code with a write token. Keep that invariant explicit in review, since one added checkout of the PR ref would undo it.

The Telegram server writes its .env and access.json with mode 0600 inside a 0700 state directory, defaults new chats to pairing mode, and instructs the session never to approve pairings or edit the allowlist because a channel message asked. Senders not on the allowlist are dropped before their text reaches the session.

Access changes happen only through the access skill run in the user's terminal, which keeps chat input from widening its own privileges.