@nanmicoder/dsh-agent-teams 0.1.22-rc.1 → 0.1.23

package/lib/types/artifacts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Workspace byte identity: the only module in this plugin that reads artifact
+ * bytes off disk.
+ *
+ * Two plugin surfaces need it:
+ *  · a quality verdict must record which revision it judged (issue #161), so
+ *    delivery can refuse to advertise bytes no review ever saw;
+ *  · an auto-generated work order must record the workspace it was derived
+ *    from (issue #174), so it can be marked stale after a later round edits a
+ *    cited file.
+ *
+ * Safety rules this module must never lose:
+ *  · directory traversal never follows symlinks, and every explicitly named
+ *    path is resolved with `realpath` and rejected when it leaves the
+ *    workspace — a symlink must not become a read of arbitrary host files, and
+ *    a symlink cycle must not become an infinite walk;
+ *  · a scope that cannot be enumerated completely (file cap, unreadable
+ *    directory, non-workspace-relative path) produces an explicit
+ *    {@link ArtifactScopeGap} instead of a short list that reads as complete;
+ *  · "could not be read" is recorded separately from "does not exist";
+ *  · plugins and secrets never enter a broad scope by accident.
+ *
+ * The gate rules themselves stay pure: they receive {@link ArtifactDigest}
+ * values from here and never touch the filesystem.
+ * @module dsh-agent-teams/artifacts
+ */
+import type { ArtifactDigest, ArtifactScopeGap, ArtifactSnapshot } from './types.ts';
+/**
+ * Upper bound on files expanded from one scope. Verdicts are about a revision
+ * and an unbounded walk of a large tree would make every gate close slow, so
+ * the walk stops here — and says so with a gap, because a silently truncated
+ * list would let a change outside the list pass as "unchanged".
+ */
+export declare const MAX_EXPANDED_ARTIFACTS = 200;
+/** Result of reading a declared scope: what was read, and what could not be. */
+export interface ArtifactScopeRead {
+    artifacts: ArtifactDigest[];
+    gaps: ArtifactScopeGap[];
+}
+/**
+ * Read a declared scope: expand directory patterns to their current files,
+ * keep explicitly named paths even when they do not exist (a later creation is
+ * drift too), and report every part that could not be fully resolved.
+ */
+export declare function readArtifactScope(workspace: string, patterns: readonly string[]): ArtifactScopeRead;
+/**
+ * Read the current bytes of workspace-relative paths (directories expand).
+ * Illegal and unreadable paths are reported, never silently dropped.
+ */
+export declare function digestWorkspacePaths(workspace: string, paths: readonly string[]): ArtifactDigest[];
+/**
+ * Does this workspace-relative path currently exist as a file or directory?
+ * Uses the same containment rules as the digest reader: a symlink that leaves
+ * the workspace is not "an existing workspace path".
+ */
+export declare function workspacePathExists(workspace: string, path: string): boolean;
+/** Expand scope patterns to the concrete files they currently cover. */
+export declare function expandScopePaths(workspace: string, patterns: readonly string[]): string[];
+/**
+ * Read one coherent snapshot of the given scope patterns. Directory patterns
+ * expand to the files they currently contain; a pattern naming a path that
+ * does not exist is recorded as `present: false` so a later creation or
+ * deletion is visible as drift, and any incomplete coverage is carried in
+ * `gaps`.
+ */
+export declare function snapshotWorkspacePaths(workspace: string, patterns: readonly string[]): ArtifactSnapshot;

package/lib/types/client/activity-monitor.d.ts

@@ -30,6 +30,12 @@ export interface ActivityTask {
     readonly kind?: string;
     readonly round?: number;
     readonly verdict?: string;
+    /**
+     * Server-side audit of this task's verdict against the current bytes. Set
+     * when the recorded pass (or its generated work order) no longer describes
+     * the workspace, so the panel cannot render a bare green verdict.
+     */
+    readonly verdictStale?: string;
     /** Durable last-write stamp; drives the finished-member ordering (issue #192). */
     readonly updatedAt?: number;
 }

package/lib/types/client/agent-teams-card-definition.d.ts

@@ -30,19 +30,75 @@ declare module '@deepseek-ai/dsh-client-ui-chat/client' {
         'agent-teams': AgentTeamsCardData;
     }
 }
+/** One roster row folded from the create result. */
+export interface AgentTeamsCardMember {
+    readonly id: string;
+    readonly name: string;
+    readonly role: string;
+}
 /** Folded team record (the node's business state). */
 export interface AgentTeamsNodeState {
     readonly teamId: string;
     readonly name: string;
     readonly accepted: boolean;
+    /** Captain session the host reported, or `''` for a pre-#203 record. */
+    readonly captainSessionId: string;
+    /** Roster the host reported, or `[]` for a pre-#203 record. */
+    readonly members: readonly AgentTeamsCardMember[];
+}
+/**
+ * Canonical identity the host publishes on the create result (issue #203).
+ * The display name intentionally stays the create call's own name.
+ */
+export interface AgentTeamsCreateIdentity {
+    readonly teamId: string;
+    readonly captainSessionId: string;
+    readonly members: readonly AgentTeamsCardMember[];
 }
+/**
+ * Fold a team name the way the host's `sanitizeKey` does, minus the host's
+ * digest fallback. The host keeps Unicode letters and digits, so an ASCII-only
+ * client derivation turned every CJK name into the shared `team` key and the
+ * card could never match its live team (issue #203). Names with no letters or
+ * digits at all, and names longer than the host's key limit, still need the
+ * host's canonical id; the create result now carries it.
+ * @param name - the create call's team name.
+ * @returns the host-shaped key for the name.
+ */
+export declare function teamKeyFromName(name: string): string;
 /** Parse the only create-call fields the historic card owns. */
 export declare function parseAgentTeamsCreateArgs(value: string): {
     teamId: string;
     name: string;
 } | undefined;
+/**
+ * Read the canonical identity the host attaches to the `agent_teams_create`
+ * result. Records written before the host published it carry no metadata, so
+ * an absent or malformed payload falls back to the client derivation.
+ * @param meta - the durable `tool/result` metadata payload, if any.
+ * @returns the canonical identity, or `undefined` when the host published none.
+ */
+export declare function parseAgentTeamsCreateResult(meta: unknown): AgentTeamsCreateIdentity | undefined;
+/**
+ * Read the canonical team id out of a `tool/result` recorded before the host
+ * published {@link parseAgentTeamsCreateResult}'s metadata. Both historic
+ * renderings carry it and have been stable since they were introduced:
+ * `Team "<name>" created (id <canonical>) under <state_dir>. You are the
+ * captain.` and the staged `Team "<name>" plan created under <state_dir>. It is
+ * staged: …`, whose `state_dir` ends in the canonical id. This is the only
+ * legacy path for names the client cannot re-derive (host digest fallback,
+ * over-long names). Matches are taken right-to-left because the team name sits
+ * in front of the canonical segment and may itself contain a look-alike.
+ * @param text - the concatenated text blocks of one successful create result.
+ * @returns the canonical id, or `undefined` when the text carries none.
+ */
+export declare function teamIdFromCreateResultText(text: string): string | undefined;
 /** Durable first-party tool events folded into one keyed Chat node. */
 export declare const agentTeamsCardDefinition: ConversationNodeDefinition<AgentTeamsNodeState>;
+/** Concatenate the text blocks of one durable tool-result message. */
+export declare function resultText(message: {
+    readonly content: readonly unknown[];
+}): string;
 /** V4 tool-role results carry isError directly; older logs nest tool-result blocks. */
 export declare function toolResultFailed(message: {
     readonly content: readonly unknown[];

package/lib/types/harness-compat.d.ts

@@ -9,8 +9,9 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
-import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm';
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import { type MemberToolFilter } from './tool-policies.ts';
 type Setup = (childCtx: Context, child: Agent) => () => void;
 declare module '@deepseek-ai/dsh-llm' {
     interface MessageSourceMap {
@@ -19,6 +20,41 @@ declare module '@deepseek-ai/dsh-llm' {
         };
     }
 }
+/** Package identity a released plugin-wrapper source names on older hosts. */
+export declare const AGENT_TEAMS_PLUGIN_NAME = "@nanmicoder/dsh-agent-teams";
+/**
+ * First stored format generation whose migration edges admit producer-owned
+ * source kinds. The released v2→v3 payload audit validates every message source
+ * against a closed list of released kinds, so a stored format older than this
+ * must carry a released source or the whole session becomes unreadable once a
+ * newer host opens it (#160).
+ */
+export declare const RELEASED_SOURCE_VOCABULARY_VERSION = 3;
+/** Source kinds this plugin mints on a host whose stored format admits them. */
+export type AgentTeamsSource = {
+    readonly kind: 'agent-teams';
+} | {
+    readonly kind: 'agent-teams-command';
+    readonly goal?: string;
+    readonly profile?: string;
+};
+/** Stored session format generation of the running host; 0 when it exposes none. */
+export declare function hostSessionFormatVersion(): number;
+/**
+ * Source for one AgentTeams-authored message on the running host.
+ *
+ * Current hosts mint producer-owned kinds: the Harness documents message
+ * sources as a merge-extensible vocabulary without a catch-all, so this plugin
+ * declares its own. Hosts that still store a pre-v3 generation are a different
+ * contract — their released v2→v3 migration rejects any source outside the
+ * released vocabulary, which is exactly how a plugin kind written on an older
+ * supported host poisons its session log for every later host. On those hosts
+ * the released plugin wrapper is used instead; the goal and profile already
+ * travel in the message text.
+ * @param modern - the producer-owned source to use where the host admits it.
+ * @returns a source accepted by the running host and by its migration chain.
+ */
+export declare function agentTeamsSource(modern: AgentTeamsSource): MessageSource;
 /**
  * 0.1.6 moved startup admission to serial agent/created. Older created events
  * have no source and precede session-start; ignore those until the old hook.
@@ -54,29 +90,35 @@ export declare function restrictableToolNames(agent: Agent): ReadonlySet<string>
  * forwarding a name the host dropped aborts every member spawn (#163, #164).
  * Depth enforcement itself does not depend on these names —
  * installMemberDelegationGuard bounds descendant creation by parent chain.
+ *
+ * This is the legacy filter of a member without a configured tool policy; a
+ * selected policy resolves through `resolveMemberToolFilter` instead (#59).
  */
-export declare function memberToolFilter(maxDepth: number | undefined, knownTools: ReadonlySet<string> | undefined): {
-    deny: string[];
-};
+export declare function memberToolFilter(maxDepth: number | undefined, knownTools: ReadonlySet<string> | undefined): MemberToolFilter;
 /**
- * Start one member, dropping any filter name the host reports as unknown and
- * retrying.
+ * Start one member, dropping only the built-in filter names the host reports
+ * as unknown and retrying.
  *
  * Resolving the filter against the registry view ({@link memberToolFilter})
  * only covers hosts that expose one. A rejected filter still leaves the member
  * without a session for the lifetime of the team, so the start must survive the
  * cases that resolution cannot see — no registry view, a name that is known but
  * not restrictable, a composition that mounted differently than expected. The
- * host names the offenders in its rejection, so they are removed and the start
- * retried; the retry only runs while the deny list strictly shrinks, and any
- * failure that is not an unknown-name report propagates untouched.
+ * host names the offenders in its rejection, so the relaxable ones are removed
+ * and the start retried.
+ *
+ * Only `relaxableDeny` names may be dropped, and only from `deny`. The default
+ * is exactly the built-in captain-only and depth entries (#163/#164); a name an
+ * owner-declared tool policy contributed is never removed, because silently
+ * spawning a member with a different filter than the owner declared is contract
+ * drift, not recovery. Dropping a denied name the host does not register
+ * changes nothing; dropping an allowed name would loosen the policy, so `allow`
+ * is never relaxed and the four required coordination tools can never be
+ * removed.
  * @param start - performs one start attempt for the given `toolFilter`.
  * @param filter - the filter to attempt first.
+ * @param relaxableDeny - built-in deny names the retry may drop.
  * @returns the started member.
  */
-export declare function startMemberWithLenientFilter<T>(start: (filter: {
-    deny: string[];
-}) => Promise<T>, filter: {
-    deny: string[];
-}): Promise<T>;
+export declare function startMemberWithLenientFilter<T>(start: (filter: MemberToolFilter) => Promise<T>, filter: MemberToolFilter, relaxableDeny?: readonly string[]): Promise<T>;
 export {};

package/lib/types/index.d.ts

@@ -21,6 +21,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type TeamProfileConfig } from './profiles.ts';
+import { type MemberToolPolicy } from './tool-policies.ts';
 export declare const name = "agent-teams";
 export declare const inject: string[];
 /** Plugin configuration. */
@@ -32,8 +33,22 @@ export interface Config {
     stateDir?: string;
     /** `ctx.subagents` provider used to spawn members; must support continuable children and personas (default `spawn`). */
     memberProvider?: string;
-    /** Optional model override applied to every member. */
+    /**
+     * Optional model override applied to every member. The id is used verbatim.
+     * When the captain's provider does not advertise it, the provider that does
+     * is resolved from the live catalogs (only if exactly one advertises it);
+     * set `memberLlmProvider` to name the owner explicitly instead.
+     */
     memberModel?: string;
+    /**
+     * LLM provider route that owns `memberModel`. Set this when the member model
+     * is served by a different provider than the captain's session; without it
+     * the captain's provider is only used if it actually advertises the model,
+     * and an ambiguous or unowned model fails with the provider catalogs instead
+     * of being silently paired with the captain's route (issue #189).
+     * Distinct from `memberProvider`, which is the subagent runtime backend.
+     */
+    memberLlmProvider?: string;
     /** Prompt injected into member personas and automatic task assignments. */
     executionPrompt?: string;
     /** Plugin-wide fallback route for unavailable member models. */
@@ -44,6 +59,16 @@ export interface Config {
     maxMembers?: number;
     /** Named multi-role team profiles. */
     profiles?: Record<string, TeamProfileConfig>;
+    /**
+     * Reusable per-member tool policies declared by the deployment owner (#59),
+     * keyed by policy id. A member selects one by id (`tool_policy` on
+     * `agent_teams_add_member`, a plan member, or a profile member row); the
+     * Captain model can select an existing policy but never submit raw lists.
+     * `allow` keeps only the named global tools (the four coordination tools are
+     * always added); `deny` removes the named global tools. Captain-only tools
+     * stay denied either way.
+     */
+    toolPolicies?: Record<string, MemberToolPolicy>;
     /** Prompt-section order for the usage policy (default `117`, after delegation policy). */
     promptSectionOrder?: number;
     /**

package/lib/types/lineage.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Durable session lineage for team identity.
+ *
+ * Forking is a first-class DSH operation: the fork receives a new session id
+ * and records the source session as `header.parentSession`. Team identity must
+ * therefore be resolved along that chain, or a captain that continues in its
+ * own fork stops matching the team it leads (#176). Membership keeps its exact
+ * id match: a member is a subagent child of its captain, so its parent chain
+ * also contains the captain and must never be read as lead identity. Only a
+ * top-level conversation may inherit lead identity from an ancestor.
+ *
+ * Authorization paths resolve the chain durably: a hop is read from the live
+ * session when that session is resident and from the persistence service's
+ * stored header otherwise, so a fork still resolves its team while an
+ * intermediate session (or the original captain) is not loaded. The
+ * synchronous prompt-assembly path uses the calling session's own durable
+ * header plus resolvable live hops; failing to resolve there only leaves the
+ * default captain-side prompt in place — every tool re-authorizes
+ * asynchronously.
+ * @module dsh-agent-teams/lineage
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Session } from '@deepseek-ai/dsh-session';
+/** Maximum fork-chain depth resolved for one identity (cycle- and length-bounded). */
+export declare const LINEAGE_MAX_DEPTH = 32;
+/** One calling session's durable identity as the team lookups need it. */
+export interface LeadIdentity {
+    /** The calling session id. */
+    readonly sessionId: string;
+    /** Ancestor session ids reachable through `header.parentSession`, nearest first. */
+    readonly ancestry: readonly string[];
+    /** Whether this session may inherit lead identity from an ancestor at all. */
+    readonly inheritsLead: boolean;
+}
+/** The live session for one id: resident agent first, then the live session store. */
+export declare function liveSession(ctx: Context, id: string): Session | undefined;
+/** Whether one session is a top-level conversation rather than a subagent child. */
+export declare function isTopLevelSession(session: Session): boolean;
+/**
+ * Durable ancestry of one session, nearest first. The calling session's own
+ * header supplies the first hop; later hops come from resident sessions or
+ * stored headers, so a fork resolves through sessions that are not loaded.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param session - the calling session.
+ * @returns ancestor session ids, bounded by {@link LINEAGE_MAX_DEPTH}.
+ */
+export declare function resolveAncestry(ctx: Context, session: Session): Promise<readonly string[]>;
+/**
+ * Ancestry resolvable without awaiting: the calling session's durable first
+ * hop, then resident sessions, then whatever the async resolver cached.
+ */
+export declare function sessionAncestry(ctx: Context, session: Session): readonly string[];
+/** Resolve one session's lead identity synchronously (prompt-assembly path). */
+export declare function leadIdentityOf(ctx: Context, session: Session): LeadIdentity;
+/** Resolve one session's lead identity durably (authorization paths). */
+export declare function leadIdentityOfAsync(ctx: Context, session: Session): Promise<LeadIdentity>;
+/** The lead-relevant view of a team record. */
+export interface LeadScopedTeam {
+    readonly captainSessionId: string;
+    /** Present on real team state; omitting it keeps the pure exact-id contract. */
+    readonly members?: readonly {
+        readonly id: string;
+        readonly status?: string;
+    }[];
+}
+/** Whether one identity leads (or inherits the lead of) a team's recorded captain. */
+export declare function teamLeadMatch(team: LeadScopedTeam, lead: LeadIdentity): boolean;
+/**
+ * Whether one live session id leads a team: the recorded captain itself, or a
+ * top-level fork descendant of it. Members never match through their parent
+ * chain, and a member's fork does not match either.
+ */
+export declare function sessionLeadsTeam(ctx: Context, team: LeadScopedTeam, sessionId: string): boolean;
+/** Durable {@link sessionLeadsTeam}: resolves the caller's chain through stored headers. */
+export declare function sessionLeadsTeamAsync(ctx: Context, team: LeadScopedTeam, sessionId: string): Promise<boolean>;
+/**
+ * Nearest live lead session of a team: the recorded captain while it is
+ * resident, otherwise the closest live fork descendant of it. Captain-directed
+ * reports use this so a human working in a fork still receives them, while the
+ * durable mail record stays addressed to the recorded captain.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param team - current team state.
+ * @returns the live lead agent, or undefined when no lead session is resident.
+ */
+export declare function nearestLiveLead(ctx: Context, team: LeadScopedTeam, live?: readonly Agent[]): Agent | undefined;
+/**
+ * Diagnostic note for a caller that matched no team but is a fork, so an
+ * operator can distinguish "no team exists" from "a team exists that this
+ * session does not lead".
+ */
+export declare function forkLineageNote(session: Session): string;

package/lib/types/members.d.ts

@@ -14,6 +14,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { type Agent } from '@deepseek-ai/dsh-agent';
 import type { Session } from '@deepseek-ai/dsh-session';
+import type { MemberToolFilter } from './tool-policies.ts';
 import { type TeamMember, type TeamState, type TeamTask } from './types.ts';
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export declare const PERSONA_PROTOCOL_MAX_CHARS = 400;
@@ -53,6 +54,8 @@ export interface MemberLlmSelectionRequest {
     model?: string;
     /** Plugin-level member model default. */
     defaultModel?: string;
+    /** Configured member LLM provider, paired with `defaultModel` (issue #189). */
+    defaultProvider?: string;
     /** Explicit reasoning effort; "default" selects the target model's default effort. */
     reasoningEffort?: string;
     /** Configured fallback route. */
@@ -61,6 +64,45 @@ export interface MemberLlmSelectionRequest {
         model: string;
     };
 }
+/** A composed member route plus where each half came from. */
+export interface MemberRouteResolution {
+    readonly provider: {
+        readonly value: string;
+        readonly source: 'request' | 'config' | 'captain';
+    };
+    readonly model: {
+        readonly value: string;
+        readonly source: 'request' | 'config' | 'captain';
+    };
+    /**
+     * Whether the provider half was *derived* rather than named. Only a
+     * model-only plugin default may have its owner looked up in the provider
+     * catalogs; a provider or model the caller named is never re-pointed.
+     */
+    readonly derivedProvider: boolean;
+}
+/**
+ * Compose one member route from request, plugin configuration and the captain
+ * session, without performing any I/O. This is the single place where the
+ * precedence between the captain's route and a configured member default is
+ * decided, so a configured model can never be silently paired with whichever
+ * provider the captain happens to sit on (issue #189).
+ *
+ * Precedence: explicit request > plugin configuration > captain session. Model
+ * ids are used verbatim: a `/` inside a model id is part of that id and is
+ * never treated as a provider separator.
+ *
+ * `derivedProvider` is true only for a bare configured `memberModel` with no
+ * provider anywhere, which is the one shape whose owner must come from the
+ * provider catalogs.
+ * @param request - the captain-supplied and plugin-configured route halves.
+ * @param captain - the captain's current session route.
+ * @returns the composed route, or `undefined` when a half cannot be determined.
+ */
+export declare function composeMemberRoute(request: Pick<MemberLlmSelectionRequest, 'provider' | 'model' | 'defaultModel' | 'defaultProvider'>, captain: {
+    readonly provider: string;
+    readonly model: string;
+}): MemberRouteResolution | undefined;
 /** Process-local bridge between spawn admission and synchronous child setup. */
 export interface MemberSelectionRuntime {
     /** Trusted fresh-child admission, before the durable member id is written. */
@@ -98,6 +140,58 @@ interface FailedMemberAttempt {
     readonly memberId: string;
     readonly task?: Pick<TeamTask, 'id' | 'attempt' | 'attemptId'>;
 }
+/** How a final member turn failure relates to the durable record. */
+export type MemberFailureDisposition = 
+/** A live observed attempt was failed and its task marked failed. */
+'failed_attempt'
+/** The work had already settled; only a durable captain note was added. */
+ | 'noted_settled'
+/** No record: stale generation, superseded attempt, retired member, or no team. */
+ | 'ignored';
+/**
+ * Classify a final member turn failure against the durable record. Pure, so the
+ * policy is testable without a lock or a Harness.
+ *
+ * A failure may only mutate the attempt the plugin actually observed. When that
+ * attempt is gone — the member moved on to newer work, the task was
+ * reassigned to a newer attempt, or the member generation was replaced — the
+ * late error carries no authority and stays silent. When the failure belongs to
+ * the current generation but its work already settled, the task and member are
+ * left exactly as they are and only a durable captain note is added: otherwise
+ * an operator cannot tell a clean run from one whose member's last turn died
+ * (429, auth failure, crash) after the delivery landed (issue #205).
+ * @param observed - the live member/task capability captured at the error event.
+ * @param current - the current durable member record and open task, if any.
+ * @returns the disposition for this failure.
+ */
+export declare function classifyMemberFailure(observed: FailedMemberAttempt, current: {
+    readonly member?: Pick<TeamMember, 'id' | 'status'> | undefined;
+    readonly task?: Pick<TeamTask, 'id' | 'attempt' | 'attemptId'> | undefined;
+    /** The durable record of the task the observation referred to, settled or not. */
+    readonly observedRecord?: Pick<TeamTask, 'id' | 'status' | 'subject'> | undefined;
+}): MemberFailureDisposition;
+/**
+ * The surviving durable record of the capability observed at the error event,
+ * or `undefined` when there is nothing honest to say about it.
+ *
+ * A task is only described as *settled* when its durable status is terminal
+ * (`completed`/`failed`/`cancelled`). A non-terminal record — for example a task
+ * that was claimed and then unclaimed or reassigned while the error was queued —
+ * must fall back to the plain "no open attempt" wording instead of implying a
+ * delivery landed.
+ */
+export declare function settledTaskRecord(observed: Pick<TeamTask, 'id'> | undefined, tasks: readonly Pick<TeamTask, 'id' | 'status' | 'subject'>[]): Pick<TeamTask, 'id' | 'status' | 'subject'> | undefined;
+/**
+ * Build the durable captain note for one recorded failure. Pure, so the wording
+ * boundaries are testable without a lock or a Harness.
+ * @param memberName - the member that failed.
+ * @param summary - the failure message plus its code.
+ * @param disposition - what the failure was allowed to do.
+ * @param task - the open attempt that was failed, when there was one.
+ * @param settledRecord - the terminal record of the observed task, when it exists.
+ * @returns the exact message the captain will read.
+ */
+export declare function memberFailureMessage(memberName: string, summary: string, disposition: MemberFailureDisposition, task: Pick<TeamTask, 'id' | 'subject'> | undefined, settledRecord: Pick<TeamTask, 'id' | 'status' | 'subject'> | undefined): string;
 /** Record a final turn failure, never an intermediate request retry. */
 export declare function failMemberOpenAttempt(ctx: Context, stateRoot: string, teamId: string, memberName: string, failure: {
     readonly code: string;
@@ -111,6 +205,15 @@ export declare function failMemberOpenAttempt(ctx: Context, stateRoot: string, t
  * An explicit effort overrides either policy; the sentinel "default" also
  * selects the target model's default. The final effort is validated against
  * the target model before a child is created.
+ *
+ * A configured `memberModel` is a route preference, not a blind model-id
+ * override: it is paired with `memberLlmProvider` (or its own `provider/model`
+ * form) when configured, and when only a bare model id is configured it is
+ * adopted by the captain's provider only if that provider actually advertises
+ * it. Otherwise the catalog decides: exactly one advertising provider wins,
+ * none or several produce an actionable error listing them (issue #189). A
+ * provider the caller *named* — explicitly or via configuration — is never
+ * silently switched away from.
  */
 export declare function resolveMemberLlmSelection(ctx: Context, captain: Agent, request: MemberLlmSelectionRequest, signal?: AbortSignal): Promise<MemberLlmSelection>;
 /**
@@ -150,8 +253,16 @@ export declare function memberWelcome(team: TeamState, memberName: string): stri
  * @param member - the member draft whose `id` is filled on success.
  * @param stateDir - configured state directory (for the persona).
  * @param signal - caller cancellation, forwarded to the start.
+ * @param initialPrompt - first turn text; the welcome message when omitted.
+ * @param resolvedFilter - the member's effective tool filter (a selected
+ *   policy, or the legacy captain-only filter when the member has none). The
+ *   caller resolves it so `spawnMember` forwards exactly one immutable filter
+ *   to `startContinuable`.
+ * @param relaxableDeny - deny names the lenient retry may drop for this
+ *   member; the caller narrows it for a policy member so a name the owner
+ *   declared is never silently removed.
  */
-export declare function spawnMember(ctx: Context, config: MemberRuntimeConfig, selections: MemberSelectionRuntime, llmSelection: MemberLlmSelection, captain: Agent, team: TeamState, member: TeamMember, stateDir: string, signal: AbortSignal, initialPrompt?: string): Promise<void>;
+export declare function spawnMember(ctx: Context, config: MemberRuntimeConfig, selections: MemberSelectionRuntime, llmSelection: MemberLlmSelection, captain: Agent, team: TeamState, member: TeamMember, stateDir: string, signal: AbortSignal, initialPrompt?: string, resolvedFilter?: MemberToolFilter, relaxableDeny?: readonly string[]): Promise<void>;
 /**
  * Deliver one message to a member as its next FIFO turn. Best effort: a
  * failure (member gone or not continuable) is logged and reported as `false`

package/lib/types/profiles.d.ts

@@ -27,6 +27,11 @@ export interface TeamProfileMemberConfig {
     reasoning_effort?: string;
     executionPrompt?: string;
     fallback?: TeamModelFallbackConfig;
+    /**
+     * Owner-declared tool-policy id this profile member selects (#59). The
+     * profile only names a configured policy; it never carries raw tool lists.
+     */
+    tool_policy?: string;
 }
 /** One seed-task row in a named team-profile template (unresolved). */
 export interface TeamProfileTaskConfig {
@@ -61,6 +66,7 @@ export interface NormalizedProfileMember {
     reasoningEffort?: string;
     executionPrompt?: string;
     fallback?: TeamModelFallbackConfig;
+    toolPolicy?: string;
 }
 /** A profile seed task after assignee canonicalization; `sourceIndex` is the YAML order. */
 export interface NormalizedProfileTask {