@xzzpig/pi-subagents 0.24.1 → 0.25.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/CHANGELOG.md +28 -0
- package/bundle/agent-management.js +4 -4
- package/bundle/agents.js +3 -3
- package/bundle/child-tool-plan.js +2 -2
- package/bundle/chunk-34TUUBRN.js +1107 -0
- package/bundle/{chunk-SW2VMNIU.js → chunk-5OD3OWTE.js} +2 -2
- package/bundle/{chunk-ZWXU5SPQ.js → chunk-5YEOWNSD.js} +371 -135
- package/bundle/{chunk-EUPJB4S7.js → chunk-5Z7JAORM.js} +196 -1219
- package/bundle/{chunk-LCDJWBVM.js → chunk-66JNFRFS.js} +1 -1
- package/bundle/{chunk-6BJUEES3.js → chunk-6MNRKUHY.js} +23 -12
- package/bundle/{chunk-ED55MIC2.js → chunk-CGFF4WA3.js} +42 -19
- package/bundle/{chunk-TMHVDPYW.js → chunk-DLVPMML3.js} +263 -154
- package/bundle/chunk-HXRB42AF.js +108 -0
- package/bundle/{chunk-355ECEP2.js → chunk-IH7LQVEE.js} +29 -14
- package/bundle/{chunk-SLNMBXLL.js → chunk-IJWITCC6.js} +411 -249
- package/bundle/{chunk-RU522D5W.js → chunk-IKFKH5EL.js} +369 -50
- package/bundle/{chunk-Z6TFJ6BR.js → chunk-INWSUNI6.js} +1 -1
- package/bundle/{chunk-JEA2ZKUA.js → chunk-IUDEI6FJ.js} +35 -200
- package/bundle/{chunk-WW76JRIX.js → chunk-JAXVBXGF.js} +1 -1
- package/bundle/{chunk-ICNYIALB.js → chunk-JH5H4CYJ.js} +784 -474
- package/bundle/{chunk-35GII5EF.js → chunk-JWFLPSTP.js} +41 -117
- package/bundle/{chunk-LMGQAJ3O.js → chunk-KCJFGKVK.js} +350 -123
- package/bundle/{chunk-RB4GELQA.js → chunk-LPJEKHOY.js} +1 -1
- package/bundle/chunk-LYKG4FKH.js +523 -0
- package/bundle/{chunk-X6LOM3Z4.js → chunk-LZ3HBDTR.js} +161 -78
- package/bundle/{chunk-FG6SQJAR.js → chunk-OGPOCGWX.js} +24 -6
- package/bundle/{chunk-Y6H2G6KX.js → chunk-OSVXFWPG.js} +67 -30
- package/bundle/{chunk-FJWI64H7.js → chunk-RMSABUN3.js} +27 -13
- package/bundle/{chunk-H36HBZB2.js → chunk-SJPABBZG.js} +2 -2
- package/bundle/{chunk-3U633XDZ.js → chunk-U3ZDUUTM.js} +11 -3
- package/bundle/{chunk-LVWU2HOO.js → chunk-ULGMXABL.js} +16 -7
- package/bundle/{chunk-WPW4V6HM.js → chunk-W7ZA6TYD.js} +2 -2
- package/bundle/{chunk-V2KFIGFH.js → chunk-XAC2XNAP.js} +503 -304
- package/bundle/{chunk-TGLFTQWJ.js → chunk-YWXILP5N.js} +5 -4
- package/bundle/control-channel.js +2 -2
- package/bundle/index.js +1 -1
- package/bundle/intercom-bridge.js +2 -2
- package/bundle/preflight.js +12 -10
- package/bundle/project-panes.js +3 -3
- package/bundle/workflow-resources.js +1 -1
- package/docs/agents.md +27 -6
- package/docs/configuration.md +20 -8
- package/docs/extension-api.md +18 -1
- package/docs/models.md +6 -2
- package/docs/observability.md +2 -0
- package/docs/tool-reference.md +7 -1
- package/docs/workflows.md +30 -2
- package/node_modules/@xzzpig/pi-components/CHANGELOG.md +12 -0
- package/node_modules/@xzzpig/pi-components/README.md +94 -0
- package/node_modules/@xzzpig/pi-components/dist/src/transcript-presenter.d.ts +186 -0
- package/node_modules/@xzzpig/pi-components/dist/src/transcript-presenter.js +693 -0
- package/node_modules/@xzzpig/pi-components/package.json +5 -1
- package/package.json +4 -4
- package/skills/pi-subagents/SKILL.md +15 -6
- package/skills/pi-subagents/references/prompting-and-roles.md +1 -0
- package/src/agents/agent-management.d.ts +1 -0
- package/src/agents/agent-management.js +46 -18
- package/src/agents/agent-memory.d.ts +1 -4
- package/src/agents/agent-memory.js +1 -4
- package/src/agents/agent-serializer.d.ts +2 -0
- package/src/agents/agent-serializer.js +1 -1
- package/src/agents/agents.d.ts +2 -3
- package/src/agents/agents.js +46 -20
- package/src/agents/frontmatter.js +1 -8
- package/src/agents/global-npm-root.d.ts +1 -0
- package/src/agents/global-npm-root.js +11 -3
- package/src/agents/skills.d.ts +0 -3
- package/src/agents/skills.js +0 -3
- package/src/api/preflight.d.ts +3 -1
- package/src/api/preflight.js +2 -0
- package/src/extension/config.d.ts +1 -0
- package/src/extension/config.js +13 -1
- package/src/extension/herdr-pi-bridge.js +10 -2
- package/src/extension/index.d.ts +0 -13
- package/src/extension/index.js +51 -37
- package/src/extension/public-execution.d.ts +1 -0
- package/src/extension/public-execution.js +4 -0
- package/src/extension/reply-workflow-script.js +24 -4
- package/src/extension/schemas.d.ts +12 -3
- package/src/extension/schemas.js +7 -3
- package/src/extension/session-switch.d.ts +25 -0
- package/src/extension/session-switch.js +138 -0
- package/src/extension/subagent-guide.d.ts +1 -1
- package/src/extension/subagent-guide.js +1 -1
- package/src/extension/subagent-launch-tool.d.ts +25 -0
- package/src/extension/subagent-launch-tool.js +48 -0
- package/src/extension/tool-activation.js +55 -15
- package/src/extension/tool-description.d.ts +1 -1
- package/src/extension/tool-description.js +14 -8
- package/src/inspectors/herdr/actions.d.ts +0 -1
- package/src/inspectors/herdr/actions.js +0 -1
- package/src/inspectors/session-roots-codec.d.ts +0 -1
- package/src/inspectors/session-roots-codec.js +0 -1
- package/src/inspectors/tmux/actions.d.ts +0 -1
- package/src/inspectors/tmux/actions.js +0 -1
- package/src/integrations/herdr-status.js +3 -8
- package/src/intercom/native-supervisor-channel.js +65 -9
- package/src/runs/background/async-execution.d.ts +7 -10
- package/src/runs/background/async-execution.js +66 -29
- package/src/runs/background/async-job-tracker.js +12 -0
- package/src/runs/background/async-resume.d.ts +2 -1
- package/src/runs/background/async-resume.js +114 -40
- package/src/runs/background/async-retention.d.ts +0 -2
- package/src/runs/background/async-retention.js +17 -6
- package/src/runs/background/async-status.d.ts +2 -0
- package/src/runs/background/async-status.js +4 -0
- package/src/runs/background/auto-drain.js +2 -1
- package/src/runs/background/boot-id.d.ts +1 -3
- package/src/runs/background/boot-id.js +1 -3
- package/src/runs/background/completion-batcher.d.ts +3 -4
- package/src/runs/background/completion-batcher.js +2 -3
- package/src/runs/background/control-channel.d.ts +0 -6
- package/src/runs/background/control-channel.js +0 -6
- package/src/runs/background/fleet-view.js +2 -3
- package/src/runs/background/notify.d.ts +0 -2
- package/src/runs/background/notify.js +0 -2
- package/src/runs/background/result-watcher.d.ts +1 -0
- package/src/runs/background/result-watcher.js +59 -29
- package/src/runs/background/resume-guidance.js +4 -2
- package/src/runs/background/retained-children.js +2 -1
- package/src/runs/background/run-child-session.d.ts +2 -3
- package/src/runs/background/run-child-session.js +5 -8
- package/src/runs/background/run-status.js +9 -7
- package/src/runs/background/runner-aliases.js +15 -0
- package/src/runs/background/scheduled-runs.d.ts +3 -1
- package/src/runs/background/scheduled-runs.js +13 -16
- package/src/runs/background/steering.d.ts +2 -11
- package/src/runs/background/steering.js +11 -6
- package/src/runs/background/subagent-runner.d.ts +2 -6
- package/src/runs/background/subagent-runner.js +88 -70
- package/src/runs/background/subagent-wait.js +12 -15
- package/src/runs/background/wait-config.d.ts +2 -0
- package/src/runs/background/wait-config.js +17 -3
- package/src/runs/background/wait-subscriptions.js +124 -12
- package/src/runs/background/wait-tool.js +4 -2
- package/src/runs/background/workflow-terminal-proof.d.ts +0 -1
- package/src/runs/background/workflow-terminal-proof.js +0 -1
- package/src/runs/foreground/async-steering-action.js +24 -9
- package/src/runs/foreground/async-stop-action.d.ts +1 -1
- package/src/runs/foreground/async-stop-action.js +9 -1
- package/src/runs/foreground/execution.d.ts +0 -3
- package/src/runs/foreground/execution.js +56 -24
- package/src/runs/foreground/prompt-audit.js +1 -0
- package/src/runs/foreground/subagent-executor.d.ts +5 -10
- package/src/runs/foreground/subagent-executor.js +164 -49
- package/src/runs/shared/acceptance.js +69 -26
- package/src/runs/shared/async-status-projection.d.ts +2 -0
- package/src/runs/shared/async-status-projection.js +10 -0
- package/src/runs/shared/child-commands.js +15 -2
- package/src/runs/shared/child-hooks.d.ts +1 -7
- package/src/runs/shared/child-hooks.js +13 -5
- package/src/runs/shared/child-launch.js +6 -2
- package/src/runs/shared/child-runtime-config.d.ts +0 -1
- package/src/runs/shared/child-session.d.ts +6 -5
- package/src/runs/shared/child-session.js +85 -38
- package/src/runs/shared/child-tool-plan.d.ts +0 -1
- package/src/runs/shared/child-tool-plan.js +0 -1
- package/src/runs/shared/claude-code-adapter.js +11 -0
- package/src/runs/shared/external-cli-contract.d.ts +49 -0
- package/src/runs/shared/external-cli-contract.js +18 -13
- package/src/runs/shared/external-cli-runner.js +26 -6
- package/src/runs/shared/herdr-connection.js +2 -1
- package/src/runs/shared/herdr-pane-host.d.ts +2 -2
- package/src/runs/shared/herdr-pane-host.js +17 -1
- package/src/runs/shared/herdr-placed-run.js +51 -24
- package/src/runs/shared/lane-metadata.d.ts +0 -1
- package/src/runs/shared/lane-metadata.js +0 -1
- package/src/runs/shared/mcp-config-sources.d.ts +4 -1
- package/src/runs/shared/mcp-config-sources.js +1 -1
- package/src/runs/shared/mcp-direct-tool-allowlist.d.ts +0 -3
- package/src/runs/shared/mcp-direct-tool-allowlist.js +26 -17
- package/src/runs/shared/mcp-direct-tool-grant.js +8 -1
- package/src/runs/shared/model-resolution-diagnostic.d.ts +0 -1
- package/src/runs/shared/model-resolution.d.ts +20 -5
- package/src/runs/shared/model-resolution.js +55 -50
- package/src/runs/shared/model-scope.d.ts +1 -5
- package/src/runs/shared/model-scope.js +1 -5
- package/src/runs/shared/mutation-evidence.d.ts +1 -1
- package/src/runs/shared/mutation-evidence.js +52 -7
- package/src/runs/shared/nested-events.d.ts +1 -0
- package/src/runs/shared/nested-events.js +1 -1
- package/src/runs/shared/parallel-utils.d.ts +0 -1
- package/src/runs/shared/permissions.js +5 -3
- package/src/runs/shared/placement-host.d.ts +5 -1
- package/src/runs/shared/rex-pane-host.d.ts +0 -1
- package/src/runs/shared/rex-pane-host.js +0 -2
- package/src/runs/shared/run-launch-folder.d.ts +12 -0
- package/src/runs/shared/run-launch-folder.js +21 -0
- package/src/runs/shared/runner-launcher.d.ts +12 -1
- package/src/runs/shared/runner-launcher.js +16 -0
- package/src/runs/shared/single-output.d.ts +3 -3
- package/src/runs/shared/single-output.js +5 -3
- package/src/runs/shared/structured-output.d.ts +8 -0
- package/src/runs/shared/structured-output.js +40 -5
- package/src/runs/shared/subagent-prompt-runtime.d.ts +0 -1
- package/src/runs/shared/subagent-prompt-runtime.js +18 -4
- package/src/runs/shared/supervisor-wait-timer.d.ts +16 -0
- package/src/runs/shared/supervisor-wait-timer.js +61 -0
- package/src/runs/shared/tool-timeout.js +2 -1
- package/src/runs/shared/worktree-cleanup-plan.d.ts +0 -1
- package/src/runs/shared/worktree-cleanup-plan.js +0 -1
- package/src/runs/shared/worktree.d.ts +3 -0
- package/src/runs/shared/worktree.js +20 -0
- package/src/shared/artifacts.d.ts +1 -0
- package/src/shared/artifacts.js +132 -22
- package/src/shared/capacity-resilient-json.d.ts +1 -1
- package/src/shared/child-cache-retention.d.ts +1 -2
- package/src/shared/child-cache-retention.js +1 -2
- package/src/shared/fleet-transcript-reader.d.ts +51 -0
- package/src/shared/fleet-transcript-reader.js +333 -0
- package/src/shared/formatters.d.ts +0 -18
- package/src/shared/formatters.js +0 -18
- package/src/shared/pruned-fork.js +2 -2
- package/src/shared/reported-progress.d.ts +1 -0
- package/src/shared/reported-progress.js +12 -0
- package/src/shared/session-succession.d.ts +16 -1
- package/src/shared/session-succession.js +41 -2
- package/src/shared/session-warnings.d.ts +7 -0
- package/src/shared/session-warnings.js +26 -0
- package/src/shared/settings.d.ts +0 -23
- package/src/shared/settings.js +3 -35
- package/src/shared/status-format.d.ts +1 -0
- package/src/shared/status-format.js +1 -1
- package/src/shared/types.d.ts +108 -59
- package/src/shared/types.js +0 -12
- package/src/shared/utils.d.ts +3 -15
- package/src/shared/utils.js +4 -22
- package/src/shared/wait-tool-name.d.ts +8 -0
- package/src/shared/wait-tool-name.js +13 -0
- package/src/slash/slash-commands.js +2 -1
- package/src/slash/subagent-cost.d.ts +3 -2
- package/src/slash/subagent-cost.js +22 -3
- package/src/slash/subagents-admin.js +0 -1
- package/src/tui/fleet-status.d.ts +0 -5
- package/src/tui/fleet-status.js +4 -24
- package/src/tui/fleet.js +6 -4
- package/src/tui/render.d.ts +0 -9
- package/src/tui/render.js +194 -68
- package/src/tui/subagent-messages.js +3 -2
- package/src/watchdog/model-selection.js +2 -2
- package/src/watchdog/permission-arbiter.js +1 -0
- package/src/watchdog/register-child.d.ts +2 -3
- package/src/watchdog/register-child.js +2 -3
- package/src/watchdog/review.d.ts +0 -5
- package/src/watchdog/review.js +4 -3
- package/src/watchdog/turn-delta.js +2 -1
- package/src/workflows/scripted-workflow.d.ts +2 -0
- package/src/workflows/scripted-workflow.js +344 -59
- package/src/workflows/structured-workflow-scripts.d.ts +4 -3
- package/src/workflows/structured-workflow-scripts.js +32 -11
- package/src/workflows/workflow-launch-record.d.ts +15 -6
- package/src/workflows/workflow-launch-record.js +30 -12
- package/src/workflows/workflow-receipt.js +36 -53
- package/src/workflows/workflow-resources.js +4 -4
- package/src/workflows/workflow-resume-claim.d.ts +2 -0
- package/src/workflows/workflow-resume-claim.js +3 -3
- package/src/workflows/workflow-resume.d.ts +1 -1
- package/src/workflows/workflow-resume.js +13 -8
- package/src/workflows/workflow-script-worker.d.ts +13 -0
- package/src/workflows/workflow-script-worker.js +81 -0
- package/workflow-script-process.cjs +36 -0
- package/workflow-script-worker.cjs +4 -1
- package/bundle/chunk-U4ODUYAG.js +0 -235
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// package.json
|
|
2
2
|
var package_default = {
|
|
3
3
|
name: "@xzzpig/pi-subagents",
|
|
4
|
-
version: "0.
|
|
4
|
+
version: "0.25.0",
|
|
5
5
|
description: "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
6
6
|
author: "Nico Bailon",
|
|
7
7
|
license: "MIT",
|
|
@@ -28,7 +28,7 @@ var package_default = {
|
|
|
28
28
|
},
|
|
29
29
|
repository: {
|
|
30
30
|
type: "git",
|
|
31
|
-
url: "git+https://github.com/
|
|
31
|
+
url: "git+https://github.com/xzzpig/pi-extensions.git"
|
|
32
32
|
},
|
|
33
33
|
homepage: "https://github.com/nicobailon/pi-subagents#readme",
|
|
34
34
|
bugs: {
|
|
@@ -52,6 +52,7 @@ var package_default = {
|
|
|
52
52
|
"src/**/*.ts",
|
|
53
53
|
"*.mjs",
|
|
54
54
|
"workflow-script-worker.cjs",
|
|
55
|
+
"workflow-script-process.cjs",
|
|
55
56
|
"agents/",
|
|
56
57
|
"skills/**/*",
|
|
57
58
|
"prompts/**/*",
|
|
@@ -106,11 +107,11 @@ var package_default = {
|
|
|
106
107
|
}
|
|
107
108
|
},
|
|
108
109
|
dependencies: {
|
|
109
|
-
"@xzzpig/pi-components": "0.
|
|
110
|
+
"@xzzpig/pi-components": "0.5.0",
|
|
110
111
|
"@js-temporal/polyfill": "0.5.1",
|
|
111
112
|
acorn: "8.18.0",
|
|
112
113
|
jiti: "2.7.0",
|
|
113
|
-
undici: "8.12.
|
|
114
|
+
undici: "8.12.4",
|
|
114
115
|
yaml: "2.8.3"
|
|
115
116
|
},
|
|
116
117
|
devDependencies: {
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import {
|
|
2
2
|
requestAsyncStop
|
|
3
|
-
} from "./chunk-
|
|
3
|
+
} from "./chunk-LPJEKHOY.js";
|
|
4
4
|
import "./chunk-NIXWDZZV.js";
|
|
5
|
-
import "./chunk-
|
|
5
|
+
import "./chunk-XAC2XNAP.js";
|
|
6
6
|
import "./chunk-UQDHXMUG.js";
|
|
7
7
|
import "./chunk-QXASAHIA.js";
|
|
8
8
|
import "./chunk-YFCK7H2S.js";
|
package/bundle/index.js
CHANGED
|
@@ -17,7 +17,7 @@ function readInstalledPackageVersion() {
|
|
|
17
17
|
var loadedPackageVersion = readInstalledPackageVersion();
|
|
18
18
|
|
|
19
19
|
// index.ts
|
|
20
|
-
var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-
|
|
20
|
+
var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-6MNRKUHY.js")).default : process.env.PI_SUBAGENT_CHILD === "1" ? void 0 : (await import("./chunk-KCJFGKVK.js")).default;
|
|
21
21
|
function registerSubagentExtension(pi) {
|
|
22
22
|
const installedVersion = readInstalledPackageVersion();
|
|
23
23
|
if (installedVersion !== loadedPackageVersion) {
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import {
|
|
2
2
|
resolveIntercomSessionTarget
|
|
3
|
-
} from "./chunk-
|
|
3
|
+
} from "./chunk-JAXVBXGF.js";
|
|
4
4
|
import "./chunk-BGIYHF2W.js";
|
|
5
|
-
import "./chunk-
|
|
5
|
+
import "./chunk-XAC2XNAP.js";
|
|
6
6
|
import "./chunk-UQDHXMUG.js";
|
|
7
7
|
import "./chunk-QXASAHIA.js";
|
|
8
8
|
import "./chunk-YFCK7H2S.js";
|
package/bundle/preflight.js
CHANGED
|
@@ -3,26 +3,26 @@ import {
|
|
|
3
3
|
canPreferForkFromSnapshot,
|
|
4
4
|
projectScopedProfileTrustError,
|
|
5
5
|
resolveSubagentLaunchContext
|
|
6
|
-
} from "./chunk-
|
|
7
|
-
import "./chunk-
|
|
6
|
+
} from "./chunk-W7ZA6TYD.js";
|
|
7
|
+
import "./chunk-5OD3OWTE.js";
|
|
8
8
|
import {
|
|
9
9
|
loadConfig
|
|
10
|
-
} from "./chunk-
|
|
10
|
+
} from "./chunk-U3ZDUUTM.js";
|
|
11
11
|
import {
|
|
12
12
|
nestedResultsPath,
|
|
13
13
|
processTerminalCandidatePath,
|
|
14
14
|
processTerminalPath,
|
|
15
15
|
resultFilePath
|
|
16
|
-
} from "./chunk-
|
|
16
|
+
} from "./chunk-JH5H4CYJ.js";
|
|
17
17
|
import {
|
|
18
18
|
getArtifactPaths,
|
|
19
19
|
getArtifactsDir
|
|
20
|
-
} from "./chunk-
|
|
20
|
+
} from "./chunk-LYKG4FKH.js";
|
|
21
21
|
import {
|
|
22
22
|
applyIntercomBridgeToAgent,
|
|
23
23
|
resolveIntercomBridge,
|
|
24
24
|
validateIntercomBridgeConfig
|
|
25
|
-
} from "./chunk-
|
|
25
|
+
} from "./chunk-JAXVBXGF.js";
|
|
26
26
|
import {
|
|
27
27
|
AGENT_DEFINITION_PROJECTION_VERSION,
|
|
28
28
|
resolveLaunchBinding,
|
|
@@ -31,7 +31,7 @@ import {
|
|
|
31
31
|
import {
|
|
32
32
|
applyThinkingSuffix,
|
|
33
33
|
resolvePiLaunchToolPlan
|
|
34
|
-
} from "./chunk-
|
|
34
|
+
} from "./chunk-IH7LQVEE.js";
|
|
35
35
|
import {
|
|
36
36
|
assertRequiredChildExtensionsAdmitted,
|
|
37
37
|
resolveRequiredChildExtensions
|
|
@@ -62,7 +62,7 @@ import {
|
|
|
62
62
|
resolveSkillsWithFallback,
|
|
63
63
|
resolveStepBehavior,
|
|
64
64
|
unknownAgentDiagnosticContext
|
|
65
|
-
} from "./chunk-
|
|
65
|
+
} from "./chunk-XAC2XNAP.js";
|
|
66
66
|
import {
|
|
67
67
|
DIRS,
|
|
68
68
|
SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
|
|
@@ -281,7 +281,8 @@ async function resolveSubagentLaunchContract(input) {
|
|
|
281
281
|
const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
|
|
282
282
|
const primaryModel = externalRunner ? void 0 : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, {
|
|
283
283
|
scope: modelScopes,
|
|
284
|
-
source: modelOrigin === "explicit" ? "explicit" : "inherited"
|
|
284
|
+
source: modelOrigin === "explicit" ? "explicit" : "inherited",
|
|
285
|
+
knownProviders: input.knownProviders
|
|
285
286
|
});
|
|
286
287
|
const effectiveThinkingConfig = input.thinking !== void 0 ? input.thinking : agent.thinking;
|
|
287
288
|
const thinkingCeiling = externalRunner ? void 0 : intersectThinkingCeilings(
|
|
@@ -292,7 +293,8 @@ async function resolveSubagentLaunchContract(input) {
|
|
|
292
293
|
const model = externalRunner ? void 0 : applyThinkingSuffix(resolveModelSelection(primaryModel, availableModels, preferredProvider, {
|
|
293
294
|
scope: modelScopes,
|
|
294
295
|
primaryModelFromParent: modelOrigin === "inherited" || inheritsParentModel(input.model, agent.model, input.parentModel),
|
|
295
|
-
origin: modelOrigin
|
|
296
|
+
origin: modelOrigin,
|
|
297
|
+
knownProviders: input.knownProviders
|
|
296
298
|
}).model, effectiveThinkingConfig, input.thinking !== void 0);
|
|
297
299
|
if (!externalRunner) {
|
|
298
300
|
try {
|
package/bundle/project-panes.js
CHANGED
|
@@ -8,10 +8,10 @@ import {
|
|
|
8
8
|
openProjectPane,
|
|
9
9
|
projectPaneBindingPath,
|
|
10
10
|
readProjectPaneBinding
|
|
11
|
-
} from "./chunk-
|
|
11
|
+
} from "./chunk-SJPABBZG.js";
|
|
12
12
|
import "./chunk-7J4ZXMY7.js";
|
|
13
|
-
import "./chunk-
|
|
14
|
-
import "./chunk-
|
|
13
|
+
import "./chunk-LYKG4FKH.js";
|
|
14
|
+
import "./chunk-XAC2XNAP.js";
|
|
15
15
|
import "./chunk-UQDHXMUG.js";
|
|
16
16
|
import "./chunk-QXASAHIA.js";
|
|
17
17
|
import "./chunk-YFCK7H2S.js";
|
package/docs/agents.md
CHANGED
|
@@ -194,6 +194,12 @@ node --experimental-strip-types --import ./test/support/register-loader.mjs \
|
|
|
194
194
|
|
|
195
195
|
The read-only smoke must report `writeCanaryExists: false`. The writer smoke must report `writeCanaryMatches: true`. Both reports record `workspaceTrust: "operator-managed-saved"`, confirm that the external prompt root was added, and include startup duration and terminal proof without raw protocol output, prompts, or credentials. A trust-required error remains terminal; the harness does not retry with a trust, force, or yolo flag.
|
|
196
196
|
|
|
197
|
+
#### Safety record and wrapper commands
|
|
198
|
+
|
|
199
|
+
Each code-owned adapter run records a `safety` block in its runner status, in `subagent({ action: "status" })`, and in its workflow receipt entry. The block is the adapter's profile: the access its own argv asks the CLI for. Nothing in it is measured from the launched process, and status labels it `Safety (adapter profile, not measured)`.
|
|
200
|
+
|
|
201
|
+
The record carries `safetySource: { "measured": false, "command": "..." }` beside it. `command` is the launch command as configured; a run on a Herdr saved machine records none, because the remote pane runs the adapter's own binary. When `runner.command` is a wrapper script that changes argv before it starts the CLI, the wrapper can grant more or less than the profile shows, so read the wrapper to know the real grant. Receipts written before `safetySource` existed are read as profile values.
|
|
202
|
+
|
|
197
203
|
#### Native oracle compared with external advisors
|
|
198
204
|
|
|
199
205
|
Native `oracle` runs inside Pi and can use its configured read tools. The Claude profiles send the assembled prompt to the local Claude Code CLI through stdin. An external-job agent sends the assembled prompt to its registered provider. Provider options and a prompt digest are persisted in Pi run state. The prompt text is delivered through the local host bridge to the provider and is not stored in the public result payload. Do not place secrets in advisory prompts unless the target provider is approved to receive them.
|
|
@@ -244,7 +250,7 @@ Supported override fields: `description`, `advertise`, `machine`, `output`, `out
|
|
|
244
250
|
- `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
|
|
245
251
|
- Use `output: false`, `defaultReads: false`, `defaultContext: false`, `acceptanceRole: false`, or `machine: false` to clear an inherited value.
|
|
246
252
|
- Use `tools: "inherit"` when that one role should omit its bundled or frontmatter tool allowlist and receive Pi's normal builtins (plus ambient extensions when it runs as a background child).
|
|
247
|
-
- Project overrides beat user overrides.
|
|
253
|
+
- Project overrides beat user overrides field by field: a project override replaces only the fields it sets, and fields set only in the user override still apply.
|
|
248
254
|
- Matching package, user, and project agents also receive override fields, which replace the same fields declared in their frontmatter. This lets a shared agent keep its persona while local settings choose the effective model, context, tools, or other supported options.
|
|
249
255
|
|
|
250
256
|
Disable and restore:
|
|
@@ -333,9 +339,10 @@ How it behaves:
|
|
|
333
339
|
- **Not combined with other placement.** `launcher` cannot be combined with `machine` (from frontmatter, a settings override, or the call) or with an `external-cli` or `external-job` runner.
|
|
334
340
|
- **Unknown names fail.** If the name is not in `runnerLaunchers`, the launch fails before anything starts, without using a fan-out slot or creating a session directory. It never falls back to running without the launcher.
|
|
335
341
|
- **Status.** The run's `status.json` records `launcher: { name, argv }`. Environment values are never recorded.
|
|
336
|
-
- **Resume and revival.** A resumed run uses the launcher recorded when the run was first launched, not the agent file's current value, and looks up that name's argv in the config the session loaded, like a new launch does; edits to `runnerLaunchers` apply after `/reload`. A run launched without a launcher stays unwrapped even if its agent file gains `launcher` later. If the recorded name is no longer in `runnerLaunchers`, the resume fails before anything starts, and the run can be resumed once the name is defined again.
|
|
342
|
+
- **Resume and revival.** A resumed run uses the launcher recorded when the run was first launched, not the agent file's current value, and looks up that name's argv in the config the session loaded, like a new launch does; edits to `runnerLaunchers` apply after `/reload`. A run recorded as launched without a launcher stays unwrapped even if its agent file gains `launcher` later. When no launcher choice is recorded (a run started before this was recorded, a foreground run, or a workflow child resumed through its workflow run), the resume uses the agent file's current `launcher`, so it never runs unwrapped just because the record is missing. If the recorded name is no longer in `runnerLaunchers`, the resume fails before anything starts, and the run can be resumed once the name is defined again.
|
|
337
343
|
- **Several agents in one runner.** A new chain attached to a running subagent, or steps appended to a running chain, run in one background runner. All agents in it must name the same launcher, or none; a mix is refused before anything starts, and the error names each agent and its launcher. Appended steps must also match the launcher of the runner they join. Steps in one wrapped chain share its sandbox; to give branches different sandboxes, run them as workflow-script children, which each get their own runner.
|
|
338
344
|
- **Agent management.** `subagent({ action: "create" })` and `update` cannot set `launcher`; edit the agent file instead. Other updates keep an existing `launcher` line.
|
|
345
|
+
- **Requiring a launcher from the call.** `options.requireLauncher: { name, definitionDigest }` refuses a launch unless it runs under that launcher with that agent definition. See [Requiring a launcher](extension-api.md#requiring-a-launcher).
|
|
339
346
|
|
|
340
347
|
### Wrapper requirements
|
|
341
348
|
|
|
@@ -348,11 +355,25 @@ A launcher command must:
|
|
|
348
355
|
|
|
349
356
|
Steering, stop, and supervisor requests and replies travel through files in those directories, not through signals, so they work as long as the paths are shared.
|
|
350
357
|
|
|
358
|
+
With `~/.pi/agent` read-only, a child cannot refresh an OAuth login, because Pi locks and rewrites `auth.json` there, so it fails once its token needs a refresh; API keys are unaffected. Child sessions sit under `~/.pi/agent/sessions/` by default, so the child session directory still needs its own read-write binding.
|
|
359
|
+
|
|
360
|
+
### Isolating a run from the parent
|
|
361
|
+
|
|
362
|
+
A launcher can also keep a run from reaching the parent session and other runs. Resume and auto-resume take what to relaunch and under which identity only from records the parent keeps in `async-subagent-launches/<id>/` under the temp root: a workflow's saved launch (its script, owning session and capability ceiling), and a single run's recovery descriptor (its agent, session file, cwd, model, tools, ceilings and launcher). A run that rewrites files in its own run directory, such as `status.json`, cannot make a later resume start something else or continue another run's transcript. For the isolation to hold, the launcher must not give the run write access to:
|
|
363
|
+
|
|
364
|
+
- `async-subagent-launches/`, or other runs' directories under `async-subagent-runs/`;
|
|
365
|
+
- `~/.pi/agent`: extensions, settings and agent files there load into the parent session, so write access to them is a way into the parent. Bind it read-only.
|
|
366
|
+
|
|
367
|
+
The run's working directory stays writable, so a run can still reach the parent through it: the project's `.pi/` extensions and agents, or `.git/config` settings such as `core.fsmonitor` that the parent's git commands run. Give an isolated run a checkout the parent session does not use.
|
|
368
|
+
|
|
369
|
+
Runs that a child starts itself (nested runs) keep these records in their root run's folder under `nested-subagent-runs/`. The child's runner writes them, so they add no isolation.
|
|
370
|
+
|
|
351
371
|
### Broker wrappers
|
|
352
372
|
|
|
353
373
|
Some sandboxes, such as nono's broker mode, start the runner in a separate process instead of as a child of the launcher command. pi-subagents does not rely on the launcher's process being the runner:
|
|
354
374
|
|
|
355
375
|
- Before it starts any work, the runner reports its own process id. The launch waits up to 10 seconds for it and fails if it does not arrive. `status.json` and run events use the runner's process id, not the launcher's.
|
|
376
|
+
- If the launch fails before the runner is told to proceed, pi-subagents stops the reported process only when it is the launcher's process or one of its descendants, so a runner cannot make the parent signal an unrelated process. A broker-started runner is not signalled; it exits by itself within 30 seconds when it is never told to proceed.
|
|
356
377
|
- When the launcher process exits, its exit code and signal are kept in `launcher-close.json` in the run directory. That exit is treated as the runner's exit only when the runner's process is confirmed dead. A runner killed by a signal may be reported by the launcher as exit code `128 + n` (for example `143` for `SIGTERM`).
|
|
357
378
|
- If only the launcher process is killed while the runner keeps working, the run keeps running and still accepts steer and stop. No process-exit proof is recorded when the runner later exits, so if `maxActiveAsyncRunsPerSession` is set, the run's capacity slot stays held; the abandoned-slot policy releases it only if the run ends failed.
|
|
358
379
|
- If the sandbox does not let the parent check the runner's process id, a runner that dies without its launcher noticing stays `running` until the stale-run check marks it failed after 24 hours without a status update.
|
|
@@ -383,11 +404,11 @@ Use these fields when an agent should see more:
|
|
|
383
404
|
|-------|--------|
|
|
384
405
|
| `systemPromptMode: append` | Append the agent prompt to Pi's normal base prompt. |
|
|
385
406
|
| `inheritProjectContext: true` | Keep inherited repository instructions from files like `AGENTS.md` and `CLAUDE.md`. |
|
|
386
|
-
| `inheritGlobalContext: true` | Also keep the operator's global context file from the Pi config agent directory (such as `~/.pi/agent/AGENTS.md`). Defaults to `false
|
|
407
|
+
| `inheritGlobalContext: true` | Also keep the operator's global context file from the Pi config agent directory (such as `~/.pi/agent/AGENTS.md`). Defaults to `false`, or to `subagents.defaultInheritGlobalContext` when that is set. |
|
|
387
408
|
| `inheritSkills: true` | Let the child see Pi's discovered skills catalog. |
|
|
388
409
|
| `defaultContext: fork` | Prefer forked session context when a launch omits `context`; if the parent has no persisted session file or current leaf yet, the implicit default falls back to `fresh` without a failed first attempt. Explicit `context: "fork"` remains strict, and explicit `context: "fresh"` still wins. |
|
|
389
410
|
|
|
390
|
-
Builtin agents opt into repository instruction inheritance by default so they follow repo-specific rules out of the box, but global context remains excluded unless `inheritGlobalContext: true` is set. This changes the behavior of existing agents that previously received global context as part of `inheritProjectContext: true`. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
|
|
411
|
+
Builtin agents opt into repository instruction inheritance by default so they follow repo-specific rules out of the box, but global context remains excluded unless `inheritGlobalContext: true` is set, per agent or for every agent with `subagents.defaultInheritGlobalContext: true` (see [models.md](models.md#global-context-default)). This changes the behavior of existing agents that previously received global context as part of `inheritProjectContext: true`. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
|
|
391
412
|
|
|
392
413
|
These fields and `systemPromptMode` shape a fresh child's system prompt. A forked child (`context: "fork"`) sends its parent's whole system prompt instead, project context, global context, and skills included, and gets its agent prompt in its task message (see [fork context details](tool-reference.md#fork-context-details)).
|
|
393
414
|
|
|
@@ -461,7 +482,7 @@ tools:
|
|
|
461
482
|
| `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. On the two Claude Code adapters it becomes `--effort`, and a suffix on `model` wins over it. |
|
|
462
483
|
| `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
|
|
463
484
|
| `inheritProjectContext` | Keeps or strips inherited repository instruction blocks. |
|
|
464
|
-
| `inheritGlobalContext` | Keeps or strips the operator's global context file from the Pi config agent directory (e.g. `~/.pi/agent/AGENTS.md`). It has an effect only when `inheritProjectContext` is `true`; otherwise all context files are already disabled.
|
|
485
|
+
| `inheritGlobalContext` | Keeps or strips the operator's global context file from the Pi config agent directory (e.g. `~/.pi/agent/AGENTS.md`). It has an effect only when `inheritProjectContext` is `true`; otherwise all context files are already disabled. |
|
|
465
486
|
| `inheritSkills` | Keeps or strips Pi's discovered skills catalog. For in-process children this includes skills that loaded extensions add; herdr-placed children rely on Pi's `--no-skills`. |
|
|
466
487
|
| `defaultContext` | Optional `fresh` or `fork` launch-context preference. An implicit `fork` falls back to `fresh` when the parent has no persisted session file or current leaf; an explicit launch `context: "fork"` remains strict. |
|
|
467
488
|
| `skills` | Selects specific skills for the child, regardless of `inheritSkills`. |
|
|
@@ -576,7 +597,7 @@ Examples:
|
|
|
576
597
|
|
|
577
598
|
When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed, `mcp:server` and `mcp:server/tool` entries resolve against Pi's built-in MCP. Name the server and tool as the server reports them: `mcp:my-docs/get-item` selects the tool Pi registers as `mcp__my_docs__get_item`. The server part may also use the `-`→`_` form of its name that Pi's MCP namespace uses, such as `mcp:my_docs`. The child connects the servers in Pi's `mcp.json` (the project's `.pi/mcp.json` only when the parent trusts the project) and gets only the selected tools, as direct tools, whatever exposure the server is configured with; tools configured as `hidden` cannot be selected. Servers that an extension adds with `pi.registerMcpServer()` work in background children, because the registering extension loads there too. They do not work in foreground children, which load no ambient extensions, so a foreground launch that selects one fails and says to use `async: true`. The child waits for the selected servers' current MCP connection attempts before its first prompt, then rejects the launch if any selected tool is missing or not available as a direct tool. Pi's MCP request timeout still bounds each connection; stopping, interrupting, timing out, or shutting down the child cancels the startup wait. An unrelated server does not delay this check.
|
|
578
599
|
|
|
579
|
-
When pi-mcp-adapter is installed, it keeps priority and provides the direct MCP tools. Subagents only receive direct MCP tools when `mcp:` entries are listed in their frontmatter; global `directTools: true` in the adapter's MCP config is not enough by itself. The generic `mcp` proxy tool can still be used for discovery when available. The adapter caches tool metadata at startup, so after connecting a new MCP server for the first time, restart Pi before relying on direct tools. Server `includeTools` and `excludeTools` policies are enforced while resolving cached metadata for children: both accept exact names and `*`/`?` glob patterns against raw, generated-resource, and server/short/mcp/none-prefixed names, with `excludeTools` taking precedence. `mcp:` entries must name servers from the adapter's configuration files. A server that exists only in the adapter's runtime snapshot (registered at runtime, not persisted) cannot be provided to a child: children are pi sessions inside the parent or the runner process, not `pi` processes that could receive an MCP config argument, so such a launch fails with an error saying that MCP tools must come from an ambient adapter extension in a background child. An `mcp:` entry named `subagent` does not authorize nested fanout; declare the builtin `subagent` tool or set `allowNestedSubagents: true`. If a resolved direct MCP name is missing from the child registry, pi-subagents keeps the launch failed under the strict allowlist and reports the registration mismatch; check the resolved names against what the host or pi-mcp-adapter actually registers before child startup.
|
|
600
|
+
When pi-mcp-adapter is installed, it keeps priority and provides the direct MCP tools. Subagents only receive direct MCP tools when `mcp:` entries are listed in their frontmatter; global `directTools: true` in the adapter's MCP config is not enough by itself. The generic `mcp` proxy tool can still be used for discovery when available. The adapter caches tool metadata at startup, so after connecting a new MCP server for the first time, restart Pi before relying on direct tools. Selectors for servers explicitly configured with `disabled: true` are skipped; unknown servers and enabled servers without matching cached tools still fail the launch. Server `includeTools` and `excludeTools` policies are enforced while resolving cached metadata for children: both accept exact names and `*`/`?` glob patterns against raw, generated-resource, and server/short/mcp/none-prefixed names, with `excludeTools` taking precedence. `mcp:` entries must name servers from the adapter's configuration files. A server that exists only in the adapter's runtime snapshot (registered at runtime, not persisted) cannot be provided to a child: children are pi sessions inside the parent or the runner process, not `pi` processes that could receive an MCP config argument, so such a launch fails with an error saying that MCP tools must come from an ambient adapter extension in a background child. An `mcp:` entry named `subagent` does not authorize nested fanout; declare the builtin `subagent` tool or set `allowNestedSubagents: true`. If a resolved direct MCP name is missing from the child registry, pi-subagents keeps the launch failed under the strict allowlist and reports the registration mismatch; check the resolved names against what the host or pi-mcp-adapter actually registers before child startup.
|
|
580
601
|
|
|
581
602
|
### Extension loading
|
|
582
603
|
|
package/docs/configuration.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
`pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
|
|
4
4
|
|
|
5
|
-
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `defaultSubagentOnlyExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, `allow: ["inherit"]` permits the current parent model, and `allow: ["scoped"]` permits the parent session's scoped models (the parent model when the session is unscoped). See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
|
|
5
|
+
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `defaultSubagentOnlyExtensions`, `defaultInheritGlobalContext`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, `allow: ["inherit"]` permits the current parent model, and `allow: ["scoped"]` permits the parent session's scoped models (the parent model when the session is unscoped). See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
|
|
6
6
|
|
|
7
7
|
## Project root resolution (settings)
|
|
8
8
|
|
|
@@ -86,6 +86,14 @@ The recorded native `subagent` selection is restored on resume, reload, and tree
|
|
|
86
86
|
|
|
87
87
|
Some providers fix the tool list for a whole prompt, for example bridges that hand Pi's tools to another agent SDK. There `subagent` appears only on the next user prompt, not the next model request. Start Pi with `--exclude-tools subagents_enable` to keep `subagent` active from the start.
|
|
88
88
|
|
|
89
|
+
### First installation into an existing recorded session
|
|
90
|
+
|
|
91
|
+
If intact tool-selection history never declared this extension, `"auto"` keeps both `subagents_enable` and `subagent` absent. Installing the extension and running `/reload` alone does not add them.
|
|
92
|
+
|
|
93
|
+
To enable delegation in that session, merge `"toolActivation": "dynamic"` into the existing `~/.pi/agent/extensions/subagent/config.json` object; do not replace the file with the one-key example below. Restart Pi and resume the session, then ask the model to call the `subagents_enable({})` tool. This is a model tool, not a slash command.
|
|
94
|
+
|
|
95
|
+
Alternatively, merge `"toolActivation": "eager"` into the same config, restart Pi to remove the loader, then run `/reload` in the resumed session (see `"eager"` below).
|
|
96
|
+
|
|
89
97
|
## `toolActivation`
|
|
90
98
|
|
|
91
99
|
```json
|
|
@@ -96,9 +104,9 @@ Controls how a new parent session offers the `subagent` tool. The default is `"a
|
|
|
96
104
|
|
|
97
105
|
- `"auto"`: a new session starts with the `subagents_enable` loader only when its model can take a new tool mid-conversation. Otherwise it starts with `subagent` active and no loader, because calling the loader on such a model makes Pi resend the conversation in a form the provider may not have cached. A model qualifies when its Pi `compat` settings set `supportsMidConvoSystemMessages: true` and, for its API, `supportsMidConvoToolChanges: true` (`anthropic-messages`), `supportsMidConvoToolAdditions: true` (`openai-completions`), or `supportsAdditionalTools: true` or `supportsToolSearch: true` (`openai-responses`, `openai-codex-responses`, `azure-openai-responses`). Other APIs, missing settings, and no model do not qualify.
|
|
98
106
|
- `"dynamic"`: every new session starts with the loader, whatever the model. This was the behavior before `toolActivation` existed.
|
|
99
|
-
- `"eager"`: the loader is not registered,
|
|
107
|
+
- `"eager"`: the loader is not registered, and the extension does not change the tool selection. A new session or `/reload` makes `subagent` active; a resumed session whose recorded tools lack `subagent` stays without it until `/reload`. See the recovery steps above.
|
|
100
108
|
|
|
101
|
-
The choice is made
|
|
109
|
+
The choice is made only for a session with no messages, using the model selected before its first prompt. Switching models after that prompt does not change it. If a compaction that kept no tool checkpoint dropped the record of this choice, the session is decided again as a new session would be; tool selections recorded after that compaction (for `bg_wait` or another extension's tools) are not evidence that the choice survived. Under `"auto"`, resumed sessions keep the tools they recorded. `"dynamic"` also adds the loader to recorded sessions that did not have it. `"auto"` avoids only the loader's cache miss; other tool-list or provider changes can still miss the cache. An active `subagent` sends its full schema on every request. An invalid value is a config error, not a fallback to the default. Restart Pi after changing it.
|
|
102
110
|
|
|
103
111
|
## `toolDescriptionMode`
|
|
104
112
|
|
|
@@ -108,7 +116,7 @@ The choice is made at session start or tree navigation, and only for a session w
|
|
|
108
116
|
|
|
109
117
|
Controls the parent-facing `subagent` tool description registered at startup. The default registers the short execution/safety description, which states the delegation authorization rule, plus a one-line `promptSnippet`. Explicit `"compact"` uses the same description without the snippet; `"full"` adds workflow and management detail, also without the snippet. All modes retain the same flat parameter schema. Extended examples and recipes are available on demand through `action:"guide"` and the bundled pi-subagents skill; full mode is not an exhaustive manual. Count the default snippet as well as the tool definition when comparing prompt footprints.
|
|
110
118
|
|
|
111
|
-
`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.pi/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Pi after changing the mode or custom file. The change applies to new sessions; a resumed session keeps the tool definition and prompt text it already declared, so its prompt cache stays valid. To apply it to resumed sessions too, set [`pinToolDeclarations`](#pintooldeclarations) to `false`.
|
|
119
|
+
`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.pi/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the two description placeholders leave out features turned off with [`disabledFeatures`](#disabledfeatures), and the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Pi after changing the mode or custom file. The change applies to new sessions; a resumed session keeps the tool definition and prompt text it already declared, so its prompt cache stays valid. To apply it to resumed sessions too, set [`pinToolDeclarations`](#pintooldeclarations) to `false`.
|
|
112
120
|
|
|
113
121
|
## `pinToolDeclarations`
|
|
114
122
|
|
|
@@ -124,7 +132,7 @@ Pi records each tool definition and prompt section a session declares, and decla
|
|
|
124
132
|
{ "disabledFeatures": ["watchdog", "panes", "preflight", "lane-metadata", "gates"] }
|
|
125
133
|
```
|
|
126
134
|
|
|
127
|
-
Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features. Every `{ action: "guide" }` response starts with a notice: a topic lists what is disabled, and a section points to the `tool-reference` topic for that list. With `workflow-scripts` disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. Custom tool descriptions
|
|
135
|
+
Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features. Every `{ action: "guide" }` response starts with a notice: a topic lists what is disabled, and a section points to the `tool-reference` topic for that list. With `workflow-scripts` disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. Custom tool descriptions keep their own text; only their `{{compactDescription}}` and `{{fullDescription}}` placeholders leave out disabled features. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
|
|
128
136
|
|
|
129
137
|
| Feature | Parameters removed | Actions rejected |
|
|
130
138
|
|---|---|---|
|
|
@@ -404,7 +412,7 @@ Adds a short `active_subagents` section to the parent's system prompt while this
|
|
|
404
412
|
{ "waitTool": { "enabled": true, "defaultTimeoutMs": 120000 } }
|
|
405
413
|
```
|
|
406
414
|
|
|
407
|
-
`defaultTimeoutMs` sets the blocking window used when a `bg_wait` call omits `timeoutMs`; explicit call values win, followed by this setting, then the 30-minute fallback. `bg_wait`
|
|
415
|
+
`defaultTimeoutMs` sets the blocking window used when a `bg_wait` call omits `timeoutMs`; explicit call values win, followed by this setting, then the 30-minute fallback. pi-subagents registers one wait tool, named `bg_wait` unless `name` sets another (a letter, then letters, digits or underscores, at most 64 characters). Rename it when another extension also registers `bg_wait`, because Pi refuses to start when two extensions register the same tool name; for example `{ "waitTool": { "name": "subagent_wait" } }`. Everything pi-subagents says about waiting then uses that name, children get the same name, and a child agent that should wait lists that name in its `tools`. When the window elapses, the tool returns a non-error `window_elapsed` result with the still-active work identities, and that work keeps running. Set `enabled` to `false` to make direct calls return immediately instead of blocking. The default is enabled. You can also set `"waitTool": false`; set `PI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. The effective enabled, default-timeout and name values are passed explicitly to child runtimes. Headless `agent_end` auto-drain does not use this window; see [`timeoutMs`](#timeoutms). Invalid config or environment values fail instead of being coerced.
|
|
408
416
|
|
|
409
417
|
|
|
410
418
|
Blocking `bg_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention, even when the run is still working normally, for example a `bash` command open longer than `activeNoticeAfterMs`; the result then says the run is still running. Use `bg_wait({ stopOnAttention: false })` for run-to-completion flows: it waits through idle time, a tool held open, or repeated tool failures, and still ends for a supervisor/contact request, a finished run, the timeout, user input, or abort. A steer or follow-up the operator sends while a blocking wait is open also ends it, with a non-error `user_input` result listing the still-active work, so the message reaches the model without waiting out the window. In a long-lived interactive parent session, `bg_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Use it for provider, detached, or other background work without a native completion notification; ordinary async subagent runs notify the parent natively and do not need a wait subscription. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work. A native completion notification goes to the Pi process that launched the run while that process is running; once it has exited, the session gets the result the next time it is open in any Pi. `nonBlocking` subscriptions need a host with a UI context, such as interactive or RPC mode; plain SDK embedding without a UI context rejects them.
|
|
@@ -436,8 +444,12 @@ Forces depth-0 internal single, parallel, and chain runs into background mode an
|
|
|
436
444
|
|
|
437
445
|
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflow scripts) and plain single-agent async runs whenever no call-level `timeoutMs`/`maxRuntimeMs` applies. For single-agent launches, selected agent frontmatter `timeoutMs` still wins. This only moves the *default*. Expiring this run-level deadline is terminal.
|
|
438
446
|
|
|
447
|
+
A run's deadline does not count time a child spends waiting for its supervisor's reply to a `contact_supervisor` decision or interview, or to an `intercom` ask; `progress_update` does not pause it, and the overall deadline of a workflow script stays wall-clock.
|
|
448
|
+
|
|
439
449
|
This deadline bounds the whole run. The wait for a single model response is bounded separately by Pi's `httpIdleTimeoutMs` setting (default 300000; `0` disables it), which Pi applies both as the SDK request timeout and as the undici header/body idle timeout. Detached async runners read the same setting from `~/.pi/agent/settings.json` and the project `.pi/settings.json` for their own HTTP dispatcher, so a local model that queues or prefills for longer than five minutes needs `httpIdleTimeoutMs` raised or disabled in Pi settings, plus a `timeoutMs` long enough for the run.
|
|
440
450
|
|
|
451
|
+
In a non-interactive session (`pi -p`), the same value is how long Pi stays open at the end of a turn waiting for background subagent work to finish. When it is unset, Pi waits 30 minutes, then fails and exits if that work is still running.
|
|
452
|
+
|
|
441
453
|
Use it when foreground orchestration or plain async single-agent runs need a longer default than 30 minutes. It does not set async composite top-level deadlines, and it does not replace async fan-out child deadlines.
|
|
442
454
|
|
|
443
455
|
Composite async runs (async chains, parallel tasks, and scripted workflows) stay unbounded at the top level by design. Their runner children are bounded individually by their own agent or runner defaults, so this value does not cap them. Must be a positive integer no greater than `2147483647` (the largest delay a Node.js timer can honor, roughly 24.8 days); invalid or out-of-range values are ignored and the built-in defaults apply.
|
|
@@ -470,7 +482,7 @@ An explicit `subagent` call value wins over this default. Choose a value at leas
|
|
|
470
482
|
{ "globalConcurrencyLimit": 20 }
|
|
471
483
|
```
|
|
472
484
|
|
|
473
|
-
Caps simultaneously running children inside one run, including durable legacy multi-child runs and workflow script launches through `runs.run`/`runs.all`. Queued workflow children retain their stable keys and begin when a running sibling releases capacity. The default is `20`.
|
|
485
|
+
Caps simultaneously running children inside one run, including durable legacy multi-child runs and workflow script launches through `runs.run`/`runs.all`. Queued workflow children retain their stable keys and begin when a running sibling releases capacity. The default is `20`. The value must be a positive integer; an invalid value fails config loading.
|
|
474
486
|
|
|
475
487
|
Inline or file-backed top-level workflow calls may set a positive safe-integer `globalConcurrencyLimit` to override this value for that workflow. The override is workflow-only and is not forwarded to child calls.
|
|
476
488
|
|
|
@@ -724,7 +736,7 @@ Controls where subagent artifact files (inputs, outputs, transcripts, metadata)
|
|
|
724
736
|
|
|
725
737
|
This preference also controls the default workflow artifact directory used by scripted chaining. `"project"` uses `<cwd>/.pi/subagents/chain-runs/`; the directory keeps its legacy name for compatibility. The default `"session"` and `"temp"` use the user-scoped temp workflow artifact directory.
|
|
726
738
|
|
|
727
|
-
The `"session"` option uses the same directory that `cleanupAllArtifactDirs` already scans for age-based cleanup, so artifacts are still cleaned up automatically. Temporary workflow artifact directories are cleaned up separately after 24 hours.
|
|
739
|
+
The `"session"` option uses the same directory that `cleanupAllArtifactDirs` already scans for age-based cleanup, so artifacts are still cleaned up automatically: files older than `artifactConfig.cleanupDays` (default 7, `0` turns cleanup off) are removed, including those in nested folders such as workflow `outputs/`. `handoffs/` and `worktree-diffs/` are kept, because they record worktrees that can be kept longer than that. Temporary workflow artifact directories are cleaned up separately after 24 hours. The same setting covers forked children: each one writes a copy of the parent's session file to `<parent session file without .jsonl>/forks/<run id>/`, and once a day at extension load a copy is deleted when nothing has written to it for `cleanupDays` and its async run is not queued or running; the forked child's own artifacts, which live in that folder, go with it. Resuming a child after its copy is deleted fails with an error that says so.
|
|
728
740
|
|
|
729
741
|
When a project-scoped launch runs from an npm package directory, pi-subagents warns if package settings can include `.pi/subagents/` in the published package. Add `.pi/subagents/` to `.npmignore` (or `.gitignore` when no `.npmignore` exists), use a `files` allowlist that does not include `.pi/subagents/`, or select `"session"` or `"temp"`.
|
|
730
742
|
|
package/docs/extension-api.md
CHANGED
|
@@ -275,6 +275,8 @@ const result = await resolveSubagentLaunchContract({
|
|
|
275
275
|
cwd: ctx.cwd,
|
|
276
276
|
sessionRoot: "/tmp/my-extension-preflight-session-root",
|
|
277
277
|
availableModels: ctx.modelRegistry.getAvailable(),
|
|
278
|
+
// Every provider Pi knows, so `anthropic/...` never resolves to another provider's copy.
|
|
279
|
+
knownProviders: () => ctx.modelRegistry.getAll().map((model) => model.provider),
|
|
278
280
|
});
|
|
279
281
|
|
|
280
282
|
if (!result.ok) {
|
|
@@ -312,6 +314,21 @@ Boundaries:
|
|
|
312
314
|
- Some host-owned facts, such as exact fork snapshots, nested async roots, and live model registries, can only be proven by the Pi host; those appear as `host_required` diagnostics instead of silently pretending to be exact.
|
|
313
315
|
- Preflight reads the extension config, so `defaultSubagentContext: "fresh"` or `"fork"` affects omitted context in the same way as execution. Explicit `context` still wins.
|
|
314
316
|
|
|
317
|
+
### Requiring a launcher
|
|
318
|
+
|
|
319
|
+
An extension that approved one agent definition for one [launcher](agents.md#sandboxing-background-children-with-a-launcher) can make the launch depend on that approval. Read `contract.agent.definitionDigest` from preflight, then pass it with the launcher name in the call, for example by adding it to the `subagent` tool call's input in your `tool_call` handler:
|
|
320
|
+
|
|
321
|
+
```ts
|
|
322
|
+
event.input.options = { ...event.input.options, requireLauncher: { name: "net", definitionDigest } };
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
pi-subagents checks the requirement after every `tool_call` handler has run, against the agent and launcher it is about to start, and again when it spawns the runner. The launch is refused if the agent has no launcher, uses another launcher, or has a different definition digest (for example because the agent file changed, or a project agent now shadows it). It never falls back to running without the launcher, and a refusal starts nothing. The runner records the checked digest.
|
|
326
|
+
|
|
327
|
+
- Only a top-level single-agent call (`agent` + `task`) accepts it, and it runs in the background because launcher agents always do. `tasks`, `chain`, workflows, workflow children (`runs.run`), actions and `resume` are refused.
|
|
328
|
+
- The requirement travels in the call. Another extension's `tool_call` handler that runs after yours can remove it, and pi-subagents cannot tell. Register your handler so it runs last, or check the run's `status.json` (`launcher.name`) afterwards.
|
|
329
|
+
- Releases without this option reject `options.requireLauncher` as an unknown option, so an older install fails the call instead of ignoring it.
|
|
330
|
+
- The run's recovery record keeps the requirement, and `resume` checks it again: it is refused if the agent is gone, names another launcher, or has a different definition digest, and attaching a chain to the run is refused.
|
|
331
|
+
|
|
315
332
|
## Structured delegation API
|
|
316
333
|
|
|
317
334
|
Other Pi extensions can ask `pi-subagents` to run one configured foreground leaf agent through the structured delegation API. It uses the established `prompt-template:subagent:*` event family and the same executor as the `subagent` tool; it does not add another launcher.
|
|
@@ -593,7 +610,7 @@ When Pi runs inside [Herdr](https://herdr.dev), pi-subagents automatically repor
|
|
|
593
610
|
- The bridge is enabled only when Herdr supplies `HERDR_ENV=1` and `HERDR_PANE_ID`; outside Herdr it registers no listeners or timers.
|
|
594
611
|
- It restores current-session active runs after `/reload` or `/resume`, refreshes metadata while work is active, and clears it on completion or shutdown.
|
|
595
612
|
- The bridge emits `herdr:busy` while async work remains and never raises `herdr:blocked`, because a child's attention request goes to the parent agent, not the user. Herdr's Pi integration does not consume `herdr:busy` yet, so the pane's dot follows the parent's own turn and the metadata label shows the active work.
|
|
596
|
-
- The owning Pi session is the only publisher for its own pane metadata. When an active workflow has an explicit bounded `label`, the newest active label appears in the summary
|
|
613
|
+
- The owning Pi session is the only publisher for its own pane metadata. When an active workflow has an explicit bounded `label`, the newest active label appears in the summary; overlapping completion restores the previous active label. Raw task and goal prompts never enter Herdr metadata. The compact `title-suffix` is always `⏳N`, where N is the number of active subagents, so it stays short in narrow sidebar rows. Attention adds `⚠`, and the suffix is cleared when active work reaches zero.
|
|
597
614
|
|
|
598
615
|
To show the reported label in the expanded Agent sidebar, include `state_text` or `$summary` in its row layout:
|
|
599
616
|
|
package/docs/models.md
CHANGED
|
@@ -164,6 +164,10 @@ Set `subagents.defaultSubagentOnlyExtensions` to give agents without a `subagent
|
|
|
164
164
|
|
|
165
165
|
The two defaults resolve independently, with an explicitly present project value winning over the user value. If both are set, `defaultExtensions` still disables ambient discovery and the child-only paths are loaded alongside its allowlist. Both reject non-arrays, non-string or blank entries with an error naming the setting and source file. Extension paths execute trusted code, so use project defaults only for trusted repositories and extensions.
|
|
166
166
|
|
|
167
|
+
## Global context default
|
|
168
|
+
|
|
169
|
+
Set `subagents.defaultInheritGlobalContext: true` to give every builtin, package, user and project agent your global context file (such as `~/.pi/agent/AGENTS.md`). An agent that declares `inheritGlobalContext` in its frontmatter keeps its own value, and `agentOverrides.<name>.inheritGlobalContext` still wins over both, so `false` in either place opts that agent out. A project value wins over the user value. The setting only matters for agents with `inheritProjectContext: true` (every builtin agent has it); without project context a child gets no context files at all. Runtime-registered agents keep their extension's value. A non-boolean value is rejected with an error naming the settings file.
|
|
170
|
+
|
|
167
171
|
## Inspecting the live mapping
|
|
168
172
|
|
|
169
173
|
To see what `pi-subagents` has actually loaded right now:
|
|
@@ -184,9 +188,9 @@ You do not have to spell a model exactly. Model ids are matched fuzzily against
|
|
|
184
188
|
- Case differences: `Claude-Sonnet-4` vs `claude-sonnet-4`
|
|
185
189
|
- Optional trailing date stamps: `claude-haiku-4-5-20251001` or `claude-haiku-4-5-2025-10-01` vs `claude-haiku-4-5`
|
|
186
190
|
|
|
187
|
-
Exact `provider/id` matches still win, and a qualified provider query never silently switches providers — it only matches within the named provider. Ambiguous bare ids that exist under multiple providers still require a provider prefix or the current session's provider to disambiguate.
|
|
191
|
+
Exact `provider/id` matches still win, and a qualified provider query never silently switches providers — it only matches within the named provider. This holds for providers you are not signed in to: without Anthropic credentials, `anthropic/claude-opus-4-8` fails with an error that names the OpenRouter copy (`openrouter/anthropic/claude-opus-4.8`) instead of running it. Ambiguous bare ids that exist under multiple providers still require a provider prefix or the current session's provider to disambiguate.
|
|
188
192
|
|
|
189
|
-
Registry ids that themselves contain `/` (Hugging Face `owner/name`) resolve the same way as Pi's main agent: `thinkingmachines/Inkling` becomes `huggingface/thinkingmachines/Inkling` when that id is unique or offered by the current session provider. A first path segment that
|
|
193
|
+
Registry ids that themselves contain `/` (Hugging Face `owner/name`) resolve the same way as Pi's main agent: `thinkingmachines/Inkling` becomes `huggingface/thinkingmachines/Inkling` when that id is unique or offered by the current session provider. A first path segment that names any provider Pi knows, signed in or not, still means `provider/id`.
|
|
190
194
|
|
|
191
195
|
## Model scope enforcement
|
|
192
196
|
|
package/docs/observability.md
CHANGED
|
@@ -16,6 +16,8 @@ Long-open `bash` attention notices identify the exact tool call and include stat
|
|
|
16
16
|
|
|
17
17
|
Live progress shows compact detail for single, chain, and parallel modes: a bounded one-line task, current tool, recent output, token counts, aggregate cost, duration, activity freshness, current-tool duration, and chain graph metadata when available. Workflow `label` metadata wins over raw task text in compact multi-child cards.
|
|
18
18
|
|
|
19
|
+
While a child runs, the first line of its latest successful `contact_supervisor` `progress_update` shows as a `progress:` row under its task, with the time since the report.
|
|
20
|
+
|
|
19
21
|
Press Pi's configured expand key (`Ctrl+O` by default) to expand the full streaming view with complete output per step.
|
|
20
22
|
|
|
21
23
|
Sequential chains show a flow line like `done scout → running worker`. Chains with parallel steps show per-step cards instead. Chain status uses `label` and `phase` metadata when present, while falling back to agent names for older chains.
|
package/docs/tool-reference.md
CHANGED
|
@@ -95,6 +95,7 @@ The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `
|
|
|
95
95
|
| `options.view` | `fleet \| transcript` | - | Optional `status` view for the active fleet surface or transcript tail inspection. |
|
|
96
96
|
| `options.lines` | number | `80` | Maximum transcript lines for `action: "status"` with `options.view: "transcript"`; capped at 500. |
|
|
97
97
|
| `options.agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
|
|
98
|
+
| `options.search` | string | - | With `action: "list"`, show only agents whose name, alias, or description contains this text (case-insensitive). |
|
|
98
99
|
| `options.capabilities` | boolean | `false` | With `action: "list"`, return compact prompt-free rows and `details.agentCapabilities` machine-readable records for each agent's declared/default routing capabilities. External CLI rows also include their command and passive local availability. |
|
|
99
100
|
|
|
100
101
|
### Execution parameters
|
|
@@ -105,7 +106,7 @@ The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `
|
|
|
105
106
|
| `options.chatProgress` | `auto \| off \| live-card` | `auto` | Workflow chat projection. `auto` renders a live in-chat card only for watched foreground workflows in the same Git repository, including managed worktrees; it is off otherwise. Explicit `live-card` requires `async:false` and the same Git repository. Async workflows have no inline live card, so omit `chatProgress` or use `auto`/`off`; use `async:false` only when the parent must block. |
|
|
106
107
|
| `isolation` | `none \| worktree` | - | Alias kept at the top level; prefer `worktree`. Workflow child isolation. `none` runs in the shared cwd and does not need Git. `worktree` requires a managed Git worktree. Do not combine it with a contradictory `worktree` value. |
|
|
107
108
|
| `options.baseRef` | string | `HEAD` | `HEAD` or a supported named ref such as `refs/heads/release`, `refs/tags/v1`, or `origin/main`. Full 40/64-character commit IDs and revision expressions such as `HEAD~1` are unsupported. The ref must resolve to a commit at worktree allocation; omitted values default to `HEAD` resolved at that time. Source-checkout cleanliness is still checked. For a workflow script, set it on the outer request as a default or on an individual `runs.run`/`runs.all` child to override it. |
|
|
108
|
-
| `options.timeoutMs` | number | config `timeoutMs`, else 30 min foreground / single-agent async | Optional run-level max runtime in milliseconds. The top-level alias `maxRuntimeMs` is also accepted; both must agree. When omitted, the global [`timeoutMs`](configuration.md#timeoutms) config provides the default; absent that, foreground and plain single-agent async runs fall back to 30 minutes, while composite async runs (chains, parallel tasks, workflows) stay unbounded at the top level. Expiration of this run-level deadline is terminal. |
|
|
109
|
+
| `options.timeoutMs` | number | config `timeoutMs`, else 30 min foreground / single-agent async | Optional run-level max runtime in milliseconds; time a child spends waiting for a supervisor reply (`contact_supervisor` decision or interview, `intercom` ask) does not count. The top-level alias `maxRuntimeMs` is also accepted; both must agree. When omitted, the global [`timeoutMs`](configuration.md#timeoutms) config provides the default; absent that, foreground and plain single-agent async runs fall back to 30 minutes, while composite async runs (chains, parallel tasks, workflows) stay unbounded at the top level. Expiration of this run-level deadline is terminal. |
|
|
109
110
|
| `options.toolTimeoutMs` | number | fast-tool default | Optional positive hard per-tool-call deadline in milliseconds. Precedence: call value → agent frontmatter → config → `PI_SUBAGENT_TOOL_TIMEOUT_MS`. The timer starts on `tool_execution_start`, clears on the matching `tool_execution_end`, and terminates the run with `timedOut: true` if the tool remains open. When omitted, known-fast built-in tools get a five-minute default; long-running tools get attention notices but no hard default. It never extends the run deadline; `contact_supervisor`, `intercom`, and `bg_wait` are exempt. |
|
|
110
111
|
| `options.checkpointBeforeDeadlineMs` | number | none | Async single-agent runs only. The runner requests that the child "checkpoint and stop" this many milliseconds before the run deadline (finish the current tool call, report changed files, build/test state, remaining work, commit/PR state; start no new work). This best-effort steer uses the normal steering lifecycle at the next tool boundary, so the receipt is visible in status and events; the ordinary deadline kill still applies. Precedence: call value → config `checkpointBeforeDeadlineMs`. Disarmed when the deadline leaves under one second before the checkpoint. |
|
|
111
112
|
| `options.toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`: `hard` is a positive integer and `soft`, if set, is a positive integer no greater than `hard`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, and accepts either a nonempty array of tool names or `"*"` for every tool call. Final assistant text is never blocked. |
|
|
@@ -210,6 +211,7 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
210
211
|
{ action: "list" }
|
|
211
212
|
{ action: "list", options: { agentScope: "project" } }
|
|
212
213
|
{ action: "list", options: { capabilities: true } }
|
|
214
|
+
{ action: "list", options: { search: "review" } }
|
|
213
215
|
{ action: "get", agent: "scout" }
|
|
214
216
|
{ action: "models" }
|
|
215
217
|
{ action: "models", agent: "reviewer" }
|
|
@@ -252,6 +254,7 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
252
254
|
|
|
253
255
|
Rules:
|
|
254
256
|
|
|
257
|
+
- `action: "list"` shows at most 30 agents, then a `+N more` line pointing at `options.search`; `details.agentCapabilities` still covers every match.
|
|
255
258
|
- `options.capabilities: true` changes `action: "list"` to compact one-line rows and adds `details.agentCapabilities: { agents, restrictedCount, capabilityCeilingSources? }`. Each agent row includes source, aliases, runner type/capabilities, tools, MCP direct tools, mutation tools, model/thinking, default async/timeout, declared acceptance policy/role, output path/mode, skills/extensions, and whether the current capability ceiling allows execution. External CLI rows include `runner.command`, `runner.available`, and a bounded `runner.unavailableReason` when passive PATH/PATHEXT/X_OK lookup cannot find the command. It never includes an agent's system prompt. Rows show declared/default capabilities and command discoverability, not authentication, version compatibility, or successful launch; launch preflight remains authoritative.
|
|
256
259
|
- `create` uses `config.scope`, not `agentScope`.
|
|
257
260
|
- `config.name` is the local frontmatter name; optional `config.package` registers the runtime name as `{package}.{name}` and is saved as separate `name` and `package` frontmatter.
|
|
@@ -392,6 +395,7 @@ Commands remain owned by the child session. Normal completion with unfinished co
|
|
|
392
395
|
- `/subagents-stop` without an id opens a selector with confirmation when a TUI is available. Use `↑`/`↓` or `j`/`k` to move through the selector. When two or more current-session async runs are active, the first row is "stop all", which stops each of them after one confirmation and leaves scheduled runs alone.
|
|
393
396
|
- In non-TUI contexts the slash command prints exact `subagent({ action: "stop", id })` and `/subagents-stop <id>` commands.
|
|
394
397
|
- Pass a child id to stop one child of a multi-child async run or workflow while the rest continue: `/subagents-stop <run-id> <child-id>` (equivalent to `subagent({ action: "stop", id, childId })`). Child ids come from status output, the async status snapshot, or `/subagents-inspect-rpc` replies. Only pending or running children are stoppable; the request is rejected for anything else instead of widening to a run-level stop.
|
|
398
|
+
- `subagent({ action: "stop", id, options: { drain: true } })` stops a live async workflow in this session without killing running children: children that have not started are stopped, the script cannot start new children or `runs.host` commands, and children already running finish and keep their results. The workflow then ends as stopped and is never resumed. It cannot be combined with `childId`; a full `stop` still works during a drain.
|
|
395
399
|
- Inactive schedules can appear in the selector, but they are labeled as schedules and route through `schedule.pause`, not `stop`.
|
|
396
400
|
|
|
397
401
|
### steer
|
|
@@ -539,6 +543,8 @@ async: true
|
|
|
539
543
|
|
|
540
544
|
Supported: status artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are written to log files, while the in-memory final stdout response and stderr error are limited to their last 64 KiB.
|
|
541
545
|
|
|
546
|
+
A code-owned adapter (`adapter: claude-code-writer` and the others in [agents.md](agents.md#claude-code-profiles)) records a `safety` block and a `safetySource: { measured: false, command }` beside it. The block is the adapter's profile, not a measurement, so a wrapper `command` that changes the CLI's argv can grant something else; see [Safety record and wrapper commands](agents.md#safety-record-and-wrapper-commands).
|
|
547
|
+
|
|
542
548
|
Intentionally unsupported: native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, and nested subagents are also unsupported.
|
|
543
549
|
|
|
544
550
|
## Session sharing
|