@nanmicoder/dsh-agent-teams 0.1.22 → 0.1.23

package/lib/types/quality-gates.d.ts

@@ -3,7 +3,7 @@
  * coverage, and resume. Tools and persistence call these; they do not I/O.
  * @module dsh-agent-teams/quality-gates
  */
-import { type AcceptanceResult, type CommandResult, type FindingSeverity, type ReviewFinding, type ReviewPolicy, type ReviewVerdict, type TaskKind, type TaskEvidence, type TaskRevision, type TaskStatus, type TeamState, type TeamTask } from './types.ts';
+import { type AcceptanceResult, type ArtifactDigest, type ArtifactScopeGap, type ArtifactSnapshot, type CommandResult, type FindingSeverity, type ReviewFinding, type ReviewPolicy, type ReviewVerdict, type TaskKind, type TaskEvidence, type TaskRevision, type TaskStatus, type TeamState, type TeamTask } from './types.ts';
 declare const QUALITY_KINDS: readonly TaskKind[];
 declare const WRITE_KINDS: readonly TaskKind[];
 declare const DEFAULT_REVIEW_POLICY: Required<Pick<ReviewPolicy, 'requirementsMinRounds' | 'requirementsMaxRounds' | 'codeMaxRounds' | 'maxRepairAttempts'>>;
@@ -54,6 +54,7 @@ export interface PlannedFollowUpTask {
     id?: string;
     kind: TaskKind;
     subject?: string;
+    description?: string;
     assignee?: string;
     dependencies?: string[];
     round?: number;
@@ -64,13 +65,23 @@ export interface PlannedFollowUpTask {
     verify?: string[];
     sourceTaskId?: string;
     sourceFindingIds?: string[];
+    findingSourceTaskIds?: string[];
     reviewedTaskId?: string;
+    /**
+     * Paths whose current bytes the generated contract was derived from. The
+     * caller snapshots them so the work order can later be marked stale.
+     */
+    contractPaths?: string[];
 }
 export interface PlanQualityFollowUpResult {
     created: PlannedFollowUpTask[];
     tasks: PlannedFollowUpTask[];
     escalated?: boolean;
     status?: 'escalated';
+    /** Why the automatic loop stopped; surfaced to the captain. */
+    reason?: string;
+    /** Findings that were refused as contract material (default-excluded paths). */
+    excludedFindings?: string[];
 }
 export interface CoverageRow {
     goal_item: string;
@@ -81,6 +92,38 @@ export interface CoverageRow {
 export interface DeliveryResult {
     ok: boolean;
     blockers: string[];
+    /**
+     * Non-blocking observations: gates that legitimately drifted because a later
+     * revision superseded them, and generated work orders whose cited files
+     * moved on. Delivery is still allowed, but never silently.
+     */
+    warnings: string[];
+}
+/**
+ * Current workspace bytes handed to the delivery check. The rules stay pure:
+ * the caller (which owns the workspace path) reads the digests and passes them
+ * in. Omit it when no workspace is available — the attempt-level staleness
+ * checks still run, and content checks simply cannot be made.
+ */
+export interface ScopeEntry {
+    path: string;
+    present: boolean;
+}
+export interface DeliveryAudit {
+    /** Current bytes of the paths recorded by verdicts and work orders. */
+    artifacts?: readonly ArtifactDigest[];
+    /**
+     * Current contents of the scope patterns recorded verdicts bound. A path that
+     * appears here but not in the verdict's recorded artifacts was never
+     * reviewed, so a broad scope cannot silently absorb it.
+     */
+    expandedScope?: readonly ScopeEntry[];
+    /**
+     * Parts of the *current* read that could not be completed (expansion cap,
+     * unreadable directory or file, illegal pattern). A non-empty list means the
+     * audit itself is incomplete, so no verdict may be confirmed from it.
+     */
+    gaps?: readonly ArtifactScopeGap[];
 }
 export interface ResumeTeamResult {
     ok?: boolean;
@@ -95,6 +138,8 @@ export interface QualityLoopSnapshot {
     escalated: boolean;
     deliverable: boolean;
     summary: string;
+    /** Non-blocking gate observations (stale verdicts and work orders). */
+    warnings: string[];
 }
 export interface QualityGraphDraft {
     subject: string;
@@ -116,6 +161,13 @@ export declare function isReviewPolicy(value: unknown): value is ReviewPolicy;
 /** Normalize a workspace-relative POSIX path. `undefined` means illegal. */
 export declare function normalizeWorkspacePath(path: string): string | undefined;
 export declare function pathMatchesScope(path: string, pattern: string): boolean;
+/**
+ * Paths no quality contract may claim: version control, harness/plugin state,
+ * secrets and private keys. Exported because the completion gate and contract
+ * generation (including the artifact reader that must not walk into
+ * `.agent-teams/`, `secrets/` or `.env*`) have to share exactly one predicate.
+ */
+export declare function isDefaultExcludedPath(path: string): boolean;
 export declare function classifyChangedPath(path: string, inScope?: readonly string[], outOfScope?: readonly string[]): PathClassification;
 export declare function collectChangedPaths(gitStatusText: string): string[];
 export declare function inScopeOverlap(left: readonly string[] | undefined, right: readonly string[] | undefined): string[];
@@ -132,15 +184,36 @@ export declare function evaluateQualityCompletion(task: TeamTask, update: Qualit
  * forbids, so no honest completion exists and the repair dead-locks.
  *
  * Absolute and otherwise illegal paths are dropped (they can never match
- * workspace-relative scope patterns anyway); when nothing legal remains,
- * the source task's own inScope is kept as the fallback. Over-inclusion is
- * accepted: inScope is an audit upper bound, and the requiredFix text still
- * tells the implementer what to touch.
+ * workspace-relative scope patterns anyway), and so are paths the completion
+ * gate refuses by default (`secrets/` segments, `.env*`, `.git`, `.dsh`,
+ * `id_rsa*` — issue #183). `classifyChangedPath` checks that default-exclusion
+ * set BEFORE inScope, so collecting such a path here would generate a contract
+ * that demands an edit the gate calls `out_of_scope`: no honest completion
+ * exists and the repair burns its rounds. Contract generation and the
+ * completion gate must agree; the exemption channel stays the user-configured
+ * outOfScope list, never a reviewer's finding.
  *
- * Keep all derived paths until the generator resolves inherited exclusions;
- * filtering first would silently discard a required fix target.
+ * When nothing legal remains, the source task's own inScope is kept as the
+ * fallback. Over-inclusion is accepted otherwise: inScope is an audit upper
+ * bound, and the requiredFix text still tells the implementer what to touch.
+ * Keep every remaining derived path until the generator resolves inherited
+ * exclusions; filtering those first would silently discard a required fix
+ * target.
  */
 export declare function repairScopeFromFindings(findings: readonly ReviewFinding[], fallback: string[] | undefined): string[] | undefined;
+/**
+ * Every workspace-relative path one finding names, before any exclusion rule:
+ * the observed file plus the fix targets referenced by `requiredFix`.
+ */
+export declare function findingDerivedPaths(finding: ReviewFinding): string[];
+/**
+ * Findings whose every cited path is default-excluded. They cannot become an
+ * honest repair contract (see {@link repairScopeFromFindings}), so they are
+ * surfaced to the captain instead of silently disappearing or dead-locking a
+ * member. A finding that names no path at all is NOT excluded: it simply falls
+ * back to the judged task's own scope, exactly as before.
+ */
+export declare function excludedFindingsOf(findings: readonly ReviewFinding[], pathExists?: (path: string) => boolean): ReviewFinding[];
 /** Captain-only amendment payload: replacement values for contract fields. */
 export interface ContractAmendmentInput {
     objective?: string;
@@ -170,14 +243,136 @@ export interface AmendTaskContractResult {
  * amended contract.
  */
 export declare function amendTaskContract(team: TeamState, task: TeamTask, input: ContractAmendmentInput, by: string, reason: string): AmendTaskContractResult;
-export declare function planQualityFollowUp(team: TeamState, closed: TeamTask): PlanQualityFollowUpResult;
+/** Remove drifting line anchors from generated contract text. */
+export declare function stripLineAnchors(text: string): string;
+export interface PlanQualityFollowUpOptions {
+    /**
+     * Whether a derived path exists in the workspace. Used only to classify a
+     * finding as excluded-only; without it every derived path counts.
+     */
+    pathExists?: (path: string) => boolean;
+}
+export declare function planQualityFollowUp(team: TeamState, closed: TeamTask, options?: PlanQualityFollowUpOptions): PlanQualityFollowUpResult;
 export declare function buildCoverageMatrix(goalItems: readonly string[], tasks: readonly TeamTask[]): CoverageRow[];
-export declare function canDeclareDelivery(team: TeamState): DeliveryResult;
+/** Kinds whose completion is a verdict about a revision. */
+export declare function isVerdictKind(kind: TaskKind | undefined): boolean;
+/**
+ * Compare recorded bytes against the bytes on disk now. Every returned entry
+ * is a reason a verdict or a work order no longer describes the workspace.
+ * "Cannot be read" is reported as its own reason: a permission error is not a
+ * match, and a partial read is not proof of an unchanged file.
+ */
+/** One reason an artifact set no longer describes the workspace. */
+export interface ArtifactDriftDetail {
+    /** The implicated path, when the reason is about one concrete file. */
+    path?: string;
+    message: string;
+}
+/**
+ * Compare recorded bytes against the bytes on disk now, keeping the path each
+ * reason belongs to. "Cannot be read" is reported as its own reason: a
+ * permission error is not a match, and a partial read is not proof of an
+ * unchanged file.
+ */
+export declare function artifactDriftDetails(recorded: readonly ArtifactDigest[] | undefined, current: readonly ArtifactDigest[] | undefined): ArtifactDriftDetail[];
+/** Message-only view of {@link artifactDriftDetails}. */
+export declare function artifactDrift(recorded: readonly ArtifactDigest[] | undefined, current: readonly ArtifactDigest[] | undefined): string[];
+/** A partially enumerated scope is incomplete evidence, never a silent pass. */
+export declare function gapDrift(gaps: readonly ArtifactScopeGap[] | undefined): string[];
+/**
+ * The task a verdict is about: an explicit `reviewedTaskId`/`sourceTaskId`
+ * first, otherwise the implementation/repair this gate depends on.
+ */
+export declare function reviewedTargetOf(team: TeamState, task: TeamTask): TeamTask | undefined;
+/**
+ * Bind a closing verdict to the revision it judged: the target's execution
+ * generation plus the bytes of the paths it changed. Without this a `pass` is
+ * only a task record, and delivery cannot tell that the reviewed bytes were
+ * edited or deleted afterwards. `gaps` carries the parts of the reviewed scope
+ * that could not be enumerated, `scope` the patterns it bound, and
+ * `duringDrift` any change observed between claim and close — partial or
+ * moving coverage is never read as complete.
+ */
+export interface ReviewBinding {
+    artifacts: readonly ArtifactDigest[];
+    gaps?: readonly ArtifactScopeGap[];
+    scope?: readonly string[];
+    duringDrift?: readonly string[];
+}
+export declare function bindReviewToRevision(team: TeamState, task: TeamTask, binding: ReviewBinding): TeamTask;
+/**
+ * Scope a verdict must bind: the paths the judged task changed, otherwise the
+ * scope patterns of its contract (expanded by the caller).
+ */
+export declare function verdictScopePatterns(team: TeamState, task: TeamTask): string[];
+/** Scope patterns recorded verdicts bound, for new-file detection. */
+export declare function deliveryScopePatterns(team: TeamState): string[];
+/** Paths whose current bytes decide whether recorded verdicts and orders hold. */
+export declare function deliveryArtifactPaths(team: TeamState): string[];
+/**
+ * Every completed verdict that claims to cover the current revision but no
+ * longer does.
+ *
+ * A drifted review/requirements pass is the delivery evidence itself, so it
+ * blocks — unless a later sound verdict covers the same lineage, which is the
+ * normal shape of `pass → repair → new pass` and must converge instead of
+ * blocking forever behind an old snapshot. A drifted `verification` is only a
+ * warning: a later repair legitimately supersedes it, but never silently.
+ * A verdict that predates content binding is reported as an unauditable gap
+ * rather than being read as a pass over the current bytes.
+ */
+/** One audited verdict observation, attributed to the task that carries it. */
+export interface VerdictAuditNote {
+    taskId: string;
+    /**
+     * `blocker` when this pass is the delivery evidence itself, `warning` when a
+     * later sound verdict supersedes it or when it is an intermediate gate.
+     */
+    level: 'blocker' | 'warning';
+    message: string;
+}
+/**
+ * Audit every completed verdict against the current revision (issue #161).
+ *
+ * A drifted review/requirements pass is the delivery evidence itself, so it
+ * blocks — unless a later sound verdict covers the same lineage, which is the
+ * normal shape of `pass → repair → new pass` and must converge instead of
+ * blocking forever behind an old snapshot. A drifted `verification` or a
+ * superseded pass is reported as a warning: a later repair legitimately
+ * supersedes it, but never silently. A verdict that predates content binding
+ * is reported as an unauditable gap rather than being read as a pass over the
+ * current bytes.
+ */
+export declare function verdictAuditNotes(team: TeamState, audit?: DeliveryAudit): VerdictAuditNote[];
+/** Staleness of one auto-generated work order against the current workspace. */
+export declare function contractStaleness(task: TeamTask, current: readonly ArtifactDigest[] | undefined): string[];
+export interface WorkOrderWarning {
+    taskId: string;
+    message: string;
+}
+/**
+ * Open auto-generated work orders whose cited bytes moved on (issue #174).
+ * A repair round's acceptance/inScope is a snapshot of the workspace at
+ * finding-generation time; every later round invalidates it, and nothing used
+ * to say so — a member following it literally edits the wrong line or redoes
+ * work that is already done.
+ */
+export declare function workOrderWarnings(team: TeamState, current: readonly ArtifactDigest[] | undefined): WorkOrderWarning[];
+export declare function canDeclareDelivery(team: TeamState, audit?: DeliveryAudit): DeliveryResult;
 export declare function resumeTeamState(team: TeamState, reason: string): ResumeTeamResult;
+/**
+ * The durable `findings[].line` contract, shared by the write-side parser
+ * (`parseFindings`) and the durable validator (`isReviewFinding`) so the two
+ * cannot drift apart again (issue #188, #105 class).
+ */
+export declare function isValidFindingLine(value: unknown): value is number;
 export declare function isReviewFinding(value: unknown): value is ReviewFinding;
 export declare function isAcceptanceResult(value: unknown): value is AcceptanceResult;
 export declare function isCommandResult(value: unknown): value is CommandResult;
 export declare function isTaskRevision(value: unknown): value is TaskRevision;
+export declare function isArtifactDigest(value: unknown): value is ArtifactDigest;
+export declare function isArtifactScopeGap(value: unknown): value is ArtifactScopeGap;
+export declare function isArtifactSnapshot(value: unknown): value is ArtifactSnapshot;
 /**
  * Normalize blank optional task fields to omitted ("blank means absent").
  * Blank string scalars are deleted; string lists have blank entries filtered
@@ -186,6 +381,17 @@ export declare function isTaskRevision(value: unknown): value is TaskRevision;
  * validation stays strict.
  */
 export declare function normalizeBlankOptionalTaskFields<T extends object>(task: T): T;
+/**
+ * Treat an out-of-contract **numeric** sentinel as absent, including
+ * `findings[].line` (contract: `isValidFindingLine`).
+ *
+ * Only numbers are healed. A value of any other type (`round: "oops"`,
+ * `attempt: {}`, `line: "12"`) is left exactly as written and stays a hard,
+ * named validation failure, so genuine corruption is never silently swallowed
+ * while `-1`-style sentinels — the #188 brick — self-heal. Field order, unknown
+ * fields and every in-range value are preserved.
+ */
+export declare function normalizeSentinelNumericTaskFields<T extends object>(task: T): T;
 export declare function hasValidQualityTaskFields(value: Record<string, unknown>): boolean;
 export declare function isTaskKind(value: unknown): value is TaskKind;
 export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;
@@ -202,7 +408,7 @@ export declare function defaultQualityDeliveryGraph(input: {
     integrator?: string;
 }): QualityGraphDraft[];
 export declare function qualityPlanningPrompt(): string;
-export declare function describeQualityLoop(team: TeamState): QualityLoopSnapshot;
+export declare function describeQualityLoop(team: TeamState, audit?: DeliveryAudit): QualityLoopSnapshot;
 export { QUALITY_KINDS, WRITE_KINDS };
 /** Persisted evidence must remain loadable after process restart. */
 export declare function isTaskEvidence(value: unknown): value is TaskEvidence;

package/lib/types/scheduler.d.ts

@@ -65,6 +65,7 @@ export interface DispatchTicket {
     readonly acceptance?: readonly string[];
     readonly verify?: readonly string[];
     readonly reviewedTaskId?: string;
+    readonly findingSourceTaskIds?: readonly string[];
 }
 /**
  * Recursively collect `status=completed` ancestors of `taskId` in topological
@@ -73,6 +74,6 @@ export interface DispatchTicket {
 export declare function collectCompletedDependencyOutputs(tasks: readonly TeamTask[], taskId: string, warn?: (message: string) => void): DependencyOutput[];
 /** Format completed-dependency outputs with per-item and total truncation. */
 export declare function formatDependencyOutputs(items: readonly DependencyOutput[]): string;
-export declare function assignmentPrompt(ticket: DispatchTicket, stateDir: string, teamId: string): string;
+export declare function assignmentPrompt(ticket: DispatchTicket, stateDir: string, teamId: string, workOrderWarnings?: readonly string[]): string;
 /** Install one scheduler and its member activity observer. */
 export declare function installTeamScheduler(ctx: Context, config: SchedulerConfig): TeamScheduler;

package/lib/types/snapshot.d.ts

@@ -42,6 +42,11 @@ export interface TeamActivityTask {
     readonly kind?: string;
     readonly round?: number;
     readonly verdict?: string;
+    /**
+     * Set when this task's verdict or auto-generated work order no longer
+     * describes the current bytes; the panel must not render a bare pass badge.
+     */
+    readonly verdictStale?: string;
     /** Durable last-write stamp; drives the finished-member ordering (issue #192). */
     readonly updatedAt: number;
 }
@@ -64,6 +69,14 @@ export interface TeamActivitySnapshot {
     readonly tasks: readonly TeamActivityTask[];
     readonly messageCount: number;
     readonly captainInbox: readonly TeamActivityMessage[];
+    /** Present when the snapshot could audit the workspace bytes. */
+    readonly loopState?: string;
+    readonly deliverable?: boolean;
+    readonly delivery?: {
+        readonly ok: boolean;
+        readonly blockers: readonly string[];
+        readonly warnings: readonly string[];
+    };
 }
 /** Snapshot projection switches for live and archived teams. */
 export interface TeamSnapshotOptions {
@@ -71,6 +84,12 @@ export interface TeamSnapshotOptions {
     readonly includeRemoved?: boolean;
     /** Archived teams have no meaningful live activity after their sessions stop. */
     readonly historic?: boolean;
+    /**
+     * Absolute workspace path of the owning workspace. When present, the snapshot
+     * audits the current bytes behind every recorded verdict, so the panel and
+     * the model-facing status tool cannot report different delivery verdicts.
+     */
+    readonly workspacePath?: string;
 }
 /** Compact `provider/model` route for the activity panel, or just the model. */
 export declare function memberModelRoute(member: {
@@ -95,6 +114,7 @@ export declare function assembleTeamSnapshot(ctx: Context, stateRoot: string, wo
 export declare function collectTeamsActivity(ctx: Context, roots: readonly {
     workspace: string;
     stateRoot: string;
+    workspacePath?: string;
 }[]): Promise<TeamActivitySnapshot[]>;
 /**
  * Collect every archived team under the given workspace state roots (the

package/lib/types/state.d.ts

@@ -13,7 +13,8 @@
  * @module dsh-agent-teams/state
  */
 import { type TaskStatus, type TeamMessage, type TeamState, type TeamTask } from './types.ts';
-export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
+import { type LeadIdentity } from './lineage.ts';
+export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, isValidFindingLine, normalizeBlankOptionalTaskFields, normalizeSentinelNumericTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
 export type { ContractAmendmentInput } from './quality-gates.ts';
 /** Mailbox key of the captain. */
 export declare const CAPTAIN_KEY = "captain";
@@ -116,18 +117,22 @@ export declare function recordRetiredMemberIds(stateRoot: string, memberIds: rea
  * Find the team owned by one captain session (at most one per captain).
  * @param stateRoot - resolved absolute state root directory.
  * @param captainSessionId - the owning session id.
+ * @param lead - durable lead identity of the calling session, when it may lead
+ *   through a fork chain; omitted keeps the exact-id contract.
  * @returns the team record, or undefined when the captain leads no team.
  */
-export declare function findTeamByCaptain(stateRoot: string, captainSessionId: string): Promise<TeamState | undefined>;
+export declare function findTeamByCaptain(stateRoot: string, captainSessionId: string, lead?: LeadIdentity): Promise<TeamState | undefined>;
 /**
  * Find the team in which one session is an active participant.
- * Captains match `captainSessionId`; members match their durable child session
- * id. Removed members no longer have access to team-scoped tools.
+ * Captains match `captainSessionId` — including a lead session that inherited
+ * it through a fork — and members match their durable child session id.
+ * Removed members no longer have access to team-scoped tools.
  * @param stateRoot - resolved absolute state root directory.
  * @param agentSessionId - calling captain/member session id.
+ * @param lead - durable lead identity of the calling session, when available.
  * @returns the team record, or undefined when the caller belongs to no team.
  */
-export declare function findTeamByParticipant(stateRoot: string, agentSessionId: string): Promise<TeamState | undefined>;
+export declare function findTeamByParticipant(stateRoot: string, agentSessionId: string, lead?: LeadIdentity): Promise<TeamState | undefined>;
 /** Build a fresh message record. */
 export declare function createMessage(from: string, to: string, content: string): TeamMessage;
 /**
@@ -193,6 +198,18 @@ export interface AtomicReplaceOptions {
  * @returns nothing once the file has been replaced by one of the two paths.
  */
 export declare function replaceFileAtomicOrDirect(temporary: string, file: string, content: string, primitives: AtomicReplacePrimitives, options?: AtomicReplaceOptions): Promise<void>;
+/**
+ * Name the first durable defect in a record `coerceTeamState` rejected. Before
+ * this, a rejected `team.json` surfaced only as
+ * `invalid AgentTeams state in team "x"` — no task, no field, no value — while
+ * every AgentTeams tool (read *and* write) failed at once, leaving an operator
+ * to bisect the file by hand (issue #188). The detail is computed only on the
+ * failure path, so the happy path keeps its existing cost.
+ * @param raw - the parsed record as read from disk, before coercion.
+ * @param expectedId - the team id the record was read for.
+ * @returns a `task "t2": findings[0].line -1 must be ...` style detail.
+ */
+export declare function describeTeamStateDefect(raw: unknown, expectedId: string): string;
 export declare function isTeamTask(value: unknown): value is TeamTask;
 /**
  * Remove a team's whole directory (members should be interrupted first).

package/lib/types/tool-policies.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Owner-declared, reusable per-member tool policies (#59).
+ *
+ * A deployment owner declares reusable policies under `toolPolicies`; a member
+ * *selects* one by id (`tool_policy` on `agent_teams_add_member`, an inline
+ * plan member, or a profile member row). The Captain model can therefore only
+ * choose an existing policy — it can never submit raw allow/deny lists or
+ * invent one at runtime.
+ *
+ * One pure resolver turns the selection into the immutable effective filter
+ * that is persisted on the member (`toolPolicy` + `toolFilter`) and handed to
+ * the existing `startContinuable({ toolFilter })` seam, which hides the named
+ * tools from the child's schemas and rejects their execution. This is tool
+ * visibility / invocation policy for global tools, not an OS sandbox.
+ *
+ * Invariants (issue #59):
+ * 1. the captain-only deny list always applies and cannot be undone by a
+ *    policy — the host intersects `allow` and `deny`, so a denied name never
+ *    becomes visible again;
+ * 2. the four member coordination tools stay available, and a policy may not
+ *    deny them;
+ * 3. an allow-list policy explicitly includes those coordination tools;
+ * 4. the effective deny list is the union of the policy deny list and the
+ *    captain-only deny list.
+ * @module dsh-agent-teams/tool-policies
+ */
+/**
+ * Deny names the lenient spawn retry may drop when the host reports them
+ * unknown: exactly the built-in captain-only and depth entries (#163/#164).
+ * Names an owner policy declares are never relaxed — a policy that the host
+ * cannot apply must fail loud instead of silently applying a different one.
+ */
+export declare const BUILTIN_DENY_TOOLS: readonly string[];
+/** One owner-declared reusable member tool policy. */
+export interface MemberToolPolicy {
+    /** Global tool names that stay visible; coordination tools are added automatically. */
+    allow?: string[];
+    /** Global tool names removed from visibility; captain-only tools are added automatically. */
+    deny?: string[];
+}
+/** The immutable effective filter of one member. */
+export interface MemberToolFilter {
+    /** Visible global tools; absent means "no allow-list" (everything not denied stays). */
+    allow?: string[];
+    /** Removed global tools; never empty (the captain-only deny list is always included). */
+    deny: string[];
+}
+/** How the running host resolves the depth entries; both fields are optional. */
+export interface ToolPolicyContext {
+    /** Member delegation depth cap; `0` denies the host delegation tools when they exist. */
+    maxDepth?: number;
+    /** Names the host's `tools.restrict()` would admit, or undefined without a registry view. */
+    knownTools?: ReadonlySet<string>;
+}
+/** Trim, drop blanks, and de-duplicate names, preserving first-seen order. */
+export declare function dedupeToolNames(names: readonly string[]): string[];
+/**
+ * Validate and normalize one declared policy. Empty policies and empty lists
+ * are configuration mistakes: an `allow: []` policy would hide even the
+ * coordination tools, and a policy with neither list restricts nothing.
+ * Denying a required coordination tool is rejected for the same reason.
+ * @param id - the policy id, used in error messages.
+ * @param policy - the declared policy.
+ * @returns the normalized policy (trimmed, de-duplicated, blanks dropped).
+ */
+export declare function normalizeToolPolicy(id: string, policy: MemberToolPolicy): MemberToolPolicy;
+/**
+ * Validate every configured policy once, at plugin mount, so a malformed
+ * deployment config fails loud instead of at the first member creation.
+ * @param raw - the configured `toolPolicies` map.
+ * @returns normalized policies keyed by trimmed id.
+ */
+export declare function parseToolPolicies(raw: Record<string, MemberToolPolicy> | undefined | null): Record<string, MemberToolPolicy>;
+/**
+ * The policy behind one selected id, or `undefined` when this deployment no
+ * longer declares it (a config change after the member was created). Used on
+ * paths that must not fail a durable record merely because the owner edited
+ * configuration; selection itself uses {@link requireToolPolicy}.
+ * @param policies - normalized configured policies.
+ * @param id - the selected policy id.
+ * @returns the declared policy, or undefined.
+ */
+export declare function optionalToolPolicy(policies: Record<string, MemberToolPolicy>, id: string): MemberToolPolicy | undefined;
+/**
+ * The deny names one spawn may relax for a member that selected a policy.
+ *
+ * The built-in captain/depth entries keep the #163/#164 recovery path, but a
+ * name the owner explicitly declared in the policy's own `deny` list is never
+ * relaxable — even when it is also a built-in entry (`send_message` and
+ * `subagent` are depth entries, and every captain-only name is a built-in
+ * deny). Dropping such a name would spawn the member under a different policy
+ * than the owner declared, which is contract drift rather than recovery.
+ * @param policy - the member's selected policy, or undefined when the member
+ *   selected none (or the id is no longer configured).
+ * @param policySelected - whether the member selected a policy at all. A
+ *   selected id whose policy is no longer configured relaxes nothing, so the
+ *   member fails loud instead of spawning under an unknown filter.
+ * @returns the deny names the lenient retry may drop.
+ */
+export declare function memberSpawnRelaxableDeny(policy: MemberToolPolicy | undefined, policySelected?: boolean): readonly string[];
+/**
+ * The policy behind one selected id. A model-facing selection may only name a
+ * policy the deployment owner declared, so an unknown id is an error raised
+ * before any member is persisted.
+ * @param policies - normalized configured policies.
+ * @param id - the selected policy id.
+ * @returns the declared policy.
+ */
+export declare function requireToolPolicy(policies: Record<string, MemberToolPolicy>, id: string): MemberToolPolicy;
+/**
+ * Turn a selected policy (or no policy) into the immutable effective filter.
+ *
+ * Without `knownTools` the host's delegation names are forwarded verbatim, as
+ * before #163: the spawn retry drops whatever the host reports unknown.
+ * @param policy - the normalized policy, or undefined for the legacy behavior.
+ * @param context - depth cap and the host's restrictable-name view.
+ * @returns the effective filter handed to `startContinuable`.
+ */
+export declare function resolveMemberToolFilter(policy: MemberToolPolicy | undefined, context?: ToolPolicyContext): MemberToolFilter;

package/lib/types/tools.d.ts

@@ -10,6 +10,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type MemberToolPolicy } from './tool-policies.ts';
+import type { ArtifactSnapshot } from './types.ts';
 import { type TeamState, type TeamTask } from './types.ts';
 export { steerCaptainReport } from './members.ts';
 /** Resolved plugin config consumed by the tools. */
@@ -20,6 +22,8 @@ export interface ToolsConfig {
     memberProvider: string;
     /** Optional member model override. */
     memberModel?: string;
+    /** Optional member LLM provider, paired with `memberModel` (issue #189). */
+    memberLlmProvider?: string;
     /** Prompt injected into member personas and assignments. */
     executionPrompt?: string;
     /** Plugin fallback route. */
@@ -30,6 +34,8 @@ export interface ToolsConfig {
     maxMembers: number;
     /** Named team profiles from the active DSH profile. */
     profiles: Record<string, import('./profiles.ts').TeamProfileConfig>;
+    /** Owner-declared reusable member tool policies, keyed by policy id (#59). */
+    toolPolicies: Record<string, MemberToolPolicy>;
 }
 /** Browser/UI mutations allowed while a plan is waiting for approval. */
 export type StagedPlanMutation = {
@@ -40,6 +46,8 @@ export type StagedPlanMutation = {
     model: string;
     reasoningEffort?: string | null;
     executionPrompt?: string | null;
+    /** Selected tool-policy id; an empty string clears it back to no policy. */
+    toolPolicy?: string;
 } | {
     action: 'update_task';
     taskId: string;
@@ -86,6 +94,7 @@ export declare function haltTeamWork(input: {
     signal?: AbortSignal;
 }): Promise<{
     teamName: string;
+    captainSessionId: string;
     cancelledTasks: number;
     alreadyHalted: boolean;
 }>;
@@ -101,7 +110,9 @@ export declare function stagedPlanFeedbackContext(teamName: string): string;
  * @param config - resolved tool config.
  */
 export declare function registerAgentTeamsTools(ctx: Context, config: ToolsConfig): AgentTeamsRuntime;
-export declare function applyQualityFollowUp(team: TeamState, closed: TeamTask): {
+export declare function applyQualityFollowUp(team: TeamState, closed: TeamTask, snapshotPaths?: (paths: readonly string[]) => ArtifactSnapshot, pathExists?: (path: string) => boolean): {
     created: TeamTask[];
     escalated: boolean;
+    reason?: string;
+    excludedFindings?: string[];
 };