#19833: feat: contextScripts pre-spawn hook for sub-agent sessions (rebased on v2026.2.17)

## Summary Rebased version of #13965, updated for the v2026.2.17 refactor that extracted spawn logic into `subagent-spawn.ts` (`spawnSubagentDirect`). ### What changed from #13965 - **Schema**: already merged upstream — no schema changes in this PR - **Implementation**: `context-scripts.ts` unchanged - **Wiring**: hook now lives in `subagent-spawn.ts` instead of the old inline `sessions-spawn-tool.ts` - **Allowlist**: checks both original requested ID and any script-overridden ID ### Files | File | Change | |------|--------| | `src/agents/context-scripts.ts` | New — execution engine (resolve, dedupe, execute) | | `src/agents/subagent-spawn.ts` | Modified — hook after targetAgentId resolution, before allowlist | | `docs/concepts/context-scripts.md` | New — concept documentation | ### How it works 1. Before the allowlist check, resolves context scripts from both default and agent-specific config 2. Executes scripts with spawn variables (targetAgentId, task, label, etc.) 3. Scripts can prepend/append to the task and override the target agent ID 4. Allowlist validates both the original and overridden agent IDs Supersedes #13965. <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds a pre-spawn hook system ("context scripts") for sub-agent sessions, allowing scripts to inject context (identity, charters, instructions) into the task message and optionally override the target agent ID before session creation. - **New file `context-scripts.ts`**: Implements the full context script lifecycle — resolution (merge defaults + per-agent, dedupe, sort by priority), execution (local scripts via `execFile`/`spawn`, HTTP via `fetch`), and output parsing (JSON response pipeline with error detection, content extraction, agent ID override). - **Modified `subagent-spawn.ts`**: Wires the context scripts hook into `spawnSubagentDirect`, executing between target agent resolution and allowlist validation. The allowlist now checks both the original requested ID and any script-overridden ID. - **New docs `context-scripts.md`**: Comprehensive concept documentation covering configuration, variable passing, output parsing, and override resolution. - The HTTP script execution path in `context-scripts.ts` lacks a timeout (`fetch` without `AbortSignal`), which could block spawns indefinitely on unresponsive endpoints — the local script paths correctly enforce a 10-second timeout. <h3>Confidence Score: 3/5</h3> - Mostly safe to merge; the missing HTTP timeout is the main concern that should be addressed before merging. - The core logic is sound — script resolution, deduplication, priority sorting, and the spawn integration are all well-implemented. The allowlist correctly validates both original and overridden agent IDs. However, the missing timeout on HTTP fetch calls in context scripts is a real issue that could cause indefinite hangs during spawn. The outer try/catch in subagent-spawn.ts would not help since the await would never resolve. No tests are included for the new context-scripts module. - `src/agents/context-scripts.ts` — missing HTTP fetch timeout; `src/agents/subagent-spawn.ts` — minor unreachable code in allowlist error message _{Last reviewed commit: 10359fe} <!-- greptile_other_comments_section --> _{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!} <!-- /greptile_comment -->