@crewhaus/tool-task 0.6.0 → 0.8.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -0,0 +1,11 @@
+# @crewhaus/tool-task
+
+Task(description, prompt, subagent_type?) tool — spawns a sub-agent and returns its final message (Section 13)
+
+Part of [CrewHaus](https://github.com/crewhaus/factory). Most people install the CLI (`npm install -g crewhaus`) rather than this package.
+
+Which tools a spec can turn on, and how: [tools reference](https://github.com/crewhaus/docs/blob/main/TOOLS-REFERENCE.md).
+
+Requires [Bun](https://bun.sh) `>=1.3.14`; plain Node is not supported.
+
+[Source](https://github.com/crewhaus/factory/tree/main/packages/tool-task)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type SubAgentDefinition, type SubAgentFailure } from "@crewhaus/agent-context-isolation";
 import { CrewhausError } from "@crewhaus/errors";
-import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { type RegisteredTool } from "@crewhaus/tool-catalog";
 import { z } from "zod";
 export declare class SubAgentResolutionError extends CrewhausError {
     readonly name = "SubAgentResolutionError";

package/dist/index.js

@@ -14,7 +14,12 @@
  *   1. `opts.subAgents.get(name)` — inline spec map (codegen-supplied).
  *   2. `<opts.subAgentDir or cwd/.crewhaus/sub-agents>/<name>.md` — frontmatter
  *      file on disk. Format mirrors SKILL.md: leading `---` YAML block, body
- *      becomes `instructions`.
+ *      becomes `instructions`. Any agent with a write tool can put a file
+ *      there, so a definition from disk can only NARROW: its permissions
+ *      meet the parent's, its pool candidates carry no tool_config, it runs
+ *      only on models the spec already names (a model id can carry an
+ *      endpoint), and the file is read without following a link or opening
+ *      a FIFO planted in its place.
  *   3. Built-in `general-purpose` fallback.
  *
  * Concurrency: a Task dispatch runs in parallel with its siblings ONLY
@@ -38,12 +43,14 @@
  * occurs when callers wire `Task` into a `runChatLoop` invocation that
  * doesn't pass `spawnSubAgent`.
  */
-import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { projectParentHandle, subAgentProfileAllowlist, } from "@crewhaus/agent-context-isolation";
 import { CrewhausError } from "@crewhaus/errors";
-import { resolveChildPermissions } from "@crewhaus/sub-agent-permission-inheritance";
+import { resolveChildPermissions, resolveChildPermissionsNarrowOnly, } from "@crewhaus/sub-agent-permission-inheritance";
 import { buildTool } from "@crewhaus/tool-builder";
+import { toolListEntryNames } from "@crewhaus/tool-catalog";
+import { builtinKeyForName, expandToolSelectors, registeredToolName, } from "@crewhaus/tool-categories";
+import { openForReadSync } from "@crewhaus/tool-safety/fs";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 export class SubAgentResolutionError extends CrewhausError {
@@ -128,7 +135,9 @@ const FRONTMATTER_TIER_ROUTING = z
  * circuit_breaker? }` — the already-resolved shape the compiler produces for a
  * spec-declared sub-agent. `model_pool` is validated for its routing identity
  * (`candidates[].{model, tags}`, `policy`) and otherwise passed through: the
- * runtime owns the per-candidate settings grammar.
+ * runtime owns the per-candidate settings grammar. The Task tool then keeps
+ * only the candidate keys {@link DISK_CANDIDATE_KEYS} allows, because a file
+ * read from the sub-agents directory may have been written by the model.
  */
 const FRONTMATTER_SCHEMA = z.object({
     name: z.string().min(1),
@@ -275,12 +284,29 @@ export function parseSubAgentFile(content, fallbackName) {
     };
     return def;
 }
+/** A definition is a page of prose; anything past this is not one. */
+const SUB_AGENT_FILE_MAX_BYTES = 256 * 1024;
+/**
+ * The file is read contained to the directory, never through a symlink at
+ * the leaf, with a FIFO refused before it is opened and the size capped.
+ * The directory is one any agent with a write tool can populate: `<name>.md`
+ * linked to a file outside it used to be read and handed to a child as its
+ * instructions, and a FIFO there blocked the event loop for every session.
+ */
 function loadSubAgentFromDisk(name, dir) {
-    const filePath = join(dir, `${name}.md`);
-    if (!existsSync(filePath))
-        return null;
-    const content = readFileSync(filePath, "utf-8");
-    return parseSubAgentFile(content, name);
+    const read = openForReadSync(dir, `${name}.md`, {
+        maxBytes: SUB_AGENT_FILE_MAX_BYTES,
+        followLeafSymlink: false,
+    });
+    if (!read.ok) {
+        if (read.code === "not-found")
+            return null;
+        throw new SubAgentResolutionError(`sub-agent "${name}" in ${dir} was not read: ${read.reason}`);
+    }
+    if (read.truncated) {
+        throw new SubAgentResolutionError(`sub-agent "${name}" in ${dir} is larger than ${SUB_AGENT_FILE_MAX_BYTES} bytes, so it was not read`);
+    }
+    return parseSubAgentFile(read.text, name);
 }
 /**
  * `subagent_type` is a model-filled tool argument and model output is
@@ -302,11 +328,20 @@ function isUnsafeSubAgentName(name) {
 }
 /** Resolve a sub-agent name to a definition using the documented order. */
 export function resolveSubAgentDefinition(name, opts) {
+    return resolveSubAgent(name, opts).def;
+}
+/**
+ * The definition AND where it came from. A definition read from the
+ * sub-agents directory is untrusted: any agent that can write a file can
+ * put one there mid-run, so its permissions may only narrow the parent's
+ * (security-1#1). The inline spec map and the built-in are operator-written.
+ */
+function resolveSubAgent(name, opts) {
     const resolveName = name ?? "general-purpose";
     if (opts.subAgents !== undefined) {
         const inline = opts.subAgents.get(resolveName);
         if (inline !== undefined)
-            return inline;
+            return { def: inline, fromDisk: false };
     }
     // Guard the disk lookup against path traversal (the inline map above is an
     // exact-key lookup and is intentionally not gated).
@@ -316,9 +351,9 @@ export function resolveSubAgentDefinition(name, opts) {
     const dir = opts.subAgentDir ?? join(process.cwd(), ".crewhaus", "sub-agents");
     const onDisk = loadSubAgentFromDisk(resolveName, dir);
     if (onDisk !== null)
-        return onDisk;
+        return { def: onDisk, fromDisk: true };
     if (resolveName === "general-purpose")
-        return BUILTIN_GENERAL_PURPOSE;
+        return { def: BUILTIN_GENERAL_PURPOSE, fromDisk: false };
     throw new SubAgentResolutionError(`unknown subagent_type "${resolveName}" — not in spec sub_agents map, not on disk at ${dir}, and no built-in by that name`);
 }
 /**
@@ -326,15 +361,296 @@ export function resolveSubAgentDefinition(name, opts) {
  * tool-name allowlist on the definition. Undefined `def.tools` (with
  * `permissions: "inherit"`) → the child inherits the parent's full
  * catalog. Undefined `def.tools` with any other permission mode → empty
- * child catalog (the user has implicitly opted out).
+ * child catalog (the user has implicitly opted out). An MCP tool may be
+ * listed by its pre-0.7.1 spelling (`<server>__<tool>`).
  */
 function buildChildCatalog(parentTools, def) {
     const allowed = def.tools;
     if (allowed === undefined) {
         return def.permissions === undefined || def.permissions === "inherit" ? parentTools : [];
     }
-    const allowlist = new Set(allowed);
-    return parentTools.filter((t) => allowlist.has(t.name));
+    // A spec key (`read`) names the same tool as its registered name (`Read`);
+    // the parent catalog carries registered names, so map keys first. Before
+    // this, a definition written with spec keys — the documented spelling for
+    // every other tools: list — gave the child no tools at all. An MCP entry may
+    // still use the pre-0.7.1 `<server>__<tool>` spelling (toolListEntryNames).
+    return parentTools.filter((t) => allowed.some((entry) => toolListEntryNames(registeredToolName(entry) ?? entry, t.name)));
+}
+/**
+ * The definition with its `tools` mapped to registered names (`read` → `Read`).
+ *
+ * A definition from disk never passed through the compiler, so its list is
+ * also expanded here the way the compiler expands a spec's: a category
+ * (`all-git`) or an exclusion (`-gitPush`) becomes the tool keys it names,
+ * and a builtin key is matched without regard to case (`gitstatus`), as
+ * `builtinKeyForName` does. Before this, either spelling gave the child no
+ * tools at all, silently. A bad category throws the compiler's own
+ * `ToolCategoryError`, which the Task call reports.
+ */
+function withRegisteredToolNames(def, fromDisk) {
+    if (def.tools === undefined)
+        return def;
+    const listed = fromDisk ? expandToolSelectors(def.tools).tools : def.tools;
+    const tools = listed.map((n) => registeredToolName(n) ??
+        (fromDisk ? registeredToolName(builtinKeyForName(n) ?? n) : undefined) ??
+        n);
+    if (tools.length !== def.tools.length)
+        return { ...def, tools };
+    // Already canonical (every spec-declared definition is, since lowering maps
+    // it): hand back the same object.
+    return tools.every((n, i) => n === def.tools?.[i]) ? def : { ...def, tools };
+}
+/** Definitions whose ignored allow list has already been reported. */
+const reportedIgnoredAllows = new Set();
+/**
+ * The `model_pool` candidate keys a definition read from `.crewhaus/sub-agents`
+ * keeps. Every key of the candidate type is decided here — this mapped type
+ * stops compiling when the IR gains one — and any other key in the file is
+ * dropped. `toolConfigs` is not kept: a candidate's block REPLACES the
+ * operator's `tool_config` for every call that candidate serves (an http
+ * allow-list, a webhook target) and reads `$VAR`s from the operator's
+ * environment, so a file the model could have written must not set it. The
+ * rest can only narrow (`tools`, `permissions`, `rateLimits`, `costCapUsdMicros`)
+ * or pick what the file could pick anyway with `model:`.
+ */
+const DISK_CANDIDATE_KEYS = {
+    profile: true,
+    model: true,
+    tags: true,
+    enabled: true,
+    thinking: true,
+    maxTokens: true,
+    temperature: true,
+    modelCallTimeoutMs: true,
+    overlay: true,
+    tools: true,
+    toolConfigs: false,
+    permissions: true,
+    rateLimits: true,
+    caching: true,
+    costCapUsdMicros: true,
+    requires: true,
+    capabilities: true,
+    fallbacks: true,
+    circuitBreaker: true,
+};
+/**
+ * security — a definition on disk keeps only {@link DISK_CANDIDATE_KEYS} on
+ * each pool candidate. Returns the refused keys it found, to report.
+ */
+function narrowDiskModelPool(def) {
+    const pool = def.modelPool;
+    if (pool === undefined)
+        return { def, refused: [] };
+    const refused = new Set();
+    let changed = false;
+    const candidates = pool.candidates.map((candidate) => {
+        const kept = {};
+        for (const [key, value] of Object.entries(candidate)) {
+            const decided = Object.hasOwn(DISK_CANDIDATE_KEYS, key)
+                ? DISK_CANDIDATE_KEYS[key]
+                : undefined;
+            if (decided === true) {
+                kept[key] = value;
+                continue;
+            }
+            changed = true;
+            if (decided === false)
+                refused.add(key);
+        }
+        return kept;
+    });
+    if (!changed)
+        return { def, refused: [] };
+    return { def: { ...def, modelPool: { ...pool, candidates } }, refused: [...refused] };
+}
+/** Definitions whose refused model_pool keys have already been reported. */
+const reportedRefusedPoolKeys = new Set();
+/**
+ * The model strings a pool's `strategy` block names (`guide.model`,
+ * `shadow.candidate`, `shadow.gradeWith`, `committee.judge`). A pool from
+ * disk is passed through unvalidated below `candidates`, so a slot may hold
+ * anything: it is returned as found, and the caller refuses a non-string.
+ */
+function strategyModelSlots(strategy) {
+    if (typeof strategy !== "object" || strategy === null)
+        return [strategy];
+    const s = strategy;
+    const field = (block, key) => typeof block === "object" && block !== null
+        ? block[key]
+        : undefined;
+    return [
+        field(s["guide"], "model"),
+        field(s["shadow"], "candidate"),
+        field(s["shadow"], "gradeWith"),
+        field(s["committee"], "judge"),
+    ].filter((v) => v !== undefined);
+}
+/**
+ * security — a disk definition's pool keeps only models the spec names, in
+ * every slot the runtime can call: each candidate's `model` (a candidate on
+ * another model is removed) and its `fallbacks` (the runtime builds a
+ * failover chain from them, and a file-chosen breaker threshold of 1 turns
+ * one transient error into every call going to the fallback), and the
+ * pool-level `classifier` and `strategy` blocks, which name models of their
+ * own. Returns the same object when nothing was narrowed, and undefined when
+ * no candidate is left.
+ */
+function narrowPoolModels(pool, ok) {
+    let changed = false;
+    const candidates = [];
+    for (const candidate of pool.candidates) {
+        if (!ok(candidate.model)) {
+            changed = true;
+            continue;
+        }
+        const fallbacks = candidate.fallbacks;
+        if (fallbacks === undefined) {
+            candidates.push(candidate);
+            continue;
+        }
+        const kept = Array.isArray(fallbacks)
+            ? fallbacks.filter((m) => typeof m === "string" && ok(m))
+            : [];
+        if (Array.isArray(fallbacks) && kept.length === fallbacks.length) {
+            candidates.push(candidate);
+            continue;
+        }
+        changed = true;
+        const { fallbacks: _dropped, ...rest } = candidate;
+        candidates.push(kept.length > 0 ? { ...rest, fallbacks: kept } : rest);
+    }
+    if (candidates.length === 0)
+        return undefined;
+    const { classifier, strategy, ...base } = pool;
+    const classifierModel = classifier?.model;
+    const keepClassifier = classifier === undefined || (typeof classifierModel === "string" && ok(classifierModel));
+    const keepStrategy = strategy === undefined ||
+        strategyModelSlots(strategy).every((m) => typeof m === "string" && ok(m));
+    if (!changed && keepClassifier && keepStrategy)
+        return pool;
+    return {
+        ...base,
+        candidates,
+        ...(keepClassifier && classifier !== undefined ? { classifier } : {}),
+        ...(keepStrategy && strategy !== undefined ? { strategy } : {}),
+    };
+}
+/**
+ * Every model the operator's spec names for this Task tool: every model the
+ * parent run was configured with (its primary, fallbacks, tiers, pool
+ * candidates and their fallbacks, compaction and budget-degrade models — the
+ * runtime puts them on the bridge as `specModels`), the arm serving the
+ * parent right now, and every model an inline (spec) definition can run on.
+ * Exact strings: `vertex/claude-x` and `claude-x` reach different endpoints,
+ * and so do two `local/…@url` strings.
+ */
+function declaredModels(bridge, subAgents) {
+    const out = new Set([bridge.model, ...(bridge.specModels ?? [])]);
+    if (bridge.routing?.served.model !== undefined)
+        out.add(bridge.routing.served.model);
+    for (const def of subAgents?.values() ?? []) {
+        if (def.model !== undefined)
+            out.add(def.model);
+        for (const m of def.modelFallbacks ?? [])
+            out.add(m);
+        if (def.modelTiers !== undefined) {
+            out.add(def.modelTiers.fast);
+            out.add(def.modelTiers.default);
+        }
+        for (const c of def.modelPool?.candidates ?? []) {
+            out.add(c.model);
+            for (const m of c.fallbacks ?? [])
+                out.add(m);
+        }
+        for (const o of def.allowedProfiles ?? []) {
+            out.add(o.model);
+            for (const m of o.modelFallbacks ?? [])
+                out.add(m);
+        }
+    }
+    return out;
+}
+/**
+ * security — a definition on disk may run only on models the spec already
+ * names ({@link declaredModels}). A model id can carry an endpoint
+ * (`local/<model>@<url>`), so a file the agent wrote could otherwise send the
+ * child's whole conversation — its prompt and every tool result it reads —
+ * to a host of its choosing, or pick a model the operator never agreed to pay
+ * for; 0.6.0 §7.7 already refuses the second for the Task `profile` argument.
+ * Anything else is dropped, and the child runs on the parent's model.
+ * Returns the fields it dropped, to report — never the model strings, which
+ * can carry a URL.
+ */
+function narrowDiskModels(def, declared) {
+    const refused = [];
+    const ok = (model) => declared.has(model);
+    let next = def;
+    const drop = (field, label) => {
+        const { [field]: _dropped, ...rest } = next;
+        next = rest;
+        refused.push(label);
+    };
+    if (def.model !== undefined && !ok(def.model)) {
+        drop("model", "model");
+        if (next.modelProfile !== undefined) {
+            const { modelProfile: _p, ...rest } = next;
+            next = rest;
+        }
+    }
+    if (def.modelFallbacks !== undefined && !def.modelFallbacks.every(ok)) {
+        const kept = def.modelFallbacks.filter(ok);
+        if (kept.length > 0) {
+            next = { ...next, modelFallbacks: kept };
+            refused.push("model_fallbacks");
+        }
+        else
+            drop("modelFallbacks", "model_fallbacks");
+    }
+    if (def.modelTiers !== undefined && !(ok(def.modelTiers.fast) && ok(def.modelTiers.default))) {
+        drop("modelTiers", "model_tiers");
+    }
+    if (def.modelPool !== undefined) {
+        const narrowed = narrowPoolModels(def.modelPool, ok);
+        if (narrowed === undefined)
+            drop("modelPool", "model_pool");
+        else if (narrowed !== def.modelPool) {
+            next = { ...next, modelPool: narrowed };
+            refused.push("model_pool");
+        }
+    }
+    if (def.allowedProfiles !== undefined &&
+        !def.allowedProfiles.every((o) => ok(o.model) && (o.modelFallbacks ?? []).every(ok))) {
+        const options = def.allowedProfiles
+            .filter((o) => ok(o.model))
+            .map((o) => o.modelFallbacks === undefined || o.modelFallbacks.every(ok)
+            ? o
+            : { ...o, modelFallbacks: o.modelFallbacks.filter(ok) });
+        if (options.length > 0) {
+            next = { ...next, allowedProfiles: options };
+            refused.push("allowed_profiles");
+        }
+        else
+            drop("allowedProfiles", "allowed_profiles");
+    }
+    return { def: next, refused };
+}
+/** Definitions whose refused models have already been reported. */
+const reportedRefusedModels = new Set();
+/** Definitions from disk whose tool list matched nothing, already reported. */
+const reportedToolless = new Set();
+/**
+ * A file's tool entries for a notice: each quoted with its control
+ * characters escaped (the file is the agent's to write, and the notice goes
+ * to the operator's terminal), shortened, and at most a handful of them.
+ */
+function describeEntries(entries) {
+    const shown = entries
+        .slice(0, 8)
+        .map((e) => JSON.stringify(e.length > 64 ? `${e.slice(0, 64)}…` : e));
+    return entries.length > shown.length
+        ? `${shown.join(", ")} and ${entries.length - shown.length} more`
+        : shown.join(", ");
 }
 export function createTaskTool(opts = {}) {
     const knownNames = opts.subAgents !== undefined ? [...opts.subAgents.keys()] : [];
@@ -381,7 +697,8 @@ export function createTaskTool(opts = {}) {
                 return false;
             let def;
             try {
-                def = resolveSubAgentDefinition(parsed.data.subagent_type, opts);
+                const resolved = resolveSubAgent(parsed.data.subagent_type, opts);
+                def = withRegisteredToolNames(resolved.def, resolved.fromDisk);
             }
             catch {
                 return false;
@@ -401,12 +718,32 @@ export function createTaskTool(opts = {}) {
             }
             const spawnSubAgent = bridge.spawnSubAgent;
             let def;
+            let fromDisk;
+            // The tool list as the definition wrote it, for a notice.
+            let listedTools;
             try {
-                def = resolveSubAgentDefinition(input.subagent_type, opts);
+                ({ def, fromDisk } = resolveSubAgent(input.subagent_type, opts));
+                listedTools = def.tools ?? [];
+                // One spelling for everything below: the child catalog AND a
+                // `scoped` rule filter both match registered names (`Bash`), and a
+                // permission glob is case-sensitive. A spec key left raw here would
+                // give the child the tool while scoping away the parent's rules for
+                // it — so map before either reads the list.
+                def = withRegisteredToolNames(def, fromDisk);
             }
             catch (err) {
                 return `[Task error] ${err.message}`;
             }
+            // A definition from disk runs only on models the spec names — before
+            // the `profile` check below reads its allowed_profiles.
+            if (fromDisk) {
+                const narrowedModels = narrowDiskModels(def, declaredModels(bridge, opts.subAgents));
+                def = narrowedModels.def;
+                if (narrowedModels.refused.length > 0 && !reportedRefusedModels.has(def.name)) {
+                    reportedRefusedModels.add(def.name);
+                    process.stderr.write(`[task] sub-agent "${def.name}" comes from .crewhaus/sub-agents, so it may run only on models the spec names — its ${narrowedModels.refused.join(", ")} named others, which were dropped; where none was left, it runs on the parent's model. To run it on another model, declare the sub-agent under sub_agents in crewhaus.yaml.\n`);
+                }
+            }
             // 0.6.0 §7.7 / §10.1 — the model-filled `profile` argument is checked
             // against the definition's allowlist BEFORE anything is spawned. Thrown
             // (not returned) so tool-executor renders it `is_error: true`: the
@@ -418,7 +755,32 @@ export function createTaskTool(opts = {}) {
                 }
             }
             const childTools = buildChildCatalog(bridge.tools, def);
-            const childPerms = resolveChildPermissions({ mode: bridge.permissionMode, rules: bridge.permissionRules }, def);
+            if (fromDisk &&
+                childTools.length === 0 &&
+                listedTools.length > 0 &&
+                !reportedToolless.has(def.name)) {
+                reportedToolless.add(def.name);
+                process.stderr.write(`[task] sub-agent "${def.name}" comes from .crewhaus/sub-agents, and none of its tools (${describeEntries(listedTools)}) is a tool the parent has, so it runs with no tools. List registered names (Read) or spec keys (read); a category (all-git) gives the child only the tools of it the parent has.\n`);
+            }
+            const parentPerms = { mode: bridge.permissionMode, rules: bridge.permissionRules };
+            let childPerms;
+            if (fromDisk) {
+                const narrowedPool = narrowDiskModelPool(def);
+                def = narrowedPool.def;
+                if (narrowedPool.refused.length > 0 && !reportedRefusedPoolKeys.has(def.name)) {
+                    reportedRefusedPoolKeys.add(def.name);
+                    process.stderr.write(`[task] sub-agent "${def.name}" comes from .crewhaus/sub-agents, so its model_pool candidates cannot set ${narrowedPool.refused.join(", ")} — ignored, so its tools run under the parent's tool_config. To give a candidate its own tool_config, declare the sub-agent under sub_agents in crewhaus.yaml.\n`);
+                }
+                const narrowed = resolveChildPermissionsNarrowOnly(parentPerms, def);
+                if (narrowed.ungrantedAllows.length > 0 && !reportedIgnoredAllows.has(def.name)) {
+                    reportedIgnoredAllows.add(def.name);
+                    process.stderr.write(`[task] sub-agent "${def.name}" comes from .crewhaus/sub-agents, so its permissions can only narrow the parent's — the parent does not allow ${narrowed.ungrantedAllows.join(", ")}, so its allow list does not grant them. To grant them, declare the sub-agent under sub_agents in crewhaus.yaml.\n`);
+                }
+                childPerms = narrowed;
+            }
+            else {
+                childPerms = resolveChildPermissions(parentPerms, def);
+            }
             // 0.6.0 §10.2 — ONE shared projection replaces the field-by-field hand
             // copy this tool carried (and whose optional-seam omissions were the
             // mechanism of the G11 approval bug): `projectParentHandle` lives beside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-task",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Task(description, prompt, subagent_type?) tool — spawns a sub-agent and returns its final message (Section 13)",
   "main": "dist/index.js",
@@ -8,18 +8,21 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/agent-context-isolation": "0.6.0",
-    "@crewhaus/errors": "0.6.0",
-    "@crewhaus/sub-agent-permission-inheritance": "0.6.0",
-    "@crewhaus/tool-builder": "0.6.0",
-    "@crewhaus/tool-catalog": "0.6.0",
+    "@crewhaus/agent-context-isolation": "0.8.0",
+    "@crewhaus/errors": "0.8.0",
+    "@crewhaus/sub-agent-permission-inheritance": "0.8.0",
+    "@crewhaus/tool-builder": "0.8.0",
+    "@crewhaus/tool-catalog": "0.8.0",
+    "@crewhaus/tool-categories": "0.8.0",
+    "@crewhaus/tool-safety": "0.8.0",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },
@@ -46,5 +49,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }