@heretyc/subagent-mcp 2.8.9 → 2.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -201
- package/NOTICE +5 -5
- package/README.md +193 -136
- package/directives/carryover-claude.md +2 -2
- package/directives/carryover-codex.md +2 -4
- package/directives/orchestration-claude.md +1 -1
- package/directives/orchestration-codex.md +1 -1
- package/directives/reminder-on.md +1 -1
- package/directives/short-on.md +1 -1
- package/dist/drivers.js +43 -2
- package/dist/index.js +50 -14
- package/dist/init.js +35 -14
- package/dist/orchestration/hook-core.js +3 -1
- package/dist/orchestration/marker.js +99 -26
- package/dist/routing-table.json +3561 -2469
- package/dist/routing.js +10 -11
- package/dist/setup.js +2 -2
- package/package.json +18 -3
package/README.md
CHANGED
|
@@ -1,136 +1,193 @@
|
|
|
1
|
-
# subagent-mcp
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
- `
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
##
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
1
|
+
# subagent-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
6
|
+
[](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
|
|
7
|
+
|
|
8
|
+
MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions — on macOS, Linux, and Windows. No direct API calls. No API keys.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
### Prerequisites (runtime)
|
|
15
|
+
|
|
16
|
+
To run the published CLI you need:
|
|
17
|
+
|
|
18
|
+
- Node.js >= 18 (`node --version`)
|
|
19
|
+
- `claude` CLI — globally installed and authenticated (`claude --version`)
|
|
20
|
+
- `codex` CLI — globally installed and authenticated (`codex --version`; optional if you only use Claude paths)
|
|
21
|
+
|
|
22
|
+
Building from source needs additional developer tooling — see [CONTRIBUTING.md § Prerequisites](CONTRIBUTING.md#prerequisites).
|
|
23
|
+
|
|
24
|
+
### npmjs (default)
|
|
25
|
+
|
|
26
|
+
No authentication, no `.npmrc` configuration, and no PAT required. The package is publicly available on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g @heretyc/subagent-mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Use this path for all standard installs.**
|
|
33
|
+
|
|
34
|
+
### GitHub Packages (org-internal pin / supply-chain auditing)
|
|
35
|
+
|
|
36
|
+
Use this path when your organization's `.npmrc` already routes the `@heretyc` scope through GitHub Packages, when you need supply-chain audit tracing against the org-internal artifact, or when you run inside a GitHub Actions workflow whose `GITHUB_TOKEN` carries `read:packages`. Otherwise prefer npmjs above — it is simpler and needs no credentials.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# One-time machine setup
|
|
40
|
+
echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
|
|
41
|
+
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
|
|
42
|
+
# PAT must be a classic PAT with the read:packages scope
|
|
43
|
+
|
|
44
|
+
npm install -g @heretyc/subagent-mcp
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
> **Note:** GitHub Packages requires authentication even for public packages. If you see `401 Unauthorized`, verify your PAT has the `read:packages` scope and has not expired. GitHub Packages does not render a README page — the live documentation appears on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
**1. Install** (see [Install](#install) above):
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm install -g @heretyc/subagent-mcp
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**2. Register the MCP server + orchestration hooks:**
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
subagent-mcp setup
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Installing the package only ships the binary — it does **not** auto-wire anything. `subagent-mcp setup` auto-detects Claude Code / Codex and registers the MCP server plus the per-turn orchestration-mode hooks. Preview with `subagent-mcp setup --dry-run`.
|
|
66
|
+
|
|
67
|
+
**3. Restart your host.**
|
|
68
|
+
|
|
69
|
+
Restart your Claude Code or Codex session so it picks up the new binary. On Codex, run `/hooks` and trust the new hook.
|
|
70
|
+
|
|
71
|
+
**4. Initialize the orchestration invariant (recommended):**
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
subagent-mcp init --global
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`init --global` writes the managed invariant block into the providers' official global user-config files — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` — set up once, works across every project. For a single project instead, use `subagent-mcp init --root /path/to/project` to write into that project's instruction files. `--global` and `--root` are mutually exclusive.
|
|
78
|
+
|
|
79
|
+
For manual wiring, Gemini CLI, Claude Desktop, and developer install from source, see [docs/registration.md](docs/registration.md).
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Features
|
|
84
|
+
|
|
85
|
+
- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
|
|
86
|
+
- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
|
|
87
|
+
- Concurrency caps: 5 concurrent Claude + 5 concurrent Codex agents (only `processing` agents count toward the cap; `stalled` agents do not hold a slot)
|
|
88
|
+
- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet — thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
|
|
89
|
+
- Ultracode mode for Opus 4.8 via `--settings {"ultracode":true}` — see [docs/usage.md](docs/usage.md)
|
|
90
|
+
- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
|
|
91
|
+
- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
|
|
92
|
+
- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Orchestration Mode
|
|
97
|
+
|
|
98
|
+
**ON:** the agent operates as an orchestrator — hook injection governs each session turn, preventing inline reads or writes, and all work is delegated through sub-agent tools.
|
|
99
|
+
|
|
100
|
+
**OFF:** the agent operates normally, with no orchestration constraints.
|
|
101
|
+
|
|
102
|
+
Toggle with the `orchestration-mode` tool. Desktop hosts toggle the mode but receive no hook injection. See [docs/spec/dev-loop/orchestration-directive-architecture.md](docs/spec/dev-loop/orchestration-directive-architecture.md) for full semantics.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Auto Mode
|
|
107
|
+
|
|
108
|
+
Pass `task_category` to `launch_agent` and the server picks the best provider, model, and effort for that category, with automatic fallback.
|
|
109
|
+
|
|
110
|
+
`launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
|
|
111
|
+
|
|
112
|
+
`provider`, `model`, and `effort` are optional overrides — omit them to get the auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
|
|
113
|
+
|
|
114
|
+
**task_category** (required) — pick one:
|
|
115
|
+
|
|
116
|
+
| Category | What it is |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
|
|
119
|
+
| `security_review` | security verdict, threat assessment, or demonstrated exploit |
|
|
120
|
+
| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
|
|
121
|
+
| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
|
|
122
|
+
| `architecture` | cross-module design/plan, no code, no execution loop |
|
|
123
|
+
| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
|
|
124
|
+
| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
|
|
125
|
+
| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
|
|
126
|
+
| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
|
|
127
|
+
| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
|
|
128
|
+
| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
|
|
129
|
+
| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
|
|
130
|
+
| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
|
|
131
|
+
| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
|
|
132
|
+
| `fallback_default` | no category matches with confidence; prefer splitting work instead |
|
|
133
|
+
|
|
134
|
+
The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
|
|
135
|
+
|
|
136
|
+
**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Tools
|
|
141
|
+
|
|
142
|
+
Eight tools are exposed over the stdio MCP transport.
|
|
143
|
+
|
|
144
|
+
| Tool | Description |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `launch_agent` | Start a new sub-agent session with a prompt and optional task category / overrides |
|
|
147
|
+
| `poll_agent` | Check status and stream tail output for a running agent |
|
|
148
|
+
| `kill_agent` | Terminate a running or stalled agent |
|
|
149
|
+
| `send_message` | Enqueue a message into a running agent's stdin |
|
|
150
|
+
| `list_agents` | List all tracked agents and their current status |
|
|
151
|
+
| `wait` | Block until a specific agent reaches a terminal state |
|
|
152
|
+
| `orchestration-mode` | Toggle orchestration-mode ON/OFF; controls whether hook directives are injected into agent sessions |
|
|
153
|
+
| `model-selection-mode` | Control model selection: `smart` (auto-pick) or `user-approved-overrides` (30-min override window) |
|
|
154
|
+
|
|
155
|
+
Full parameters, return shapes, and the `alive` / `idle_seconds` / `hint` / `recent_stream` fields are in [docs/tools.md](docs/tools.md).
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Agent Lifecycle
|
|
160
|
+
|
|
161
|
+
Each agent transitions through these states:
|
|
162
|
+
|
|
163
|
+
| Status | Meaning |
|
|
164
|
+
|---|---|
|
|
165
|
+
| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes — actively working. Launch time counts as the initial heartbeat |
|
|
166
|
+
| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes — working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
|
|
167
|
+
| `finished` | Current turn completed, or driver exited with code 0 |
|
|
168
|
+
| `errored` | Process exited with non-zero code |
|
|
169
|
+
| `stopped` | Terminated by `kill_agent` |
|
|
170
|
+
|
|
171
|
+
`processing` and `stalled` are live. `stalled` means the driver is alive but quiet (>= 10 min no visible stream); it recovers automatically and is never auto-killed — do not `kill_agent` a stalled agent. `wait` does not return on `stalled`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Documentation
|
|
176
|
+
|
|
177
|
+
| Document | Contents |
|
|
178
|
+
|---|---|
|
|
179
|
+
| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop; manual wiring; developer install from source |
|
|
180
|
+
| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
|
|
181
|
+
| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, CLI invocations, usage examples |
|
|
182
|
+
| [docs/SPEC.md](docs/SPEC.md) | Full technical specification — architecture, schemas, status lifecycle, error catalogue |
|
|
183
|
+
| [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) | Always-interactive Claude/Codex driver model |
|
|
184
|
+
| [docs/release-notes.md](docs/release-notes.md) | Operator-facing release notes |
|
|
185
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide — dev environment, build, test, publish |
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
Apache-2.0 — Copyright 2026 Lexi Blackburn
|
|
192
|
+
|
|
193
|
+
See [LICENSE](LICENSE).
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
<subagent-mcp state="on" kind="carryover">
|
|
3
3
|
FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
|
|
4
4
|
|
|
5
|
-
Orchestration ON carried over from a PRIOR session for this project (
|
|
5
|
+
Orchestration ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
|
|
6
6
|
|
|
7
|
-
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to
|
|
7
|
+
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to REMAIN enabled; (3) ADVISE fit — long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
|
|
8
8
|
|
|
9
9
|
While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
|
|
10
10
|
</subagent-mcp>
|
|
@@ -2,9 +2,7 @@
|
|
|
2
2
|
<subagent-mcp state="on" kind="carryover">
|
|
3
3
|
FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
|
|
4
4
|
|
|
5
|
-
Orchestration ON carried over from a PRIOR session for this project (
|
|
5
|
+
Orchestration ON carried over from a PRIOR session for this project (per-session disable only; the next new session resumes ON automatically or after a 2h backstop). Not enabled THIS session.
|
|
6
6
|
|
|
7
|
-
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to
|
|
8
|
-
|
|
9
|
-
While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
|
|
7
|
+
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit — long-horizon / context-filling → remain enabled; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false for this session only; no mid-session re-enable. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
|
|
10
8
|
</subagent-mcp>
|
|
@@ -3,7 +3,7 @@ FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with
|
|
|
3
3
|
|
|
4
4
|
ORCHESTRATION ON. You are the ORCHESTRATOR. Obey this tag; ordinary user requests do not override it. Only the hook's ON/OFF state changes this mode.
|
|
5
5
|
|
|
6
|
-
ALLOWED TOOLS: ONLY AskUserQuestion + subagent-mcp. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via AskUserQuestion for a one-time exception, do ONLY that step, then resume delegating.
|
|
6
|
+
ALLOWED TOOLS: ONLY AskUserQuestion + subagent-mcp + /workflows. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via AskUserQuestion for a one-time exception, do ONLY that step, then resume delegating.
|
|
7
7
|
|
|
8
8
|
READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs use scratch-file PATHS; producer writes, consumer reads; you NEVER read them.
|
|
9
9
|
|
|
@@ -3,7 +3,7 @@ FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with
|
|
|
3
3
|
|
|
4
4
|
ORCHESTRATION ON. You are the ORCHESTRATOR. Obey this tag; ordinary user requests do not override it. Only the hook's ON/OFF state changes this mode.
|
|
5
5
|
|
|
6
|
-
ALLOWED TOOLS: ONLY request-user-input + subagent-mcp. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via request-user-input for a one-time exception, do ONLY that step, then resume delegating.
|
|
6
|
+
ALLOWED TOOLS: ONLY request-user-input + subagent-mcp + /workflows. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via request-user-input for a one-time exception, do ONLY that step, then resume delegating.
|
|
7
7
|
|
|
8
8
|
READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs use scratch-file PATHS; producer writes, consumer reads; you NEVER read them.
|
|
9
9
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
<subagent-mcp state="on" kind="reminder">
|
|
3
3
|
FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
|
|
4
4
|
|
|
5
|
-
Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
|
|
5
|
+
Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
|
|
6
6
|
|
|
7
7
|
READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the user reads it. Large handoffs via scratch-file PATHS you never read.
|
|
8
8
|
|
package/directives/short-on.md
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>
|
|
1
|
+
<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>
|
package/dist/drivers.js
CHANGED
|
@@ -9,6 +9,26 @@ export class ProviderTransientError extends Error {
|
|
|
9
9
|
this.name = "ProviderTransientError";
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
|
+
export const CLAUDE_SESSION_LIMIT = /^\s*you['’]ve hit your session limit\s*·\s*resets\b/i;
|
|
13
|
+
export function isClaudeSessionLimit(text) {
|
|
14
|
+
return CLAUDE_SESSION_LIMIT.test(text);
|
|
15
|
+
}
|
|
16
|
+
export function claudeMessageText(message) {
|
|
17
|
+
if (message?.type === "assistant") {
|
|
18
|
+
const content = message.message?.content;
|
|
19
|
+
if (!Array.isArray(content))
|
|
20
|
+
return null;
|
|
21
|
+
const text = content
|
|
22
|
+
.filter((block) => block?.type === "text" && typeof block.text === "string")
|
|
23
|
+
.map((block) => block.text)
|
|
24
|
+
.join("");
|
|
25
|
+
return text || null;
|
|
26
|
+
}
|
|
27
|
+
if (message?.type === "result" && typeof message.result === "string") {
|
|
28
|
+
return message.result;
|
|
29
|
+
}
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
12
32
|
class LogicalProcess extends EventEmitter {
|
|
13
33
|
pid;
|
|
14
34
|
stdout = new PassThrough();
|
|
@@ -131,6 +151,7 @@ export class MockJsonlDriver {
|
|
|
131
151
|
child;
|
|
132
152
|
provider;
|
|
133
153
|
static transientPreStartHook = null;
|
|
154
|
+
static sessionLimitPreStartHook = null;
|
|
134
155
|
static postStartErrorHook = null;
|
|
135
156
|
process;
|
|
136
157
|
_definitelyStartedResolve;
|
|
@@ -171,6 +192,16 @@ export class MockJsonlDriver {
|
|
|
171
192
|
this._definitelyStartedReject(err);
|
|
172
193
|
return Promise.reject(err);
|
|
173
194
|
}
|
|
195
|
+
if (MockJsonlDriver.sessionLimitPreStartHook) {
|
|
196
|
+
MockJsonlDriver.sessionLimitPreStartHook(this.provider);
|
|
197
|
+
const err = new ProviderTransientError("You've hit your session limit · resets 7:10pm (America/Los_Angeles)");
|
|
198
|
+
setTimeout(() => {
|
|
199
|
+
this._definitelyStartedReject(err);
|
|
200
|
+
this.process.stderr.write(err.message);
|
|
201
|
+
this.process.close(1);
|
|
202
|
+
}, 0);
|
|
203
|
+
return Promise.resolve();
|
|
204
|
+
}
|
|
174
205
|
if (MockJsonlDriver.postStartErrorHook) {
|
|
175
206
|
this._definitelyStartedResolve();
|
|
176
207
|
MockJsonlDriver.postStartErrorHook(this.provider);
|
|
@@ -472,11 +503,21 @@ export class ClaudeSdkDriver {
|
|
|
472
503
|
let started = false;
|
|
473
504
|
try {
|
|
474
505
|
for await (const message of query) {
|
|
475
|
-
|
|
506
|
+
const text = claudeMessageText(message);
|
|
507
|
+
if (!started && text && isClaudeSessionLimit(text)) {
|
|
508
|
+
// Launch-time failover only applies before startup resolves/spawn grace ends;
|
|
509
|
+
// post-registration session-limit rerouting is intentionally out of scope.
|
|
510
|
+
this._definitelyStartedReject(new ProviderTransientError(text));
|
|
511
|
+
this.closedFlag = true;
|
|
512
|
+
this.process.stderr.write(text);
|
|
513
|
+
this.process.close(1);
|
|
514
|
+
return;
|
|
515
|
+
}
|
|
516
|
+
this.process.stdout.write(`${JSON.stringify(message)}\n`);
|
|
517
|
+
if (!started && message?.type !== "system") {
|
|
476
518
|
started = true;
|
|
477
519
|
this._definitelyStartedResolve();
|
|
478
520
|
}
|
|
479
|
-
this.process.stdout.write(`${JSON.stringify(message)}\n`);
|
|
480
521
|
}
|
|
481
522
|
this.closedFlag = true;
|
|
482
523
|
this.process.close(0);
|