Skip to content

Latest commit

 

History

History
831 lines (739 loc) · 235 KB

CLAUDE.arch.md

File metadata and controls

831 lines (739 loc) · 235 KB

Architecture Reference

token-goat is a TypeScript CLI bundled to dist/token-goat.mjs via esbuild. The source lives in src/*.ts; tests under tests/. Build, test, and release tooling is npm-based (npm install, npm test, npm run typecheck, npm run lint). The canonical contributor guide lives in AGENTS.md — this file is the deeper architecture reference it complements.

Component Map

The table below is generated by scripts/sync-arch-docs.mjs from the tracked modules under src/, using the layers in config/arch-docs.json: one row per module, ordered by layer and then by path. A Role written by hand is kept; an empty Role, or one that only restates the generated text, is regenerated from the module's first doc-comment sentence. npm run docs:arch rewrites the table and npm run docs:arch:check reports drift on stderr (exit 1). A new module under a directory the config does not list lands in Uncategorized until a layer is added for it.

Module Layer Role Key exports
src/cli.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli.ts expandGlobs, CliError, formatCommandError, out, outWithPayload
src/cli_cmd_analysis.ts Entry and CLI Dispatch CLI command registration for code analysis, dependency, graph, and git commands GuardFn, registerAnalysisCommands
src/cli_cmd_content.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_content.ts registerContentCommands
src/cli_cmd_diagnostics.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_diagnostics.ts registerDiagnosticCommands
src/cli_cmd_documents.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_documents.ts registerDocumentCommands
src/cli_cmd_formats.ts Entry and CLI Dispatch CLI command registration for file formats: PDF, Office, Structured Data, SQLite, Media, and Text utilities GuardFn, fenceOcrText, cmdImageMeta, cmdImageText, cmdImageSlice
src/cli_cmd_index.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_index.ts registerIndexCommands
src/cli_cmd_inspect.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_inspect.ts registerInspectCommands
src/cli_cmd_integrations.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_integrations.ts registerIntegrationCommands
src/cli_cmd_session.ts Entry and CLI Dispatch CLI command registration for session, caching, audit, skill, and note commands GuardFn, registerSessionCommands
src/cli_cmd_system.ts Entry and CLI Dispatch Entry and CLI Dispatch module: cli_cmd_system.ts registerSystemCommands
src/cli_dispatch.ts Entry and CLI Dispatch Shared CLI execution and dispatch helpers readStdinPaths, runExit, runExitText, ExtraArgsNoteOpts, noteExtraFileArgs
src/cli_help.ts Entry and CLI Dispatch Compact CLI help generation generateCompactHelp
src/main.ts Entry and CLI Dispatch Package executable —
src/mcp_server.ts Entry and CLI Dispatch Entry and CLI Dispatch module: mcp_server.ts DEFAULT_MCP_TOOLS, inferProjectRootFromTarget, checkWithinProjectRoot, mcpToolAllowlist, createMcpServer
src/search/types.ts Entry and CLI Dispatch Types and interfaces for token-goat parallel multi-angle search SearchChannel, ALL_CHANNELS, SearchOptions, ChannelHit, FusedSearchResult
src/types.ts Entry and CLI Dispatch Wire shapes and discriminated unions shared across token-goat modules HookOutput, HOOK_EVENTS, HookEventName, GitResult, GIT_DEFAULT_TIMEOUT_MS
src/fingerprint.ts Indexer and Worker (Critical Path) SHA-256 file and content fingerprinting fingerprintContent, shortFingerprint, indexedFileIsGone, statIndexedFile, fingerprintFileWithBytes
src/index_prune.ts Indexer and Worker (Critical Path) Indexer and Worker (Critical Path) module: index_prune.ts removeFileFromIndex, purgeReconcileCursors, purgeOrphanedReconcileCursors, countFilesUnderRoot, pruneDeletedFiles
src/parser.ts Indexer and Worker (Critical Path) Tree-sitter source indexer (Layer 7) ParseResult, Grammar, TsNode, TsParser, TsParserCtor
src/parser_fingerprint.ts Indexer and Worker (Critical Path) Indexer and Worker (Critical Path) module: parser_fingerprint.ts PARSER_FINGERPRINT, LANGUAGE_PARSER_FINGERPRINTS
src/parser_refs.ts Indexer and Worker (Critical Path) Call-site reference extraction via tree-sitter AST traversal extractRefs
src/parser_stamp.ts Indexer and Worker (Critical Path) Resolves the files.parser_sha stamp a row of a given language is expected to carry, from the generated digests in parserFingerprintForLanguage
src/parser_structured.ts Indexer and Worker (Critical Path) Extractors for structured textual formats (Markdown, JSON, YAML, TOML, CSS, Dockerfile) and fallback regex symbol extractMarkdownSymbols, extractJsonSymbols, yamlOpenQuoteAfter, yamlLineClosesQuote, extractYamlSymbols
src/parser_treesitter.ts Indexer and Worker (Critical Path) Tree-sitter symbol extractors for typed and compiled languages (TS/JS, Python, Go, Rust, Ruby, Java, C/C++) extractTsTypeDefinitions, extractTsTypeImports, extractTsSignatureInfos, extractTsJsSymbols, extractPythonSymbols
src/parser_ts_types.ts Indexer and Worker (Critical Path) Minimal structural typings for the node-tree-sitter API surface we touch TsPoint, TsNode, TsTypeDefinitionKind, TsTypeDefinition, TsTypeImportBinding
src/parser_types.ts Indexer and Worker (Critical Path) Type definitions shared between the tree-sitter parser (Layer 7) and the layers that query the index SymbolEntry, RefEntry, FileIndexEntry, Language, TREE_SITTER_LANGUAGES
src/reconcile.ts Indexer and Worker (Critical Path) Catch-up reconciliation: detect index drift caused by edits token-goat never saw DEFAULT_RECONCILE_BUDGET_MS, PreHashStamp, readPreHashStamp, restampVerifiedUnchanged, ReconcileOptions
src/worker.ts Indexer and Worker (Critical Path) Background worker: drain the dirty queue and re-index changed files FOREGROUND_ACTIVITY_YIELD_MS, hasRecentForegroundActivity, clearRetryCount, cleanupWorkerStateFiles, pendingEmbeddings
src/constants.ts Storage and Database Package-wide constants: version re-export, data-directory resolution, and the canonical TOKEN_GOAT_* VERSION, dataDirForHome, dataDir, ensureDataDirPrivate, tokenGoatHome
src/db.ts Storage and Database SQLite connection management and index-DB schema FTS_TOKENIZER, SCHEMA_VERSION, enableWalWithRetry, WAL_SIZE_LIMIT_BYTES, WAL_SIZE_LIMIT_PRAGMA
src/db_integrity.ts Storage and Database Integrity probe and quarantine for the global index database QuickCheckResult, QuarantineResult, quickCheckDb, quarantineMalformedDb, recreateDb
src/index_reader.ts Storage and Database Read side of the symbol index DEFAULT_QUERY_LIMIT, querySymbols, queryFileSymbolsWithIds, distinctSymbolKinds, countSymbols
src/section_reader.ts Storage and Database Named-section extraction from text files SectionResult, normalizeHeading, findMarkdownHeaders, extractShellBannerHeading, findShellBannerHeaders
src/section_regions.ts Storage and Database C# and Visual Basic region directive extraction RegionSectionHeader, findCsharpRegionHeaders, findVbRegionHeaders
src/stats.ts Storage and Database Token-savings telemetry: record and aggregate stats in the stats table StatsSummary, HARNESS_UNRECORDED, PRICING_VERSION_UNRECORDED, hasMixedPricingEras, SOURCE_IMAGE
src/stats_report.ts Storage and Database Storage and Database module: stats_report.ts _useRichStats, _buildStatsDataForTest, renderShortStats, renderStats
src/embed_backfill.ts Embeddings and Semantic Search One-time-per-release sweep that deletes chunk rows an already-indexed file would no longer be allowed to contribute BACKFILL_META_KEY, BackfillResult, selectUnembeddableChunkFiles, EmbedSkipMarkers, pruneUnembeddableChunks
src/embed_fingerprint.ts Embeddings and Semantic Search Embeddings and Semantic Search module: embed_fingerprint.ts EMBED_FINGERPRINT, EMBED_KIND_FINGERPRINTS, PRE_KIND_EMBED_FINGERPRINT, SPLIT_EMBED_FINGERPRINT
src/embed_model.ts Embeddings and Semantic Search The embedding backend: fetch the pinned model, verify it, run it, pool it DEFAULT_MODEL, DEFAULT_DIM, DEFAULT_EMBED_THREADS, PINNED_MODEL_REVISION, modelDir
src/embed_preflight.ts Embeddings and Semantic Search Whether semantic search can run now, and when it cannot because the embedding model has not downloaded, why and what WARM_COMMAND, modelDownloadHeld, foregroundDownloadDeferred, downloadAdvice, runtimeDownloadAdvice
src/embed_runtime.ts Embeddings and Semantic Search Which ONNX Runtime build runs the embedding model, and getting it running RuntimeName, ORT_WEB_VERSION, ORT_WEB_WASM, NATIVE_RUNTIME_INSTALL, RUNTIME_UNAVAILABLE_ADVICE
src/embed_runtime_web.ts Embeddings and Semantic Search Getting the WebAssembly build of ONNX Runtime running WebRuntimeHost, ORT_WEB_TARBALL, ORT_WEB_GLUE, ensureWasmBinary, extractTarMember
src/embed_stamp.ts Embeddings and Semantic Search Resolves which extraction kind a file's embedding stamp belongs to, and which digest from embed_fingerprint.ts that embedKindForPath, embedFingerprintForPath
src/embed_tokenizer.ts Embeddings and Semantic Search A BERT WordPiece tokenizer for exactly the spec bge-small-en-v1.5's tokenizer.json declares MAX_SEQUENCE_TOKENS, UnsupportedTokenizerError, BertWordPiece
src/embeddings.ts Embeddings and Semantic Search Semantic search: chunking, embedding, storage and the search itself DEFAULT_DIM, DEFAULT_MODEL, PINNED_MODEL_REVISION, checkEmbeddingPreflight, EmbeddingPreflightResult
src/semantic_distances.ts Embeddings and Semantic Search The semantic_queries ledger: one text-free row per semantic query, and the semantic --distances report that turns MIN_QUERIES_FOR_ADVICE, SemanticQueryRow, DistanceBand, DistanceSummary, summarizeDistances
src/semantic_merge.ts Embeddings and Semantic Search Merges semantic search hits from the same file around the best-matching chunk, kept out of embeddings.ts so an edit here mergeNearbyHits
src/semantic_relevance.ts Embeddings and Semantic Search The relevance decision every surface that answers from the dense index makes the same way: the configured applyRelevanceFloor, DenseRelevance, assessDenseRelevance, floorEmptiedPhrase, weakMatchPhrase
src/paths.ts Paths, Filesystem, and Project Detection Path normalization and join safety isUncOrDevicePath, WSL_PATH_RE, MSYS_PATH_RE, expandShortPath, lowercaseDriveLetter
src/project.ts Paths, Filesystem, and Project Detection Project marker detection and path canonicalization canonicalize, isInsideRoot, escapesOntoNetworkThroughLinks, PROJECT_MARKERS, Project
src/repomap.ts Paths, Filesystem, and Project Detection Git-tracked file listing, used by token-goat arch's import-graph scan (see runArch in graph_commands.ts) TrackedFilesResult, listTrackedFiles, listTrackedFilesAsync, requireTrackedFiles
src/code_fold.ts Hook Subsystem Body folding: keep a source file's structure, replace the inside of long function bodies with a pointer to the command FoldSpan, BodyFold, planBodyFolds, CommentSyntax, commentSyntaxFor
src/hook_registry.ts Hook Subsystem Hook handler registry HookEvent, sessionStateKey, HookHandler, registerHook, handlersFor
src/hooks_agent_spawn.ts Hook Subsystem Subagent briefing pack hook resetProjectMapBriefingCache, subagentStartWired, subagentStartHandler, preAgentHandler, collapseFencedBlocks
src/hooks_agent_spawn_register.ts Hook Subsystem Registers the subagent hooks of hooks_agent_spawn.ts behind dynamic imports, so the hook entry does not parse that —
src/hooks_bash.ts Hook Subsystem pre_tool_use hook for the Bash tool COMPRESS_TIMEOUT_MAX, preBashHandler
src/hooks_bash_commands.ts Hook Subsystem Shell command parsing, git mutation detection, pipeline filtering, and syntax validation stripExportPrefix, stripCdPrefix, stripSubshellGroup, stripGroupAndExports, stripCommandPrefix
src/hooks_bash_post.ts Hook Subsystem post_tool_use hook for the Bash tool: caches a finished command's output for recall, records the files it read and the readPersistedBashOutput, extractExitCode, postBashHandler
src/hooks_bashoutput.ts Hook Subsystem BashOutput poll-delta caching hook, and the poll pipeline hooks_taskoutput.ts runs TaskOutput through PollTool, rewritePoll, postBashOutputHandler
src/hooks_browser_image.ts Hook Subsystem post_tool_use handler for browser-automation MCP tools whose results embed an inline base64 screenshot with no postBrowserImageHandler
src/hooks_cli.ts Hook Subsystem Harness payload normalization: translate harness-specific tool payloads to token-goat's canonical internal shape before Harness, HookPayload, CANONICAL_TG_TOOLS, foldToolName, normalizeToolNameWithMap
src/hooks_common.ts Hook Subsystem Shared helpers for hook handlers (Layers 5+) getToolName, getToolInput, getFilePath, resolveEventPath, getFilePaths
src/hooks_compact.ts Hook Subsystem The compaction hooks: emit the session manifest before a compaction, measure what came out of it after preCompactHandler, postCompactHandler
src/hooks_edit.ts Hook Subsystem post_tool_use edit hooks (Write / Edit / MultiEdit / NotebookEdit) postEditHandler
src/hooks_exitplanmode.ts Hook Subsystem ExitPlanMode plan-body deduplication hook postExitPlanModeHandler
src/hooks_fetch.ts Hook Subsystem Hook Subsystem module: hooks_fetch.ts preFetchHandler, postFetchHandler
src/hooks_glob.ts Hook Subsystem post_tool_use / pre_tool_use handlers for the Glob tool isBroadCatchAllGlob, postGlobHandler, preGlobDedupHandler, preGlobHandler
src/hooks_grep.ts Hook Subsystem post_tool_use / pre_tool_use handlers for the Grep tool DOC_EXT_RE, STRUCTURAL_DOC_PATTERN_RE, GrepStructuralSearchResult, extractGrepStructuralSearch, inlineSymbolGrepHandler
src/hooks_index.ts Hook Subsystem Dirty-queue management for incremental re-indexing dirtyQueuePath, appendDirtyPaths, appendDirtyPath, enqueueDirtyPathSafe, enqueueDirtyPathsSafe
src/hooks_mcp.ts Hook Subsystem MCP read-tool caching hooks MCP_OVERSIZED_THRESHOLD_BYTES, isTokenGoatMcpTool, isMcpErrorResponse
src/hooks_read.ts Hook Subsystem pre_tool_use read hooks (Read / Grep / Glob) relPathWithinRoot, isSessionArtifactFile, isDiffableSource, isSourceExtension, extractQuickSymbolSamples
src/hooks_read_override.ts Hook Subsystem The explicit size overrides a host's Read tool takes, and the escalation of a repeated large-file refusal fileTypeHost, isBoundedPagesRange, readOverridesFileTypeDeny, readOverridesLargeFileDeny, EscalationText
src/hooks_read_policy.ts Hook Subsystem Hook Subsystem module: hooks_read_policy.ts ReadPolicyContext, ReadPolicyDecision, formatKb, meetsFirstReadSymbolThreshold, buildReadPolicyContext
src/hooks_read_post.ts Hook Subsystem post_tool_use hook for the Read tool postReadHandler
src/hooks_read_slice.ts Hook Subsystem Line windowing, slice estimation, line diffing, and truncated-read detection NumberedRow, readIntToolInput, RequestedSliceWindow, requestedSliceSpan, readRequestedSliceWindow
src/hooks_read_window_stream.ts Hook Subsystem Streams bounded source-line windows without buffering a large file as a string STREAMING_READ_MIN_BYTES, readWindowFromDiskStreaming
src/hooks_recovery.ts Hook Subsystem post_tool_use side of the failure-recovery pairs (recovery_pairs.ts): a successful Bash command may close a pending recoveryBashHandler, recoveryEditHandler, textPathMiss
src/hooks_screenshot.ts Hook Subsystem Pre-tool-use hook — pre_screenshot: denies MCP screenshot tool calls that don't specify a destination file —
src/hooks_session.ts Hook Subsystem Hook Subsystem module: hooks_session.ts claimsCommittedChange, pendingContextHandler, userPromptSubmitHandler
src/hooks_session_start.ts Hook Subsystem session_start hook: re-inject a short command-routing reminder every time a session starts, resumes, or restarts after SESSION_START_LISTING_DEADLINE_MS, sessionStartHandler, savingsReceiptText, withSavingsReceipt, SessionStartOutputOptions
src/hooks_skill.ts Hook Subsystem Hook Subsystem module: hooks_skill.ts preSkillHandler, postSkillHandler
src/hooks_stop.ts Hook Subsystem The Stop hook: when the agent ends a turn with source edits that no test, lint, typecheck or build run has covered stopAdvisoryText, stopHandler
src/hooks_taskoutput.ts Hook Subsystem TaskOutput poll-delta caching hook postTaskOutputHandler
src/hooks_tool_failure.ts Hook Subsystem post_tool_use_failure handler -- the repeat-failure brake MAX_TRACKED_FAILURES, failureSignature, extractFailureText, REPEAT_NOTICE_EXEMPT, repeatFailureNotice
src/hooks_verification.ts Hook Subsystem The eager half of the verification bookkeeping: a keyword gate and the registrations mayBeVerificationCommand, noteFailedVerificationHandler
src/hooks_websearch.ts Hook Subsystem WebSearch caching/dedup hooks preWebSearchDedupHandler, postWebSearchHandler
src/hooks_write.ts Hook Subsystem pre_tool_use hook for the Write tool: full-rewrite detector (feature-queue #302) preWriteRewriteHandler
src/image_shrink.ts Hook Subsystem Image shrink — intercept large images before they reach the model visionTokens, visionTokensSaved, visionTierMaxTokens, visionTokensSavedByText, SINGLE_FRAME_DECODERS
src/install.ts Hook Subsystem Install / uninstall token-goat's hooks in Claude Code settings HookScope, InstallResult, anchoredMarkerPattern, claudeExecFormHooksSupported, execFormSupportedForVersionOutput
src/relay.ts Hook Subsystem Hook Subsystem module: relay.ts buildEvent, RELAY_QUEUE_WAIT_MS, RelayInProcessOptions, NATIVE_FALLBACK_ENV, nativeFallbackDetail
src/shell_writes.ts Hook Subsystem What a shell command line writes, for the post-shell hook that keeps the index fresh ShellWriteTargets, extractPowerShellWriteTargets, ShellSyntax, scanShellSyntax, enqueueShellWrites
src/spooled_output.ts Hook Subsystem Hook Subsystem module: spooled_output.ts COPILOT_SPOOLED_NOTICE_RE, COPILOT_SPOOLED_FILENAME_RE, isCopilotSpooledNotice, isCopilotHarness, extractCopilotSpooledPath
src/compact.ts Session, Compaction, and Audit Session manifest generator for compaction assist CONTEXT_AUTOCOMPACT_TOKENS, CATALOG_TOKENS, CONTEXT_TIER_WARM, CONTEXT_TIER_HOT, CONTEXT_TIER_CRITICAL
src/compact_dropped.ts Session, Compaction, and Audit The paths a compaction summary left out, kept beside the session so the resume packet can name them recordCompactDroppedPaths, readCompactDroppedPaths
src/resume.ts Session, Compaction, and Audit Session, Compaction, and Audit module: resume.ts MAX_RESUME_TOKENS, MAX_RESUME_CHARS, buildResumePacket
src/session.ts Session, Compaction, and Audit In-memory session state FileRangeIdentity, RANGE_FINGERPRINT_MAX_BYTES, CurrentFileHash, OnceFileHash, onceCurrentFileHash
src/session_audit.ts Session, Compaction, and Audit Corpus-wide session audit: streams every Claude Code transcript (JSONL) under a corpus root MeasuredUsage, EstimatedCategory, EstimatedAttribution, EstimatorCalibration, computeCalibration
src/session_audit_report.ts Session, Compaction, and Audit Plain-text rendering of the summary session_audit.ts builds, for token-goat session-audit formatSessionAudit
src/session_read.ts Session, Compaction, and Audit Session, Compaction, and Audit module: session_read.ts resolveSessionTranscript, SessionBlock, SessionOutlineTurn, SessionTurnDetail, buildSessionOutline
src/session_reminder.ts Session, Compaction, and Audit The routing reminder the SessionStart hook injects buildReminder
src/session_start_owed.ts Session, Compaction, and Audit Settle marker for a session-start hook that may have missed its budget OWED_RESERVE_MS, SessionStartMarker, recordSessionStartSettled, recordSessionStartBegun, resetSessionStartOwed
src/session_store.ts Session, Compaction, and Audit Per-session state persistence — the dropped Python SessionCache JSON SESSIONS_SUBDIR, AGENT_SALT_MARKER, sessionFileStem, ensureSessionDirectory, sessionSidecarPath
src/session_store_schema.ts Session, Compaction, and Audit Session store and database schema catalog, discovery, and runtime error diagnostics SessionStoreColumn, SessionStoreTableKind, SessionStoreTableSource, SessionStoreTable, SESSION_STORE_TABLES
src/shared_memory_db.ts Session, Compaction, and Audit Session, Compaction, and Audit module: shared_memory_db.ts getSharedMemoryDb, sharedMemoryDigest, redactSharedMemoryText
src/skill_cache.ts Session, Compaction, and Audit Persistent store for loaded-skill bodies SKILLS_OUTPUT_SUBDIR, setSkillOutputsDirForTesting, setSkillsSourceDirForTesting, setPluginsManifestPathForTesting, SkillMeta
src/skill_section_spec.ts Session, Compaction, and Audit Resolve the skill-section Heading#N suffix without hiding a literal heading parseSkillSectionSpec
src/snapshots.ts Session, Compaction, and Audit Session, Compaction, and Audit module: snapshots.ts MAX_SNAPSHOTS_PER_SESSION, MAX_SNAPSHOT_BYTES, SNAPSHOT_TRUNCATE_BYTES, SnapshotResult, snapshot_path
src/read_brief.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_brief.ts BriefOptions, BriefResult, runBriefCore, runBriefMulti, runBriefCrossFile
src/read_commands.ts Surgical Reads and Text Processing CLI command handlers for surgical-read commands fileExists, ConfinementIdentityError, ABSENT_PIN, pinKey, fileIdentity
src/read_git.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_git.ts ConflictsCliOptions, runConflicts, parseDiffHunks, parseHunklessFiles, ChangedOptions
src/read_inspect.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_inspect.ts ZipListCliOptions, runZipList, ZipReadCliOptions, runZipRead, SqliteSchemaCliOptions
src/read_meta.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_meta.ts symbolExtractorGap, noSymbolsMessage, hasRealDocstring, formatStatsSuffix, previewLines
src/read_navigation_evidence.ts Surgical Reads and Text Processing The pre-read navigation probe behind the first-read symbol policy NavigationSymbol, NavigationEvidence, getReadNavigationEvidence
src/read_outline.ts Surgical Reads and Text Processing Outline and skeleton command handlers SkeletonOptions, OutlineOptions, filteredToEmptyNotice, prepareSymbolListing, runPerFileListing
src/read_outline_cache.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_outline_cache.ts OutlineListingCacheValue, getOutlineListingCache, setOutlineListingCache, clearOutlineListingCache
src/read_range_evasion.ts Surgical Reads and Text Processing Sticky, epoch-scoped explicit-range refusals and bounded recent-window evasion detection ReadRange, RangeEvasionState, RangeEvasionEntries, RangeEvasionReason, evaluateRangeEvasion
src/read_refs.ts Surgical Reads and Text Processing The refs command: every call site of a symbol, found by name in the index, narrowed by the TypeScript checker when the RefsOptions, runRefs
src/read_section.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_section.ts AMBIGUOUS_HEADING_LIMIT, SectionOptions, literalHeadingExists, findSectionSeparator, runSection
src/read_semantic.ts Surgical Reads and Text Processing The semantic command: a dense embedding search fused with a BM25 keyword pass by reciprocal rank, each hit tagged with runSemantic, runSemanticMulti
src/read_shape.ts Surgical Reads and Text Processing What the session's last Read of each file actually delivered, when that was less than the whole file, kept beside the ReadShape, recordReadShape, readShapeOf
src/read_signature.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_signature.ts SignatureTypeContextSource, extractSignatureWithTypeContext, extractSignature
src/read_spec.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_spec.ts resolveLineRegions, LineRegion, SymbolResolution, parseReadSpec, parseCrossFileMultiSpec
src/read_structured_data.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_structured_data.ts CsvQueryCliOptions, runCsvQuery, CsvProfileCliOptions, runCsvProfile, JsonOutlineCliOptions
src/read_suggest.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: read_suggest.ts DIDYOUMEAN_LIMIT, TYPO_TWO_EDIT_MIN_LEN, TYPO_MAX_QUERY_LEN, MIN_REVERSE_MATCH_LEN, MIN_WORD_SIMILARITY_LEN
src/read_symbol.ts Surgical Reads and Text Processing The symbol command: every indexed definition of a name, or of each name --grep matches, printed with a short body SymbolOptions, runSymbol
src/text_commands.ts Surgical Reads and Text Processing Text-processing and session/index/config CLI commands (Family C2) cmdTodo, cmdTrace, cmdLogfold, DepEntry, findLockfile
src/text_logfold.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: text_logfold.ts cmdLogfold
src/text_todo.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: text_todo.ts cmdTodo
src/text_trace.ts Surgical Reads and Text Processing Surgical Reads and Text Processing module: text_trace.ts isPathUnderRoot, cmdTrace
src/token_estimate.ts Surgical Reads and Text Processing Bytes-to-tokens estimation, by content class ContentClass, BYTES_PER_TOKEN, GUARD_MARGIN, creditDivisor, guardDivisor
src/bridges/aider_install.ts Harness Bridges Harness Bridges module: aider_install.ts AIDER_CONVENTIONS_BEGIN, AIDER_CONVENTIONS_END, AiderScopeOptions, AiderInstallResult, resolveScope
src/bridges/antigravity_hooks.ts Harness Bridges Wire-format shaping for the Antigravity CLI (agy 1.2.11) antigravityToolName, serializeAntigravityOutput
src/bridges/antigravity_install.ts Harness Bridges Antigravity CLI (agy) hook integration AntigravitySettingsParseError, antigravityPluginsDir, antigravityPluginDir, antigravityHooksPath, antigravityHookCommand
src/bridges/claudecode.ts Harness Bridges Claude Code bridge CLAUDECODE_HOOK_SCRIPT
src/bridges/codex.ts Harness Bridges Codex CLI bridge CODEX_HOOK_SCRIPT
src/bridges/codex_install.ts Harness Bridges Codex CLI install / uninstall writer CodexConfigParseError, codexHomeDir, codexConfigPath, codexAgentsPath, codexHookScriptPath
src/bridges/commented_settings.ts Harness Bridges Comment-keeping writes for the JSON settings files whose real consumer accepts comments CommentedSettingsOptions, writeSettingsKeepingComments
src/bridges/copilot_cli.ts Harness Bridges Copilot CLI hook shim COPILOT_CLI_HOOK_SCRIPT, foldToolName, resolveCanonicalToolName, translateCopilotPayload
src/bridges/copilot_cli_install.ts Harness Bridges Copilot CLI install/uninstall wiring CopilotCliScopeOptions, copilotCliCacheRoot, copilotCliMcpToolsDir, copilotCliUserRoot, copilotHooksOwnersPath
src/bridges/copilot_hooks_owners.ts Harness Bridges The owner record for a Copilot hooks directory, split out of copilot_cli_install.ts so the hook path CopilotHooksOwner, HOOKS_CONFIG_FILE, copilotHooksOwnersPath, readCopilotHooksOwners
src/bridges/copilot_mcp_install.ts Harness Bridges Harness Bridges module: copilot_mcp_install.ts copilotMcpConfigPath, copilotManagedServer, isCopilotManagedServer, installCopilotMcpServer, uninstallCopilotMcpServer
src/bridges/copilot_session_start.ts Harness Bridges Harness Bridges module: copilot_session_start.ts COPILOT_SESSION_START_HELPERS
src/bridges/created_configs.ts Harness Bridges A record of the config files token-goat itself created, so uninstall can delete one it created and never one that was recordCreatedConfig, hasCreatedConfig, takeCreatedConfig, recordCreatedRootKey, takeCreatedRootKey
src/bridges/cursor_install.ts Harness Bridges Cursor MCP-server installer CursorScopeOptions, cursorMcpPath, cursorManagedServer, isCursorManagedServer, CursorInstallResult
src/bridges/detect_ecosystems.ts Harness Bridges Harness Bridges module: detect_ecosystems.ts EcosystemDetectionItem, DetectedEcosystems, DetectOptions, detectEcosystems
src/bridges/gemini_install.ts Harness Bridges Gemini CLI install / uninstall writer GeminiSettingsParseError, geminiSettingsPath, GeminiInstallResult, installGemini, uninstallGemini
src/bridges/grok.ts Harness Bridges Grok CLI (xAI's "Grok Build") bridge GROK_HOOK_SCRIPT
src/bridges/grok_install.ts Harness Bridges Grok CLI (xAI's "Grok Build") install / uninstall writer grokHooksDir, grokConfigPath, grokHookScriptPath, grokHookCommandFor, wiredGrokHookWords
src/bridges/guidance_block.ts Harness Bridges Shared guidance-block builder for every harness that gets a token-goat routing block written into its instructions file GuidanceHarness, GuidanceOptions, buildGuidanceBody, skillDescriptionLine, buildGuidanceBlock
src/bridges/index.ts Harness Bridges Bridges barrel detectHarness, getHarnessName, BridgeConfig, HarnessName, CLAUDECODE_HOOK_SCRIPT
src/bridges/jetbrains_install.ts Harness Bridges Harness Bridges module: jetbrains_install.ts JETBRAINS_GUIDANCE_BEGIN, JETBRAINS_GUIDANCE_END, JetbrainsScopeOptions, JetbrainsInstallResult, jetbrainsProjectMcpPath
src/bridges/kimi.ts Harness Bridges Kimi Code CLI bridge (MoonshotAI/kimi-code) KIMI_HOOK_SCRIPT
src/bridges/kimi_install.ts Harness Bridges Kimi Code CLI (MoonshotAI/kimi-code) install / uninstall writer KIMI_HOOK_EVENTS, KimiConfigParseError, kimiHome, kimiConfigPath, kimiAgentsPath
src/bridges/matcher_group.ts Harness Bridges Harness Bridges module: matcher_group.ts HookMatcherGroup, findTokenGoatEntryPosition, findAnyTokenGoatEntryPosition, groupHasTokenGoat
src/bridges/mcp_servers_json.ts Harness Bridges Shared reader and writer for the servers-keyed MCP JSON files that VS Code (mcp.json) and Visual Studio bundledCliPath, managedServer, isManagedServer, ServersJsonConfig, readServersJson
src/bridges/neovim_install.ts Harness Bridges Harness Bridges module: neovim_install.ts NEOVIM_GUIDANCE_BEGIN, NEOVIM_GUIDANCE_END, NeovimScopeOptions, NeovimInstallResult, neovimProjectConfigPath
src/bridges/openclaw.ts Harness Bridges OpenClaw bridge plugin OPENCLAW_PLUGIN_SCRIPT
src/bridges/openclaw_install.ts Harness Bridges OpenClaw install / uninstall writer OpenclawConfigParseError, openclawConfigPath, openclawPluginPath, openclawEntrySidecarPath, OpenclawInstallResult
src/bridges/opencode.ts Harness Bridges opencode bridge plugin OPENCODE_PLUGIN_SCRIPT
src/bridges/opencode_install.ts Harness Bridges opencode install / uninstall writer opencodePluginPath, opencodeEntrySidecarPath, OpencodeInstallResult, installOpencode, uninstallOpencode
src/bridges/pi.ts Harness Bridges pi (pi-coding-agent) extension bridge PI_EXTENSION_SCRIPT
src/bridges/pi_install.ts Harness Bridges pi (pi-coding-agent) install / uninstall writer PiScopeOptions, piGlobalExtensionPath, piLocalExtensionPath, piExtensionPath, piEntrySidecarPath
src/bridges/project_scope_guard.ts Harness Bridges Refuse a project-scope install target that does not really live inside the project assertProjectScopeTarget, withInstallScope, projectScopeRoot, assertWriteInScope, projectPathIsConsultable
src/bridges/qwen_install.ts Harness Bridges Qwen Code (QwenLM/qwen-code, a Gemini CLI fork) hook integration QwenSettingsParseError, qwenSettingsPath, installQwen, uninstallQwen, isQwenInstalled
src/bridges/registry.ts Harness Bridges Harness detection KNOWN_HARNESS_NAMES, setRelaySeededSessionId, relaySeededSessionId, hasClaudeCodeEnvSignal, detectHarness
src/bridges/relay_block.ts Harness Bridges Harness Bridges module: relay_block.ts BRIDGE_RELAY_JS
src/bridges/shim_common.ts Harness Bridges Text fragments shared by the generated harness hook shims SHIM_FILE, LEGACY_SHIM_FILE, legacyShimForwarder, SHIM_REQUIRES, SHIM_VALID_HOOK_EVENTS
src/bridges/shim_try_server.ts Harness Bridges The shim fragment that hands a hook call to the resident hook server SHIM_TRY_SERVER
src/bridges/shrink_block.ts Harness Bridges Harness Bridges module: shrink_block.ts MATERIALIZE_SHRUNK_IMAGE_JS
src/bridges/types.ts Harness Bridges Shared bridge types HarnessName, BridgeConfig
src/bridges/visualstudio_install.ts Harness Bridges Visual Studio (the full IDE, 2022 17.14+ and 2026) GitHub Copilot agent-mode integration: an MCP server entry and VISUALSTUDIO_GUIDANCE_BEGIN, VISUALSTUDIO_GUIDANCE_END, SIBLING_GATE_MARKERS, VisualStudioScopeOptions, visualStudioUserMcpPath
src/bridges/vscode_hooks.ts Harness Bridges Wire-format shaping for VS Code's agent hooks (the built-in Copilot agent, VS Code 1.136+) vscodeToolName, materializeShrunkImageFile, isShrunkImagePayload, serializeVscodeOutput
src/bridges/vscode_install.ts Harness Bridges Project-local VS Code MCP configuration and routing guidance VSCODE_GUIDANCE_BEGIN, VSCODE_GUIDANCE_END, VscodeScopeOptions, vscodeUserMcpPath, vscodeProjectMcpPath
src/bridges/zed_install.ts Harness Bridges Zed context-server installer zedSettingsPath, zedShimPath, zedManagedServer, isZedManagedServer, ZedInstallResult
src/languages/abap.ts Language Adapters ABAP adapter: the REPORT/PROGRAM/FUNCTION-POOL name, local and global classes extractAbap
src/languages/abl.ts Language Adapters Progress OpenEdge ABL adapter: internal PROCEDUREs and FUNCTIONs, CLASS, INTERFACE and ENUM types with their METHODs extractAbl, ABL_SNIFF_CHARS, isAblSource
src/languages/apache.ts Language Adapters Language Adapters module: apache.ts extractApache
src/languages/apex.ts Language Adapters Language Adapters module: apex.ts extractApex
src/languages/asm.ts Language Adapters Assembly adapter for GNU as (.s, .S), NASM (.asm, .nasm) and IBM High Level Assembler, which share .asm: one isHlasmSource, extractAsm
src/languages/bash_idx.ts Language Adapters Shell/Bash symbol extractor extractBash
src/languages/batch.ts Language Adapters Windows batch adapter for .bat and .cmd files: the labels cmd.exe jumps to, each running to the line before the next extractBatch
src/languages/body_segments.ts Language Adapters Language Adapters module: body_segments.ts BodySegment, bodySegments, bodyBraceAt, OpenMember, endOpenMember
src/languages/brace_engine.ts Language Adapters Shared scanner for the brace-language adapters (Objective-C, Groovy, Solidity, Thrift, GLSL, HLSL, WGSL, Metal) BraceLexOpts, Scope, DeclContext, Decl, BraceLanguage
src/languages/brace_spans.ts Language Adapters Brace-span pass shared by the regex language adapters: finds the block a declaration opens and the line that closes it BraceSpanOpts, BraceScanOpts, findMatchingBraceEndLine, assignBraceBlockSpans, InterpolationLang
src/languages/caddy.ts Language Adapters Extracts symbols from Caddyfile configurations (global options, snippets, site blocks, directives) extractCaddy
src/languages/clojure.ts Language Adapters Clojure adapter: defn, defn-, def, defmacro, defprotocol, defrecord, deftype, defmulti, defmethod extractClojure
src/languages/cmake.ts Language Adapters CMake adapter for CMakeLists.txt and .cmake files: function and macro definitions extractCmake
src/languages/cobol.ts Language Adapters COBOL adapter: programs, procedure-division sections and paragraphs, level-01/77 data items and FD/SD file descriptions extractCobol
src/languages/common.ts Language Adapters Shared helpers for regex-based language adapters buildLineIndex, offsetToLine, lineTextAt, stripCstyleComments, stripXmlComments
src/languages/common_lisp.ts Language Adapters Common Lisp adapter: defun, defmacro, defvar/defparameter/defconstant, defclass, defgeneric, defmethod extractCommonLisp
src/languages/csharp.ts Language Adapters C# symbol extractor — regex-based (no tree-sitter grammar needed) extractCsharp
src/languages/dart.ts Language Adapters Dart symbol extractor — regex-based (no tree-sitter grammar needed) extractDart
src/languages/elixir.ts Language Adapters Elixir symbol extractor — regex-based (no tree-sitter grammar needed) extractElixir
src/languages/emacs_lisp.ts Language Adapters Emacs Lisp adapter: defun, defmacro, defvar, defcustom, defconst, defgroup, defface extractEmacsLisp
src/languages/env_idx.ts Language Adapters Dotenv / environment variable file extractor extractEnvFile
src/languages/erlang.ts Language Adapters Erlang adapter for .erl and .hrl files extractErlang
src/languages/fortran.ts Language Adapters Fortran adapter: PROGRAM, MODULE, SUBMODULE, SUBROUTINE, FUNCTION, separate MODULE PROCEDURE and BLOCK DATA units extractFortran
src/languages/fsharp.ts Language Adapters F# (The F# Language Specification, version 4.1, section 3.1 "Lexical Analysis" and section 3.2 "Comments") adapter extractFSharp
src/languages/graphql_idx.ts Language Adapters GraphQL schema / document extractor extractGraphql
src/languages/groovy.ts Language Adapters Groovy symbol extractor, also used for Gradle build scripts and Jenkinsfiles extractGroovy
src/languages/haskell.ts Language Adapters Haskell (Haskell 2010 Language Report) adapter: module, data/newtype, type, class, instance, and top-level extractHaskell
src/languages/html.ts Language Adapters HTML extractor — headings, id/class attributes, link/script imports maskHtmlStyleBodies, HtmlSection, HtmlTag, makeTagScanner, extractHtml
src/languages/index.ts Language Adapters Re-exports all language adapters added in the languages/ subdirectory —
src/languages/ini_idx.ts Language Adapters INI/CFG section extractor and .env key extractor extractIni, _lineClosesQuote, _detectOpenQuote, extractEnv
src/languages/ipynb_idx.ts Language Adapters Jupyter notebook (.ipynb) adapter IpynbVirtualSource, ipynbToVirtualSource
src/languages/jcl.ts Language Adapters z/OS JCL adapter: the JOB (to the next JOB, a // null statement, or the end of the file), PROC procedures extractJcl
src/languages/kotlin.ts Language Adapters Kotlin symbol extractor — regex-based (no tree-sitter grammar needed) extractKotlin
src/languages/liquid.ts Language Adapters Shopify Liquid template extractor LiquidSection, extractLiquid
src/languages/lua.ts Language Adapters Lua symbol extractor — regex-based (no tree-sitter grammar needed) extractLua
src/languages/makefile_idx.ts Language Adapters Makefile target and define-block extractor extractMakefile
src/languages/markup_scan.ts Language Adapters Linear replacements for the "tag start, anything up to >, lazy body, close tag" regexes that re-read the rest of a OpenTag, Element, charFinder, gtFinder, findOpenTags
src/languages/matlab.ts Language Adapters MATLAB and Octave adapter: functions (nested and local ones too), classdef classes with their properties, methods isMatlabSource, extractMatlab
src/languages/natural.ts Language Adapters Software AG Natural adapter: the object itself (named by its file stem, kind by extension), inline DEFINE SUBROUTINE extractNatural
src/languages/nginx.ts Language Adapters Nginx configuration language extractor and symbol parser extractNginx
src/languages/nix.ts Language Adapters Nix extractNix
src/languages/objc.ts Language Adapters Objective-C and Objective-C++ symbol extractor isObjcHeader, isObjcSource, selectorOf, extractObjc
src/languages/ocaml.ts Language Adapters OCaml extractOcaml
src/languages/pascal.ts Language Adapters Pascal, Delphi and Free Pascal adapter: the program, unit, library or package header, classes, records, objects isPascalSource, extractPascal
src/languages/perl.ts Language Adapters Perl symbol extractor: packages and named subs, a sub taking its package as parent PerlResult, isPerlSource, isPrologSource, extractPerl
src/languages/php.ts Language Adapters PHP symbol extractor — regex-based (no tree-sitter grammar needed) maskPhpInlineHtml, extractPhp
src/languages/pli.ts Language Adapters PL/I adapter: labeled PROCEDURE blocks (nested ones under their parent) and PACKAGE blocks, each to the END that closes extractPli
src/languages/powershell_idx.ts Language Adapters Language Adapters module: powershell_idx.ts extractPowershell
src/languages/proto_idx.ts Language Adapters Protocol Buffers (.proto) extractor extractProto
src/languages/r.ts Language Adapters R symbol extractor — regex-based (no tree-sitter grammar needed) extractR
src/languages/racket.ts Language Adapters Racket adapter: define, define-values, define-syntax, define-syntax-rule, struct, define-struct extractRacket
src/languages/registry.ts Language Adapters The regex language adapters and the table that dispatches to them extractCobol, extractNatural, extractSalesforceMetadata, extractVue, extractSvelte
src/languages/rpg.ts Language Adapters ILE RPG adapter extractRpg
src/languages/salesforce_frontend.ts Language Adapters Language Adapters module: salesforce_frontend.ts SalesforceFrontendResult, extractLwcJavaScript, extractLwcTemplate, attributeScanWork, extractSalesforceMarkup
src/languages/salesforce_metadata.ts Language Adapters Language Adapters module: salesforce_metadata.ts xmlText, directChildText, rootElement, elementBlocks, propertyElements
src/languages/sas.ts Language Adapters SAS adapter: %MACRO definitions (to their %MEND, nested ones under their parent) and DATA steps named by their first extractSas
src/languages/scala.ts Language Adapters Scala symbol extractor — regex-based (no tree-sitter grammar needed) extractScala
src/languages/scheme.ts Language Adapters Scheme (R7RS) adapter: define, define-syntax, define-record-type, define-values, define-library extractScheme
src/languages/sfc_idx.ts Language Adapters Single-File-Component extractor for Vue (.vue), Svelte (.svelte), and Astro (.astro) SfcResult, extractTagBlocks, extractVue, extractSvelte, extractAstro
src/languages/shader.ts Language Adapters Shader symbol extractors extractCShader, extractWgsl
src/languages/sniff.ts Language Adapters Content sniffs that pick a language for an ambiguous extension (.m, .pp, .h, .pl, .t, .p, .w, .cls) ABL_SNIFF_CHARS, isAblSource, isMatlabSource, isObjcSource, isObjcHeader
src/languages/solidity.ts Language Adapters Solidity symbol extractor: contracts, interfaces and libraries with their functions, constructors, fallback and receive extractSolidity
src/languages/span_collector.ts Language Adapters Shared bookkeeping for the statement-scanning adapters (ABAP, SAS, PL/I, RPG, JCL, OpenEdge ABL): a symbol is opened StatementAdapterResult, SpanCollector, topLevelWords, wordBeforeParen
src/languages/sql_idx.ts Language Adapters SQL DDL extractor — CREATE TABLE/VIEW/FUNCTION/PROCEDURE/INDEX/TRIGGER names extractSql
src/languages/swift.ts Language Adapters Swift symbol extractor — regex-based (no tree-sitter grammar needed) stripLeadingAttributes, IMPORT_RE, extractSwift
src/languages/templates_idx.ts Language Adapters Template-engine adapters: Jinja2 (.j2/.jinja/.jinja2), Handlebars (.hbs/.handlebars), ERB (.erb), EJS DelimiterPair, TemplateResult, maskTemplateDelimiters, extractJinja2, extractHandlebars
src/languages/terraform_idx.ts Language Adapters Terraform / HCL (.tf, .tfvars, .hcl) extractor extractTerraform
src/languages/thrift.ts Language Adapters Apache Thrift IDL symbol extractor: structs, unions, exceptions, enums and services, the functions inside each service extractThrift
src/languages/vb.ts Language Adapters Visual Basic symbol extractor, regex-based (no tree-sitter grammar ships for VB) extractVb
src/languages/vhdl.ts Language Adapters VHDL adapter: entity, architecture, package declaration, package body, function and procedure extractVhdl
src/languages/zig.ts Language Adapters Zig symbol extractor — regex-based (no tree-sitter grammar needed) extractZig
src/bash_backslash_repair.ts Bash Output, Compression, and Tool Filters Repair of a Bash command that Claude Code on Windows would hand to Git Bash damaged: the command is written byte for MSYS_SAFE_COMMAND_CHARS, msysDamagesCommand, hasHalvedRun, repairIsUnsafe, msysPathOf
src/bash_extractors.ts Bash Output, Compression, and Tool Filters Command line extractors, classification, and surgical hint builders for bash hook handlers commandPathIsTouchable, sqlTableHint, surgicalHintFor, surgicalHintForConfigDoc, splitShellSegments
src/bash_output_cache.ts Bash Output, Compression, and Tool Filters Bash-output cache with cross-process disk persistence BASH_OUTPUT_SUBDIR, BashOutputEntry, isCommandOfType, isGitMutableCommand, isDirListingCommand
src/bash_range_savings.ts Bash Output, Compression, and Tool Filters Prices a line-range read's proposed surgical replacement against the read itself, so a hint that redirects a line-range RangeSubstitute, rangeSubstituteFor
src/bash_runner.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: bash_runner.ts DEFAULT_TIMEOUT_SECONDS, DEFAULT_HEARTBEAT_INTERVAL_MS, RunOptions, scheduleHeartbeat, resolveFilter
src/bash_structural_index.ts Bash Output, Compression, and Tool Filters Recognizes a plain-enumeration rg/grep invocation over a single, already-fresh-indexed file whose pattern maps StructuralIndexRewrite, detectStructuralIndexRewrite
src/filters.ts Bash Output, Compression, and Tool Filters Line-level output filters applied during bash output compression Filter, FILTERS
src/tool_filters/ai_clis.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: ai_clis.ts ghCopilotFilter, copilotFilter, aiderFilter, geminiCliFilter, claudeCliFilter
src/tool_filters/base.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: base.ts resolveMinNetSavingsBytes, RewriteWorthwhileInput, isRewriteWorthwhile, compressedTokensSaved, CompressedOutput
src/tool_filters/build.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: build.ts MakeFilter, CmakeFilter, BazelFilter, MesonFilter, CargoFilter
src/tool_filters/build_dotnet.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: build_dotnet.ts MSBuildFilter, DotnetFilter, msbuildFilter, dotnetFilter
src/tool_filters/build_js.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: build_js.ts NxFilter, LernaFilter, TurboFilter, WebpackFilter, nxFilter
src/tool_filters/build_jvm.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: build_jvm.ts GradleFilter, MavenFilter, AntFilter, SbtFilter, JavacFilter
src/tool_filters/ci.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: ci.ts GhRunLogFilter, GhFilter, ActFilter, GenericCIFilter, PreCommitFilter
src/tool_filters/cloud.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: cloud.ts TerraformFilter, terraformFilter, AnsibleFilter, ansibleFilter, PulumiFilter
src/tool_filters/cloud_providers.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: cloud_providers.ts AwsFilter, awsFilter, AwsCliFilter, awsCliFilter, GcloudFilter
src/tool_filters/containers.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: containers.ts DockerFilter, DockerComposeFilter, KubectlFilter, KubectlLogsFilter, HelmFilter
src/tool_filters/db_clients.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: db_clients.ts PsqlFilter, psqlFilter, MySQLFilter, mySQLFilter, Sqlite3Filter
src/tool_filters/diff_blocks.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: diff_blocks.ts isDiffAdd, isDiffRemove, DiffBlockShape, collapseDiffBlocksToCap
src/tool_filters/dispatch.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: dispatch.ts TOOL_FILTERS, dispatchArgv, selectFilter, detectFromCommand, CompressOptions
src/tool_filters/families.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: families.ts plural, NodeTestRunnerConfig, DropRule, PackageManagerFilterConfig, makePackageManagerFilter
src/tool_filters/generic.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: generic.ts PassthroughFilter, GenericFilter
src/tool_filters/git.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: git.ts GitLogFilter, GitDiffFilter, GitStatusVerboseFilter, GitBlameFilter, GitCommitFilter
src/tool_filters/helpers.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: helpers.ts DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES, MAX_INSPECT_BYTES, DEFAULT_MAX_INPUT_BYTES, FALLBACK_MAX_LINE_CHARS
src/tool_filters/index.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: index.ts CompressedOutput, ToolFilter, compressedTokensSaved, isRewriteWorthwhile, resolveMinNetSavingsBytes
src/tool_filters/languages.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: languages.ts NodeFilter, nodeFilter, PythonFilter, pythonFilter, RubyFilter
src/tool_filters/linters.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: linters.ts LINTER_FILTERS
src/tool_filters/linters_js.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: linters_js.ts tscFilter, eslintFilter, oxlintFilter, biomeFilter, linterFilter
src/tool_filters/linters_python.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: linters_python.ts ruffFilter, mypyFilter, pylintFilter, blackIsortFilter
src/tool_filters/misc.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: misc.ts PlaywrightFilter, playwrightFilter, CypressFilter, cypressFilter, SysPackageFilter
src/tool_filters/package_managers.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: package_managers.ts PACKAGE_MANAGER_FILTERS
src/tool_filters/pytest.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: pytest.ts PytestFilter, pytestFilter, looksLikePytestOutput
src/tool_filters/shell_file.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: shell_file.ts GrepFilter, RgFilter, LsFilter, EzaFilter, TreeFilter
src/tool_filters/stack_trace.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: stack_trace.ts isExternalStackTraceFrame, externalStackFrameNote
src/tool_filters/test_runners.ts Bash Output, Compression, and Tool Filters Bash Output, Compression, and Tool Filters module: test_runners.ts jestFilter, vitestFilter, nodeTestFilter, TEST_RUNNER_FILTERS
src/hints/file_type_handler.ts Hints, Guidance, and Formatting Universal large-file interception; CSV deny omits --columns for a non-comma header, an unsafe name or over 500 chars FileTypeResult, LARGE_SYMBOL_LINE_THRESHOLD, TXT_WINDOW_LINES, FILE_TYPE_THRESHOLDS, BYTE_RANGE_ADVICE
src/hints/lang_patterns.ts Hints, Guidance, and Formatting Hints, Guidance, and Formatting module: lang_patterns.ts BUILD_COMMAND_PATTERNS, LOCK_FILE_COUNT, MANIFEST_FILE_COUNT, BUILD_DIR_COUNT, GENERATED_EXT_COUNT
src/hints/markdown_hints.ts Hints, Guidance, and Formatting Markdown heading extraction and formatting for large-file hints MarkdownHeading, MARKDOWN_SIZE_THRESHOLD, extractMarkdownHeadings, HeadingTreeParts, formatHeadingTreeParts
src/render/ansi.ts Hints, Guidance, and Formatting ANSI 24-bit colour primitives and text-alignment helpers for terminal rendering colorStdout, RGB, RESET, stripAnsiEscapes, fmtBytes
src/render/index.ts Hints, Guidance, and Formatting Stats renderer package — ANSI truecolor terminal output renderStats, setStatsMessages, C, RESET, fg
src/render/stats_renderer.ts Hints, Guidance, and Formatting Terminal renderer for token-goat stats setStatsMessages, _renderedKindNames, _kindGroupLabel, renderStats
src/render/types.ts Hints, Guidance, and Formatting Data-transfer types for the stats renderer Sparklines, TotalStats, KindStat, DayStat, ProjectStat
src/cli_doctor.ts Diagnostics, Doctor, and Maintenance Doctor CLI helpers — diagnose token-goat health autoReclaimRow, repairBlocker, runDoctorRepair, DoctorRepairResult, checkInstall
src/cli_doctor_guidance.ts Diagnostics, Doctor, and Maintenance Diagnostics, Doctor, and Maintenance module: cli_doctor_guidance.ts INSTRUCTION_GATE_BEGIN, INSTRUCTION_GATE_END, CODEX_GATE_BEGIN, CODEX_GATE_END, InstructionGateCandidate
src/cli_doctor_harness_perf.ts Diagnostics, Doctor, and Maintenance Diagnostic checks for AI harness session storage bloat and AV/EDR exclusion posture DEFAULT_MAX_HARNESS_SESSION_BYTES, MAX_SESSION_SCAN_FILES, AV_EXCLUSION_DISCLAIMER, HarnessDirectoryCandidate, getHarnessStorageCandidates
src/cli_doctor_hooks.ts Diagnostics, Doctor, and Maintenance Harness hook repairs for token-goat doctor --repair and token-goat install shimIsCurrent, wiringPointsAtMissingFile, HarnessRepairResult, repairHarnessHooks
src/cli_doctor_index.ts Diagnostics, Doctor, and Maintenance Index and reindex-queue diagnostics for token-goat doctor DB_SIZE_WARN_BYTES, freelistBytes, CategoryByteShare, dbCategoryBreakdown, oversizeDbMessage
src/cli_doctor_native.ts Diagnostics, Doctor, and Maintenance doctor's native hook client rows: per harness and scope, which form of hook command is wired NativeWiring, NativeAvailability, nativeAvailability, nativeWirings, formatNativeCounts
src/cli_doctor_platforms.ts Diagnostics, Doctor, and Maintenance Platform and harness integration diagnostics for token-goat doctor globalMcpConfigPath, checkGlobalMcpConfig, VSCODE_USER_SCOPE_MIGRATED_NOTE, VSCODE_PROJECT_SCOPE_COVERAGE_NOTE, VSCODE_USER_SCOPE_MULTIROOT_NOTE
src/cli_doctor_process.ts Diagnostics, Doctor, and Maintenance Process table and MCP process health diagnostics for token-goat doctor ProcessInfo, ProcessListFailure, isTokenGoatResidentProcess, checkMcpProcessHealth, processListOutput
src/cli_doctor_repair.ts Diagnostics, Doctor, and Maintenance Repair utilities and routines for token-goat doctor --fix / --repair DoctorRepairResult, autoReclaimRow, repairBlocker, runDoctorRepair
src/cli_doctor_security.ts Diagnostics, Doctor, and Maintenance Security posture and configuration override diagnostics for token-goat doctor LOCKED_BOOLEAN_SAFE_VALUE, lockedEnvOverridableKeys, EnvOverriddenSetting, envOverriddenSecuritySettings, dataDirPermissionResult
src/pack.ts Diagnostics, Doctor, and Maintenance Diagnostics, Doctor, and Maintenance module: pack.ts PackFile, PackResult, SecretHit, BudgetEntry, BudgetResult
src/disk_cache.ts Caches and Output Stores Cross-process disk persistence for id-keyed content caches DEFAULT_MAX_COUNT, DEFAULT_MAX_AGE_MS, tokenGoatHome, blobPath, isBlobStale
src/gdrive.ts Caches and Output Stores Google Docs section extraction via public export API GdriveSection, FetchDocOptions, fetchDoc, getDocSections, formatSections
src/mcp_cache.ts Caches and Output Stores MCP tool result cache — dedup repeated read-only MCP calls across hook processes MCP_MAX_CACHE_BYTES, isMcpReadOnly, mcpHash, mcpOutputId, storeMcpOutput
src/project_memory.ts Caches and Output Stores Per-project persistent key-value memory for session-start context injection MAX_ENTRIES, NoteAnchor, NoteEntry, AnchorStatus, AnchorStatusOf
src/web_cache.ts Caches and Output Stores Web-fetch result cache with cross-process disk persistence WEB_OUTPUT_SUBDIR, storeWebOutput, getWebOutput, hasWebOutput, getWebOutputRaw
src/webfetch.ts Caches and Output Stores Caches and Output Stores module: webfetch.ts ssrfPinnedLookup, isPrivateIPv4, isPrivateIPv6, cleanupStaleDownloads, HttpFetchResult
src/config.ts Configuration and Utilities Configuration and Utilities module: config.ts validateNumericField, validateEnumField, configEnvFingerprint, getLastConfigParseError, getLastProjectConfigParseError
src/env.ts Configuration and Utilities Environment-variable parsers with safe fallbacks FALSY_ENV_VALUES, TRUTHY_ENV_VALUES, envStr, envBool, envInt
src/reset.ts Configuration and Utilities Module-reset registry registerReset, clearModuleCaches, clearPerRequestCaches, _clearResetRegistryForTesting
src/util.ts Configuration and Utilities Cross-cutting helpers shared across token-goat modules normalizePath, GitResult, RunGitAsyncOptions, RunGitOptions, HookEntryLike
src/util_config.ts Configuration and Utilities Configuration file manipulation, hook stripping, and delimited block helpers HookEntryLike, commandHookFields, isOwnHookEntry, MatcherGroupLike, MatcherGroupWithMatcher
src/util_context.ts Configuration and Utilities Source context window building and rendering SourceContextLine, buildContextWindow, renderContextWindow
src/util_suggest.ts Configuration and Utilities Levenshtein distance and string suggestion helpers levenshteinDistance, suggestPackageNames
src/version.ts Configuration and Utilities Single source of truth for the package's own manifest fields: its version, its npm name and where issues go VERSION, BUILD_STAMP, PACKAGE_NAME, ISSUES_URL, SUPPORT_EMAIL
src/image_engine.ts Media, Documents, and Structured Formats Pure TypeScript / JavaScript Image Processing Engine for token-goat assertDecodableSize, ImageMeta, DecodedImage, AnimatedGifFrame, DecodedAnimatedGif
src/image_gif_encode.ts Media, Documents, and Structured Formats Re-encode an already-decoded animated GIF as delta frames PixelRect, GifFrameDelta, unionRects, gifFrameDelta, sliceIndexedRect
src/image_isobmff.ts Media, Documents, and Structured Formats Header-only probe for ISO base media (ISOBMFF) still images: AVIF and HEIC/HEIF IsoBmffMeta, probeIsoBmffMeta
src/image_ocr.ts Media, Documents, and Structured Formats OCR — extract text from text-heavy images (screenshots of a terminal, a stack trace, a table, an editor, a doc page) DEFAULT_OCR_LANG, SUPPORTED_OCR_LANGS, getOcrLangSpec, isSupportedOcrLang, resolveOcrLangs
src/image_slice.ts Media, Documents, and Structured Formats Image slicing, difference calculation, and compact visual layout inspection ImageSliceOptions, ImageSliceResult, ImageDiffResult, sliceImage, diffImages
src/json_path_eval.ts Media, Documents, and Structured Formats Media, Documents, and Structured Formats module: json_path_eval.ts JsonValueType, jsonType, MAX_RECURSIVE_NODES, MAX_RECURSIVE_DEPTH, JsonQueryResult
src/json_path_parser.ts Media, Documents, and Structured Formats Media, Documents, and Structured Formats module: json_path_parser.ts ProjectionObjectField, FilterOperator, FilterLiteral, FilterCondition, FilterNode
src/json_query.ts Media, Documents, and Structured Formats Narrow structural summary + path-based extraction for token-goat json-outline / json-query, so a multi-thousand-line JsonValueType, jsonType, JsonFieldSummary, JsonOutlineArray, JsonOutlineObject
src/pdf_extract.ts Media, Documents, and Structured Formats PDF -> plain text extraction for token-goat pdf-extract, so a PDF's useful content reaches the model as text instead PdfExtractResult, MAX_PDF_TEXT_BYTES, MAX_PDF_INPUT_BYTES, MAX_PDF_TEXT_ITEMS, MAX_OUTLINE_ENTRIES
src/sqlite_driver.ts Media, Documents, and Structured Formats A better-sqlite3-shaped facade over Node's built-in node:sqlite suppressSqliteExperimentalWarning, sqliteResultCodeName, SqliteColumn, SqliteRunResult, SqliteStatement
src/sqlite_query.ts Media, Documents, and Structured Formats Narrow schema summary + read-only query extraction for token-goat sqlite-schema / sqlite-query, so a project's SQLITE_QUERY_ROW_CAP, isSqliteFile, openReadonlySqlite, SqliteColumnInfo, SqliteIndexInfo
src/xml_parser.ts Media, Documents, and Structured Formats Minimal XML reader for the OOXML parts token-goat extracts (.docx, .pptx, .xlsx) MAX_XML_DEPTH, XmlTooDeepError, decodeXmlEntities, parseXml
src/xml_query.ts Media, Documents, and Structured Formats XML structure inspection and querying for token-goat XmlNode, XmlOutlineSummary, XmlOutlineElement, XML_ATTR_REGION, xmlTokenScanText
src/xml_selector.ts Media, Documents, and Structured Formats The selector language of xml-query: a path such as catalog/book[@id='101']/@lang parsed into steps, and the tag XmlPredicate, XmlSelectorStep, matchTag, getAttrValue, evalPredicate
src/affected.ts Specialized Subsystems token-goat affected -- which test files a set of changed source files can reach DEFAULT_AFFECTED_DEPTH, AffectedOptions, AffectedResult, computeAffected, runAffected
src/agent_receipt.ts Specialized Subsystems The evidence receipt a subagent's report carries when its own record gives the parent a reason to doubt it: the last GIT_STATUS_TIMEOUT_MS, receiptLines, checkChangeClaim, receiptForStoppedAgent, parkAgentReceipt
src/answer_router.ts Specialized Subsystems token-goat answer -- a deterministic question router AnswerOptions, refusal, AnswerIntent, Classification, normalizeQuestion
src/archive_query.ts Specialized Subsystems Entry listing + single-member extraction for token-goat zip-list / zip-read, so a .zip/.jar/.whl/.vsix/.nupkg ArchiveDependencyMissingError, ZipEntry, listZipEntries, formatZipList, extractZipEntry
src/asset_extensions.ts Specialized Subsystems Extension-based classification of files whose bytes are not text, kept in one leaf module with no imports of its own so IMAGE_EXTENSIONS, isImagePath, NON_TEXT_ASSET_EXTENSIONS, isNonTextAsset, NON_TEXT_ASSET_SET_ID
src/baseline.ts Specialized Subsystems Project map / overview (token-goat map) ProjectMap, SKIP_DIRS, isIgnoredIndexPath, MAX_FILES_SCANNED, WalkResult
src/batch_serve.ts Specialized Subsystems --batch-serve: run many CLI invocations inside one already-started process BatchRequest, BatchOperationResult, BatchResponse, swapEnv, serveOne
src/bridges_status.ts Specialized Subsystems Bridge hook-event parity matrix HOOK_EVENTS, BridgeCapabilityRow, BridgeVerification, VERIFICATION_RANK, VERIFICATION_BLURB
src/build_stamp.ts Specialized Subsystems Tells a process that its bundle was rebuilt under it BUILD_INFO_FILE, BuildInfo, readBuildInfo, BuildVerdict, compareBuilds
src/cache_session_commands.ts Specialized Subsystems Cache and history commands: bash-history, web-history, clean-cache, prune-cache, cache-audit cmdBashHistory, cmdWebHistory, cmdMcpHistory, cmdCleanCache, cmdPruneCache
src/call_streak.ts Specialized Subsystems Call-streak advisories: the two hints that judge a run of tool calls rather than one call SERIAL_GAP_MS, SERIAL_READS_BEFORE_HINT, ZERO_HIT_SEARCHES_BEFORE_BRAKE, MAX_BATCH_HINTS_PER_SESSION, MAX_SEARCH_BRAKES_PER_SESSION
src/canonical_skill.ts Specialized Subsystems Specialized Subsystems module: canonical_skill.ts CANONICAL_SKILL_MD
src/capabilities.ts Specialized Subsystems A machine-readable statement of every capability token-goat has that can send data off the machine or leave data on it CapabilityKind, Capability, EGRESS_MODULES, LOCAL_IPC_MODULES, collectCapabilities
src/change_claim.ts Specialized Subsystems Whether a subagent's final report claims a change of its own claimsOwnChange
src/claude_config_dir.ts Specialized Subsystems Where Claude Code keeps its own per-user configuration, and nothing else claudeConfigDir, claudeGlobalJsonPath, projectTranscriptsDir
src/claude_hidden_rules.ts Specialized Subsystems Whether a Claude Code session could be under permission rules no settings file shows, so that rewrite_permission.ts must HiddenRuleHelpers, HiddenRuleQuery, resetHiddenRuleCache, commandLineRuleSource, primeProcessReason
src/cli_audit.ts Specialized Subsystems CLI handler for token-goat audit AuditCommandOptions, MaintainerFeedbackCard, buildFeedbackCardFromClaude, buildFeedbackCardFromCopilot, formatMaintainerCard
src/cli_bench.ts Specialized Subsystems Specialized Subsystems module: cli_bench.ts BenchCase, BenchCaseResult, BenchReport, loadCorpus, runCase
src/cli_bootstrap_audit.ts Specialized Subsystems Specialized Subsystems module: cli_bootstrap_audit.ts BootstrapAuditOptions, BootstrapAuditResult, buildBootstrapAudit, runBootstrapAudit
src/cli_cached_output.ts Specialized Subsystems The three cached-output recall commands, bash-output, web-output and mcp-output, with the --file reader two of RecallFilterOpts, _applyFiltersAndPrint, cmdBashOutput, cmdWebOutput, cmdMcpOutput
src/cli_commands.ts Specialized Subsystems Machine-readable command manifest CommandManifestOption, CommandManifestArgument, CommandManifestEntry, BATCH_QUERY_COMMANDS, BatchQueryCommand
src/cli_context_stats.ts Specialized Subsystems CLI handler for token-goat context-stats tok, findClaudeMdFiles, findMemoryMd, buildStats, ContextStatsOptions
src/cli_diagnostics.ts Specialized Subsystems Diagnostic, inspection, packaging, and budgeting command handlers cmdCoverageReportGaps, cmdConflicts, cmdScreenshot, expandGlobs, readIgnoreFile
src/cli_file_ops.ts Specialized Subsystems Specialized Subsystems module: cli_file_ops.ts resolveNoteAnchor, autoNoteAnchor, cmdNoteAdd, cmdWriteFile, cmdReplace
src/cli_hint_stats.ts Specialized Subsystems CLI handler for token-goat hint-stats HintStatsCommandOptions, runHintStatsCommand
src/cli_hook_server.ts Specialized Subsystems token-goat hook-server: start, inspect and stop the resident hook servers in hook_server.ts cmdHookServerRun, formatHookServerStatus, cmdHookServerStatus, cmdHookServerStop
src/cli_install.ts Specialized Subsystems The install, uninstall and mcp-status commands and the helpers only they use: the Claude Code base gate visualStudioManualSteps, cmdInstall, cmdMcpStatus, cmdUninstall, leftoverIntegrations
src/cli_mcp_audit.ts Specialized Subsystems CLI handler for token-goat mcp-audit McpAuditCommandOptions, readMcpConfig, analyzeMcpCache, buildMcpAuditReport, printReport
src/cli_memory.ts Specialized Subsystems CLI handler for token-goat memory --analyze / --fix MemoryCommandOptions, runMemoryCommand
src/cli_office.ts Specialized Subsystems Specialized Subsystems module: cli_office.ts fileSizeOrZero, recordDocStat, recordXlsxStat, cmdPdfExtract, cmdPdfLocate
src/cli_payloads.ts Specialized Subsystems token-goat stats --payloads: what token-goat itself adds to every session's context, measured rather than estimated PayloadBlock, NoteProbe, PayloadReport, namedFiles, probeNotes
src/cli_recall.ts Specialized Subsystems CLI handler for token-goat recall RecallCommandOptions, runRecallCommand
src/cli_session.ts Specialized Subsystems Session, corpus audit, memory, and output recall command handlers cmdContextStats, cmdBootstrapAudit, cmdMemory, cmdWaste, cmdAudit
src/cli_skills.ts Specialized Subsystems Specialized Subsystems module: cli_skills.ts cmdSkillBody, cmdSkillCompact, cmdSkillList, cmdSkillSize, cmdSkillHistory
src/cli_stats.ts Specialized Subsystems CLI handler for token-goat stats writeRaw, renderTopSessionFiles, MOST_RECENT_SESSION_HEADING, renderTopFilesForSession, renderTopSessionFilesFromDisk
src/cli_statusline.ts Specialized Subsystems CLI handler for token-goat statusline StatuslinePayload, StatuslineData, buildStatuslineData, renderStatusline, StatuslineCommandOptions
src/cli_structured.ts Specialized Subsystems Specialized Subsystems module: cli_structured.ts PHP_LINT_CONFIG, cmdCsvQuery, cmdCsvProfile, cmdJsonOutline, cmdJsonQuery
src/cli_upgrade.ts Specialized Subsystems Upgrade command for token-goat UpgradeOptions, VersionCheckResult, UPDATE_CACHE_TTL_MS, CachedUpdateInfo, FAILED_CHECK_TTL_MS
src/cli_waste.ts Specialized Subsystems CLI handler for token-goat waste WasteCommandOptions, runWasteCommand
src/codex_rules.ts Specialized Subsystems Codex's half of rewrite_permission.ts: Codex matches its execpolicy rules (https://developers.openai.com/codex/rules) CodexRuleHelpers, decideCodex
src/cold_gap.ts Specialized Subsystems Cold-cache re-write accounting behind session-audit COLD_TTL_MS_5M, COLD_TTL_MS_1H, COLD_MIN_CACHE_WRITE_TOKENS, COLD_MIN_REWRITE_SHARE_OF_PREV, COLD_NO_TOOL_BUCKET
src/command_error.ts Specialized Subsystems Specialized Subsystems module: command_error.ts CliError, setCliInvocation, clearCliInvocation, cliInvocation, formatCommandError
src/command_intent.ts Specialized Subsystems Intent-based suggestions for command names that don't exist suggestForUnknownCommand, attemptedCommandName, GLOBAL_VALUE_OPTIONS, commandWordIndex
src/config_commands.ts Specialized Subsystems D3 commands: config, project, compact-doc, fetch-image, history cmdConfig, cmdProject, cmdCompactDoc, cmdFetchImage, cmdHistory
src/config_defaults.ts Specialized Subsystems Default configuration values and factory functions for token-goat RETIRED_CONFIG_KEYS, CONFIG_DEFAULTS, getDefaultConfig, defaultConfig
src/config_project.ts Specialized Subsystems Specialized Subsystems module: config_project.ts PROJECT_LOCKED_SECTIONS, PROJECT_LOCKED_KEYS, lastProjectConfigLockedKeys, setLastProjectConfigLockedKeys, resetLastProjectConfigLockedKeys
src/config_types.ts Specialized Subsystems Configuration types and interfaces for token-goat COMPRESSION_PROFILES, CompressionProfile, COMPRESSION_PROFILE_SETTINGS, CompressionProfileSetting, isCompressionProfile
src/confirm_apply.ts Specialized Subsystems Small, reusable diff-preview + confirm-before-write helper FileChange, ConfirmAndApplyOptions, ConfirmAndApplyResult, confirmAndApply
src/conflict_query.ts Specialized Subsystems Unresolved git merge-conflict marker extraction (token-goat conflicts) ConflictSide, ConflictContextLine, ConflictRegion, ConflictWarning, FileConflicts
src/content_store.ts Specialized Subsystems Local, bounded storage for generic compressed text and named handoffs CONTENT_MAX_INPUT_CHARS, CONTENT_MAX_ITEMS, CONTENT_MAX_BYTES, CONTENT_MAX_ITEM_BYTES, CONTENT_SUBDIR
src/copilot_home.ts Specialized Subsystems Copilot CLI's user-scope and cache directories, in a module small enough for the hook path to import copilotCliUserRoot, copilotCliCacheRoot, copilotCliMcpToolsDir
src/copilot_mcp_names.ts Specialized Subsystems Specialized Subsystems module: copilot_mcp_names.ts canonicalizeCopilotMcpToolName, resetCopilotMcpToolNameCache
src/copilot_mcp_tools.ts Specialized Subsystems Reads Copilot CLI's on-disk MCP tool-definition cache COPILOT_BUILTIN_MCP_SERVERS, readCopilotDisabledMcpServers, CopilotMcpServerTools, CopilotMcpToolsReport, readCopilotMcpTools
src/copilot_skill_path.ts Specialized Subsystems Finds the SKILL.md Copilot CLI loads for a skill name, in Copilot's own project and personal skill directories copilotSkillPath
src/copilot_tool_names.ts Specialized Subsystems Copilot CLI's built-in tool names, mapped to the canonical token-goat names every hook gates on COPILOT_CLI_TOOL_NAME_MAP
src/copilot_waste.ts Specialized Subsystems Waste analysis for Copilot CLI sessions CopilotBlockClass, CopilotTokenSplit, CopilotCompaction, CopilotWasteReport, splitInjectedBlocks
src/could_not_read.ts Specialized Subsystems Failures for a file no command could open, each followed by a Did-you-mean list of the existing paths it may have been retryCommand, nearPathLines, couldNotReadError, fileNotFoundError
src/coverage_query.ts Specialized Subsystems Narrow "gaps only" extraction for token-goat coverage-report-gaps, so a code-coverage report LineRange, FunctionGap, BranchGap, FileCoverageGaps, CoverageReportFormat
src/csv_query.ts Specialized Subsystems Narrow CSV projection/filter for token-goat csv-query, so a multi-thousand row CSV never needs a full Read just to CsvWhereOp, CsvWhere, CsvQueryOptions, detectDelimiter, CsvQueryResult
src/delivering_deny.ts Specialized Subsystems The wording that marks a token-goat deny as the delivery of content rather than a refusal DELIVERS_CONTENT_RE
src/delivery_cap.ts Specialized Subsystems Specialized Subsystems module: delivery_cap.ts CLAUDE_CODE_BASH_OUTPUT_CAP_BYTES, CLAUDE_CODE_PERSISTED_PREVIEW_BYTES, bashOutputCapBytes, clipToDeliveryCap, deliveredOutputBytes
src/dep_docs.ts Specialized Subsystems Specialized Subsystems module: dep_docs.ts DeclarationRow, extractDtsOutline, DepDocsOptions, DepDocsResult, runDepDocs
src/describe_sqlite.ts Specialized Subsystems Specialized Subsystems module: describe_sqlite.ts describeSqliteFile
src/dirty_queue.ts Specialized Subsystems Specialized Subsystems module: dirty_queue.ts dirtyQueuePathFor, encodeDirtyQueueLine, parseDirtyQueueLines, getDirtyPathsFor, appendDirtyQueueFile
src/doc_comment.ts Specialized Subsystems Shared doc-comment recovery, used by both the tree-sitter parser (parser.ts) and the regex-based language adapters DocCommentStyle, precedingDocComment
src/doc_compact.ts Specialized Subsystems Stable-doc compact serving for large reference docs compactPathFor, isCompactFresh, markCompactStale, readCompactBody, writeCompact
src/doc_embed_extract.ts Specialized Subsystems Extracted-text bridge from the binary-document readers (pdf, docx, pptx, xlsx) into the embeddings/chunking pipeline, so isEmbeddableDocument, isDocumentRefusal, isTransientDocumentRefusal, extractEmbeddableDocumentText
src/doctor_probe.ts Specialized Subsystems Specialized Subsystems module: doctor_probe.ts PROBE_PROMPT, PROBE_COMMANDS, IDE_HOSTS_WITHOUT_PROBE, NO_HEADLESS_PROBE_EXIT_CODE, noHeadlessProbeMessage
src/doctor_result.ts Specialized Subsystems The shape every doctor check returns DoctorResult
src/document_refusal.ts Specialized Subsystems How long any one document's extraction may run, whatever format it is MAX_DOCUMENT_WORK_MILLIS, DocumentRefusedError
src/docx_extract.ts Specialized Subsystems Word (.docx) narrow-slice reader DocxHeading, DocxTable, docxOutline, docxText, docxTables
src/dotenv_redact.ts Specialized Subsystems Value redaction for dotenv files DOTENV_VALUE_PLACEHOLDER, isDotenvPath, redactDotenvValues, redactIfDotenv
src/edit_near_miss.ts Specialized Subsystems Near-miss search for an Edit whose old_string is not in the file NearMissRung, NearMissHit, NearMiss, findNearMiss, NEAR_MISS_RUNG_NOTE
src/embedding_boundaries.ts Specialized Subsystems Specialized Subsystems module: embedding_boundaries.ts buildEmbeddingBoundaries
src/emit.ts Specialized Subsystems The two writers every command surface uses to put its result on stdout and its diagnostics on stderr emit, emitErr
src/encoding.ts Specialized Subsystems Source file character encoding and BOM detection / transcoding SourceEncoding, stripBom, detectSourceEncoding, decodeSource, encodeSource
src/env_proxy.ts Specialized Subsystems Completes the proxy settings the background worker starts with, so its downloads go through a proxy the machine already PROXY_VARS, proxyConfigured, nodeFetchHonoursEnvProxy, fetchBypassesProxy, rerunWithEnvProxy
src/evidence_cache.ts Specialized Subsystems Specialized Subsystems module: evidence_cache.ts EvidenceRepresentation, EvidenceEntry, readEvidenceFileText, recordEvidence, findVerifiedFileEvidence
src/failures.ts Specialized Subsystems Extract failing test blocks from test runner output FailureBlock, FailureResult, getFailureCount, extractFailures, formatFailuresText
src/failures_state.ts Specialized Subsystems Cross-invocation state for token-goat failures --delta -- persists the failure-signature set DEFAULT_FAILURES_STATE_KEY, FailureSnapshot, failuresStatePath, loadFailureSnapshot, saveFailureSnapshot
src/fence_cap.ts Specialized Subsystems Specialized Subsystems module: fence_cap.ts guardThenFence, guardRedactAndFence, guardAndFenceFileText, capListField
src/filter_counts.ts Specialized Subsystems Aggregated filter/rule counts for all hook types BASH_OUTPUT_FILTER_COUNT, BUILD_RECALL_PATTERN_COUNT, MONITORING_PATTERN_COUNT, PATH_PATTERN_COUNT, FILE_TYPE_HANDLER_COUNT
src/filter_notice.ts Specialized Subsystems The notices a listing command prints when a filter left nothing of what the store holds, so a filtered view never reads allOfCount, filteredSubject, grepFilteredToEmptyNotice, filtersFilteredToEmptyNotice
src/fold_delivery.ts Specialized Subsystems Turning a delivered slice of a source file into a folded one: pick the spans, render the notices BODY_FOLD_KEEP_LINES, BODY_FOLD_MIN_SPAN, COMMENT_FOLD_KEEP_LINES, COMMENT_FOLD_MIN_BLOCK, bodyFoldNotice
src/fold_structure.ts Specialized Subsystems Turning a whole-file delivery into a structural view of it: a heading tree for a document, a declaration skeleton for OUTLINE_MIN_BODY_BYTES, OUTLINE_MIN_HEADINGS, OUTLINE_MAX_REPLACEMENT_RATIO, OUTLINE_LEADIN_MAX_BYTES, SKELETON_MIN_BODY_BYTES
src/git_async.ts Specialized Subsystems The non-blocking git runner runGitAsync
src/git_hint.ts Specialized Subsystems Git facts the hooks read inside the hints.git_hint_max_ms budget: the branch from the HEAD file with no spawn, and a readBranchWithoutSpawn, GitFindings, gitFindings, findingsOfGitResult
src/git_porcelain.ts Specialized Subsystems Specialized Subsystems module: git_porcelain.ts PorcelainEntry, parsePorcelainZ, GIT_OPTIONS_WITH_VALUE, safeShlexSplit, skipEnvAssignments
src/graph_analysis.ts Specialized Subsystems Code graph analysis and query commands: similar, context-for, test-for, coverage-gaps, arch, blame, and ask SimilarOptions, runSimilar, ContextForOptions, runContextFor, TestForOptions
src/graph_commands.ts Specialized Subsystems CLI command handlers for code-graph commands isTestFile, CallersOptions, runCallers, CallChainOptions, runCallChain
src/graph_inspection.ts Specialized Subsystems Code graph inspection commands: dead, deps, types, and scope DeadOptions, runDead, DepsOptions, runDeps, TypesOptions
src/graph_traversal.ts Specialized Subsystems Core graph traversal, scope analysis, and cycle detection primitives DEFAULT_REF_QUERY_LIMIT, ALL_SYMBOLS_IN_FILE_LIMIT, UNBOUNDED_REF_LIMIT, enclosingSymbol, enclosingNamedScope
src/grep_scan.ts Specialized Subsystems Specialized Subsystems module: grep_scan.ts GrepScanLine, GrepScanHit, GrepScanResult, scanGrepText
src/handle_stat.ts Specialized Subsystems File identity taken through an open handle, so it can be compared against a descriptor's fstat statThroughHandle
src/harness_channels.ts Specialized Subsystems Which harnesses discard which hook event's response PROMPT_SUBMIT_CONTEXT_DROPPED, dropsPromptSubmitContext, PRE_COMPACT_CONTEXT_DROPPED, dropsPreCompactContext, STOP_CONTEXT_DROPPED
src/hint_stats.ts Specialized Subsystems Efficacy tracking + auto-suppression for token-goat's discretionary hint hooks (token-goat hint-stats) HINT_CATEGORIES, HintCategory, isHintCategory, extractPathCorrelator, classifyBashHint
src/hint_stats_read.ts Specialized Subsystems The read side of token-goat hint-stats, kept out of hint_stats.ts so the hook bundle, which loads that module for the getHintStatsSummary, getHintStatsTotals, getHintSpendTotals
src/hint_suggestion_guard.ts Specialized Subsystems Strip shell commands that a path broke out of, from hint and deny text on its way to the model stripUnsafeSuggestions, quotedArg, canQuoteArg, UNQUOTABLE, quotedArgs
src/hint_target.ts Specialized Subsystems Resolves the real name a deny or read hint's suggested command carries -- a heading, symbol, key or table the file HintSlice, HintTarget, HintTargetSource, HINT_PLACEHOLDERS, sliceForPath
src/hint_target_cache.ts Specialized Subsystems Specialized Subsystems module: hint_target_cache.ts HintTargetCandidate, getHintTargetCandidates, setHintTargetCandidates, clearHintTargetCache
src/hints.ts Specialized Subsystems Specialized Subsystems module: hints.ts HintItem, HINT_PRIORITY_MEDIUM, buildPackageManifestHint
src/hook_adapters.ts Specialized Subsystems What each harness's hook shim decides around a token-goat hook call, in TypeScript, for the resident hook server's ADAPTER_HARNESSES, AdapterHarness, isAdapterHarness, AdapterIo, AdapterRequest
src/hook_client.ts Specialized Subsystems Thin client for the resident hook server, and the entry of dist/token-goat-hook-client.mjs responseTimeoutFor, serverEnabled, callServer, relayViaServer, WARM_CLI_COMMANDS
src/hook_ipc.ts Specialized Subsystems Wire protocol shared by the resident hook server and its thin client PROTOCOL_VERSION, SERVER_SLOTS, MAX_FRAME_BYTES, HARNESS_PROTOCOL_VERSION, HarnessHookRequest
src/hook_latency.ts Specialized Subsystems Read/render side of Batch S's hook wall-clock timing: token-goat stats --hooks and doctor's Hook latency check both formatAgeSeconds, HookLatencyRow, hookLatencyBreakdown, renderHookLatencyStats, NativeHookCounts
src/hook_lib.ts Specialized Subsystems In-process hook library entry point relayInProcess
src/hook_server.ts Specialized Subsystems Resident hook server: one long-lived process that answers hook calls and read-only CLI calls from an already-loaded runHookServer
src/html_query.ts Specialized Subsystems HTML structure inspection, querying, and structural linting for token-goat HtmlNode, HtmlLintIssue, HtmlLintResult, HtmlOutlineSummary, HTML_VOID_TAGS
src/impact_order.ts Specialized Subsystems Orders impact-hop entries by hop distance, then puts cross-file callers ahead of same-file callers ImpactHopEntry, CompareImpactHopsOptions, compareImpactHops
src/import_export_extract.ts Specialized Subsystems Language-specific import and export extractors extractExportNames, extractImports, importsExtensionFor
src/import_graph.ts Specialized Subsystems The project's internal import graph, built once and shared by every command that needs it ImportGraph, buildImportGraph
src/index_freshness.ts Specialized Subsystems Whether the index's record of a file still matches what is on disk matchingFileEntry, indexMatchesDisk
src/index_health.ts Specialized Subsystems Shared "this project has zero indexed files" diagnosis, reused by doctor's Symbols check getProjectIndexCounts, getEmbeddingCoverage, getParserFreshness, isIndexEmptyForProject, suggestedIndexCommand
src/index_reclaim.ts Specialized Subsystems Index-space reclamation (token-goat reclaim-index) ReclaimResult, indexSizeBytes, comparableSizes, reclaimIndex, walCheckpointBusy
src/indexed_file_names.ts Specialized Subsystems The index's file list for a project, looked up by name IndexedFile, indexedFileList, indexedProjectFiles, filesNamed, indexedFilesNamed
src/indexed_roots.ts Specialized Subsystems Which projects were indexed on purpose: by token-goat index, or by the first index install queues recordIndexedRoot, isIndexedRoot
src/indexed_source.ts Specialized Subsystems Resolves the document a stored symbol line range actually addresses indexedSourceText, isVirtualIndexedPath, virtualIndexedScopeNote, NOTEBOOK_CELL_LINES_SUFFIX, formatSymbolLocation
src/injection_scan.ts Specialized Subsystems Lexical scan for prompt-injection attack patterns in untrusted fetched content scanForInjectionPatterns, UNTRUSTED_WEB_TAG, FenceSpan, fenceMarkerPattern, CONFUSABLE_ENTRIES
src/inline_grep_scan.ts Specialized Subsystems The lines of a file as ripgrep, run the way Claude Code runs it, would test a pattern against them, for the inlined Grep ripgrepLines, SCOPE_MAX_FILES, SCOPE_MAX_BYTES, SCOPE_MAX_LISTED, ScopeGitDeps
src/inline_symbol_answer.ts Specialized Subsystems Answers a single-file structural Grep with the one symbol it names, instead of a hint that names the command which would INLINE_SYMBOL_MAX_BYTES, NameReason, Staleness, InlineCandidate, InlineBody
src/install_index.ts Specialized Subsystems First index of the project install runs in INSTALL_INDEX_ENV, InstallIndexResult, queueInstallIndex, formatInstallIndexResult
src/jsonc_text.ts Specialized Subsystems JSONC (JSON with line and block comments and trailing commas) support shared by the MCP bridge writers and the JSON read jsonc, stripBom, parseJsonOrJsonc
src/known_roots.ts Specialized Subsystems Specialized Subsystems module: known_roots.ts isTooShallowToPrune, recordKnownRoot, sweepExpiredKnownRootMarkers, recordKnownRootThrottled
src/language_specs.ts Specialized Subsystems The one table of languages token-goat indexes LANGUAGE_SPECS, Language, TreeSitterLanguage, RegexLanguage, OwnResultLanguage
src/lazy_module.ts Specialized Subsystems Shared factory for the "lazily load an optional npm dependency" pattern used by every optional-dependency reader createLazyModuleLoader
src/line_diff.ts Specialized Subsystems Line-level comparison helpers shared by the Write pre-hook and its guards (hooks_write.ts, write_guards.ts) splitLines, lcsLength
src/line_matchers.ts Specialized Subsystems Linear-time matchers for header-like lines ATX_DOT_BREAK_RE, ATX_CLASS_BREAK_RE, AtxHeading, matchAtxHeading, matchTomlSectionName
src/line_regions.ts Specialized Subsystems Maps a requested line span onto the file regions that cover it LineRegion, resolveLineRegions
src/listing_size.ts Specialized Subsystems token-goat listing-size: price the skill and agent listings Claude Code puts in context ListingEntry, ListingSummary, ListingReport, splitListingContent, applyListingAttachment
src/manifest.ts Specialized Subsystems The compaction manifest: what this session touched, rendered for whoever reads it next MEM_EPOCH_TIMEOUT_MS, mergeManifestFiles, renderWebFetchRow, renderWebFetchRows, manifestPrintedPaths
src/manifest_fit.ts Specialized Subsystems Fits an ordered list of manifest sections to a character budget by dropping whole rows, never by cutting text FitSection, FitResult, fitSections
src/manifest_sweep.ts Specialized Subsystems Specialized Subsystems module: manifest_sweep.ts ManifestSweepQuery, ManifestSweepOptions, ManifestSweepDependency, ManifestSweepCoordinate, ManifestSweepLockfile
src/markdown_frontmatter.ts Specialized Subsystems Index of the first line after a leading front-matter block, or 0 when the document has none frontMatterEndIndex
src/markdown_lines.ts Specialized Subsystems Specialized Subsystems module: markdown_lines.ts eachUnfencedLine
src/mcp_client_text.ts Specialized Subsystems Token-goat's own notes worded for whichever client asked answeringMcpToolCall, mcpToolListed, forClient, mcpFriendlyText
src/mcp_compress.ts Specialized Subsystems Deterministic, structural compression for MCP tool results MCP_COMPRESS_MIN_BYTES, compressMcpResult
src/mcp_compress_packs.ts Specialized Subsystems Specialized Subsystems module: mcp_compress_packs.ts compressGithubMcpResult, compressAtlassianMcpResult, BROWSER_TOOL_RE, compressBrowserMcpResult, compressGWorkspaceMcpResult
src/mcp_jsonrpc.ts Specialized Subsystems A minimal Model Context Protocol server, in-house LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, JSONRPC_INVALID_REQUEST, JSONRPC_METHOD_NOT_FOUND, JSONRPC_INVALID_PARAMS
src/mcp_stdio.ts Specialized Subsystems The stdio transport for token-goat's MCP server -- newline-delimited JSON over the process's own stdin and stdout, which STDIO_MAX_BUFFER_BYTES, StdioServerTransport
src/mcp_tool_pattern.ts Specialized Subsystems The toolPattern every MCP tool name matches, shared by hooks_mcp.ts's registerHook calls and cli_doctor.ts's MCP_TOOL_PATTERN
src/memory_prune.ts Specialized Subsystems Automatic pruning and analysis of Claude Code's native auto-memory store IndexEntry, parseIndex, PruneResult, pruneIndex, DupCluster
src/model_download_gate.ts Specialized Subsystems Remembers a download that could not reach its host, so the next caller waits it out instead of repeating it MODEL_DOWNLOAD_HOST, RUNTIME_DOWNLOAD_HOST, DownloadFailure, DownloadCooldown, DownloadFailedError
src/modules.ts Specialized Subsystems Module detection over the project's internal import graph WEAK_MODULARITY, DetectedModule, CrossModuleImport, ModuleResult, detectModules
src/native_hook.ts Specialized Subsystems The native hook client (native/tg-hook) as installers and doctor see it: where this install's binary is, whether an NativeHarness, HookShell, packagedNativeBinary, nativeCopyPath, syncNativeCopy
src/nested_worktrees.ts Specialized Subsystems Git linked worktrees that sit inside a project's own directory, and the SQL that keeps their rows out of that project's commonGitDir, nestedWorktreeRoots, ownProjectScope, nestedWorktreeExclusions
src/note_anchor.ts Specialized Subsystems Specialized Subsystems module: note_anchor.ts anchorStatus
src/notebook_compact.ts Specialized Subsystems Strip cell outputs from Jupyter notebooks to reduce token burn NB_STRIP_MIN_SAVINGS, NotebookCell, NotebookDict, stripNotebook, pruneSidecars
src/notes.ts Specialized Subsystems Architecture-notes storage layer WHOLE_FILE_NOTE_SYMBOL, NoteRow, SymbolMatch, resolveSymbolMatch, symbolNamesInFile
src/ocr_hashes.ts Specialized Subsystems Specialized Subsystems module: ocr_hashes.ts OcrLangSpec, ocrLangPath, OCR_LANG_HASHES, SUPPORTED_OCR_LANGS, getOcrLangSpec
src/ocr_languages.ts Specialized Subsystems Supported language codes and resolver for Tesseract OCR DEFAULT_OCR_LANG, SUPPORTED_OCR_LANG_CODES, SupportedOcrLang, isSupportedOcrLang, resolveOcrLangs
src/ooxml_extract.ts Specialized Subsystems Shared ZIP+XML core for OOXML formats (.pptx, .docx are both a ZIP container of XML parts) MAX_OOXML_WORK_MILLIS, OoxmlTookTooLongError, NotAnOfficeDocumentError, ooxmlWorkDeadline, assertOoxmlWithinDeadline
src/openapi_query.ts Specialized Subsystems Narrow structural summary + single-operation extraction for token-goat openapi-outline / openapi-op, so a parseOpenApiSpec, OpenApiOperation, extractOperations, formatOpenApiOutline, findOperation
src/option_intent.ts Specialized Subsystems Translation of a flag an agent guesses into the one token-goat has FlagRename, FLAG_RENAMES, LINE_RANGE_FLAGS, OptionRewrite, rewriteLineRangeFlag
src/overflow_guard.ts Specialized Subsystems Overflow guard — cap oversized output to protect the model's context estimateTokensFromLength, estimateTokens, sliceToEstimatedTokens, isCappedOutput, trimToBudget
src/own_lookup.ts Specialized Subsystems Own-property lookup for plain-object maps whose keys arrive from outside this process ownGet
src/path_containment.ts Specialized Subsystems Path canonicalization and the symlink-resolving containment test isCaseInsensitiveFs, foldPath, isNodeModulesPath, foldCase, foldCaseForContainment
src/path_miss.ts Specialized Subsystems The nudge after a tool call named a path that does not exist: when an existing path is plausibly the one meant missingPathsFromStderr, pathMissAfterFailure
src/path_suggest.ts Specialized Subsystems Existing paths a missing one was probably meant to be MAX_PATH_SUGGESTIONS, MAX_DIR_ENTRIES, suggestPaths
src/pending_context.ts Specialized Subsystems Deferred hint delivery, for harnesses that run a prompt-submit hook but discard its response MAX_PENDING_CONTEXT_BYTES, queuePendingContext, replacePendingContextBlock, peekPendingContext, peekPendingContextWith
src/pinned_fetch.ts Specialized Subsystems Hashing, copying and downloading files pinned by digest and length setPinnedRetryDelayForTesting, sha256Of, copyFromSharedCache, downloadPinned
src/pinned_file.ts Specialized Subsystems Files held to a SHA-256 and byte length recorded in this repository PinnedFile, sha256Of, copyFromSharedCache, downloadPinned, publishToSharedCache
src/powershell_compat.ts Specialized Subsystems Adapts bash-style heredocs and inline Python scripts with complex quotes for reliable execution under PowerShell MAX_ENCODED_CHARS, base64Bytes, adaptHeredoc, adaptInlinePython, adaptPowerShellCommand
src/pptx_extract.ts Specialized Subsystems PowerPoint (.pptx) narrow-slice reader SlideOutlineEntry, inlineSlideMath, pptxOutline, pptxSlideText, pptxAllSlidesText
src/pr_slice.ts Specialized Subsystems Surgical GitHub PR reads via the gh CLI isGhAvailable, isGhAuthenticated, parseGithubRepoFromRemoteUrl, isSafeRepoSlug, isSafePrNumber
src/probe_marker.ts Specialized Subsystems The hook half of token-goat doctor --probe PROBE_NONCE_ENV, PROBE_EVENT_TAGS, probeDir, probeMarkerLine, applyProbeMarker
src/process_priority.ts Specialized Subsystems Scheduling priority for the processes that index DEFAULT_PRIORITY_NAME, resolveWorkerPriority, applyIndexingPriority, applyIndexingPriorityTo
src/process_tree.ts Specialized Subsystems Specialized Subsystems module: process_tree.ts KillResult, killProcessTree, OwnedChild, spawnOwned
src/process_util.ts Specialized Subsystems Process and OS execution utilities sleepSync, isWindows, noWindowCreationFlags, windowsCmdQuoteArg, quoteShellPath
src/purge.ts Specialized Subsystems uninstall --purge: delete everything token-goat has written to disk PurgeResult, directorySize, purgeRoots, purgeDataDirectories, formatBytes
src/query_limits.ts Specialized Subsystems Query bounds shared by modules that sit in one import cycle, kept in a leaf with no imports of its own so nothing can UNBOUNDED_QUERY_LIMIT, FIND_SCAN_LIMIT
src/query_notices.ts Specialized Subsystems The trailing notices the structured-query commands headElidedNotice, traversalLimitNotice
src/queue_waker.ts Specialized Subsystems Wakes the worker's between-cycle sleep as soon as a producer appends to the dirty queue, instead of leaving the edit to QueueWaker, noteOwnQueueWrite, createQueueWaker
src/recall_index.ts Specialized Subsystems Cross-cache full-text search index for token-goat recall RecallCacheType, RECALL_COMMAND, RecallHit, RECALL_DEFAULT_LIMIT, isRecallCacheType
src/reconcile_requests.ts Specialized Subsystems The worker's side of a reconcile request: a hook that knew files changed but could not learn which drainReconcileRequestsAsync
src/reconcile_stamp.ts Specialized Subsystems What session start remembers per project, in the reconcile_cursor table under the root, a NUL and a word SESSION_SWEEP_REUSE_MS, SLOW_LISTING_MEMORY_MS, writeSweepStamp, sweptRecently, markListingSlow
src/recovery_fix_policy.ts Specialized Subsystems What a recovery pair may store and replay (recovery_pairs.ts) FIX_TASK_VERBS, FixVerbClass, FIX_VERB_ALLOWLIST, RERUN_COMMAND, RERUN_PLACEHOLDER
src/recovery_pairs.ts Specialized Subsystems Failure-recovery pairs: remember what fixed a failed Bash command, and say so the next time it fails the same way RECOVERY_WINDOW, MAX_PAIRS, PAIR_TTL_MS, MAX_FIX_CHARS, OTHER_STEP
src/ref_blindness.ts Specialized Subsystems Honest answers for questions the reference index cannot answer REF_INDEXED_LANGUAGES, isRefIndexedLanguage, isRefIndexedFile, languageLabel, refBlindLanguageNotice
src/regex_guard.ts Specialized Subsystems Refusing a regular expression that can stall the process that runs it hasNestedQuantifier, PROBE_LENGTHS, PROBE_GROWTH_FACTOR, climbsBetweenRungs, probeAlphabets
src/resident_context.ts Specialized Subsystems Accounting for the context the harness injects and token-goat's hooks never see LARGE_TASK_LIST_BYTES, LARGE_SKILL_BODY_BYTES, SKILL_BODY_REPEAT_THRESHOLD, RESIDENT_TAIL_MAX_BYTES, AttachmentClassCost
src/resident_process.ts Specialized Subsystems Recognising, reading and ending token-goat's own resident background processes (the worker daemon and the hook servers) ResidentKind, PROCESS_QUERY_TIMEOUT_MS, residentKindOf, isTokenGoatResidentProcess, isResidentOfInstall
src/rewrite_permission.ts Specialized Subsystems Decides whether a PreToolUse input rewrite may ship, and whether it may carry Claude Code's `permissionDecision RewriteKind, RewriteVerdict, PermissionRule, PermissionSnapshot, SettingsDoc
src/screenshot.ts Specialized Subsystems Local screenshot capture for token-goat screenshot, so a page render can reach the model as a small shrunk image ScreenshotOptions, ScreenshotResult, resolveBrowserExecutablePath, isBlockedIpAddress, blockedAddressAmong
src/search/parallel_search.ts Specialized Subsystems Specialized Subsystems module: parallel_search.ts symbolPreview, executeParallelSearch
src/search/path_weight.ts Specialized Subsystems Specialized Subsystems module: path_weight.ts ARCHIVE_PATH_SEGMENTS, ARCHIVE_FILE_RE, DOCS_FILE_RE, DOCS_DIR_SEGMENT, pathPriorityWeight
src/search/rrf.ts Specialized Subsystems Specialized Subsystems module: rrf.ts DEFAULT_RRF_K, FUSION_GAP_LINES, FUSION_SPAN_CAP, fuseChannelHits
src/search/search_cli.ts Specialized Subsystems Specialized Subsystems module: search_cli.ts formatSearchText, NEAR_RETRY, NearRetryOutcome, searchWithNearRetry, runParallelSearch
src/search/symbol_fts.ts Specialized Subsystems Full-text symbol search split by kind, for the search command's symbol and heading channels SymbolKindFilter, searchSymbolsFtsByKind
src/secret_file_names.ts Specialized Subsystems File names whose contents are credentials isSecretFileName
src/secret_redact.ts Specialized Subsystems Specialized Subsystems module: secret_redact.ts RedactResult, countRedactionPlaceholders, CustomPatternProblem, compileCustomPatterns, hasPreciseSecret
src/served_extent.ts Specialized Subsystems The line extents a successful token-goat read or token-goat section call handed the model, so the session's ServedExtent, SectionReadEvidence, SectionReadReceipt, createSectionReadReceiptNonce, sectionReadReceiptSessionKey
src/served_lines.ts Specialized Subsystems Finding the stretches of a delivered file window that this session has already served NumberedRow, SERVED_RUN_COMPARISON_BUDGET, ServedBody, ServedRun, indexServedBody
src/sessions_dir.ts Specialized Subsystems Where per-session state blobs live on disk, and nothing else SESSIONS_SUBDIR, sessionsDir
src/sharepoint_resolve.ts Specialized Subsystems Best-effort resolution of a SharePoint/OneDrive sharing URL to a local synced file path, so token-goat can read a ParsedShareUrl, parseShareUrl, ResolveResult, resolveLocalPath
src/shell.ts Specialized Subsystems Specialized Subsystems module: shell.ts locateBashOnPath, resolveWindowsBash, wrappedShell, canRunWrappedShell, resolvePowerShell
src/shrink_temp_copies.ts Specialized Subsystems The shrunk image copies written to the OS temp dir for a host that can only point a Read at another path, and the age SHRINK_COPY_PREFIX, SHRINK_COPY_MAX_AGE_MS, sweepStaleShrinkCopies
src/sibling_copy.ts Specialized Subsystems Name checks behind the Write pre-hook's sibling-copy advice (hooks_write.ts): which existing file a new file's name says siblingCandidates, siblingCopyExcluded, siblingCopyMessage
src/skill_version_drift.ts Specialized Subsystems Session-scoped nudge for token-goat's own version drift recordSkillVersionSnapshot, checkSkillVersionDrift
src/skip_scope.ts Specialized Subsystems Which directory segments of an indexed file's path count when the path is tested against a skip-directory set withDeclaredSkipScopeRoot, hasSkipSegmentBelowRoot
src/snippet_window.ts Specialized Subsystems At most maxLen characters of text with the character at idx a third of the way in snippetAround
src/source_text.ts Specialized Subsystems The text a source file's symbol line numbers count: a leading byte order mark dropped, and a lone carriage return normalizeSourceText
src/spec_path.ts Specialized Subsystems expandSpecPath() and resolveSpecPath(): ~ and Windows shell mount paths in a typed file spec, shared by every expandSpecPath, resolveSpecPath
src/sql_path.ts Specialized Subsystems Specialized Subsystems module: sql_path.ts pathEqClause, pathSuffixClause, projectScopeClause, filePathSpellingsClause, fileRowByIndexKey
src/stdin_json.ts Specialized Subsystems Reading a JSON payload off stdin, with a timeout and a byte cap readStdinJson
src/stray_residents.ts Specialized Subsystems Ends the token-goat resident processes of this install that no pid file or reachable hook server names any more, and UPGRADE_RESIDENT_KINDS, RetireOptions, RetireReport, retireStrayResidents, describeRetirement
src/symbol_body_probe.ts Specialized Subsystems Doctor's oversized-stored-body check, hosted outside cli_doctor.ts OVERSIZED_BODY_PROBE_SQL, checkSymbolBodySize
src/symbol_scan.ts Specialized Subsystems Full-scope symbol scanning for the commands that filter symbol names client-side SymbolScanScope, SymbolHead, forEachSymbol, symbolsById, compareBinary
src/tool_error_census.ts Specialized Subsystems Per-tool and per-model tool-error census behind session-audit --tool-errors ToolErrorTally, UnknownErrorPrefix, ToolErrorCensus, ToolErrorAccumulator, UNKNOWN_PREFIX_LIMIT
src/tool_error_class.ts Specialized Subsystems Classifies a failed tool call as expected (a known failure shape with a named cause) or unknown (everything else) ToolErrorKind, ToolErrorFlags, ToolErrorClass, UNKNOWN_REASON, CONTENT_DELIVERED_REASON
src/tool_name_fold.ts Specialized Subsystems The one fold applied to a tool name before it is compared to another tool name foldToolName
src/transcript_extract.ts Specialized Subsystems Zero-dependency WebVTT/SRT transcript reader TranscriptCue, parseTranscript, readTranscript, formatTimestamp, TranscriptOutlineEntry
src/ts_compiler.ts Specialized Subsystems The typescript compiler API behind ts_refs.ts (the type-resolved refs tier) and dep_docs.ts (the .d.ts outline) loadTs, isAvailable, loadError, setTsModuleForTesting
src/ts_refs.ts Specialized Subsystems Type-resolved reference disambiguation for TypeScript, using the TypeScript compiler API isTsPath, ResolveTypedRefsInput, resolveTypedRefs, resolveTypedRefsBatch, TypedRefsSession
src/unbounded_walk.ts Specialized Subsystems Refuses a shell command that walks a whole filesystem root or the home directory with no depth bound, or that starts the WalkContext, WalkRefusal, detectUnboundedWalk
src/untrusted_fence.ts Specialized Subsystems The single decision point for "should this text be fenced, and under what notice" injectionFencingEnabled, fenceUntrusted, fenceUntrustedSpans, fenceWithMatches, scanAndRecord
src/url_policy.ts Specialized Subsystems Shared allow/deny matching for URL policy (webfetch.allow / webfetch.deny) wildcardToRegExp, matchesAllowPattern, matchesDenyPattern, UrlPolicy, urlPolicyDenialReason
src/verification_commands.ts Specialized Subsystems Checks beyond the test, lint, typecheck and build runners that verification_state.ts recognises by name isScriptCheckSegment, isDocumentOnlyScriptCheckSegment
src/verification_state.ts Specialized Subsystems What the session has verified isVerificationCommand, exitStatusIsCheckVerdict, noteVerificationRun, noteFailedVerificationRun, VerificationState
src/video_chapters.ts Specialized Subsystems Reads embedded chapter markers and subtitle-stream metadata out of a video file via ffprobe, so an agent can see a VideoChapter, VideoSubtitleStream, VideoChaptersResult, extractVideoChapters
src/vscode_duplicate.ts Specialized Subsystems Duplicate-invocation suppression for VS Code agent hooks VSCODE_HOOKS_DIR_ENV, COPILOT_HOOKS_DIR_ENV, shouldSuppressDuplicateVscodeHook
src/vscode_path_gate.ts Specialized Subsystems Which paths a pre_tool_use handler may open isUncOrDevicePath, vscodePathAllowed, preToolPathDeclined, commandPathIsTouchable
src/vscode_savings.ts Specialized Subsystems Specialized Subsystems module: vscode_savings.ts StatsDay, StatsJson, SavingsBarContent, parseStatsJson, formatSavingsBar
src/walk_index.ts Specialized Subsystems Non-git walk-index fallback policy (token-goat index --walk) assertWalkableRoot, MAX_FILES_SCANNED_FORCED, collectWalkIndexFiles
src/walk_mode.ts Specialized Subsystems Git-vs-non-git detection for the indexer's walk mode detectWalkMode
src/waste.ts Specialized Subsystems Session spend-ledger: parses a Claude Code session transcript (JSONL) and attributes token cost per tool call, per tool findLatestTranscript, ParsedToolCall, ParsedTranscript, safeStringify, extractResultText
src/web_extract.ts Specialized Subsystems HTML -> clean text extraction for fetched web content, so a WebFetch body never lands in context as raw markup looksLikeHtml, extractCleanText
src/windows_powershell.ts Specialized Subsystems How token-goat starts Windows PowerShell to ask about processes: one place for the executable and its arguments, shared windowsPowerShellPath, powerShellTextQueryArgs
src/windows_system32.ts Specialized Subsystems Where a Windows system executable lives, from SystemRoot, then windir, then the literal C:\Windows: only an absolute windowsSystem32Exe
src/worker_lifecycle.ts Specialized Subsystems Finding, starting and stopping the background worker daemon: its pid and stamp files, the drain heartbeat that proves it WorkerOptions, resolvePollIntervalMs, WORKER_STARTUP_GRACE_MS, drainHeartbeatPathFor, writeDrainHeartbeat
src/write_guard_hooks.ts Specialized Subsystems The checks behind the Write/Edit pre-hook's partial-view guard and sibling-copy advice, with the session and config placeholderGuard, blindDropGuard, siblingCopyGuard, preWriteContentGuard, preEditPlaceholderGuard
src/write_guards.ts Specialized Subsystems Pure checks behind the Write/Edit pre-hook's partial-view guard (hooks_write.ts): a placeholder standing in for content findNewElisionLine, patchAddedLines, MAX_DIFF_SPAN, removedLineIndexes, unseenRemovedRuns
src/write_target.ts Specialized Subsystems What a Write/Edit pre-hook can learn about the file it targets without touching the session: the diff caps and a bounded MAX_LINES_FOR_DIFF, MAX_OLD_FILE_BYTES_FOR_DIFF, OnDisk, inspectFile, readKnownText
src/xlsx_extract.ts Specialized Subsystems Excel (.xlsx) narrow-slice reader XlsxScanTooLargeError, SheetInfo, listSheets, headSheet, allSheetsHeadText
src/xlsx_reader.ts Specialized Subsystems Minimal in-house SpreadsheetML (.xlsx) reader ExcelCell, ExcelRow, ExcelWorksheet, ExcelWorkbook, refToColumn
src/zip_bounds.ts Specialized Subsystems Shared decompression bounds for zip-format archives MAX_ZIP_INPUT_BYTES, MAX_ZIP_OUTPUT_BYTES, ZipStreamModule, ZipOutputTooLargeError, ZipInputTooLargeError
src/copilot_host_config.ts Uncategorized Uncategorized module: copilot_host_config.ts skillDirectories, disabledMcpServers, CopilotMcpSettings, mcpSettings, disableBuiltinMcps

Storage Layout

Windows: %LOCALAPPDATA%\dfk-helper\token-goat\ macOS: ~/Library/Application Support/token-goat/ Linux / WSL: $XDG_DATA_HOME/token-goat/ (or ~/.local/share/token-goat/ when XDG is unset)

Logic lives in src/constants.ts::defaultDataDir.

SQLite: global.db

All index data and stats live in a single global.db. src/db.ts opens, initializes, and caches connections. src/stats.ts applies its own schema extension on first open.

Table Schema source Purpose
files src/db.ts SCHEMA_SQL One row per indexed source file (path, sha, mtime, language, indexed_at)
symbols src/db.ts SCHEMA_SQL Extracted definitions (id, file_path, name, kind, line_start, line_end, body, docstring)
refs src/db.ts SCHEMA_SQL Call-site references (id, file_path, name, line, col, context)
chunks src/db.ts SCHEMA_SQL Semantic search chunk metadata (id, file_path, start_line, end_line, text, kind)
symbols_fts src/db.ts FTS_SQL FTS5 external-content virtual table mirroring symbols (name, body, docstring); INSERT/DELETE/UPDATE triggers keep it in sync
chunk_vectors src/db.ts initConnection vec0 virtual table (embedding float[384]); rowid matches chunks.id; created only when sqlite-vec is available
stats src/stats.ts GLOBAL_SCHEMA_SQL Cumulative token/byte savings (id, ts, kind, tokens_saved, bytes_saved, detail)

File-system layout

Path Contents
global.db Single index and stats SQLite database (tables above)
sessions/{session_id}.json Per-session state persisted across hook processes by src/session_store.ts (loaded/saved in src/relay.ts): file reads, edits, web-fetch index, bash-output index, curl downloads, shown hints
projects/{hash}/sessions/ Session manifest JSON files written by src/compact.ts for the PreCompact hook
projects/{hash}_memory.toml Project-scoped key-value memory written by src/project_memory.ts
queue/dirty.txt Append-only list of edited file paths; drained by worker.ts as soon as a producer appends (an fs.watch on queue/), with the 2 s poll as the fallback
queue/pending.txt Dirty-queue snapshot written by src/hooks_index.ts::preCompactIndexHandler before compact
images/ Shrunk image cache (LRU-evicted, written by src/image_shrink.ts)
skills/ Skill body/compact cache keyed by (session, name, content_sha) (src/skill_cache.ts)
bash_outputs/{id}.json Content-addressed bash stdout cache for cross-process bash-output <id> recall (src/bash_output_cache.ts via src/disk_cache.ts); pruned by age (24h) and count (200)
web_outputs/{id}.json Content-addressed web body cache for cross-process web-output <id> recall (src/web_cache.ts via src/disk_cache.ts); same prune policy
recovery_pairs/{projectHash}.json SHA-256 digests of the failed Bash commands (never their text) and the allowlisted fix that followed them as text, per project (50 pairs, 90 days), replayed once two sessions have learned the same fix (src/recovery_pairs.ts, allowlist in src/recovery_fix_policy.ts)
sessions/{session_id}.recovery-pending, sessions/{session_id}.path-miss Per-session sidecars next to the session state, written by src/recovery_pairs.ts (failures still waiting for a fix) and src/path_miss.ts (paths already answered this session); aged out with the rest of sessions/ by the worker's sweepCacheRoots (src/disk_cache.ts)

Project hash = crypto.createHash('sha1').update(canonicalRoot) from src/project.ts::projectHash.

Data Flow

(a) Initial indexing

token-goat index [path] calls requireTrackedFiles() (via git ls-files) to enumerate files, then calls indexFileSync(absPath, dbPath) for each. indexFileSync in src/parser.ts calls detectLanguage() then parseContent() (tree-sitter or regex extractor) then writeParseResult(), which runs a single transaction: DELETE existing rows for the file, then INSERT new files, symbols, and refs rows. Embeddings are written separately by embeddings.ts::upsertChunks().

(b) Incremental updates (background worker)

  1. Every Write or Edit tool event fires postEditHandler() in src/hooks_edit.ts, which appends the normalized absolute path to queue/dirty.txt via appendDirtyPath() in src/hooks_index.ts.
  2. The background worker (worker.ts::runWorkerLoop) drains queue/dirty.txt as soon as a producer appends (fs.watch on queue/, via createQueueWaker in src/queue_waker.ts), with the 2 second poll (DEFAULT_POLL_INTERVAL_MS = 2000) as the fallback.
  3. drainOnce() reads the queue and calls processDirtyBatch(), which SHA-fingerprints each file (fingerprintFile()), skips unchanged files, and calls makeIndexer(globalDbPath())(absPath, sha) which resolves to indexFileSync().
  4. The worker runs either as a Node.js Worker thread (in-process, started by startWorker()) or as a detached child process with the --worker-daemon flag (worker_daemon.ts::startDaemon()).

(c) Hook intercept

Installed hook events call the generated shim (~/.claude/hooks/token-goat-shim.cjs), which first tries the in-process path — importing dist/token-goat-hook.mjs and calling relayInProcess() directly — and falls back to spawning token-goat hook <event> only if that is unavailable. That bundle is built with esbuild code splitting, so it is a small entry plus sibling dist/token-goat-chunk-*.mjs files; anything that copies the hook library must copy the chunks with it. Those chunks are shared with dist/token-goat.core.mjs, because one esbuild.build() call emits both entry points — building them separately gave each its own private copy of nearly every chunk and doubled what dist/ shipped (tests/guards/dist_chunks_deduped.test.ts). Splitting is what keeps the CLI surface, the MCP server and zod out of the bytes V8 parses on every hook — without it esbuild inlines a dynamically imported module into the entry, deferring its execution but not its parsing. Sharing chunks across the two entries does not undo that: a module the CLI reaches statically and the hook only dynamically still sits behind the hook's dynamic edge, and that same guard pins the hook's eager set. tests/guards/hook_bundle_excludes_cli.test.ts walks the esbuild metafile's static import graph and fails if the CLI becomes eagerly reachable again. relay.ts::relay() reads the JSON payload from stdin, calls hooks_cli.ts::normalizePayload() for tool-scoped events (translates Codex/Gemini tool name aliases to canonical names), dispatches via hook_registry.ts::runHook(), and serializes the result back to the harness wire format via hook_registry.ts::serializeOutput().

On Windows and Linux (x64 and arm64) the installed command is tg-hook --harness <h> --event <ev> --entry <bundle> [--script-dir <dir>] -- <the Node hook command>: the native client in native/tg-hook/ speaks hook server protocol v2 to the resident server (src/hook_server.ts, adapters in src/hook_adapters.ts) and prints its answer, and runs the wrapped Node command when nothing was dispatched. Before it runs that command it clears the inherit flag on every handle it holds (stop_handle_inheritance in native/tg-hook/src/sys.rs), not only its three standard ones: PowerShell, which runs Copilot CLI's hook commands on Windows, hands its child its own stdout as an extra inheritable handle, Node cannot clear a handle it does not know is there, and the hook server the shim starts would otherwise hold the harness's output pipe open until it idles out. The Node command alone has no such remedy, so on Windows under PowerShell without the native client the call that starts a server leaves that pipe held by it. src/native_hook.ts decides whether an install writes that form (hooks.native, TOKEN_GOAT_NATIVE_HOOKS, a binary for this platform that passes --selftest) and, on Windows, keeps the copy under <data dir>/native/<id>/ that the entries name so an upgrade can replace the packaged file. macOS gets the Node command alone, and so does Windows when the release carried no signed binary.

The shared Copilot CLI/VS Code shim treats sessionStart specially: it frames one complete JSON object without waiting for EOF, then runs the normal session_start handler under one absolute 10-second deadline, reserving the final second for cleanup. A payload already in the pipe when the deadline expires is still framed: expiry opens a SESSION_START_LATE_PAYLOAD_GRACE_MS (1000 ms) window in readSessionStartInput (src/bridges/copilot_session_start.ts) that data, end or error closes at once, because a Windows pipe read completes on a worker thread and can land many event-loop turns after the deadline timer. Only a start whose payload never arrives pays the whole grace, so it exits about 11 s after process start; startup_owner.rs caps a deadline at the same budget (startup_entry::budget_ms(), 10000 ms by default). The installed native wrapper routes Copilot CLI/VS Code startup aliases through native/tg-hook/src/startup_entry.rs before ordinary EOF buffering or resident-server dispatch. Windows framing and relay work run off the external parent thread, and the relay is itself atomically owned through the same strict Job primitive. Its deadline starts at native entry and reaches the shim as a trusted trailing argument; direct Node starts use the process time origin. Neither input nor cold child launch starts a fresh budget. POSIX wrappers inherit stdin directly into the existing detached-group shim with the original deadline. On Windows, the existing packaged tg-hook handles the private --session-start-owner-v1 mode in native/tg-hook/src/startup_owner.rs. native/tg-hook/src/startup_process.rs creates a private, non-inherited, kill-on-close Job Object with neither breakaway flag, and associates the canonical process at creation through PROC_THREAD_ATTRIBUTE_JOB_LIST. An explicit handle list inherits only canonical stdin/stdout/stderr, not the owner's job handle. The owner stays outside its job; owner death closes the sole job handle, killing owned descendants without traversing a possibly dead root PID. Success requires ActiveProcesses == 0, root exit and bounded pipe drainage before a versioned capability acknowledgement can release the candidate. The internal argv deliberately has no -- separator, so older native binaries cannot execute it as an ordinary fallback; an isolated built legacy variant exercises the actual owner argv and a separator negative control. Missing/incompatible owners and association failures fail open with diagnostics, never unowned canonical execution. The ordinary native adopt_child path remains unchanged so background resident services still outlive other hook calls.

POSIX retains the detached process-group supervisor and waits for output-pipe closure after group termination. Both paths disable resident-server dispatch only for bounded startup work. The canonical handler still reconciles drift into the dirty queue, preserving the existing worker/indexer contract, and returns reminder, saved notes, capsule and receipt context. Invalid input, a stalled helper, or unverified cleanup produces one {} response with a stderr diagnostic; other events retain their existing input and dispatch paths. Windows startup input and canonical streams are capped at 1 MiB. Runtime behavior on POSIX must be validated separately from Windows kernel ownership tests.

A start that misses the deadline is deferred, not lost, on Copilot CLI and VS Code (SESSION_START_MAY_BE_DEFERRED in src/harness_channels.ts). The shim resets the owed state first at each start: resetSessionStartOwedFiles deletes <session>.session-start-owed (the claim) and rewrites <session>.session-start (the settle file) as a begun stamp under ~/.token-goat/sessions. sessionStartHandler stamps it begun first and replaces it with the settle marker as its last step, so a settled marker on disk means the helper reached its end. On the first post_tool_use of the session, deliverOwedSessionStart in src/hooks_session.ts reads the marker. A begun stamp that never settled, or a marker written inside the final second before the deadline or after it, means the start is owed; no file at all means no start began and nothing is owed. It then claims the start by creating .session-start-owed with the wx flag, so of two concurrent first calls one delivers. The winner builds the session-start output without post-compact recovery, queues it as pending context for the existing peek, and records the session_start_deferred stat that doctor reports as "Deferred session starts". If building throws, releaseOwedSessionStart deletes the claim so a later hook process retries. A subagent call is skipped, and any other failure is swallowed so the tool call is never blocked. A host with no session-start hook installed has no file, so nothing is delivered.

For Windows bounded startup, worker_lifecycle.ts::ensureWorkerAlive defers daemon activation with an exact internal stderr marker rather than spawning inside a strict job. The canonical owner strips that marker and includes only a boolean wake request in its verified acknowledgement. A nested shim relays the request to the installed outermost owner; a direct top-level shim launches it itself. Only after canonical-tree cleanup does that parent launch the trusted installed bundle as the existing --worker-daemon, with no bootstrap process. The daemon claims its own slot through the existing atomic PID-file lifecycle before starting the production drain loop. Native activation inherits no handles, so a live worker cannot retain the client's pipes. Source queueing and drift context remain unchanged, and the wake request never supplies a program, path or shell command.

Registered handlers by event:

  • PreToolUse / Read — preReadHandler (session hint, diff-on-reread, large-file gate, surgical hint), preReadImageHandler (image shrink)
  • PreToolUse / Bash — preBashHandler (cat detection, bash output dedup, compression)
  • PreToolUse / WebFetch — preFetchHandler (image shrink for web content; on a repeat fetch of a URL already retrieved this session, a non-blocking recall hint pointing at token-goat web-output <id>)
  • PreToolUse / Skill — preSkillHandler (skill cache dedup)
  • PostToolUse / Read — postReadHandler (snapshot, session record)
  • PostToolUse / Edit, Write — postEditHandler (dirty queue append)
  • PostToolUse / Bash — postBashHandler (cache stdout/stderr)
  • PostToolUse / WebFetch — postFetchHandler (web-output cache)
  • PostToolUse / Skill — postSkillHandler (capture skill body to disk)
  • PreCompact — preCompactHandler (build session manifest), preCompactIndexHandler (flush dirty queue)

(d) CLI surgical reads

Commands such as symbol, read, section, skeleton, outline, refs, and semantic query global.db via index_reader.ts (querySymbols(), queryRefs(), searchSymbolsFts()) or section_reader.ts (readSection()). Every path argument passes through resolveIndexPath() before the DB query so the lookup key matches the write key byte-for-byte.

Key Design Decisions

Absolute-normalized index key (resolveIndexPath) — Every symbol and file row is keyed by normalizePath(path.resolve(base, file)) at write time. Every reader (skeleton, outline, read, refs, imports, changed) routes the user-supplied path through the same resolveIndexPath() helper in src/paths.ts before querying. Without this, a relative path (src/worker.ts), a backslash path (src\worker.ts), or a WSL mount path all produce a key that never matches an absolute forward-slashed lowercase-drive key and the query silently returns nothing. Routing every query site through this one helper guarantees the lookup key matches the write key byte-for-byte across platforms. A typed file spec reaches it through resolveSpecPath() in src/spec_path.ts, which first expands ~ and, on Windows, a Git Bash /c/ path; the disk side (resolveAgainstProjectRoot) and the MCP confinement gate apply the same expandSpecPath(). Hooks call resolveIndexPath() directly, since only the hook knows whether a ~ was quoted.

Real-default-path wiring in the worker — processDirtyBatch in src/worker.ts defaults the indexer to makeIndexer(globalDbPath()), which calls the real indexFileSync from parser.ts. A previous release shipped with the worker calling a stub callback, which meant nothing was ever written to the symbols table and the parser was tree-shaken out of the built bundle — yet the test suite was green because every worker test injected its own callback. See AGENTS.md for the full injected-seam trap analysis. Any change touching the worker or indexer must include an end-to-end test on the real default path (drain → index → symbols populated → a known symbol resolves) plus a smoke test against the built bundle.

FTS5 query must name the virtual table directly — searchSymbolsFts() in src/index_reader.ts references symbols_fts directly in the FROM clause and in MATCH/bm25(). An alias (e.g. FROM symbols_fts f … WHERE f MATCH ?) resolves as a bare column reference, raises no such column: f, and the catch block silently returns empty results — which is indistinguishable from a search miss. The correct form is … FROM symbols_fts JOIN symbols s ON s.id = symbols_fts.rowid WHERE symbols_fts MATCH ? ORDER BY bm25(symbols_fts) LIMIT ?.

Refs via enclosing-scope resolution — extractRefs() in src/parser.ts tracks the enclosing function/method/class during the tree walk and stores it in refs.context, enabling refs --callers to group usages by the containing symbol.

Two-tier testing model — A fast pre-commit guard tier (npm run test:guards, ~2 s, no bundle, no DB, no git fixtures) lives in tests/guards/. The pre-push/CI tier runs the full suite plus the built-bundle command matrix (tests/command_matrix_e2e.*.test.ts), which indexes a real fixture against dist/token-goat.mjs and runs every registered command. Both tiers derive their command set from tests/registry.ts::allCommandNames(), so a newly registered command is automatically in scope for both — there is no second list to maintain. A registered command with no matrix case fails the coverage gate by design. See AGENTS.md for the full two-tier description.

Fail-soft hook handlers — Every handler wrapped by hooks_cli.ts::failSoft() catches any exception, logs to stderr, and returns { continue: true }. A broken token-goat must never interrupt the agent's work.

Session persistence (cross-process) — The installer wires each hook to the generated shim, so every tool call still starts a fresh process — the shim's in-process fast path avoids a second spawn, not the first, and there is no long-lived server. The session state in src/session.ts (file-read/edit tracking, shown-hint dedup, and the web/bash/curl recall indexes) and the bash/web content caches are therefore meaningless if kept only in memory: the maps die when the hook process exits. Three on-disk layers under tokenGoatHome() (TOKEN_GOAT_HOME, else ~/.token-goat, mirroring src/snapshots.ts) restore the behavior the Python original's SessionCache JSON provided:

  • Session state — src/relay.ts calls loadSessionState(sessionId) immediately after building the event and saveSessionState(sessionId) after the handler returns, each in its own try/catch so a persistence failure can never suppress the handler's real output. Save is merge-on-save: it re-reads the on-disk JSON and unions it with the in-memory state (set-union for hints, field-wise for files keeping every read/edit/truncation signal, newest-wins for the indexes), then atomic-writes. Combined with the atomic rename, two overlapping same-session hook processes (e.g. background-task hooks) can at worst drop a hint — never corrupt the file. File entries are capped at 500 (oldest by last-read evicted). An empty sessionId skips persistence entirely (no shared anon file bleeding across sessions).
  • Bash/web content — storeBashOutput() / storeWebOutput() also write a content-addressed blob (bash_outputs/<id>.json, web_outputs/<id>.json) via src/disk_cache.ts; getBashOutput() / getWebOutput() fall back to a disk read on an in-memory miss, so the session-less CLI (token-goat bash-output <id>, web-output <id>) and a later hook process resolve a value cached by an earlier one. Blobs are pruned by age (24h) and count (200) on each write.
  • Honest recall hints — the three bash recall sites in src/hooks_bash.ts (monitoring, curl GET, build) guard on the content entry existing, not just the session index, so a pruned/evicted blob never yields a bash-output <id> hint that would error. preFetchHandler in src/hooks_fetch.ts mirrors this for WebFetch: it resolves the URL via the persisted session index (getWebFetchCacheId()) and guards on the cached body (getWebOutput()) before emitting a web-output <id> recall hint, so the WebFetch cache is recalled in-band instead of silently re-fetched.

All three layers are fail-soft: a disk error never throws into a hook.

Compaction assist — Before Claude Code compacts, preCompactHandler() in src/hooks_compact.ts calls compact.ts::buildManifest() / buildManifestAdaptive() to build a structured, token-budgeted summary (edited files, files read, web fetches, skills) and returns it as systemMessage. The budget scales with session age and edit density via computeAdaptiveBudget(). Configurable via config.toml ([compact_assist]) or TOKEN_GOAT_COMPACT_ASSIST=0.

Skill preservation — postSkillHandler() in src/hooks_skill.ts captures every loaded skill body to skills/ keyed by (session, name, content_sha), enabling token-goat skill-body <name> recall after compaction without re-invoking the skill. preSkillHandler() reads the same store via hasSessionOutput(): if a body for the skill was already cached this session, the re-load is denied with a skill-body <name> --compact recall hint rather than re-injecting the whole body.

Codex/Gemini compatibility — hooks_cli.ts::normalizePayload() maps Codex tool-name aliases (shell to Bash) and Gemini aliases (read_file to Read, write_file to Write, and others) to canonical names before dispatching, using CODEX_TOOL_NAME_MAP and GEMINI_TOOL_NAME_MAP. The same registerHook('pre_tool_use', handler, { toolName: 'Bash' }) registrations fire identically across harnesses.

Bash output compression framework — Build/test/tooling commands emit far more output than the agent needs (progress bars, ANSI, repeated lines, passing-test noise). The framework in src/tool_filters/ compresses that output structurally, per tool, before it reaches the model. The pre-bash hook recognizes a command, rewrites it to run through token-goat compress -f <name> -c '<orig>', and the wrapped subprocess captures stdout/stderr, applies the matching filter, and re-emits a compressed view with a one-line savings marker. Layers:

  • helpers.ts — the shared, dependency-free helper layer every filter builds on: normalisation (normalise = CRLF→LF + ANSI strip + progress-line collapse), safeDecode/sanitizeControlChars, run-collapsing (dedupeConsecutive, dedupeNumericRuns with a high-entropy bypass so UUID/hash/JWT lines are never merged), error-preserving truncation (truncateMiddleSmart), byte/token caps (capBytes, capTokens), and command parsing (shlexSplit, stripPrefixes resolving sudo/env/python -m/uv run/npx-style launchers). Family factories and bespoke filters compose these rather than re-implementing them — the DRY foundation that keeps the ported filters small.

  • base.ts — CompressedOutput (the result type: text + byte accounting + withMarker()) and the abstract ToolFilter with the universal 10-step apply() pipeline (sanitise → per-stream input cap → normalise → early-exit when normalisation alone suffices → structural compress() → line cap → byte cap → notes prepend). Subclasses declare binaries/subcommands and override compressBody; errorPassthrough short-circuits to raw combined output on a non-zero exit with stderr; a postNormalise hook lets the git family strip CRLF warnings without per-family checks in apply.

  • generic.ts — GenericFilter, the catch-all the hook selects when it wraps a command no per-tool filter matches: ANSI/progress strip + consecutive-line dedupe, capped at ~2000 tokens.

  • families.ts — filter family factories: shared compression skeletons that several per-tool filters configure instead of reimplementing. makeNodeTestRunnerFilter(cfg) powers the Node test-runner batch. makePackageManagerFilter(cfg) is the package-manager factory — a single line-walk loop (keep if ERROR_SIGNAL_RE, keep if keepRe matches, drop by ordered DropRule array, emit per-rule collapsed notes) used by BundlerFilter and PubFilter; filters with richer structural logic (npm/pip/uv/conda/gem/composer/nuget/conan/vcpkg) subclass ToolFilter directly. Both factories are concurrency-safe (all state is per-call with no shared mutable fields).

  • test_runners.ts (batch A) — jestFilter (also covers mocha/ava/tap) and vitestFilter, both built from makeNodeTestRunnerFilter, exported as TEST_RUNNER_FILTERS and spread into TOOL_FILTERS at the head. Faithful ports of the Python JestFilter/VitestFilter; golden tests in tests/tool_filters_test_runners.test.ts assert the ported behavior, and tests/bash_compress_rewrite.test.ts has a built-bundle e2e proving npx vitest run rewrites to compress -f vitest (the registration survives esbuild and detectFromCommand prefers the specific filter over generic).

  • pytest.ts (batch A) — PytestFilter, bespoke (too structured for the Node family): strips pytest-xdist [gwN] prefixes, collapses pytest-cov tables to TOTAL, trims slowest N durations to five, dedupes the warnings summary, drops banner/preamble/test session starts lines, and collapses PASSED (default + verbose) to a count while keeping FAILURES/ERRORS + the final tally verbatim. Matches pytest/py.test (and python -m pytest / uv run pytest via stripPrefixes).

  • go_test.ts (batch A) — GoTestFilter, bespoke: collapses --- PASS:/=== RUN to counts, drops go: downloading, counts --- SKIP: separately, passes go test -json through untouched, and keeps WARNING: DATA RACE blocks verbatim with goroutine stacks collapsed to five frames. Overrides matches to fire only when test is the first positional (so go build/go run fall through), and is registered ahead of any future go build filter.

  • package_managers.ts (batch B) — 15 filters for the full package-manager landscape, faithful port of the Python bash_compress.py filter family: NpmInstallFilter (npm/yarn/pnpm install paths with per-manager sub-pipelines), PnpmFilter (richer install collapse + pnpm run <script>: label + exec/dlx passthrough), YarnFilter (classic v1 fetch-phase collapse + warning dedup; berry v2+ per-package progress collapse), PipFilter (download/cache-hit/build-wheel/metadata drop, Collecting cap at 5, progress-bar ━ drop), UvFilter (Download/Fetch drop, +/- diff drop, freeze/list truncation at 50 → show first 20), CondaFilter (install: download-section collapse + package-install lines collapse; list: truncate at 50; env export: dep truncation at 50), GemFilter (Fetching/doc-noise drop, Successfully installed collapse to head-2+count+tail-1 when >4), BundlerFilter (factory: Using-gem and Fetching/Installing-gem collapse), ComposerFilter (install/download collapse, %-progress drop, funding-notice drop, warning dedup), NuGetFilter (Installing/OK-https/already-installed/Successfully-installed collapse, 1-project vs N-project Restoring aggregate), PubFilter (factory: pkg-line and downloading collapse with PUB_KEEP_RE passthrough), ConanFilter (errorPassthrough + per-package lifecycle + download collapse via compressBody), VcpkgFilter (errorPassthrough + Building/Installing/sub-step/timing collapse via compressBody), NodePackageFilter (general npm/pnpm/yarn audit + spinner/progress + deprecated map), DepListFilter (errorPassthrough; matches pip/pip3/uv/poetry directly + npm/pnpm/yarn/cargo via custom PKG_MGR_STEMS check on list/freeze/tree/show/ls subcommands; truncates at 30 lines with a '<cmd>' to see full output hint). Golden tests in tests/tool_filters_package_managers.test.ts; e2e smoke in tests/bash_compress_rewrite.test.ts.

  • dispatch.ts — TOOL_FILTERS registry (ordered; specific filters precede the package-manager handlers they overlap; batch A test-runners at the head, batch B package managers next, batch C linters next, batch D vcs/git next, batch E build-tools next, batch F containers next, batch G cloud/IaC next, batch H CI/security-scanner filters last of the current batches), selectFilter/detectFromCommand (reject compounds, pipes, ;, command-substitution, and redirects — the wrapper only intercepts a single command), compressOutput with profiles (aggressive 50 / balanced 200 / minimal 500 lines; minimal skips progress collapse), and filterByName.

  • linters.ts (batch C) — 16 filters for the linter/type-checker/formatter landscape, split by ecosystem: linters.ts holds golangci-lint/phpstan/psalm/swiftlint/ktlint/cppcheck/clang-tidy and the LINTER_FILTERS registry, linters_js.ts tsc/eslint/oxlint/biome/prettier and the generic LinterFilter, which shares its ESLint-stanza compressor with ESLintFilter, and linters_python.ts ruff/mypy/pylint/black/isort. Faithful port of the Python bash_compress.py linter family. Dispatch order mirrors Python FILTERS registration: TscFilter (custom matches() covering bare/npx/yarn/pnpm tsc, three compression modes: typecheck dedup by TS error code, watch-cycle collapse, build up-to-date collapse), RuffFilter (check: per-code cross-file summary for codes with ≥3 occurrences in ≥2 files; format: reformatted/would-reformat sample), MypyFilter (error/note dedup by normalised message with quote/trailing-code stripping, standalone [error-code] drop, See-https drop), PylintFilter (module-header defer, E/F always-keep, C/W/R dedup by code at 3), OxlintFilter (per-file per-rule dedup with location-block suppression for elided issues), ESLintFilter (stanza-based: always keep errors; dedup warnings by rule within each file stanza), BiomeFilter (custom matches(); ≤40-line pass-through; rule-stanza collapse to first 3 with ≤2 source lines), generic LinterFilter (pyright/pylint via dedupeByKey; stylelint/rome via ESLint-stanza), GolangciLintFilter (per-file/linter dedup with placeholder-replacement for accurate extra counts; structured-log noise drop), PhpStanFilter (dispatches by stem: phpstan per-file row dedup; psalm progress drop + error-type dedup), swiftlintFilter (produced by makeLinterFilter factory; always-keep error/serious; warning dedup by rule with summary-last), BlackIsortFilter (black: reformatted/would-reformat sample at 5; isort: Fixing sample at 5), PrettierFilter (custom matches(); changed-file sample at 5; unchanged drop counted), KtlintFilter (plain-text error/warning dedup; checkstyle XML: rule dedup via <error source=), CppcheckFilter (Checking/progress/config drop with count notes), ClangTidyFilter (warnings-generated aggregate; include-chain drop; context-block keep-first). PylintFilter is registered BEFORE generic LinterFilter in LINTER_FILTERS so pylint always dispatches to the specific filter. Golden tests in tests/tool_filters_linters.test.ts; e2e smoke (eslint) in tests/bash_compress_rewrite.test.ts.

  • git.ts (batch D) — 7 filters for the VCS landscape, faithful port of the Python bash_compress.py git filter family. Specific-subcommand filters precede the generic catch-all so the most precise compression runs: GitLogFilter (log — format-aware: oneline cap at 50, patch collapse at 50 diff lines, stat collapse at 20 files, full-format collapse at 10 commits → one-liners), GitDiffFilter (diff/show — binary-file summary, large-hunk truncation, JSONL semantic summary for ≥75%-JSON hunks with ≤5 distinct key-sets, --stat dir rollup vs pathspec-truncation), GitStatusVerboseFilter (status — short/porcelain passthrough, verbose: advice strip + file listing grouped to counts by section), GitBlameFilter (blame — annotated and porcelain: same-commit runs collapsed to first-line + N more lines by marker), GitCommitFilter (commit/--amend/--fixup — lefthook banner collapse to single summary line on pass, error block preserved on fail), GitPushFilter (push — remote/local progress bundler keeping only 100% stages + non-progress informational lines, pytest-dot compression, upstream error preservation), GitFilter (generic catch-all for status/log/diff/ls-files/ls-tree/fetch/pull/push/clone via internal dispatch; fallback to dedupeCombinedOutput). All extend GitBaseFilter which overrides postNormalise to strip git CRLF warnings (modern single-line and legacy two-line pair). errorPassthrough = false for all — they handle errors structurally. Golden tests in tests/tool_filters_git.test.ts (95 cases); e2e smoke (git diff) in tests/bash_compress_rewrite.test.ts.

  • bash_runner.ts — the subprocess wrapper behind the token-goat compress CLI command (run/runRaw). It shell-runs the original command, captures stdout/stderr (32 MiB/stream cap), maps the exit code (124 on wrapper timeout, 128 + signum on signal kill, otherwise the child's own status), applies the resolved filter via compressOutput, prints the compressed view, records the savings stat, and re-exits with the wrapped command's code so cmd && next chaining is preserved. --no-compress streams raw for debugging; --max-tokens caps the body before the marker so the marker survives. The hook (pre_bash) is the only producer of wrapped commands; the command is also runnable by hand to preview compression.

  • build.ts (batch E) — 17 filters for the build-tool landscape, split by ecosystem: build.ts holds make/cmake/bazel/meson/cargo/go and the BUILD_FILTERS registry, build_jvm.ts gradle/maven/ant/sbt/javac, build_dotnet.ts msbuild/dotnet, and build_js.ts nx/lerna/turbo/webpack. Faithful port of the Python bash_compress.py build filter family: MakeFilter (matches make/gmake/ninja plus gradle/mvn/bazel/go binary stems; routes to per-stem handlers: go-specific download/error dispatch, configure probe-drop, cmake-style [N%] Building collapse, generic make[N] directory-marker drop), CmakeFilter (routes ctest subcommand to ctest-specific pass/fail compression; cmake: [N%] Building collapse with last-line note, -- Found package collapse), GradleFilter (case-insensitive subcommand matching including camelCase tasks like bootJar; Task progress drop, BUILD SUCCESSFUL/FAILED preserve, stack-trace cap at 10), MavenFilter (compress() override; error passthrough extracts [ERROR] lines + last 20; dispatches test/verify/package subcommands), AntFilter (run-length collapse per task type: echo/mkdir/copy/delete/move/chmod/touch/get), BazelFilter (INFO: From Compiling collapse with count note, PASSED test-target collapse), MesonFilter (errorPassthrough=true; keeps project-metadata via MESON_KEEP_RE; drops compiler detail/probe/Found-tool lines; collapses [N/M] Compiling, keeps [N/M] Linking), MSBuildFilter (warning dedup by code, Copy/MakeDir/task collapse, keeps first Build started), DotnetFilter (compress() override dispatching test/restore/build-publish-pack/format subcommands), SbtFilter (compress() override; collapses [info] loading noise and test dot-progress; limits [warn] to 5 per category), JavacFilter (collapses Note: *.java uses unchecked/unsafe groups; keeps error diagnostic blocks opened by file.java:N: error: pattern), CargoFilter (compress() override dispatching test/clippy/bench/build; build: collapses Compiling to [compiling N crates…] sentinel when ≥3; test: injects [N tests passed] after each running section), GoFilter (custom matches() excludes test subcommand so goTestFilter wins; dispatches get/mod-tidy/vet-like/build-like sub-handlers with download/progress collapse), NxFilter (matches nx or npx/pnpx nx; cache-hit check before task-header check; samples failed task headers on non-zero exit), LernaFilter (samples first 5 info run Ran npm script lines; drops verbose/notice), TurboFilter (tracks cacheHitTasks Set; drops body lines from cache-hit tasks), WebpackFilter (_invokesViteBuild() helper routes to vite or webpack path; vite: only matches with build subcommand). BUILD_FILTERS array (17 entries, cargo and go first for dispatch ordering). Golden tests in tests/tool_filters_build.test.ts (122 cases); e2e smoke (make, cargo) in tests/bash_compress_rewrite.test.ts.

  • containers.ts (batch F) — 5 filters for the container/kubernetes landscape, faithful port of the Python bash_compress.py container filter family. Dispatch order: KubectlLogsFilter must precede KubectlFilter (both match kubectl/k); DockerComposeFilter must precede DockerFilter (both match docker). DockerFilter (custom compress() override; reverses stdout/stderr merge order via combineOutput(stderr, stdout) because Docker writes progress to stderr; drops ---> Using cache/---> xxxxxxxx layer IDs, collapses Step N/M build steps via dedupeNumericRuns, head+tail cap at 60), DockerComposeFilter (custom matches() detects docker-compose binary OR docker compose two-word form; errorPassthrough=true; drops Network created/Volume created/Pulling/Pulled from/Pull complete/Digest:/Status: noise; dedupes service health-check wait lines; keep-first for Creating/Starting/Stopping/Removing lifecycle verbs), KubectlFilter (errorPassthrough=true; custom matches() on kubectl/k binaries; routes by first positional: get/describe/apply/delete/rollout → head+tail, events → _compressKubectlEvents, logs (non-logs-filter path) → head-30/tail-20, else generic truncation; tables: column-count collapse to first 3 rows + count note when ≥10 rows), KubectlLogsFilter (custom matches() requires kubectl/k binary + logs as first positional; errorPassthrough=true; only engages when nonEmpty.length > 50 — faithful to Python; applies in order: _collapseAccessLogs, _collapseStackTraces, _dedupLogLinesWithPodPrefix, _collapseJsonBlobs, head+tail cap at 200 lines), HelmFilter (errorPassthrough=true; custom matches() on helm/helmfile binaries; routes by first positional: install/upgrade → _compressHelmInstall (drops STATUS/LAST_DEPLOYED/CHART/APP_VERSION/NAMESPACE noise, keeps NOTES: block), list/ls → _compressHelmList (head+tail 20), template → _compressHelmTemplate (counts YAML docs, keeps first 3 + last 1), else head+tail 50). CONTAINER_FILTERS array (5 entries; kubectlLogsFilter first). Golden tests in tests/tool_filters_containers.test.ts (64 cases); e2e smoke (docker build) in tests/bash_compress_rewrite.test.ts.

  • cloud.ts (batch G) — 16 filters for the cloud/IaC landscape, faithful port of the Python bash_compress.py cloud filter family. The four cloud provider CLI filters (AwsCliFilter, AwsFilter, GcloudFilter, AzureCliFilter) live in cloud_providers.ts, and CLOUD_FILTERS in cloud.ts registers all 16 and sets their order. Dispatch order: AwsCliFilter must precede AwsFilter (both match aws/aws2; AwsCliFilter owns CFN/S3 routing; AwsFilter is the simpler JSON-array fallback). TerraformFilter (matches terraform/tofu/terragrunt; subcommand dispatch: plan — drops refresh/read lines, collapses (known after apply) attribute blocks, emits plan-summary first + last-20-line tail; apply — dedupes Still creating per-resource, keeps Creation complete + Apply complete!; init — head=5/tail=5 compression for provider installs; show/state — keeps key attributes only per resource block; validate/output passthrough; errorPassthrough=true), AwsCliFilter (json-array threshold 10/keep 3; s3 cp/sync/mv S3-transfer upload/download/progress collapse; cloudformation describe-stack-events CFN repeated IN_PROGRESS dedup via logical resource ID; generic JSON array fallback), AwsFilter (json-array threshold 20/keep 20; simple JSON-array or table truncation), GcloudFilter (spinner-char drop, Enabling service/Waiting for async operation collapse, structured-output collapse when >70% of lines are structured and >20 lines), AzureCliFilter (JSON-array threshold 10/keep 3; preview warning collapse; repeated provisioning progress-JSON collapse to last status), AnsibleFilter (compress() override — not compressBody — because ansible-playbook handles non-zero exits structurally; routes by binary: ansible-lint → rule-code grouping (keep first 3 per rule, elide rest); ansible-galaxy → head=5/tail=5; ansible-playbook — ok/changed/skipped lines collapsed per task section into [token-goat: N ok, M changed ...], failure blocks kept verbatim, PLAY RECAP always preserved), PulumiFilter (drops creating/updating/deleting in-progress lines and still heartbeat lines, keeps completion/summary/diagnostic), CdkFilter (drops asset build/upload progress, drops WORD_IN_PROGRESS table rows, keeps WORD_COMPLETE rows and failure/summary lines), VaultFilter (kv list/list collapses paths to first 5 + elision note when >10; lease/token metadata lines dropped; table dividers dropped), PackerFilter (SSH/WinRM connection-wait polls collapsed to count note; provisioner step announcements collapsed; build-step lifecycle lines kept), NixFilter (fetch/substitute lines collapsed to count note; building derivation lines collapsed to count note; flake lock update lines collapsed to count note; error/note/warning always kept), WranglerFilter (asset upload lines collapsed to count note; skip lines collapsed; bulk-operation progress collapsed; build-step noise dropped), HardhatFilter (Compiling N files lines collapsed; Solc timing lines collapsed; passing-test tick lines (✓) collapsed; tx receipt noise dropped; test summary always kept), ServerlessFilter (Packaging/Uploading/Validating/Updating step lines collapsed to count note; CF IN_PROGRESS rows dropped; polling dots dropped; Service Information/endpoint lines kept), FlyFilter (Docker build step lines + #N CACHED/DONE layer lines collapsed to count note; per-machine wait lines collapsed; DNS polling lines dropped; step headers + summary lines kept), ForgeFilter (Compiling/Solc-timing lines collapsed to count note; passing-test [PASS] lines collapsed; gas-report table separator rows dropped; test-suite header/summary always kept). CLOUD_FILTERS array (16 entries; awsCliFilter before awsFilter). Golden tests in tests/tool_filters_cloud.test.ts (117 cases); e2e smoke (terraform plan) in tests/bash_compress_rewrite.test.ts.

  • ci.ts (batch H) — 9 filters for the CI-runner and security-scanner landscape, faithful port of the Python bash_compress.py CI and security filter families. Dispatch order: GhRunLogFilter must precede GhFilter (both match gh; GhRunLogFilter is more specific — requires run view positionals AND --log flag); GenericCIFilter is last (keyword-only match, no binary gate). GhRunLogFilter (gh run view --log — strips step-name TAB column prefix and ISO-8601 timestamps; drops ##[command] echo lines unless they contain a failure signal; drops runner boilerplate/cleanup; collapses ##[group]...##[endgroup] blocks >20 lines with no failure; summarises setup-action Run lines), GhFilter (gh api/pr/run/issue — includes the python-gh-filter-ref enhancement: recursive strip of boilerplate *_url JSON fields from gh api responses, preserving html_url/avatar_url/clone_url/ssh_url and stripping noise keys gravatar_id/site_admin; compress() override dispatches on subcommand: run view → pass-step collapse, */list → 30-row cap, api → *_url strip + JSON pretty-print; redacts base64 content fields before dispatch), ActFilter (act binary — strips [job/step] | prefix from body lines, collapses Docker-pull progress, collapses matrix expansion, preserves ✅/❌ status lines verbatim), PreCommitFilter (pre-commit — collapses Passed/Skipped hook result lines into a count sentinel, keeps Failed blocks verbatim, keeps only the first [INFO] env-setup line and emits a dropped-count note for the rest), BanditFilter (bandit — per-file testing progress drop; HIGH/MEDIUM issue blocks kept verbatim, LOW blocks collapsed to count note; Code scanned:/Total issues stats block always kept), TrivyFilter (trivy — drops timestamped INFO/WARN/DEBUG log lines from stderr; parses table column positions dynamically to find SEVERITY/LIBRARY; keeps CRITICAL/HIGH rows, collapses MEDIUM/LOW to per-library count notes; always keeps Total: summary and no-vulnerability messages), SnykFilter (snyk — keeps first Testing line only; tree-lines >10 collapsed to count note; vulnerability block headers kept; More about this vulnerability: URL lines collapsed; summary line always kept; license lines always kept), SemgrepFilter (semgrep — per-rule instance cap of 3 via ruleCounts/ruleSuppressed maps; Details: and annotation URL lines dropped per block; scanning banner kept first-only; suppression notes injected before summary). CI_FILTERS array (9 entries; ghRunLogFilter first, genericCIFilter last). Golden tests in tests/tool_filters_ci.test.ts (123 cases); e2e smoke (gh run view --log) in tests/bash_compress_rewrite.test.ts.

  • shell_file.ts (batch J) — 20 filters for the shell/file-utility landscape, faithful port of the Python bash_compress.py shell/file filter family. Dispatch ordering inside SHELL_FILE_FILTERS: RgFilter precedes GrepFilter (RgFilter claims both rg and grep; GrepFilter is the simpler fallback for grep-only usage), LsFilter precedes EzaFilter (LsFilter claims ls/eza/exa; EzaFilter is reached only via exa). GrepFilter (matches grep/grep variants; head+tail 80; collapses same-file repeated-line runs to count note; errorPassthrough=true), RgFilter (matches rg + grep; context-line prefix stripping per -A/-B/-C depth; head+tail 80 cap; count aggregation from N matches summary lines), LsFilter (ls/eza/exa; collapses dot-files block to count note when total ≥30; drops extended-attribute lines @ / ACL lines +; long-format: permission-char block collapse; binary/symlink/dir totals note), EzaFilter (eza-specific: strips header/footer frame lines; icon/colour noise drop via ANSI strip; keeps only --long content rows), TreeFilter (tree; strips box-drawing chars to count note for sub-trees deeper than 2 levels; collapses homogeneous leaf blocks to N files note; always keeps first+last lines), FdFilter (fd/fdfind; head+tail 50; collapses same-extension runs to count note; errorPassthrough=true), WcFilter (wc; strips leading whitespace from each line; collapses multiple blank-separated file groups to normalized lines), BatFilter (bat/batcat; strips decorative border lines top and bottom; keeps syntax-highlighted body; head+tail 100), DeltaFilter (delta; strips commit header block; keeps hunk headers + body; head+tail 120 when large), FzfFilter (fzf; head+tail 30; strips ANSI from selection lines), LazyGitFilter (lazygit; head+tail 60; strips raw ANSI escape sequences), JqFilter (jq; head+tail 100; collapses deep-nested repeated keys to count note when >50 lines), YqFilter (yq; head+tail 100; collapses repeated scalar-list blocks when >150 lines), CurlFilter (curl/wget; drops download-progress lines %/#/- patterns; keeps headers on -v/-I; head+tail 60 for response body), RsyncFilter (rsync; drops xfr#N transfer-progress lines; keeps summary stats line; drops paths with '/' when >100 lines and keeps first 20 + count note), DiffFilter (diff; hunk scoring via _scoreAndCapHunks — each hunk gets a density score capped at MAX_HUNK_LINES; keeps top-N hunks by score; always keeps file ---/+++ headers), FfmpegFilter (ffmpeg; drops frame/fps/bitrate progress lines; collapses stream-info block to first 3 lines; keeps error/warning lines), BinaryInspectFilter (xxd/hexdump/od/hd; head+tail 30; keeps magic-byte line + offset annotation), FileTypeFilter (file; head+tail 40; collapses runs of same MIME type to count note), PsFilter (ps/top; parses column headers dynamically; keeps header row; sorts by CPU% descending; caps at 30 rows; collapses low-CPU processes to count note). SHELL_FILE_FILTERS array (20 entries). Golden tests in tests/tool_filters_shell_file.test.ts (137 cases); e2e smoke (rg) in tests/bash_compress_rewrite.test.ts.

  • languages.ts (batch K1) — 17 filters for language runtimes and compilers, faithful port of the Python bash_compress.py K1 family. All 17 have errorPassthrough = true (stderr preserved on failure). Twelve are implemented as classes/bespoke instances; five are produced by makeLanguageFilter (the new factory in families.ts). Dispatch ordering: bunFilter is registered before PACKAGE_MANAGER_FILTERS because NodePackageFilter also claims bun (first-match wins); swiftLintFilter is NOT re-declared here — it belongs to LINTER_FILTERS (batch C). NodeFilter (node -e/--eval/-p/--print; success → 500-token cap; failure → node_modules and node:internal frame collapse with user-code frames preserved). PythonFilter (python/python3/python3.1x; excludes python -m pytest; traceback: first-2+last-3 frames for >10-frame traces; _dedupeRepeatedLines on 5+ consecutive identical lines; _compressWarnings keyed on warning-class+message, capped at 3 per key). RubyFilter (ruby -e/-r; backtrace compression; gem-install progress drop). BunFilter (bun test/build/run/install; download-line collapse ↕/↑/↓ pkg@ver; test-suite result keep; error-section preserve). DenoFilter (deno run/test/compile/check; bundle/compile progress drop; error-chunk preserve). FlutterFilter (flutter build/run/test/pub; verbose framework-frame collapse; download-progress drop). DartFilter (dart run/test/compile/pub; stack-trace head+tail with omission marker). SwiftFilter (swift build/run/test/package; linker/linking-progress line collapse; compiler-warning dedup capped at 5). XcodeFilter (xcodebuild; per-phase line collapsing for CompileC/Ld/CpHeader/Copy lines; keeps error/warning lines). MixFilter (mix/elixir; compilation-warning dedup; test-suite summary keep; depencency-fetch drop). ZigFilter (zig build/run/test; note-line accumulation; error-chunk extraction). RCmdFilter (R/Rscript; message/warning dedup; Loading required package progress drop). Factory-built via makeLanguageFilter: erlangFilter (erl/escript/rebar3; crash-dump lines drop, error-chunk keep), crystalFilter (crystal; compile-error keep, progress drop), haskellFilter (ghc/stack/cabal; warning/note dedup, linking-progress collapse), elmFilter (elm; compile-error keep, dependency-fetch drop), juliaFilter (julia; precompile-progress drop, deprecation dedup — 7 ANSI-escape regexes guarded with no-control-regex disable comments), powerShellFilter (pwsh/powershell; error/warning dedup, progress-bar drop). LANGUAGE_FILTERS array (17 entries, no bunFilter — it is spread individually). Golden tests in tests/tool_filters_languages.test.ts (81 cases); e2e smoke (python) in tests/bash_compress_rewrite.test.ts.

  • misc.ts (batch K2 — completes the 158-filter port) — 19 filters for DB clients, runner tooling, CSS preprocessors, system package managers, and generic utility/catch-all filters, split by family: db_clients.ts holds the four DB clients, misc.ts the other 15 and the MISC_FILTERS registry; faithful port of the Python bash_compress.py K2 family. Dispatch ordering (critical): playwrightFilter and cypressFilter are NOT in MISC_FILTERS — they are registered individually in dispatch.ts BEFORE bunFilter because BunFilter.binaries includes bunx, and bunx playwright test/bunx cypress run must route to their bespoke filters, not the generic bun handler. The remaining 17 filters are in MISC_FILTERS spread after LANGUAGE_FILTERS, the four DB clients first. DB clients: PsqlFilter (psql — migration path: ≥3 CREATE TABLE lines → summarise counts; SELECT path: state machine detects border/header/data rows, collapses >20 rows to first 5), MySQLFilter (mysql/mysqldump — routed by binary name; query path: 4-phase table state machine; dump path: keep first 3 CREATE TABLE blocks), Sqlite3Filter (sqlite3 — schema passthrough when ≥50% non-empty lines are DDL; else collapse >20 data rows), RedisCLIFilter (redis-cli — SCAN output, bulk-OK collapse, long-list collapse). Build/runner tooling: SysPackageFilter (apt-get/apt/apt-cache/apk/brew — per-manager routing; apt: Get:N + Unpacking/Setting up + triggers collapse; apk: fetch/installing collapse; brew: first-3 progress lines sample), WmicFilter (wmic — collapses the fixed-width column padding of its table output to a two-space delimiter; /format:csv and /format:list pass through), ProtocFilter (protoc/buf — drop [libprotobuf INFO], keep WARNING; dedup repeated identical warning lines), SassFilter (sass/scss/lessc/node-sass — sample first 5 write lines; drop map-write lines; dedup deprecation warnings by 60-char prefix, keep first 2 per key), ToxFilter (tox; errorPassthrough=true — collapse env-create/pip-progress/req-satisfied/tox4-separator noise), NoxFilter (nox; errorPassthrough=true — collapse venv-create/reuse/pip noise), WasmPackFilter (wasm-pack; errorPassthrough=true — drop [INFO] and Cargo Compiling lines; WASMPACK_DONE_RE uses regex test() not match because done message appears INSIDE [INFO]: :-) Your wasm pkg...), NgFilter (ng; errorPassthrough=true — subcommand routing: test → drop Karma log noise; build/serve → webpack chunk runs + table head+tail; other → capBytes 8192), PlaywrightFilter (playwright/npx playwright/pnpx playwright/bunx playwright; custom matches(); concatenates stdout+stderr directly; drops ✓/✔ pass lines and download progress), CypressFilter (cypress/npx cypress/pnpx cypress/bunx cypress; custom matches(); 5-state machine suppresses Run Starting/Results/Video sections and separator lines). Generic/catch-all (ordered last in MISC_FILTERS): DotenvFilter (dotenv — collapse ≥2 banner lines to [dotenv] loaded N vars), EnvFilter (env/printenv — passthrough when ≤20 vars; else suppress low-priority vars), JsonArrayFilter (json stem, content-based; key-set dedup of objects unless high-entropy values; truncate to 50 items; detectFromCommand() returns false), SeverityLogFilter (no binary; matches() returns false; detect() fires when ≥5 lines and ≥30% have log-level keywords; _scoreLine: ERROR/CRITICAL=1.0, WARN=0.5, INFO=0.1, DEBUG=0.0; keeps WARN+ lines plus 2-line context window and stack-trace continuations), TailTruncFilter (no binary; matches() returns false — explicit opt-in only via filterByName('tail-trunc'); keeps first 50 + marker + last 50 when >500 lines; NOTE: Python model has matches()=True as a universal catch-all post-execution, but TS pre-hook rewrites commands before execution making a universal catch-all prohibitively expensive for trivial commands). MISC_FILTERS array (16 entries; PlaywrightFilter and CypressFilter excluded — registered before bunFilter in dispatch.ts; TailTruncFilter last). Golden tests in tests/tool_filters_misc.test.ts (108 cases); e2e smoke (psql + playwright) in tests/bash_compress_rewrite.test.ts.

  • Hook wiring (hooks_bash.ts) — preBashHandler makes the rewrite decision: for a recognized single command with no cached prior run it returns a rewriteInput HookOutput, which hook_registry.ts::serializeOutput emits as the PreToolUse wire shape {hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow",updatedInput}}. updatedInput replaces the entire tool_input, so the hook spreads {...event.toolInput, command: wrapped} to keep description/timeout. Filter selection runs on the cd-stripped command (detectFromCommand, falling back to the generic filter for commands no registered filter matches — per-tool filters land in batches, batches A through J now registered), but the wrapper quotes the full original command including any cd … && prefix so it still runs in the right cwd. A cached prior run wins over a fresh rewrite (recall is cheaper than re-running and re-compressing). Because the rewrite changes the command the post-hook then sees, postBashHandler (src/hooks_bash_post.ts) unwraps token-goat compress … -c <orig> back to <orig> before keying its output cache — so recall stays keyed on the original command and round-trips across runs. Compounds, pipes, and redirects are never wrapped (isCompressibleSingleCommand mirrors detectFromCommand's single-command rule). Honored opt-outs: TOKEN_GOAT_BASH_COMPRESS=0 and per-filter [bash_compress] disabled_filters.

Disable globally with TOKEN_GOAT_BASH_COMPRESS=0; that stops the rewrite only, and postBashHandler still caches the output for bash-output and recall. The framework is independent of the src/filters.ts line-level Filter/FILTERS (a separate, simpler post-read line filter) — this one is keyed ToolFilter/TOOL_FILTERS to avoid the name collision.

Agent-report envelope compaction never summarizes PROSE, and never will (hooks_agent_spawn.ts) — postAgentHandler only touches bytes inside fenced code blocks (collapseFencedBlocks elision, dedupeFencedBlocks cross-fence dedup, collapseBlankRunsInFences blank-run collapse); every non-fence line is byte-identical between input and output, enforced as an executable invariant in tests/hooks_agent_spawn.test.ts. LLM or extractive summarization of the PROSE portion of a subagent's report was explicitly proposed and rejected during design, for three reasons that are load-bearing, not stylistic preferences: (1) non-deterministic — a summarizer can silently drop or reword content differently each run, so the same report could compact two different ways with no way to predict which; (2) unverifiable — nothing downstream can prove a summary faithfully preserved what the original said, unlike a byte-identical passthrough or a mechanically reproducible elision (fenced content is regenerable from the repo, and the full original stays one mcp-output <id> --full away); (3) destroys the caveat signal the envelope exists to preserve — prose is exactly where a subagent writes "I did not verify X" or "not tested," and those sentences are what has caught a subagent shipping something it never checked, three cycles running in this repo's own history. A summarizer optimizing for length has no way to know which sentence is the load-bearing caveat and which is filler, so it is not a safe reduction, it is a coin flip on whether the one sentence that matters survives. If this gets re-proposed: the answer is still no, for the same three reasons, and the fenced-block-only design is what makes the "cite evidence, state unverified claims explicitly" report contract in the subagent briefing (buildSubagentBriefing) trustworthy in the first place — summarizing the prose that contract asks for would defeat the contract itself. Path-key naming in --json rows — A row's path key is filePath when the row carries an explicit type-signal field (kind, source). It is <type>File only when the path key is the row's sole type discriminator. Worked example: test-for --json rows are {testFile, testFunctions} with no kind field, so the key itself is the only thing saying what kind of file this is — hence testFile, not filePath. By contrast callers --json rows are {caller, kind, file, line} and dead --json rows are {name, kind, file, line}; both already carry kind, so the generic file key is safe there and a <type>File spelling would be redundant. Apply the rule when adding a new row shape rather than copying whichever neighbour was read most recently.

Adding a New Language

Every language is one row of LANGUAGE_SPECS in src/language_specs.ts. The row's id joins the Language union, and its columns feed every place that keys on a language: detectLanguage (extensions, basenames, exactBasenames), the read hook's diff and source hints (diffable, sourceHints), the grep hook's hint (grepSource), the bash hook's symbol/read suggestions (symbolBearing), pack's code fence (fence, fenceByExtension), the display name in ref-blind messages (label), the imports fallback for basename-only files (basenameImportsExtension), and the notice for languages whose references are only partly recorded (partialRefsReason). The module imports nothing, so any file can depend on it.

The extraction column says how symbols are found:

  • tree-sitter: inline in src/parser.ts (TypeScript/JavaScript, Python, Go, Rust, Ruby, Java, C/C++). These need a tree-sitter-<lang> npm package, a grammar branch in loadGrammar() and a branch in parseContent().
  • regex: a SymbolExtractor in ADAPTER_EXTRACTORS in src/languages/registry.ts. That map is typed Record<RegexLanguage, SymbolExtractor>, so a regex row with no extractor fails npm run typecheck.
  • own-result: the language returns its own ParseContentResult (symbols plus refs) from a language === '<id>' branch in src/parser.ts (Vue, Svelte, Astro, Salesforce markup, COBOL, Natural, notebooks). tests/language_specs.test.ts fails when a row has no branch.

Prefer a separate file in src/languages/ for a new extractor. Use src/languages/kotlin.ts as a template for class/function extraction, or src/languages/ini_idx.ts for flat key-value formats.

Steps:

  1. Add the row to LANGUAGE_SPECS. Spread CODE for a programming language or DATA for a config format and override single flags. A new extension on an existing language is just an extensions entry. .h stays C by path: telling C++ headers apart needs file contents. An extension two languages share is settled by content in CONTENT_SNIFFS (src/parser_types.ts), which is how a .h with @interface becomes Objective-C.
  2. Write the extractor: create src/languages/{lang}.ts exporting extractXxx(content: string, filePath: string). Use makeSymbolEmitter from src/languages/common.ts to deduplicate symbols, and export the function from src/languages/index.ts.
  3. Wire it in: add the extractor to ADAPTER_EXTRACTORS in src/languages/registry.ts (a regex row), or add the language === '<id>' branch (an own-result row).
  4. Only if needed, outside the table: an extractImports branch in src/read_commands.ts when the import statement is not caught by the generic import|require|use|#include fallback, and CSTYLE_EXTS/HASH_COMMENT_EXTS in src/pack.ts when the language uses // or # comments. An extension shared with another language (.cls is Apex, VB6, and LaTeX) cannot be told apart by detectLanguage, which is path-only: add a content check to refineLanguageByContent in parser_types.ts, which indexFileSync, parseFile and section_reader.ts apply after reading the file. Every such check must be a POSITIVE test for the language it routes TO (a marker only that language writes), never a negative test for the default language it routes FROM -- a negative test silently misclaims any third language nobody wrote a check for yet, which is exactly how a LaTeX .cls (which has no VB6 or ABL marker) was misclaimed as Apex before this note was added. A consumer holding only a path calls detectLanguageOfFile, which reads the head of an ambiguous file and refines it the same way. A language whose call sites the indexer records also needs REF_LANGUAGES in src/parser.ts and its mirror in src/ref_blindness.ts.
  5. Update the pinned lists: tests/language_specs.test.ts compares every derived list with the list it replaced, so a new row shows up there as a named difference to add, and the non-tree-sitter count in docs/C4_RUNTIME_ARCHITECTURE.md has to match nonTreeSitterLanguageCount().
  6. Regenerate the parser fingerprint: npm run parser:fingerprint rewrites src/parser_fingerprint.ts; tests/parser_fingerprint_gate.test.ts fails until you do. The changelog entry must say that upgrading reindexes.
  7. Add tests on the real path: a CASES entry in tests/guards/language_adapter_produces_symbols.test.ts (it fails for any table row without one) with a fixture in tests/fixtures/language_adapter_symbols/ that carries a provenance line, detectLanguage assertions in tests/parser_types.test.ts, and a built-bundle check: either a case in tests/helpers/matrix_cases.ts (the four tests/command_matrix_e2e.N.test.ts shards each run an interleaved quarter of that table) or a standalone test that spawns dist/token-goat.mjs, as tests/vb_bundle_e2e.test.ts does.

Adding a New Hook Event

  1. Add the event name to HOOK_EVENTS in src/types.ts. TypeScript will enforce that every switch on HookEventName handles the new value.
  2. Implement the handler in the appropriate src/hooks_*.ts module. Return a HookOutput value (passOutput(), contextOutput(text), denyOutput(msg)).
  3. Register the handler at module level:
    registerHook('your_event', yourHandler)
    Module-level registration runs when the module is imported on token-goat hook <event>.
  4. Wire into install if the event needs to be added to settings.json: add a ['YourEvent', 'your_event'] entry to HOOK_EVENT_MAP in src/install.ts and re-run token-goat install.
  5. Test — add a unit test for the handler, and a hook integration test if the event fires in a hook subprocess context.

Adding a New Command

  1. Implement the logic — if the command reads from the index, add a runXxx(opts: XxxOptions): number function to src/read_commands.ts. Otherwise implement directly in a new or existing module.
  2. Write a cmd* handler in src/cli.ts:
    function cmdXxx(opts: XxxOptions): number {
      return runXxx(opts)
    }
  3. Register in buildProgram() — call program.command('xxx').description('...').option(...)...action(guard(cmdXxx)). The guard in tests/guards/cli_registration.test.ts checks that every cmd* function appears in an .action(...) call and that every command in allCommandNames() appears in --help output — it will fail immediately if the handler is declared but not wired.
  4. Add a matrix case — add an entry to the shared case table in tests/helpers/matrix_cases.ts, which the four tests/command_matrix_e2e.N.test.ts shards each run an interleaved quarter of. The coverage gate in tests/command_matrix_e2e.1.test.ts fails automatically if a registered command has no case, using tests/registry.ts::allCommandNames() as the single source of truth shared with the guard.

Security Boundaries

Eleven invariants, each established by a real defect that shipped. A change that touches any of them needs a test that fails when the invariant is removed, not just a green suite.

Every path that persists bytes goes through redactSecrets, and it must run before any truncation, not merely before the write. storeBlob() in src/disk_cache.ts is the funnel for the JSON-envelope caches (bash-output, web-output, mcp-output), and it is fail-safe: a throwing regex does not write raw bytes. src/skill_cache.ts's storeOutput/storeCompact persist skill bodies and compact slices as plain .txt files rather than through storeBlob()'s JSON envelope, so they call redactSecrets directly at their own write sites, with the same fail-safe shape (a throw propagates to the function's own outer try/catch, which returns without writing anything). Presence of a redactSecrets call on a path is not sufficient on its own: redactSecrets's patterns carry a minimum-match-length floor, so a truncator (a .slice(), a line-width clip, a middle-cut, a byte cap) that runs before redaction can cut a credential's matched span short enough that the pattern no longer recognises what's left, and the fragment ships raw even though the path technically "goes through redactSecrets" downstream. Three sites shipped this exact defect before it was named as its own class: mcp_cache.ts::mcpInputPreview (truncated JSON.stringify(toolInput) to 120 chars before the caller redacted it), tool_filters/base.ts::apply() (redaction ran last, after four separate truncators had already clipped the body), and mcp_compress_packs.ts::truncateSnapshotLine via hooks_mcp.ts::postMcpHandler (compression, which truncates per-field, ran on raw resultText instead of the already-redacted text). All three fixes moved redaction to the boundary the path crosses — right after the raw bytes enter the function, before the first truncator — rather than reordering just that one call site, so a truncator added upstream later cannot reintroduce the class. A fourth, differently-shaped defect hit the same model-facing surface without any truncator being involved: tool_filters/dispatch.ts::deliverCompressed — documented in its own comment as "the single definition of what the model actually receives for this command" — computed a correctly-redacted compressed.text, then discarded it whenever compressed.worthApplying(minNet) (the net-benefit/byte-savings floor) returned false, falling back to the RAW pre-redaction combineStreams(stdout, stderr). The net-benefit gate exists to decide whether compression is worth shipping, and shipping the redacted-but-uncompressed original instead is always safe; discarding redaction along with compression on that same gate is not a truncation-ordering bug (nothing was cut short here) but the same family of mistake — a value computed correctly upstream gets thrown away by a branch that was only ever supposed to arbitrate a different tradeoff. The invariant this generalizes to: a net-benefit or worth-applying gate may only ever discard the compression it is gating, never the redaction that ran ahead of it. tests/guards/truncators_are_classified.test.ts and tests/guards/session_state_fields_are_redaction_classified.test.ts turn both halves of this invariant into a structural pre-commit check: every truncation/shortening-shaped function in src/ must carry an explicit classification (redacted-before-truncating, downstream of an already-redacted input, or otherwise verified safe) or the guard fails, and every field of SerializedSession must carry an explicit redaction-coverage classification or the guard fails — so a fifth truncator or a sixth session-state field starts red until someone consciously classifies it, rather than silently inheriting whatever the surrounding code happened to do. The per-session state file, written directly by src/session_store.ts rather than through storeBlob(), has the same shape of gap: adding a new field to SerializedSession used to mean redaction depended entirely on that field's author remembering to call redactSecrets at its own construction site in src/session.ts — outstandingAgentSpawns shipped without it, persisting a raw prompt (and any credential pasted into it) verbatim. The fix is two-layered: the field's own writer (recordOutstandingAgentSpawn) now redacts at push time, and saveSessionState additionally sweeps the fully-serialized JSON through redactSerializedJson once, immediately before the only atomicWriteText call that ever writes this file — a defense-in-depth backstop so a future field that ships without its author remembering redaction is still covered, rather than relying on that memory a second time. A pass over serialized JSON goes through redactSerializedJson in src/secret_redact.ts, never redactSecrets directly, and storeBlob() and mcp_cache.ts::mcpInputPreview do the same: the patterns are written for raw text, and JSON spells every control character as an escape, so a line break reads as the two characters \ and n. Read that way, an empty API_KEY= took every following line as its value, an AccountKey= at the start of a line missed its word-boundary anchor, and strict mode left a lone backslash that made the stored blob unparseable, as it also did when its run started at the u of the escape JSON.stringify writes for a surrogate with no partner. redactSerializedJson decodes both kinds of escape before the patterns run and writes them back after. Redaction is a pattern matcher, not a classifier: adding a pattern is cheap, and a credential shape with no distinctive prefix (presigned urls were the last one found) needs an anchor plus a length floor so a generic parameter name stays safe to key on. Persisting redacted is not the same guarantee as showing the model redacted text this turn: postMcpHandler in src/hooks_mcp.ts redacts its compression branch's rewrite, and postWebSearchHandler/postFetchHandler in src/hooks_websearch.ts/src/hooks_fetch.ts now redact on every live-rewrite path (computed once, ahead of every early-return caching guard, the same ordering discipline the injection scan below already enforces) — closing the gap where a credential that tripped no injection pattern reached the model unredacted even though the cached copy on disk was clean. One exception cannot be redacted and is bounded instead: src/bash_backslash_repair.ts writes the Bash command byte for byte to <home>/bash_repair/tg-cmd-<hex>.sh (the script must hold exactly what runs), only for a call approved with no prompt; the script deletes itself on its first line, and hooks_bash_post.ts removes any older than 10 minutes (the Bash tool's longest command time) after every Bash call.

The line that matters is rewriteOutput, not the hook. A pass result is the harness's own tool output, which token-goat neither authored nor can alter; redacting there would be a different feature (suppressing what the model would see regardless), not a leak fix. What must always hold is that text token-goat substitutes for a tool result is clean. postAgentHandler in src/hooks_agent_spawn.ts violated exactly this: it cached the subagent report through storeMcpOutput (which redacts) and, on the next line, built its compacted replacement from the same raw string. Redact where the value enters the handler, never on the branch that happens to emit — the entry point is the only place a future branch inherits it for free. tests/guards/rewritten_output_never_carries_a_secret.test.ts enforces this by firing every registered post_tool_use handler and reading what it emits, with the population taken from the registry rather than a list. It is behavioral, not static, for a measured reason: a static "reaches a rewrite must reach the redactor" rule flags hooks_bash_post.ts, whose compression rewrite is redacted inside compressOutput() in another module — invisible to same-file call analysis, and silenceable only with the kind of hand-maintained list these guards exist to eliminate.

A redaction is not a key. Two inputs differing only inside the redacted span collapse to one entry. Use a digest when the consumer is an exact-match check with a denying effect; use a redaction only when the value is displayed and must stay readable; use both when it is displayed and compared, with the readable fields first so display code that reads only the leading field keeps working. Changing a persisted key shape means migrating the old shape at coerce() in src/session_store.ts, the single boundary every disk read passes through, including the fresh re-read the save path performs. Skipping the migration does not fail anything: the lookup just misses, the work is silently redone, and the old credential stays on disk for the life of the session.

A rewrite may carry back only the bytes no string can stand in for. postMcpHandler's rewrite emits a block array: the redacted, fenced words in one text block, then the image, audio and blob blocks copied verbatim out of the server's own payload. Those copies are a second route to the model running beside the fenced one, so isTextualContentBlock in src/hooks_common.ts drops every block that holds words -- text, an EmbeddedResource with text, a ResourceLink -- and their content travels in the fenced block instead, the link's name and uri included so dropping the block loses nothing. Preserving one of them verbatim would hand the model an unredacted, unfenced copy of the exact text the block beside it marks as untrusted. tests/guards/a_preserved_block_never_carries_the_servers_words.test.ts drives the live hook over one result holding every block type in the MCP union and asserts both halves: nothing textual survives, and nothing textual is lost. A sixth block type added to that union is the case this is written to catch.

The injection scan runs before every early return, never after. postMcpHandler in src/hooks_mcp.ts computes the scan and a passOrFence() closure before the first guard. Three caching guards (error response, missing session id, dedup hit) each used to return above the scan, so a hostile server could flag its own reply as an error, or simply be called twice, and get an unfenced payload through. A guard that exists to save work must never double as a way around a security control. The same rule applies to any new guard added to a hook that fences or redacts.

Untrusted content is fenced by provenance, not by heuristic. Every surface fences unconditionally: the scan decides whether the notice names the patterns it matched, never whether the fence appears. Eight sites each restated that rule and each got it wrong the same way (if (matches.length === 0) return text), so the decision now lives in one module, src/untrusted_fence.ts -- fenceUntrusted for a printed block, fenceWithMatches where a hook already scanned, scanAndRecord for the stat. The one legitimate gate is injection.enabled = false, which is explicit user configuration rather than a detector, and it switches off the whole subsystem including the fence. The fence tags in src/injection_scan.ts are per-surface (UNTRUSTED_WEB_TAG, UNTRUSTED_TOOL_TAG, UNTRUSTED_FILE_TAG, UNTRUSTED_GITHUB_TAG) so escaping one does not escape another. neutralizeFenceMarkers has to match as loosely as an HTML parser reads: case-insensitive, whitespace anywhere inside the tag, junk attributes, and a slash before the closing bracket. Every spelling that reads as a closing tag but is not escaped is a way out of the fence. Cached Bash and MCP output recalled later is third-party text exactly as a fetched page is: bash-output and mcp-output fence on recall, web-output too. So is recall (unified search over those same three caches — its no-query browse mode returns a raw excerpt with no scan skipped even when nothing matched a search term), gdrive-sections (a Google Doc, fetched over HTTP like a WebFetch page, same UNTRUSTED_WEB_TAG), and pr-slice (a GitHub PR's title/description/comments/diff, under its own UNTRUSTED_GITHUB_TAG since it is neither a page token-goat fetched itself nor a recall of a prior tool call). _applyFiltersAndPrint in src/cli_cached_output.ts still defaults its fenceByProvenance parameter to false, because it also prints the caller's own files; nothing makes that default safe by itself, and every third-party caller passes true. A structural guard, tests/guards/third_party_content_reaches_fence.test.ts, parses every function in src/ and fails when one reaches a named third-party content source (fetchPrFiles/fetchPrDiff/fetchPrComments/fetchPrDescription, fetchDoc/getSectionContent/getDocSections, searchRecall/listRecentRecall) without also reaching a fence terminal (fenceUntrustedContent, fenceUntrusted, fenceWithMatches, fenceUntrustedOcrText) or _applyFiltersAndPrint(..., true, ...), transitively through same-file calls, and fails when a function that does reach one can still skip it via a zero-match early return — so a new command reusing one of those functions is caught the turn it is written, with nobody needing to remember a checklist. A wholly new fetch primitive that bypasses every name in that list is the one gap the guard discloses in its own header comment; it needs a human to add the new entry point, the same way a newly-lock-worthy config setting needs a human decision in project_config_lock_coverage.test.ts's allowlist. A local file is third-party content too when the caller only named it rather than authored it: pdf-extract, pdf-locate, pdf-outline, docx-text, docx-outline, pptx-outline, pptx-slide, pptx-notes, pptx-text, and xlsx-sheets/xlsx-head/xlsx-range/xlsx-query in src/cli_office.ts all fence their extracted text under UNTRUSTED_FILE_TAG whatever it says. So do the data-file readers (csv-query, csv-profile, zip-list, zip-read, sqlite-query, sqlite-schema, sqlite-tables, describe on a database) and dep-docs, whose README, package.json fields and declarations a package publisher wrote; html-query and html-outline fence under UNTRUSTED_HTML_TAG. Each redacts, then caps, then fences what the cap kept, with the cap marker below the closing tag (guardThenFence and guardRedactAndFence in src/read_commands.ts): the cap keeps leading lines only, so fencing first cut the closing tag off a long result. --json is the single documented exception, and it is a wire-format constraint rather than a judgement call: a fence wrapped around JSON is no longer JSON, so those envelopes fence individual fields on a pattern match only, while the printed form of the same command is always fenced. Each exception is named in CONDITIONAL_FENCE_EXCEPTIONS in the guard with its reason, and the guard also fails on a stale entry, so an exception that stops being conditional cannot sit there licensing a gap that no longer exists. This family used to be left out of THIRD_PARTY_SOURCE_CALLS above, on the reasoning that its entry points are also called by src/doc_embed_extract.ts to feed the embeddings/chunking pipeline rather than to print, so listing them would flag that file. That left thirteen document commands outside the guard's view entirely while it reported green. All thirteen are now listed, named by the local alias each is imported under in cli_office.ts (runPdfExtractText, docxText, pptxOutline, xlsxHeadSheet, ...), and the false positive is handled where it belongs: a module that defines one of these functions, doc_embed_extract.ts included, is exempt from the check, so an internal consumer no longer costs the emit paths their coverage. Behavioral coverage for the family stays in tests/cli_doc_extract_fencing.test.ts, which asserts the actual fenced output per command, the same proof strategy the guard's header comment already prescribes for bash-output/web-output/mcp-output.

The three emit channels are not equally defended, so "which one does this reach" is a real question. denyOutput neutralizes its payload and adds its [tg] prefix outside the neutralized region; emitRewrite is the boundary the substitution guard walks; contextOutput does neither, and its callers carry their own [token-goat] prefix inside the payload, which is why it cannot simply be made to neutralize without moving that prefix out at all 54 call sites. The consequence is not hypothetical: adding <cwd>/.claude/agents as a scan root in 2.9.7 made the unrestricted-spawn advisory's names repository-authored, and they reached the model through contextOutput in token-goat's own voice with nothing between. The fix constrains the name's shape at the parser rather than fencing the notice, because the notice is ours and a fence around it would escape our own prefix. Two further things this cost, both worth carrying: the substitution guard's population is emitRewrite/emitRewriteIfChanged only, and widening it to contextOutput surfaces 11 functions that have never been adjudicated; and postAgentHandler was already exempt for a different body, so a function-keyed exemption silently covered a second block its written reason never mentioned.

Enumerating the rest of that channel found four more instances of the same shape, which is the reason this paragraph exists rather than a note on one commit. The compaction manifest's web-fetch row was the one row of that manifest not routed through displaySafeText. buildDeltaCapsule in src/evidence_cache.ts listed the paths whose cached evidence had gone stale, and those paths come from whatever files a Read touched, so in a cloned repository the repository chooses them. repeatFailureNotice in src/hooks_tool_failure.ts named the tool that failed twice, and an MCP server chooses the names it advertises. In every case the helper already existed and the call site simply did not use it, while its siblings all did. The lesson to carry is the enumeration, not any single fix: when something lands on this channel, walk every other function that reaches it and ask what each one interpolates, because two of these four came from that walk and from no report.

Walking it by hand is not enough, which is the second half of the lesson and the more useful one. The hand-walk described above found two sites; tests/guards/context_channel_population_is_adjudicated.test.ts then found nine more, one of them a live defect in the manifest re-read hint. That guard cannot decide whether an interpolation is safe, because whether '... ' + x + ' ...' is safe depends on where x came from. What it can do is pin who is on the channel and refuse to pass until each function carries a one-line adjudication of what it interpolates, which is the part a person keeps skipping. Its entries are prose and prose cannot fail, so every entry that promises a specific mechanism is paired with a direct assertion that the call still exists.

Three of the eleven candidates that sweep produced turned out to be unreachable, and all three had looked live from the emitting line alone: the Grep hint's extractor refuses any path containing a bracket, safeSkillName refuses any skill name outside [A-Za-z0-9_:-], and the snapshot-diff messages leave on the deny channel, which already neutralizes. Read the callers before pricing a site. Getting it wrong costs in both directions: assume live and you publish a security note for a hole that was already closed, assume safe and you ship the hole. Two hints sitting two lines apart in src/hooks_read.ts went opposite ways for this reason: the tsconfig one is gated to fixed filenames, the manifest one matches by extension and so quotes an arbitrary repository-chosen name. The escaping stays on the unreachable sites as the layer that survives those gates being relaxed, since each exists for filename-safety or globbing rather than for injection, and each is now pinned by a test carrying a positive control so a gate that quietly stopped gating fails rather than goes silent.

Decision, 2026-09-04: Bash output token-goat does not substitute stays unfenced, and undefused. Recorded here because the reasoning is a measurement, and prose nobody can re-run is how a reachability claim rots. Three numbers, all taken on this machine over the 30 days to 2026-09-04. Volume: 173,739 Bash calls, of which token-goat compresses 3,172, so a fence on every result taxes 98.2% of calls that it changes nothing about, roughly 5.4M tokens a month against 468M saved. Benefit: on a build log impersonating a token-goat truncation notice, a model complied 11 times in 12 unfenced and 6 in 12 fenced, so the fence buys a halving, not a stop. Alternative: escaping the forged prefix reached 1 in 12, on the 0.19% of results (440 of 227,437) carrying a marker-shaped line at all -- strictly better protection for effectively no tokens.

That alternative was built and then withdrawn, which is the part worth keeping. Escaping on the pass-through path fires on any output containing the literal [token-goat, and that includes token-goat's own source, its docs, and its changelog: cat src/tool_filters/node_test_runners.ts came back with escaped brackets, and a model round-tripping that text writes &#91; into the file. The suite caught it, in tests/read_served_output_producer.test.ts, as four negative assertions flipping to rewriteOutput. A defence whose failure mode is corrupting the files it is defending is not worth a speculative gain on a path where token-goat is not speaking. So the escape lives where the substitution does, inside fenceUntrustedContent, and the pass-through paths are exempt from both. Reopen this if the marker prefix ever appears in the model's system prompt or documentation as something to trust, since that is the premise the whole trade rests on.

Where the fence is available, and where it is not. tests/guards/substituted_output_reaches_fence.test.ts walks every function reaching emitRewrite, and the eight it found split cleanly in two. Where token-goat's text sits at one end of the body -- the BashOutput and TaskOutput poll deltas, and the compound-Bash rewrite before them -- the notice goes above the opening tag and the fence covers the rest, which is the shape to copy. Where our markers are spliced between the bytes they replaced, there is no such cut: fencing the whole body would run the marker neutraliser over token-goat's own markers and hand the model &#91;token-goat: 40 lines elided]. The Bash elisions are no longer in that position. fenceUntrustedSpans takes the body already split into spans, each marked with whether token-goat wrote it, and runs the neutraliser on the others and on nothing else. Authorship is positional, declared by the producer that emitted the span, rather than recognised from the text: a rule that spotted our markers by their spelling would exempt a forged one just as readily. Both hooks_bash_post.ts elision sites fence through it, and the fence is priced before the net-benefit gate rather than after, so the gate cannot decline a rewrite for the cost of its own protection. Three remain open: the agent-report compaction, the already-served Read elision, and the browser block join. What keeps them open is the round-trip risk rather than the missing mechanism, since an untrusted span containing the literal [token-goat comes back escaped and those three feed the surfaces most likely to be copied into a file. Reopen them when there is a way to escape a span that a model cannot round-trip into an edit, or when a marker-shaped line is measured arriving on one of the three rather than assumed.

A rewrite must leave the user's own permission rules deciding the original call. Claude Code matches its permission rules against a PreToolUse hook's updatedInput, and permissionDecision: "allow" skips its prompt, so when serializeOutput answered every rewrite with allow, a compressible curl wrapped in token-goat compress ran with no prompt, a Bash(curl:*) deny never saw curl at the head of the command, and a shrunk image's temp path walked past a Read(./private/**) deny. Every rewriteInput producer (Bash compression, the structural rg/grep query, the Agent briefing, the image Read) goes through permissionNeutralRewrite in src/rewrite_permission.ts, which reads every settings source Claude Code could apply (managed file, registry and plist policy, the user files, every .claude directory from the cwd up) and declines the rewrite when a deny or ask rule could match the original or any source cannot be read. A registry policy key counts as absent only when reg gives its own not-found answer and gives the identical answer for a sentinel key under HKLM that no user can create; any other failure leaves the policy unreadable, because a user can deny read access to an HKCU key and so fake its absence. reg and PowerShell start only by absolute path from a validated Windows folder (src/windows_system32.ts), never by bare name, since a bare name or an unvalidated SystemRoot lets a reg.cmd planted in the working directory answer in their place. Claude Code checks a path rule against both the requested path and the file it resolves to, and the rewrite shows it neither, so the image Read's path and every word of a shell command are also matched under realpathSync.native (symlinks, junctions, 8.3 short names, a not-yet-created file through its nearest existing ancestor); a junction pics -> secrets once carried a Read past Read(./secrets/**). Its approve verdict is the only thing that puts allow on the Claude Code wire, and it is set only when the original would have run with no prompt anyway: a trusted allow rule matching a simple command, a built-in read-only command, an image Read inside the working directory. A .claude/settings.local.json allow is trusted only when git ls-files --error-unmatch exits 1 (untracked inside a repository); exit 128 once counted too, but it also means no repository at all, as in an unpacked archive that ships the file, or one git refuses under safe.directory. loadPermissionSnapshot anchors on CLAUDE_PROJECT_DIR (where the session started) as well as the hook's cwd: deny and ask rules count from every .claude folder above the cwd, the project and its main checkout (a linked worktree resolves through commondir), a cwd outside the project returns null, and a local allow counts only at the starting directory while the cwd is there and, off Windows, that directory is the checkout root, the one place old and new Claude Code versions agree they read it from. A rewrite is never approved in plan mode. In auto and bypassPermissions the user is never prompted, so a rewrite there is approved or skipped, never deferred: decideRewrite skips every kind in auto (auto drops broad allow rules and has its classifier review even read-only commands, so an allow skipped that review, and a plain rewrite could draw a prompt the original would not), and in bypassPermissions approves a non-skip verdict only when the snapshot has no PermissionRequest hook and src/claude_hidden_rules.ts finds no source the settings files do not show: an entry point other than cli/sdk-cli (an SDK host's canUseTool, an editor), a claude command line carrying any flag outside its harmless allowlist (--disallowedTools, --settings), read from CLAUDE_PID through CIM, /proc or ps, a skill, command or agent .md whose disallowed-tools names a pattern, and a plugin cache hooks.json with PermissionRequest, scanning nested .claude folders through git ls-files because Claude Code skips gitignored ones. That module is a dynamic import primed by loadingHiddenRuleCheck on the bypass event, so it stays off the eager chunk, and an unprimed check counts as hidden. Every other mode withholds an approve the same way: a PermissionRequest hook in the snapshot, or the same module asked for the files only (skills, commands, agents and plugin hooks, not the claude process), on Claude Code and VS Code alike, and lineRules (the claude command line, where --setting-sources is harmless only when it names user, project and local) on Claude Code only; with the check unloaded no mode approves. A tracked skill file that is gone from disk is read from the git index, an untracked gone one adds no rule, and the nested scan is stamped like the fixed folders so a clean answer is dropped when a file it read changes, when the checkout's index or HEAD changes (the git path stamps both, and a linked worktree's or separate git directory's), or when a folder that git listed within three levels of the project, or on the path to a listed .claude at any depth, gains an entry; a scan whose stamp is under 2 s old (RACY_MS, git's racy-index rule, which also covers a .claude made between the listing and the stamping), cannot be read (only ENOENT and ENOTDIR are absent) or needs 2000 folders or more is volatile and its clean answer is rescanned on the next call; a .claude first created untracked more than three levels down in a folder with no listed file keeps the minute. tests/guards/bypass_and_auto_never_prompt.test.ts sweeps the decision and forbids any ask decision or a rewriteInput built outside this module. Every doubt resolves to no rewrite, because losing a compression costs tokens and skipping a rule costs the user's control. Codex is the one wire that still carries allow, since it applies updatedInput only beside it. Codex matches its execpolicy prefix_rules against the command's words, which the wrapper hides, so a Codex shell rewrite goes through decideCodex in src/codex_rules.ts, a dynamic import that loadCodexRules primes from the Codex Bash hook so its Starlark reader stays off every other hook's eager path (unprimed, the rewrite is skipped): it ships only when no rule of any decision in any rules layer (the system folder, ~/.codex, CODEX_HOME, every .codex from the cwd up) could match the original, because even an allow rule runs the original outside the sandbox, which the wrapper would lose. A rule headed by a shell needs only its script tokens, since Codex matches a script it cannot split as [shell, flag, script] (the TUI saves Windows approvals that way, as pwsh.exe -Command <script>). A file the reader cannot parse, a requirements.toml naming prefix_rules, or a macOS managed preference skips every Codex shell rewrite; requirements Codex pulls from the cloud are invisible to a hook, a limit stated in docs/security.md. UNSEEN_SHELL_RULES (Copilot CLI, opencode, Grok) never ships a shell rewrite: Copilot takes --allow-tool/--deny-tool on its command line and orders hooks against them in compiled code, opencode merges permission config from an org account and a well-known URL and asks external_directory for the path arguments of cd/rm/cp/... that the wrapper hides (a probe's cd ../outside && go vet was rewritten past that ask), and Grok runs Claude Code's hook settings and applies updatedInput before its policy and prompt. opencode gets no shrunk-image path either: its read tool asks external_directory and read against the path the plugin hands it, so a temp copy stepped past a read rule on the original; image_shrink.ts leaves it out of HOST_MATERIALIZED_HARNESSES and the plugin no longer materializes a copy. Copilot CLI shares Claude Code's cwd gate in preReadImageHandler: it asks before a view outside the cwd, the system temp dir and /add-dir folders, its path check is native code whose order against modifiedArgs no hook can read, and the copy is in the temp dir, so an image outside the cwd is left alone (an added folder is invisible to the hook). The PowerShell adapter in src/powershell_compat.ts runs inside the wrapper after that decision, so it may only carry the original's own heredoc body as base64 (decoded into the heredoc's command or file) or a Python interpreter's -c script as hex (run by a -c loader that imports only sys and keeps the script's argv and stdin) and set the standard streams of a Python the original already runs to UTF-8 (the loader reconfigures them; a heredoc pipe sets PYTHONIOENCODING for that pipeline and puts it back), never change which program runs, its options, or what its arguments mean: no rule sees its output, and mypy -c or python -m pytest -c setup.cfg once came out as a different command. A hint is the same bypass in prose: preReadHandler, preGrepHandler's structural hint and preBashHandler told the model to run token-goat json-query, read or skeleton on a file under a Read(./secrets/**) deny, and that command reads the file with no rule applying, so on Claude Code and VS Code each drops a deny or context answer when readHintCrossesRule (same module, same matching and real spellings as a rewrite) finds a deny or ask Read rule that could cover the path, an unreadable settings source, blockReadsOutsideWorkingDirectories set, or a shell $, ~ or glob while any Read rule exists (a shell path word the VS Code path gate declines is matched as written, never resolved on disk); Bash's warnings about how a command is written (double backslash, unbalanced quoting) are marked with syntaxOutput and still go out. tests/rewrite_permission_e2e.test.ts drives the built bundle against real settings files.

Egress has one choke point and one switch. Every HTTP request token-goat makes itself goes through performHttpFetch in src/webfetch.ts, redirects included, so the offline check lives there rather than at each command. Four paths bypass it: the embedding model (src/embed_model.ts, huggingface.co) and the WebAssembly inference runtime (src/embed_runtime_web.ts, registry.npmjs.org), both through downloadPinned in src/pinned_fetch.ts, which checks network.offline itself, holds every byte to a recorded SHA-256 and length, and after a failed download holds further automatic tries for that host (10 minutes, doubling to an hour; src/model_download_gate.ts) unless the caller asked for the download explicitly; the OCR language data (tesseract.js, cdn.jsdelivr.net), and screenshot's browser navigation. Each has its own guard, and each preserves a warm cache rather than refusing outright. A new dependency that downloads something at runtime is a fifth, and needs the same treatment plus a line in the README's outbound list.

A per-project config file is untrusted input. .token-goat.toml arrives with the repository, so it is written by whoever wrote the repository. PROJECT_LOCKED_SECTIONS and PROJECT_LOCKED_KEYS in src/config.ts name what it may not set: the injection, webfetch, gdrive, mcp and network sections, plus indexing.cross_project_symbols. A new setting that turns a protection off, narrows an allowlist, or widens a confinement belongs in that list. The environment is deliberately not locked: a repository cannot set it, and a developer exporting a variable is configuring their own machine.

Containment compares resolved paths, and asks the platform about case. isInsideRoot in src/project.ts is the shared helper. canonicalize deliberately does not call realpath, so lexical containment alone is not containment: a directory symlink inside a root pointing out of it satisfies a prefix test while naming a confined-away file. Case folding goes through foldPath/isCaseInsensitiveFs, never a hand-rolled process.platform === 'win32' check, which wrongly rejects legitimate paths on a case-insensitive macOS volume. The trailing-separator guard is what stops /srv/project-secrets reading as inside /srv/project.

The security scan is in two halves, and the split is deliberate. Eighty-odd guards in tests/guards/ each encode a defect somebody already found, which leaves the classes nobody has looked at uncovered. The two files that close that are keyed on shape rather than on a bug. tests/guards/dangerous_sinks_are_named.test.ts runs in npm test and answers where are the sinks: eval, new Function, node:vm and string-form child_process.exec are asserted absent with no exemption map, and every shell: true and execSync site has to be named with the reason it cannot be an argv array. It is text-structural on purpose -- tests/guards/typescript_compiler_api_available.test.ts documents what happens when a guard couples to the compiler API, and this one has no need of it. The other half, does untrusted data reach a sink, needs interprocedural dataflow and lives in .github/workflows/codeql.yml, because no engine that answers it is fast, offline and cross-platform enough for a suite that also runs on Windows and macOS. tests/guards/codeql_scan_is_wired.test.ts holds that job to the extended query suite, a schedule, and a paths-ignore that does not cover src -- each of which fails silently, leaving a green check and an empty alerts tab that reads as a clean bill of health.

eslint-plugin-security was measured before the hand-rolled guard was written, and rejected on the numbers: 1,691 findings across 177 of 255 source files on 2026-09-04. Three rules are 96% of that and none is usable here. detect-unsafe-regex (260) is the star-height heuristic, strictly weaker than the automaton analysis eslint-plugin-regexp's no-super-linear-backtracking already runs in npm run lint. detect-non-literal-fs-filename (511) flags reading a file whose name came from a variable, which is the product. detect-object-injection (848) flags every computed index including arr[i], and the four detect-possible-timing-attacks hits are name matches -- a lock-file token compare, a variable called auth holding a hostname -- against a product with no secret-comparison surface. Worth recording rather than quietly not adopting: detect-object-injection is the rule that would have flagged the copilot_cli.ts prototype-key defect below, so the instinct to reach for it is right and only the granularity is wrong. A suppression file with 1,691 entries is worse than no rule, because it reads as a decision. Reconsider if the plugin gains sink-awareness, or enable single rules scoped to a directory where their false-positive shape does not apply.

Every bridge shim builds a shell command string, and what goes into it must be a closed set. Each bridge installs a generated hook shim whose last resort is spawnSync('token-goat hook ' + event, { shell: true }). The shell: true cannot come off: a global npm install puts a .cmd shim on PATH on Windows, and spawnSync cannot exec that without a shell. So the property that has to hold is on the value, not the call. Audited by surface on 2026-09-04, the seven concatenation sites split three ways. Four -- claudecode.ts, codex.ts, grok.ts, kimi.ts -- test the name against a closed Set before interpolating, which is the shape to copy. Two -- relay_block.ts, used by opencode and openclaw, and pi.ts -- validate nothing, and are safe only because every one of their call sites passes a string literal; that is a property of today's callers, not of the code. The seventh, copilot_cli.ts, read process.argv[2] into a plain object literal and gated on the result being truthy. A plain object answers that lookup for the eight members of Object.prototype, so constructor, __proto__, toString and five more resolved to a Function, were stringified into the command, and reached a shell. Measured, not inferred: with the check reverted, a recording token-goat on PATH runs for all eight, and does not for a name that is merely unknown. No member of Object.prototype stringifies with a shell metacharacter, so the outcome was a failed spawn rather than a second command -- the defect is argv reaching a shell string through a gate that reads like it stops it, not a payload. It now uses Object.prototype.hasOwnProperty.call. tests/guards/shell_concat_is_constrained.test.ts holds all three shapes: a shim reading from argv must carry one of the constraints named in CONSTRAINTS, and the two literal-only shims are checked at both hops -- every call site passes a literal, and the delegation that actually builds the string passes through only the parameter the first check constrains. A bare MAP[key] is deliberately not a member of CONSTRAINTS.

Outside the bridges, shell: true appears twice more and neither is this shape. src/bash_runner.ts is the product running the user's own command. src/cli_doctor.ts spawns the Copilot hook command the user configured, which is their own file and is documented as such in place.

Decompression is bounded on the output side, not just the input side. MAX_ZIP_INPUT_BYTES and MAX_ZIP_OUTPUT_BYTES live once in src/zip_bounds.ts, and every archive read goes through unzipBounded. The OOXML reader used to cap only stat.size, the compressed size, which bounds nothing: DEFLATE's worst case is about 1032:1, so a compliant 50MB input expands toward tens of gigabytes. zip-list and zip-read capped neither side. Two checks are needed and neither is redundant. The declared uncompressed size in the central directory is attacker-controlled, so gating on it alone is defeated by an archive that understates it; a running total of bytes actually produced, checked as the stream is pushed in chunks, catches that case regardless of what the entry claimed. The declared-size check is still worth keeping because it rejects an honestly-labeled bomb before any decompression starts. Note what fflate does on its own: unzipSync pre-allocates the output buffer to exactly the declared size and never grows it, so memory is already bounded and an understated size truncates silently rather than overallocating. It is CPU that is unbounded, because the full bitstream is decoded either way, and that is what the streaming abort actually buys. Driving fflate's low-level Unzip directly loses the end-of-central-directory validation unzipSync performs, so unzipBounded calls unzipSync with a filter that never matches purely to keep the malformed-archive throw.

An image decoder sizes every buffer from a number the attacker wrote, so the header check is not the bound. image_shrink.max_image_pixels (16 MP by default) used to be sharp's limitInputPixels, which libvips enforced inside the decode. Since the move to the pure-TypeScript engine it is a check on the header's width * height, run in probeImageMeta before token-goat's own decoders, and it sees nothing else -- not the frame count, not how far a compressed stream expands. Three separate bombs went straight through it, all measured on this engine on 2026-09-04: an 11.5 KB GIF declaring a 1600x1600 canvas and 500 frames allocated 5.1 GB, because every frame is a full canvas and all are retained at once, and 1600x1600 is 2.56 MP so the gate passed with 84% of its budget unused; a 510 KB PNG declaring 4000x4000 -- exactly 16 MP, so exactly at the gate -- inflated its IDAT to 512 MB where 61 MB was needed, and 512 MB was the number chosen for the test file rather than a limit the code imposed. MAX_DECODED_BYTES in src/image_engine.ts is the actual bound, 256 MB, checked before each allocation rather than after; it is deliberately not configurable, and setting max_image_pixels to 0 does not lift it. The PNG inflate gets an exact bound rather than a round one: a non-interlaced image's zlib stream is precisely one filter byte plus one row of samples per scanline, so maxOutputLength is that figure and anything beyond it is by definition not data the image needs.

A decoder that cannot handle a format must refuse it, not decode it into a different picture. The same engine accepted PNG bit depths 1, 2, 4 and 16 and Adam7 interlacing, then ran all of them through a row loop that assumes 8-bit progressive; an opaque red 16-bit pixel came back as [255, 255, 0, 0], a transparent yellow. BMP accepted every bit depth but only had pixel-loop branches for 24 and 32, so an 8-bit file returned the zero-filled buffer -- a fully transparent image, reported as success. Both are worse than the allocation bugs above despite looking milder, because the failure is silent and the wrong pixels are what shrinkImage re-encodes and hands to the model as the contents of the file. Refusing costs nothing: the throw is caught and the untouched original is passed through, which is the correct picture. The rule for this engine is that an unsupported header field is an error, never a default.

A read-side ceiling is not a write-side ceiling, and peak memory is their sum. MAX_DECODED_BYTES in image_engine.ts bounded the frames a GIF decode allocates at four bytes per pixel per frame. The animated branch of shrinkImage then allocates its own output buffer at five, from the same frame count, so a 1600x1600 animation between 22 and 26 frames passed the decode bound and exceeded the ceiling on the way out -- and the process held both at once. The shrink path now runs the same assertDecodableSize over the buffer it is about to write, which is why that helper is exported rather than private to the decoders. Verified against the installed build on 2026-09-04: 21 frames shrinks (1,029 KB to 78 KB, 759 ms), 22 frames is declined. When one module states a memory ceiling, every allocation shaped by the same attacker-controlled count has to be measured against it, including the ones in other files.

Decoding a whole animation to use one frame of it is a bound you did not take. The still-image branch of shrinkImage read decodeGif(input).frames[0], paying a full canvas for every frame it discarded. decodeGif takes a maxFrames option and that site passes 1. A caller that wants a prefix should say so, because the ceiling is then priced on what is actually decoded rather than on what the file claims.

Following an offset a file supplies needs a record of where it has already been. A TIFF's pages are a linked list, each IFD carrying the offset of the next, and nothing in the format forbids that offset pointing at an IFD already visited. probeBufferMeta followed it without one: measured, a 64-byte TIFF whose only IFD pointed at itself never returned. It allocates nothing, so it is never OOM-killed -- it holds the thread, and because this runs in a pre-read hook that is an agent whose Read never comes back. A synchronous loop like this also cannot be interrupted by a test timeout, which is worth knowing before writing the regression test: the proof that it was broken is that the suite itself hung.

A budget that bounds memory does not bound work, and a size measured on a name is not the size of the file you read. MAX_PDF_TEXT_BYTES, MAX_PDF_TEXT_ITEMS, MAX_PDF_INPUT_BYTES and MAX_PDF_WORK_MILLIS live once in src/pdf_extract.ts, and every entry point that reads page text opens one pdfWorkDeadline() per document. Four things need bounding here and none of them substitutes for another. Text: a content stream's expansion ratio is whatever its author chose, and the measured fixture is 160 KB on disk, 35 million characters of text, 740 MB resident. Items: a budget counted in characters lets a page of a million one-character items sit inside 8 MB while costing hundreds of megabytes to hold, since every item is an object. Encoding: that budget counts UTF-16 code units under a name stated in bytes, and accented or CJK text encodes to two or three times as much, so the finished document is measured with Buffer.byteLength before it is returned. Time: pdfjs cannot be stopped part-way through a page -- cancelling the stream closes the web-stream controller while pdfjs still believes its own is open, so the next in-flight chunk throws from inside its message handler as an uncaught exception, and abandoning the reader without cancelling deadlocks loadingTask.destroy() -- so refusing frees the memory and leaves the producer running, and the clock is the only thing that ends it. The file read is part of the same invariant: readPdfFileWithinBounds opens one descriptor and takes the type, the size and the bytes off that one handle, because a stat and a read are two lookups of one name and the file can grow or be swapped between them, and anything that is not a regular file is refused outright since a FIFO or a character device reports a size of zero and zero passes any ceiling. Where the clock is READ is part of the bound and not a detail of it: a check written in the loop that consumes text items is not reached by a page that produces none, so the clock sits on the awaits that produce, not on the loops that consume: the chunk read, the whole-page fallback, getPageWithinDeadline (through which every command walks pages), and the outline and metadata fetches, each of which materialises its whole structure before any cap is consulted. A refusal thrown mid-stream also has to be able to leave, so teardown races PDF_TEARDOWN_MILLIS. Bounds on what is retained in the ANSWER are a fifth class beside the four above: MAX_OUTLINE_ENTRIES, MAX_OUTLINE_TITLE_CHARS, MAX_LOCATE_MATCHES and MAX_LOCATE_CONTEXT_CHARS, and a snippet is measured against --context rather than against however much the caller's pattern chose to match. Finally, DocumentRefusedError in src/document_refusal.ts is the one type the indexer asks about when deciding whether a document is worth opening again: a per-format check is a check the next format is added without, which is how the OOXML size refusals spent their whole decompression on every index pass.

A release binary reaches the publish job only through the job that produced it, and the publish job checks it before it publishes. .github/workflows/publish.yml builds the four tg-hook binaries on runners of their own architecture, signs the Windows pair in a signing job that runs no repository code and alone holds the signing secrets, attests the Linux pair, and then deletes dist/native in the publish job and rebuilds it from those artifacts alone. scripts/verify-native-dist.mjs runs before npm publish and stops the release unless exactly the release binaries are present (four, or the Linux two under --without-windows), each matches the hash its producing job recorded, each Windows file ends in a certificate table holding an Authenticode SignedData with at least one signer whose image digest, recomputed over the file as the Authenticode PE spec lays out (checksum, certificate-table entry and the table itself skipped), matches, and each Linux file is an ELF executable for the right machine with an executable PT_LOAD inside the file, no PT_INTERP and no DT_NEEDED entry. The digest binds the signature to these bytes; the certificate chain is not validated here. An entry under dist/native that lists but cannot be read is reported as a problem rather than crashing the check. With no WINDOWS_SIGNING_STORETYPE set, the signing job skips its steps and reports signed=false, the publish job assembles only the Linux pair, and the gate runs with --without-windows, which refuses any Windows file; an unknown store type or a missing secret still fails the release, so a typo cannot quietly drop Windows. A pack or publish from a working tree runs the same script as prepack in --pack mode (prepack rather than prepublishOnly, because npm runs prepack on npm pack too and a packed tarball publishes without its own scripts), which refuses an unsigned Windows binary, a dynamically linked Linux one, or any other file under dist/native (CI publishes with --ignore-scripts and is gated above instead). Guards in tests/guards/ hold the shape: the signing job runs no code, downloads are hash-pinned, actions are pinned to commits, only the attest job may write attestations, dist/native is deleted before assembly, and verification runs before publish in an unconditional bash step under set -euo pipefail with nothing after the command that could discard its exit status.

Known Limitations

  • Post-compaction skill re-injection is Claude Code's own native behavior, not something token-goat's pre_compact hooks control. When the harness compacts a conversation, Claude Code itself decides which skills get reloaded into the fresh context — token-goat only gets to shape the manifest text injected alongside that compaction (see hooks_compact.ts and hooks_index.ts), it cannot prevent or filter which skill bodies the harness chooses to re-inject. The load-time gate in hooks_skill.ts (deny + redirect to skill-body --compact on a same-session repeat Skill tool call) is the closest available enforcement point, since it operates on the actual tool call rather than trying to intercept harness-internal re-injection.

  • A default (user-scope) VS Code install goes silently inert for every workspace root but the first, in a multi-root workspace. vscodePathAllowed/preToolPathDeclined (vscode_path_gate.ts) confine a hook's pre-approval stat/read to getCwd(event), the cwd VS Code's own hook payload carries. SOURCED (not dogfooded — no live multi-root capture was taken) from the installed VS Code 1.137.0 bundle, resources/app/out/vs/workbench/workbench.desktop.main.js, PromptsService.computeHooks: for every hook file w it discovers, it computes l = this.workspaceService.getWorkspace().folders[0] once per hook-list refresh, then H = (this.workspaceService.getWorkspaceFolder(w.uri) ?? l)?.uri and passes H as the default cwd for any hook definition in that file with no cwd of its own — which is every hook token-goat installs (copilot_cli_install.ts never writes a cwd key). Default install --vscode (no --project) writes to the user-scope hooks directory (~/.copilot/hooks, vscode_install.ts's vscodeHooksDir), which sits under the home directory and is therefore never inside any workspace folder — so getWorkspaceFolder(w.uri) is undefined for it regardless of how many roots are open, and H collapses to folders[0] for the whole session. In a single-root workspace folders[0] is the only root, so this is unobservable there. In a multi-root workspace it means every hook invocation gets cwd = folders[0]'s path even when the tool call concerns a file in folders[1..n]: vscodePathAllowed then correctly reports those files as outside the (wrong) root, and vscodePathDeclined makes every pre-approval handler (hooks_read.ts, hooks_write.ts, image_shrink.ts) passOutput() on them. This fails closed, not open — no path outside the intended root is ever stat'd or read, so the security boundary itself holds — but it silently disables token-goat's read-hint, image-shrink, and edit-interception hooks for every non-first root for the life of the session. A project-scope install (install --vscode --project, one .github/hooks per root) is not affected, because each root's own hooks file resolves getWorkspaceFolder(w.uri) to that same root correctly. No fix is shipped here: the miscomputation is inside VS Code's own bundle, token-goat only reads whatever cwd it is handed, and the only lever available (steering multi-root users toward a per-root project-scope install) is a documentation change beyond this note's scope, not a code change to the confinement gate itself.