pi-better-subagents 0.28.1 → 0.29.0

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/README.md CHANGED
@@ -18,7 +18,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
18
18
  - Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
19
19
  - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
20
20
  - Live background-work navigator for active runs.
21
- - Harness-owned run timing: every run gets a no-progress wake (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
21
+ - Harness-owned run timing: every run gets independent factual alerts for a tool call left open (5 min) and for no progress (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`, globally in `config.json` / `PI_SUBAGENT_*_MINUTES`, or in `/subagents settings`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-tool-wait-stuck).
22
22
 
23
23
  Every single or batch launch automatically joins one shared supervision watcher in the
24
24
  foreground Pi process. The last active run's exit or stop tears it down; a later
@@ -80,8 +80,10 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
80
80
 
81
81
  The user config sets `delegationMode` to `manual`, `adaptive` (default), or
82
82
  `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
83
- for delegation mode, the concurrent-subagent cap (default 6), and the default
84
- skill exposure. Skill exposure cycles between Discover automatically and No skill
83
+ for delegation mode, the concurrent-subagent cap (default 6), the tool-wait
84
+ alert (default 5 minutes), the no-progress alert (default 10 minutes), and the
85
+ default skill exposure. The two time values are edited independently; `0` turns
86
+ one alert off. Skill exposure cycles between Discover automatically and No skill
85
87
  catalog. The Selected skills row opens the same searchable checkbox picker used
86
88
  by `/agents`: it lists loaded skills by name and description, Space toggles one,
87
89
  Enter applies, and typing filters without dropping checked items. Saved paths
@@ -89,25 +91,26 @@ missing from discovery stay visible as unavailable and survive apply. Zero
89
91
  checked applies No skill catalog, not discovery. Manual Add skill path remains
90
92
  available. The page names whether the current value comes from the saved config
91
93
  or this session. The session choice controls the next launch before Ctrl+S, and
92
- edits persist across reloads. Ctrl+S saves mode, cap, and skill exposure as
93
- defaults, and Reset to defaults clears session overrides, including the skill
94
- list. Agents opens the same catalog as `/agents`; a definition that inherits
94
+ edits persist across reloads. Ctrl+S saves mode, cap, timing alerts, and skill
95
+ exposure as defaults, and Reset to defaults clears session overrides, including
96
+ the skill list. Agents opens the same catalog as `/agents`; a definition that inherits
95
97
  skill exposure shows whether the live value comes from this session, saved
96
98
  config, or discovery, and an invalid draft is marked invalid rather than shown
97
- as discovery. `/subagents mode manual|adaptive|coordinator` and
98
- `/subagents cap <number>` are command equivalents; `/subagents save` persists
99
+ as discovery. `/subagents mode manual|adaptive|coordinator`,
100
+ `/subagents cap <number>`, `/subagents tool-wait <minutes>`, and
101
+ `/subagents stuck <minutes>` are command equivalents; `/subagents save` persists
99
102
  the current settings. Lowering the cap blocks new single and batch launches, including launches
100
103
  still preparing, without stopping running work. Saved configuration changes are
101
104
  picked up on subsequent reads; explicit session overrides still take precedence.
102
105
  Before every model request, including continuations after tool calls,
103
106
  the foreground receives one temporary settings block with the current mode, cap,
104
- setting sources, revision, and running/reserved/available slots. The latest block
107
+ timing alerts, setting sources, revision, and running/reserved/available slots. The latest block
105
108
  replaces older snapshots and delegation guidance; it is not saved as conversation
106
109
  history. Changes reach the model at its next request, not during an in-flight
107
110
  response, and are not broadcast to running children. The cap is a ceiling, not a
108
111
  target number of agents. `subagent_settings` inspects the same effective state
109
- without changing it. Its revision is a stable fingerprint of mode, cap, and
110
- sources; occupancy changes do not change the revision. Admission rechecks capacity
112
+ without changing it. Its revision is a stable fingerprint of mode, cap, timing
113
+ alerts, and sources; occupancy changes do not change the revision. Admission rechecks capacity
111
114
  when spawning because the snapshot can become stale.
112
115
 
113
116
  The navigator's `main` row retains its mode-only controls:
@@ -122,7 +125,8 @@ Saved defaults live in global `~/.pi/agent/settings.json` under
122
125
  `piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
123
126
  reinstalls and upgrades. The old user config migrates on first use. Global values
124
127
  override the package's `config.json`, which remains a compatibility fallback.
125
- Save existing mode, cap, and skill choices with `/subagents save` or Ctrl+S.
128
+ Save existing mode, cap, timing-alert, and skill choices with `/subagents save`
129
+ or Ctrl+S.
126
130
  Discovery is saved as `defaultSkills: null`, which clears a previously saved
127
131
  path list. Put other
128
132
  custom config keys in `piBetterHarness.subagents` as well; edits made only inside
package/batch.mjs CHANGED
@@ -105,6 +105,7 @@ export function mergeJobOptions(shared, job) {
105
105
  deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
106
106
  grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
107
107
  max_minutes: job.max_minutes ?? shared?.max_minutes,
108
+ tool_wait_minutes: job.tool_wait_minutes ?? shared?.tool_wait_minutes,
108
109
  stuck_minutes: job.stuck_minutes ?? shared?.stuck_minutes,
109
110
  // A per-job agent or role replaces the shared selector pair. Mixing
110
111
  // shared.agent with job.role would invent an ambiguous run.
package/config.ts CHANGED
@@ -17,7 +17,7 @@ import { SELF_SPEC } from "./extensions.ts";
17
17
  import { installedPackage } from "./child-dependencies.mjs";
18
18
  import { isDelegationMode, type DelegationMode } from "./delegation.ts";
19
19
  import { normalizeSkillExposure } from "./skills.ts";
20
- import type { TimingSettings } from "./timing.ts";
20
+ import { validatedTimingMinutes, type TimingSettings } from "./timing.ts";
21
21
  import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
22
22
 
23
23
  export interface SubagentConfig extends TimingSettings {
@@ -197,12 +197,19 @@ export function writeSubagentSettings(
197
197
  maxConcurrent: number;
198
198
  /** Omit to preserve the saved value; `null` explicitly records discovery. */
199
199
  defaultSkills?: string[] | null;
200
+ /** Omit to preserve the saved value. `0` disables that alert. */
201
+ toolWaitMinutes?: number;
202
+ /** Omit to preserve the saved value. `0` disables that alert. */
203
+ stuckMinutes?: number;
200
204
  },
201
205
  path = configPath(),
202
206
  ): void {
203
207
  if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
204
208
  if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
205
- const next: { delegationMode: DelegationMode; maxConcurrent: number; defaultSkills?: string[] | null } = {
209
+ const next: {
210
+ delegationMode: DelegationMode; maxConcurrent: number; defaultSkills?: string[] | null;
211
+ toolWaitMinutes?: number; stuckMinutes?: number;
212
+ } = {
206
213
  delegationMode: settings.delegationMode,
207
214
  maxConcurrent: settings.maxConcurrent,
208
215
  };
@@ -218,6 +225,12 @@ export function writeSubagentSettings(
218
225
  next.defaultSkills = skills;
219
226
  }
220
227
  }
228
+ if (settings.toolWaitMinutes !== undefined) {
229
+ next.toolWaitMinutes = validatedTimingMinutes(settings.toolWaitMinutes, "toolWaitMinutes");
230
+ }
231
+ if (settings.stuckMinutes !== undefined) {
232
+ next.stuckMinutes = validatedTimingMinutes(settings.stuckMinutes, "stuckMinutes");
233
+ }
221
234
  writeConfigSettings(next, path);
222
235
  }
223
236
 
package/docs/usage.md CHANGED
@@ -19,9 +19,11 @@ Set `delegationMode` in the user config described under
19
19
  `coordinator` (default `adaptive`). This controls foreground delegation guidance,
20
20
  not child permissions or catalog definitions. `/subagents settings` (or simply
21
21
  `/subagents`) opens the terminal settings page with mode, concurrent-subagent
22
- cap, and default skill-exposure controls, an Agents shortcut to `/agents`, and
23
- Reset to defaults. The page uses the same selected-row and active-cell styling
24
- as `/sandbox`, with one editable value column. Skill exposure cycles between
22
+ cap, tool-wait alert, no-progress alert, and default skill-exposure controls, an
23
+ Agents shortcut to `/agents`, and Reset to defaults. The two time values are
24
+ edited independently in minutes; `0` turns one alert off. The page uses the same
25
+ selected-row and active-cell styling as `/sandbox`, with one editable value
26
+ column. Skill exposure cycles between
25
27
  Discover automatically and No skill catalog. The Selected skills row opens the
26
28
  shared searchable checkbox picker, which lists loaded skills by name and
27
29
  description, uses Space to toggle, Enter to apply, and Esc to cancel. Typing
@@ -33,15 +35,18 @@ absolute and exist. Invalid input stays in the editor with an explanation rather
33
35
  than being dropped.
34
36
  Edits automatically persist for this session, including across reloads; Escape
35
37
  closes the page without undoing them.
36
- Enter edits the cap as a positive whole number; Escape cancels an unfinished edit.
37
- Ctrl+S saves mode, cap, and skill exposure as defaults. Reset to defaults restores
38
- all three from the saved config. Sandbox permissions remain in `/sandbox`.
38
+ Enter edits the cap as a positive whole number or a timing value in minutes;
39
+ Escape cancels an unfinished edit. Ctrl+S saves mode, cap, timing alerts, and
40
+ skill exposure as defaults. Reset to defaults restores them from the saved
41
+ config. Sandbox permissions remain in `/sandbox`.
39
42
 
40
43
  Command equivalents also work outside the terminal UI:
41
44
 
42
45
  ```text
43
46
  /subagents mode manual|adaptive|coordinator
44
47
  /subagents cap 6
48
+ /subagents tool-wait 5
49
+ /subagents stuck 10
45
50
  /subagents save
46
51
  /subagents reset
47
52
  ```
@@ -51,8 +56,9 @@ below the running count leaves existing work untouched and blocks new admissions
51
56
  until capacity becomes available. Slots already reserved by an in-flight launch
52
57
  remain admitted. Settings apply to this parent Pi process, not
53
58
  all Pi sessions on the machine. Saving preserves unrelated config keys and
54
- clears the mode, cap, and skill session overrides. The command form asks for confirmation when a UI
55
- is available. Reset restores saved defaults without changing config.
59
+ clears the mode, cap, timing-alert, and skill session overrides. The command form
60
+ asks for confirmation when a UI is available. Reset restores saved defaults
61
+ without changing config.
56
62
 
57
63
  `/reload` retains session overrides; new sessions use config, while resuming or
58
64
  navigating a branch restores its settings. On the navigator `main` sheet, `m`
@@ -106,9 +112,9 @@ thresholds continue to take precedence for subagent health.
106
112
 
107
113
  | Tool | Blocks? | What it does |
108
114
  |------|---------|--------------|
109
- | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
115
+ | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-tool-wait-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `tool_wait_minutes`, `stuck_minutes`. |
110
116
  | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
111
- | `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
117
+ | `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, `toolWaitMinutes`, `stuckMinutes`, per-setting `sources`/`timingSources` (`environment`, `session`, `config`, or `default`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. Timing values already account for the same environment precedence a launch uses. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
112
118
  | `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. Abandoned launch records are reported separately and are never counted as runs. |
113
119
  | `subagent_output` | never | Bounded current-session excerpt (default 1 KiB / 10 lines). Params: `id`, `lines` (`tail_lines` is a deprecated alias), `cursor` (a returned `nextCursor`, `statusCursor`, or `incidentCursor`), `max_bytes` (max 4 KiB; raw 16 KiB default, 64 KiB max), `mode` (`raw` pages retained log bytes), `tail` (raw mode: start from the newest retained byte and page backwards; the final step returns an append-ready cursor), `include` (`["cost"]`, `["tools"]`, or both: opt-in spend and tool-count lines), `all` (foreign-session id). Missing/unreadable logs are gaps, not empty healthy output. |
114
120
  | `subagent_result` | never | Finished-run answer for the current session (2048-byte page). Params: `id`, `cursor` (a returned `nextCursor` continues the answer; `statusCursor` / `incidentCursor` also accepted), `max_bytes` (maximum 8192 bytes), `lines` (optional line cap per answer page), `mode` (`raw`), `tail` (raw mode: newest bytes first), `include` (`["cost"]`, `["tools"]`, or both), `all` (foreign-session id). Failures and exceptional lifecycle facts come before progress; no tool-name histories. TUI folding is display-only. |
@@ -272,21 +278,22 @@ completion callbacks with `subagent_result`; do not poll or keep a script open
272
278
  waiting for completion. Callbacks and capacity/catalog guarantees remain owned
273
279
  by the existing harness runtime.
274
280
 
275
- ## Run timing (deadline, ceiling, stuck)
281
+ ## Run timing (deadline, ceiling, tool wait, stuck)
276
282
 
277
283
  Timeout control belongs to the harness, not to the prompt or the skill that
278
284
  launched the run. A time limit written into a prompt is enforced by nothing, and
279
285
  a parent that only notices late tends to kill a child that was still making
280
- progress. Every run gets stall detection by default. Elapsed-time limits are
281
- opt-in because total runtime does not distinguish a slow agent from a stalled
282
- one.
286
+ progress. Every run gets a tool-wait alert and stall detection by default.
287
+ Elapsed-time limits are opt-in because total runtime does not distinguish a slow
288
+ agent from a stalled one.
283
289
 
284
290
  | Control | Default | What happens |
285
291
  |---------|---------|--------------|
286
292
  | Soft deadline (`deadline_minutes`) | Off | When configured, the child gets one steering message (delivered through Pi's steer queue after its current tool call finishes): stop starting new work, commit or save what is done, and report what is complete, what is not, and where the work is. The parent gets one wake saying so. |
287
293
  | Grace (`grace_minutes`) | 5 | Grace starts when the steering message actually reaches the child, which is after its current tool call. While the message is still waiting behind a running tool call, the deadline stop is held, so a test run that began just before the deadline is not killed mid-run. If the child has not finished by the end of grace, the harness stops it; the ordinary completion callback reports `killed; stopped: deadline`. A child that completes inside grace is not stopped; its surfaces say `deadline: finished in grace`. |
288
294
  | Hard ceiling (`max_minutes`) | Off | When configured, the run is stopped at once, without grace or a steer, and reported as `stopped: ceiling`. The ceiling bounds the run, including a tool call that never ends and an orphaned run (child gone, its process group still alive). |
289
- | Stuck window (`stuck_minutes`) | 10 | No progress (see below) for this long wakes the parent once (`stuck`). It never stops the run. After new progress, a later stuck spell wakes again. |
295
+ | Tool-wait window (`tool_wait_minutes`) | 5 | One tool call that stays open this long sends one factual parent wake for that call, including when it is a normal long test. Parallel calls alert independently. The alert never stops, cancels, or restarts the run, and a later call can alert on its own. |
296
+ | Stuck window (`stuck_minutes`) | 10 | No progress (see below) for this long wakes the parent once (`stuck`). It never stops the run. After new progress, a later stuck spell wakes again. Time inside a running tool call is excluded, so tool waiting and no-progress are reported separately. |
290
297
 
291
298
  `0` turns a control off. `null` or an omitted value means "inherit": on
292
299
  `subagent_spawn` that is the configured default; on a `subagent_spawn_batch` job
@@ -301,13 +308,14 @@ may be fractional. A job's own number (including `0`) wins over `shared`.
301
308
  hung tool call is never delivered, the deadline stop stays held, and the run
302
309
  is never stopped by that deadline. Opt into a ceiling to bound the whole run.
303
310
  - The parent reads at most the last 32 MiB of a child log after `/reload`. It
304
- also records the call it last saw open in the run's metadata on each
311
+ also records the calls it last saw open in the run's metadata on each
305
312
  supervision tick, so a reload normally keeps the hold and the not-stuck
306
313
  accounting even when the call's start is outside that window. The record is
307
314
  written by the tick, so a call that started less than one tick (15 s) before
308
315
  the reload is not covered; and a record whose call ended while the window was
309
316
  lost keeps the hold, and keeps the run from being reported stuck, until the
310
- next observed tool call starts. Opt into a ceiling when the run needs a hard
317
+ next observed turn proves that batch ended (a newer retained message followed
318
+ by its tool call start). Opt into a ceiling when the run needs a hard
311
319
  wall-clock bound.
312
320
  - The child confirms delivery by matching the steer's exact text in its
313
321
  conversation. If another extension rewrites user input (an input-transform
@@ -329,7 +337,9 @@ long ago counts again. Time the child spends waiting on a running tool call does
329
337
  stuck window, so a child in the middle of a 20-minute test run is waiting, not
330
338
  stuck — including after `/reload`: the call the parent saw open is stored in the
331
339
  run's metadata, so a bounded log read that no longer contains its start does not
332
- turn it into "no progress". A hanging command can be bounded by the sandbox command time limit; the run
340
+ turn it into "no progress". That same open-call evidence drives the independent
341
+ tool-wait alert: each call alerts once after its configured window, and the
342
+ durable marker survives `/reload`. A hanging command can be bounded by the sandbox command time limit; the run
333
343
  ceiling separately bounds the whole run.
334
344
  The other stuck signal is the existing escalation: the same operation failing
335
345
  three times wakes the parent once as an `Action required` incident
@@ -349,11 +359,13 @@ example it crashed or a user stopped it), `stopped: ceiling`, or `stuck`. The sp
349
359
  | Soft deadline | `PI_SUBAGENT_DEADLINE_MINUTES` | `deadlineMinutes` |
350
360
  | Grace | `PI_SUBAGENT_GRACE_MINUTES` | `graceMinutes` |
351
361
  | Hard ceiling | `PI_SUBAGENT_MAX_MINUTES` | `maxMinutes` |
362
+ | Tool-wait window | `PI_SUBAGENT_TOOL_WAIT_MINUTES` | `toolWaitMinutes` |
352
363
  | Stuck window | `PI_SUBAGENT_STUCK_MINUTES` | `stuckMinutes` |
353
364
 
354
365
  **Durability and delivery.** The policy and its one-shot markers (steer
355
- requested, deadline wake, stuck wake, stop reason) are stored in the run's
356
- metadata at launch, so `/reload` keeps the deadline and never repeats a wake.
366
+ requested, deadline wake, tool-wait marker per call, stuck wake, stop reason)
367
+ are stored in the run's metadata at launch, so `/reload` keeps the deadline and
368
+ never repeats a wake.
357
369
  The parent checks timing on its 15-second supervision tick. The steer travels
358
370
  through a request file in the run directory, read by a small harness extension
359
371
  loaded into every child (it registers no tools and runs no commands). When the
@@ -1,15 +1,35 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { delegationPrompt, type DelegationMode } from "./delegation.ts";
3
+ import { DEFAULT_TIMING_MINUTES } from "./timing.ts";
3
4
 
4
5
  import { EXECUTION_POLICY_TEXT, publishExecutionPolicy, supportsPromptSections } from "./shared-execution-policy.ts";
5
6
 
6
7
  export const SUBAGENT_SETTINGS_CONTEXT = "pi-better-subagents-settings";
7
8
 
9
+ export type TimingSettingSource = "environment" | "session" | "config" | "default";
10
+
11
+ export interface EffectiveTimingSettings {
12
+ toolWaitMinutes: number;
13
+ stuckMinutes: number;
14
+ sources: {
15
+ toolWaitMinutes: TimingSettingSource;
16
+ stuckMinutes: TimingSettingSource;
17
+ };
18
+ error?: string;
19
+ }
20
+
8
21
  export interface EffectiveSubagentSettings {
9
22
  revision: string;
10
23
  delegationMode: DelegationMode;
11
24
  maxConcurrent: number;
12
25
  sources: { delegationMode: "session" | "config"; maxConcurrent: "session" | "config" };
26
+ toolWaitMinutes: number;
27
+ stuckMinutes: number;
28
+ timingSources: {
29
+ toolWaitMinutes: TimingSettingSource;
30
+ stuckMinutes: TimingSettingSource;
31
+ };
32
+ timingError?: string;
13
33
  runningCount: number;
14
34
  pendingCount: number;
15
35
  occupiedSlots: number;
@@ -17,18 +37,39 @@ export interface EffectiveSubagentSettings {
17
37
  }
18
38
 
19
39
  export function effectiveSubagentSettings(
20
- settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources">,
40
+ settings: Pick<EffectiveSubagentSettings, "delegationMode" | "maxConcurrent" | "sources"> & {
41
+ timing?: EffectiveTimingSettings;
42
+ },
21
43
  runningCount: number,
22
44
  pendingCount: number,
23
45
  ): EffectiveSubagentSettings {
46
+ const timing = settings.timing ?? {
47
+ toolWaitMinutes: DEFAULT_TIMING_MINUTES.toolWait,
48
+ stuckMinutes: DEFAULT_TIMING_MINUTES.stuck,
49
+ sources: { toolWaitMinutes: "default" as const, stuckMinutes: "default" as const },
50
+ };
24
51
  const revision = createHash("sha256").update(JSON.stringify([
25
52
  settings.delegationMode, settings.maxConcurrent, settings.sources.delegationMode, settings.sources.maxConcurrent,
53
+ timing.toolWaitMinutes, timing.stuckMinutes, timing.sources.toolWaitMinutes, timing.sources.stuckMinutes,
26
54
  ])).digest("hex").slice(0, 12);
27
55
  const occupiedSlots = runningCount + pendingCount;
28
- return { ...settings, revision, runningCount, pendingCount, occupiedSlots,
56
+ return {
57
+ revision,
58
+ delegationMode: settings.delegationMode,
59
+ maxConcurrent: settings.maxConcurrent,
60
+ sources: settings.sources,
61
+ toolWaitMinutes: timing.toolWaitMinutes,
62
+ stuckMinutes: timing.stuckMinutes,
63
+ timingSources: timing.sources,
64
+ ...(timing.error ? { timingError: timing.error } : {}),
65
+ runningCount, pendingCount, occupiedSlots,
29
66
  availableSlots: Math.max(0, settings.maxConcurrent - occupiedSlots) };
30
67
  }
31
68
 
69
+ function alertMinutes(value: number): string {
70
+ return value === 0 ? "off" : `${value}m`;
71
+ }
72
+
32
73
  export function formatSubagentSettings(settings: EffectiveSubagentSettings): string {
33
74
  const manual = settings.delegationMode === "manual";
34
75
  const capacity = manual
@@ -43,6 +84,9 @@ export function formatSubagentSettings(settings: EffectiveSubagentSettings): str
43
84
  `Subagent settings: revision ${settings.revision}`,
44
85
  `Delegation: ${settings.delegationMode} (${settings.sources.delegationMode})`,
45
86
  `Concurrency limit: ${settings.maxConcurrent} (${settings.sources.maxConcurrent})`,
87
+ `Timing alerts: tool wait ${alertMinutes(settings.toolWaitMinutes)} (${settings.timingSources.toolWaitMinutes}); ` +
88
+ `no progress ${alertMinutes(settings.stuckMinutes)} (${settings.timingSources.stuckMinutes}).`,
89
+ ...(settings.timingError ? [`Timing alert settings error: ${settings.timingError}`] : []),
46
90
  // Mode first: the policy governs the settings that follow it.
47
91
  delegationPrompt(settings.delegationMode),
48
92
  capacity + " Spawn admission rechecks capacity; lower the limit without stopping existing runs.",
@@ -76,7 +120,7 @@ export interface PromptSectionTarget {
76
120
  * render in publication order, so Background Tasks and Goal publish after this one;
77
121
  * naming its own section keeps the sentence true whatever the load order.
78
122
  */
79
- const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode and cap. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Live occupancy is not pushed into context: inspect subagent_settings when it matters, and never treat the concurrency limit as a target number of agents.";
123
+ const SUBAGENT_DELEGATION_NOTE = "Treat the Subagent settings block in this section as the authoritative delegation mode, cap, and timing-alert settings. Its delegation guidance replaces earlier mode-specific guidance, including guidance in a plan. Live occupancy is not pushed into context: inspect subagent_settings when it matters, and never treat the concurrency limit as a target number of agents.";
80
124
 
81
125
  export function publishSubagentSettings<T extends object>(options: T, settings: EffectiveSubagentSettings): T {
82
126
  // Note first, block last inside the section: the note introduces the block it
@@ -92,12 +136,15 @@ export function subagentSettingsTool(Type: any, read: () => EffectiveSubagentSet
92
136
  return {
93
137
  name: "subagent_settings",
94
138
  label: "Subagent Settings",
95
- description: "Inspect effective subagent delegation mode, concurrency limit, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
139
+ description: "Inspect effective subagent delegation mode, concurrency limit, tool-wait and no-progress alert times, setting sources, revision, and running/reserved/available slots. Read-only; does not change settings or launch work. The limit is a ceiling, not a target.",
96
140
  parameters: Type.Object({}),
97
141
  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
98
142
  outputSchema: Type.Object({
99
143
  revision: Type.String(), delegationMode: Type.String(), maxConcurrent: Type.Number({ minimum: 1, multipleOf: 1 }),
100
144
  sources: Type.Object({ delegationMode: Type.String(), maxConcurrent: Type.String() }),
145
+ toolWaitMinutes: Type.Number({ minimum: 0 }), stuckMinutes: Type.Number({ minimum: 0 }),
146
+ timingSources: Type.Object({ toolWaitMinutes: Type.String(), stuckMinutes: Type.String() }),
147
+ timingError: Type.Optional(Type.String()),
101
148
  runningCount: Type.Number({ minimum: 0, multipleOf: 1 }), pendingCount: Type.Number({ minimum: 0, multipleOf: 1 }),
102
149
  occupiedSlots: Type.Number({ minimum: 0, multipleOf: 1 }), availableSlots: Type.Number({ minimum: 0, multipleOf: 1 }),
103
150
  }),