pi-subagents 0.57.0 → 0.58.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## [Unreleased]
 
+## [0.58.0] - 2026-08-27
+
+### Highlights
+- Launch MCP tools from more places, including runtime-registered servers, Pi package manifests, and Agent Plugin configs.
+- Keep agent context smaller by default, with an explicit `inheritGlobalContext` opt-in when a child needs the operator's global context.
+- Make detached and recovered workflow results more reliable, with clearer terminal handoffs and recovery actions.
+- Show better launch and status diagnostics for workspace, authority, context-window, and missing-directory problems.
+- Keep fast OpenAI-Codex launches compatible with priority service tier without losing provider request fields.
+
+### Added
+- Support direct MCP tool launches from runtime-registered servers.
+- Add `inheritGlobalContext` agent configuration so children can opt into the operator's global context file separately from repository context. Thanks to [@hknatm](https://github.com/hknatm) for #1560.
+- Add process-local event registration so independent Pi extensions can register runtime agents through the installed owner. Thanks to [@fmoda3](https://github.com/fmoda3) for #1533.
+- Add advisory launch preflight diagnostics for likely workspace scope and authority mismatches.
+- Document per-run thinking suffixes in model-facing subagent guidance. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1565.
+- Document unsupported native child options for external CLI agents in the subagent tool help, packaged guide, and packaged skill.
+
+### Changed
+- Agents now omit the operator's global context file by default, including existing agents with `inheritProjectContext: true`; set `inheritGlobalContext: true` to preserve the previous behavior. Thanks to [@hknatm](https://github.com/hknatm) for #1560.
+
+### Fixed
+- Fail explicitly requested models closed when a cached model exclusion is active, instead of silently selecting a fallback. Thanks to [@harpsychord](https://github.com/harpsychord) for #1556.
+- Preserve fast-mode provider request root fields when adding OpenAI's priority service tier. Thanks to [@nothingrotf](https://github.com/nothingrotf) for #1570.
+- Classify workflow budget and timeout stops as partial terminal outcomes while preserving settled child evidence. Thanks to [@yceachan](https://github.com/yceachan) for #1530.
+- Publish a deterministic terminal handoff with settled child evidence and keyed recovery actions when detached workflow lanes settle. Thanks to [@yceachan](https://github.com/yceachan) for #1530.
+- Resolve direct MCP tool selections from Pi package manifests and Agent Plugin configs. Thanks to [@fmoda3](https://github.com/fmoda3) for #1541.
+- Fail closed with a launch diagnostic when configured runtime-style MCP direct-tool selectors cannot be resolved.
+- Sync Herdr status after restoring active async jobs, so recovered work appears without waiting for another lifecycle event. Thanks to [@vicocamacho](https://github.com/vicocamacho) for #1553.
+- Show task intent and context-window use in compact in-progress async status rows.
+- Report deterministic settlement diagnostics when background children fail before required output handoff.
+- Auto-resume workflow children once after setup-phase aborts that produce zero usage, preserving the retained transcript instead of rerunning the whole task.
+- Finalize detached foreground worktree handoffs after terminal child completion, preserving captured changes before cleanup. Thanks to [@jpriverar](https://github.com/jpriverar) for #1562.
+- Fail native child launches before spawn when the requested local working directory is missing or not a directory, with the requested and resolved paths in the error.
+- Map report paths requested in workflow child tasks to the actual saved child output when workflow output routing overrides them.
+- Stop same-session workflows recovered after extension reload through the durable control channel.
+- Let agents declare extension mutation tools so real non-Git or untracked edits satisfy the implementation completion guard. Thanks to [@AlphaGodzilla](https://github.com/AlphaGodzilla) for #1532.
+- Deliver async results from an explicitly replaced predecessor session without accepting unrelated session results. Thanks to [@DresvyanskiyDenis](https://github.com/DresvyanskiyDenis) for #1531.
+- Avoid attributing assistant-issued workflow stops to the user.
+
 ## [0.57.0] - 2026-08-26
 
 ### Highlights

package/docs/agents.md

@@ -57,6 +57,8 @@ The Pi async run remains the source of truth for status, artifacts, wake/wait, m
 
 ### Advisory runner data boundary
 
+External CLI agents use their own runner contract. Do not pass 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 adapter explicitly implements them.
+
 The built-in `codex-exec` and `codex-exec-writer` profiles are the supported Codex one-shot modes. Both require an installed and authenticated Codex CLI. The adapters own `codex exec --json` argv with ignored user config and rules, ephemeral sessions, approval policy `never`, and a final-message artifact.
 
 | Profile | Access | Sandbox |
@@ -207,7 +209,7 @@ You can override selected builtin fields without copying the whole agent. Overri
 }
 ```
 
-Supported override fields: `description`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, and `systemPrompt`.
+Supported override fields: `description`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, and `systemPrompt`.
 
 - `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
 - Use `output: false`, `defaultReads: false`, `defaultContext: false`, or `acceptanceRole: false` to clear an inherited value.
@@ -234,11 +236,12 @@ Use these fields when an agent should see more:
 | Field | Effect |
 |-------|--------|
 | `systemPromptMode: append` | Append the agent prompt to Pi's normal base prompt. |
-| `inheritProjectContext: true` | Keep inherited project instructions from files like `AGENTS.md` and `CLAUDE.md`. |
+| `inheritProjectContext: true` | Keep inherited repository instructions from files like `AGENTS.md` and `CLAUDE.md`. |
+| `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`. |
 | `inheritSkills: true` | Let the child see Pi's discovered skills catalog. |
 | `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. |
 
-Builtin agents opt into project instruction inheritance by default so they follow repo-specific rules out of the box. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
+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.
 
 ## Frontmatter reference
 
@@ -255,10 +258,11 @@ tools: read, grep, find, ls, bash, mcp:chrome-devtools
 extensions:
 subagentOnlyExtensions: ./tools/child-only-search.ts
 model: claude-haiku-4-5
-fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
+fallbackModels: openai-codex/gpt-5.6-luna:low, anthropic/claude-sonnet-4
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: false
+inheritGlobalContext: false
 inheritSkills: false
 skills: safe-bash, review-checklist
 skillPath: ./skills, ../shared-skills
@@ -286,7 +290,7 @@ tools:
   - read
   - mcp:github/search_repositories
 fallbackModels:
-  - openai/gpt-5-mini
+  - openai-codex/gpt-5.6-luna:low
   - anthropic/claude-sonnet-4
 ```
 
@@ -303,7 +307,8 @@ Field notes:
 | `fallbackModels` | Ordered backup models for provider/model failures such as quota, auth, timeout, or unavailable model. Ordinary task failures do not trigger fallback. |
 | `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
 | `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
-| `inheritProjectContext` | Keeps or strips inherited project instruction blocks. |
+| `inheritProjectContext` | Keeps or strips inherited repository instruction blocks. |
+| `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. Defaults to `false`. |
 | `inheritSkills` | Keeps or strips Pi's discovered skills catalog. |
 | `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. |
 | `skills` | Selects specific skills for the child, regardless of `inheritSkills`. |
@@ -317,6 +322,7 @@ Field notes:
 | `turnBudget` | JSON object default such as `{"maxTurns":20,"graceTurns":2}` for single-agent launches. An explicit call value wins, followed by this agent default, then global `turnBudget` config. |
 | `acceptance` | Acceptance default for single-agent launches. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. Explicit call values win; chain and parallel acceptance remains task/step configuration. |
 | `acceptanceRole` | Optional `read-only` or `writer` role for automatic acceptance inference. Explicit task mutation or no-edit intent wins; otherwise the declared role replaces agent-name guessing. This does not grant or revoke tools. |
+| `mutationTools` | Comma-separated extension tool names whose calls count as mutation attempts for the completion guard. This declares evidence only; list and load each tool through `tools` and its extension provider as usual. |
 | `completionGuard` | Set `false` only for non-implementation agents that may mention implementation words while using mutation-capable tools such as `bash`. |
 | `interactive` | Parsed for compatibility but not currently enforced. |
 | `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
@@ -385,6 +391,7 @@ More rules:
 - `mcp:` entries are split out and forwarded as direct MCP selections without granting normal builtins unless those builtins are also listed.
 - Path-like `tools` entries, such as extension paths or `.ts`/`.js` files, are treated as tool-extension paths rather than tool names.
 - Internal runtime tools such as `structured_output` are added to an explicit allowlist only when their contract is active.
+- Unknown extension tool calls count as mutation attempts only when their names are listed in `mutationTools`; undeclared unknown tools keep the no-edit guard active.
 - Agents that declare only known read-only builtin tools skip the implementation completion guard. `bash`, unknown tools, and MCP tools stay mutation-capable. Use `completionGuard: false` for bash-enabled validators or advisors that should never be judged as implementation agents.
 
 Examples:

package/docs/extension-api.md

@@ -58,6 +58,45 @@ The DTO intentionally never exposes run, async, or tool IDs. Clients must ignore
 
 `pi.events` is in-process only. It does not reach separate Pi processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
 
+## Runtime agent registration from independent extensions
+
+An independently installed Pi extension can register an agent with the installed `pi-subagents` owner through the process-local `pi-subagents:runtime-agent-register:v1` event. Emit after extension setup, such as during `session_start`. Event delivery is synchronous, so the owner writes the result onto the request before `emit()` returns.
+
+```typescript
+const request: {
+  version: 1;
+  name: string;
+  definition: {
+    description: string;
+    systemPrompt: string;
+    tools?: readonly string[];
+  };
+  result?:
+    | { ok: true; registration: { dispose(): void } }
+    | { ok: false; error: Error };
+} = {
+  version: 1,
+  name: "runtime-probe-agent",
+  definition: {
+    description: "Agent registered by an independent extension",
+    systemPrompt: "Return the words runtime probe.",
+    tools: [],
+  },
+};
+
+pi.events.emit("pi-subagents:runtime-agent-register:v1", request);
+if (!request.result) throw new Error("pi-subagents is not installed or not ready");
+if (!request.result.ok) throw request.result.error;
+const registration = request.result.registration;
+// Call registration.dispose() during your extension cleanup.
+```
+
+If `pi-subagents` is a resolvable dependency of the consumer package, `pi-subagents/agents` exports `RUNTIME_AGENT_REGISTER_EVENT`, the request/result types, and `registerAgentViaEvents()` for the same contract. A separately installed Pi package is not automatically a Node dependency of another package. In that case, use the event contract directly instead of a runtime import. A type-only development dependency is optional.
+
+The installed owner applies the existing runtime-agent validation, collision checks, limits, runtime source metadata, and cleanup. If more than one owner listens, the first handler that writes `request.result` wins. Unsupported versions, malformed requests, and registration failures return `{ ok: false, error }`. No result means no compatible owner handled the event.
+
+This contract is process-local. It does not register agents in child processes or other Pi processes, and it does not change package discovery or package resolution.
+
 ## External jobs in FleetView
 
 Use `pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:

package/docs/models.md

@@ -51,7 +51,7 @@ For a persistent role override with a backup model for provider failures:
       "reviewer": {
         "model": "anthropic/claude-sonnet-4",
         "thinking": "high",
-        "fallbackModels": ["openai/gpt-5-mini"]
+        "fallbackModels": ["openai-codex/gpt-5.6-luna:low"]
       }
     }
   }
@@ -182,9 +182,9 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
     "modelScope": {
       "enforce": true,
       "strict": true,
-      "allow": ["inherit", "openai/gpt-5-*"],
+      "allow": ["inherit", "openai/gpt-5-*", "openai-codex/gpt-5.6-*"],
       "agents": {
-        "worker": { "allow": ["openai/gpt-5-mini"] },
+        "worker": { "allow": ["openai-codex/gpt-5.6-luna"] },
         "reviewer": { "allow": ["inherit"] }
       }
     }

package/docs/tool-reference.md

@@ -159,9 +159,10 @@ Agent definitions are not loaded into context by default. Management actions let
   systemPrompt: "You are a code scout...",
   systemPromptMode: "replace",
   inheritProjectContext: false,
+  inheritGlobalContext: false,
   inheritSkills: false,
   model: "anthropic/claude-sonnet-4",
-  fallbackModels: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"],
+  fallbackModels: ["openai-codex/gpt-5.6-luna:low", "anthropic/claude-haiku-4-5"],
   tools: "read, bash, mcp:github/search_repositories",
   extensions: "",
   skills: "parallel-scout",
@@ -371,7 +372,7 @@ async: true
 
 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.
 
-Intentionally unsupported: foreground/clarify, steer/resume/interrupt-as-pause, Pi models/tools/extensions, skills, structured output, nested subagents, and fallback models.
+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, nested subagents, and fallback models are also unsupported.
 
 ## Session sharing
 

package/docs/workflows.md

@@ -57,6 +57,30 @@ subagent({ action: "validate", workflowScriptPath: "workflows/review.js" });
 
 The fields are mutually exclusive. Relative paths resolve against the request `cwd`; absolute paths pass through. The host reads the file before validation, schedule creation, or workflow sandbox execution. The sandbox still has no filesystem access. Missing, unreadable, and empty files return file input errors instead of script syntax errors.
 
+### Opt-in bounded workflows
+
+Composite workflows have no default parent deadline. Add bounds only when the workflow contract calls for them:
+
+```js
+subagent({
+  workflowScript: `
+    const scan = await runs.run("scan", { agent: "scout", task: "Inspect the named files." });
+    return runs.run("review", { agent: "reviewer", task: "Review:\n" + scan.output });
+  `,
+  timeoutMs: 900000,
+  turnBudget: { maxTurns: 30, graceTurns: 2 },
+  toolBudget: { soft: 40, hard: 60 },
+  usageBudget: { tokens: { soft: 100000, hard: 150000 } }
+});
+```
+
+- `timeoutMs` sets the workflow deadline and bounds child deadlines to the remaining time.
+- `turnBudget` and `toolBudget` become defaults for each child unless that child supplies a narrower value.
+- `usageBudget` accounts for reported usage across completed workflow children. Once exhausted, it rejects later child launches but does not stop children that are already running.
+- Budget and timeout stops return a structured `terminalOutcome` with `state: "partial"` and reason `budget_exhausted` or `timeout`. Workflow receipts keep settled child evidence for recovery.
+
+These controls are opt-in. Avoid tight hard budgets for mutation-capable workers unless the workflow has an explicit checkpoint and handoff path.
+
 The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -31,6 +31,8 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 
 For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
 
+External CLI agents such as `codex-exec`, `codex-exec-writer`, `claude-code`, and `cursor-agent` use their own runner contract. Do not pass 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 that runner explicitly implements them.
+
 ## Always-on constraints
 
 - Keep the parent as orchestrator and final decision-maker.

package/skills/pi-subagents/references/execution-controls.md

@@ -24,7 +24,7 @@ Project settings resolve from the nearest parent directory containing `.pi` or `
 
 An agent may set `runner.type: external-cli` with a non-empty `command`, optional string `args`, and `promptDelivery: stdin` (the default). The command runs with `shell: false`, inherits the resolved cwd and environment, and receives the combined agent instructions and task through stdin. It must already be installed; pi-subagents adds no CLI dependency.
 
-External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support foreground/clarify, steer/resume/interrupt-as-pause, Pi models/tools/extensions/skills, tool or turn budgets, structured output, nested subagents, fallbacks, or sessions.
+External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support 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, nested subagents, fallbacks, and sessions are also unsupported.
 
 ### External job profiles
 

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -102,6 +102,7 @@ thinking: high
 tools: read, grep, find, ls, bash
 systemPromptMode: replace
 inheritProjectContext: true
+inheritGlobalContext: false
 inheritSkills: false
 skills: safe-bash, review-checklist
 skillPath: ./skills, ../shared-skills

package/skills/pi-subagents/references/prompting-and-roles.md

@@ -230,7 +230,7 @@ Direct settings example:
       "reviewer": {
         "model": "anthropic/claude-sonnet-4",
         "thinking": "high",
-        "fallbackModels": ["openai/gpt-5-mini"],
+        "fallbackModels": ["openai-codex/gpt-5.6-luna:low"],
         "acceptanceRole": "read-only"
       }
     }
@@ -239,7 +239,7 @@ Direct settings example:
 ```
 
 Useful override fields: `description`, `model`, `fallbackModels`, `thinking`,
-`systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`,
+`systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`,
 `acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
 `description` replaces the discovered description for builtin and custom agents
 in `list` output, which is useful for deployment-specific routing notes.

package/src/agents/agent-management.ts

@@ -230,6 +230,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		thinking: _thinking,
 		systemPromptMode: _systemPromptMode,
 		inheritProjectContext: _inheritProjectContext,
+		inheritGlobalContext: _inheritGlobalContext,
 		inheritSkills: _inheritSkills,
 		defaultContext: _defaultContext,
 		acceptanceRole: _acceptanceRole,
@@ -240,6 +241,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		tools: _tools,
 		mcpDirectTools: _mcpDirectTools,
 		subagentOnlyExtensions: _subagentOnlyExtensions,
+		mutationTools: _mutationTools,
 		completionGuard: _completionGuard,
 		...editable
 	} = withoutExtensions;
@@ -260,6 +262,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
 		systemPromptMode: base.systemPromptMode,
 		inheritProjectContext: base.inheritProjectContext,
+		inheritGlobalContext: base.inheritGlobalContext,
 		inheritSkills: base.inheritSkills,
 		...(base.defaultContext !== undefined ? { defaultContext: base.defaultContext } : {}),
 		...(base.acceptanceRole !== undefined ? { acceptanceRole: base.acceptanceRole } : {}),
@@ -271,6 +274,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		...(base.mcpDirectTools !== undefined ? { mcpDirectTools: [...base.mcpDirectTools] } : {}),
 		...(base.extensions !== undefined ? { extensions: [...base.extensions] } : {}),
 		...(base.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...base.subagentOnlyExtensions] } : {}),
+		...(base.mutationTools !== undefined ? { mutationTools: [...base.mutationTools] } : {}),
 		...(base.completionGuard !== undefined ? { completionGuard: base.completionGuard } : {}),
 	}, agent.filePath);
 }
@@ -303,6 +307,7 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
 	if (hasKey(cfg, "skillPath")) changed("skillPath");
 	if (hasKey(cfg, "extensions")) changed("extensions");
 	if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
+	if (hasKey(cfg, "mutationTools")) changed("mutationTools");
 	if (hasKey(cfg, "thinking")) {
 		changed("thinking");
 		if (cfg.thinking === "off") fields.add("thinking");
@@ -315,6 +320,10 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
 		changed("inheritProjectContext");
 		fields.add("inheritProjectContext");
 	}
+	if (hasKey(cfg, "inheritGlobalContext")) {
+		changed("inheritGlobalContext");
+		fields.add("inheritGlobalContext");
+	}
 	if (hasKey(cfg, "inheritSkills")) {
 		changed("inheritSkills");
 		fields.add("inheritSkills");
@@ -457,6 +466,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.subagentOnlyExtensions === "string") target.subagentOnlyExtensions = parseCsv(cfg.subagentOnlyExtensions);
 		else return "config.subagentOnlyExtensions must be a comma-separated string, empty string, or false when provided.";
 	}
+	if (hasKey(cfg, "mutationTools")) {
+		if (cfg.mutationTools === false) delete target.mutationTools;
+		else if (cfg.mutationTools === "") target.mutationTools = [];
+		else if (typeof cfg.mutationTools === "string") target.mutationTools = parseCsv(cfg.mutationTools);
+		else return "config.mutationTools must be a comma-separated string, empty string, or false when provided.";
+	}
 	if (hasKey(cfg, "thinking")) {
 		if (cfg.thinking === false || cfg.thinking === "") delete target.thinking;
 		else if (typeof cfg.thinking === "string") {
@@ -473,6 +488,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		if (typeof cfg.inheritProjectContext !== "boolean") return "config.inheritProjectContext must be a boolean when provided.";
 		target.inheritProjectContext = cfg.inheritProjectContext;
 	}
+	if (hasKey(cfg, "inheritGlobalContext")) {
+		if (typeof cfg.inheritGlobalContext !== "boolean") return "config.inheritGlobalContext must be a boolean when provided.";
+		target.inheritGlobalContext = cfg.inheritGlobalContext;
+	}
 	if (hasKey(cfg, "inheritSkills")) {
 		if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
 		target.inheritSkills = cfg.inheritSkills;
@@ -561,6 +580,7 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 			target.thinking ? "thinking" : undefined,
 			target.extensions?.length ? "extensions" : undefined,
 			target.subagentOnlyExtensions?.length ? "subagentOnlyExtensions" : undefined,
+			target.mutationTools?.length ? "mutationTools" : undefined,
 			target.skills?.length || target.skillPath?.length ? "skills" : undefined,
 			target.maxSubagentDepth !== undefined ? "maxSubagentDepth" : undefined,
 			target.completionGuard !== undefined ? "completionGuard" : undefined,
@@ -699,6 +719,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 		if (agent.runner?.type === "external-job" && agent.runner.options) lines.push(`Runner options: ${JSON.stringify(agent.runner.options)}`);
 	}
 	lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
+	lines.push(`Inherit global context: ${agent.inheritGlobalContext ? "true" : "false"}`);
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
 	if (agent.defaultAsync !== undefined) lines.push(`Async: ${agent.defaultAsync ? "true" : "false"}`);
@@ -709,6 +730,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
+	if (agent.mutationTools !== undefined) lines.push(`Mutation tools: ${agent.mutationTools.length ? agent.mutationTools.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.outputMode) lines.push(`Output mode: ${agent.outputMode}`);
@@ -915,6 +937,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 		systemPrompt: "",
 		systemPromptMode: defaultSystemPromptMode(name),
 		inheritProjectContext: defaultInheritProjectContext(name),
+		inheritGlobalContext: false,
 		inheritSkills: defaultInheritSkills(),
 	};
 	const applyError = applyAgentConfig(agent, cfg);

package/src/agents/agent-serializer.ts

@@ -15,6 +15,7 @@ export const KNOWN_FIELDS = new Set([
 	"thinking",
 	"systemPromptMode",
 	"inheritProjectContext",
+	"inheritGlobalContext",
 	"inheritSkills",
 	"defaultContext",
 	"async",
@@ -28,6 +29,7 @@ export const KNOWN_FIELDS = new Set([
 	"skillPath",
 	"extensions",
 	"subagentOnlyExtensions",
+	"mutationTools",
 	"output",
 	"outputMode",
 	"defaultReads",
@@ -78,6 +80,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	}
 	if (!preservingExistingFrontmatter || preserve("systemPromptMode")) lines.push(`systemPromptMode: ${config.systemPromptMode}`);
 	if (!preservingExistingFrontmatter || preserve("inheritProjectContext")) lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
+	if (config.inheritGlobalContext || preserve("inheritGlobalContext")) lines.push(`inheritGlobalContext: ${config.inheritGlobalContext ? "true" : "false"}`);
 	if (!preservingExistingFrontmatter || preserve("inheritSkills")) lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
 	if (config.defaultContext || preserve("defaultContext")) lines.push(`defaultContext: ${config.defaultContext ?? ""}`);
 	if (config.runner || preserve("runner")) {
@@ -114,6 +117,8 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 		const subagentOnlyExtensionsValue = joinComma(config.subagentOnlyExtensions);
 		lines.push(`subagentOnlyExtensions: ${subagentOnlyExtensionsValue ?? ""}`);
 	}
+	const mutationToolsValue = joinComma(config.mutationTools);
+	if (mutationToolsValue || preserve("mutationTools")) lines.push(`mutationTools: ${mutationToolsValue ?? ""}`);
 
 	if (config.output || preserve("output")) lines.push(`output: ${config.output ?? ""}`);
 	if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);