@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/session/validate-session.js

@@ -4,6 +4,7 @@ import { TODO_LIMITS } from '../todo/limits.js';
 import { acceptanceSummary, normalizeAcceptance } from '../todo/acceptance.js';
 import { validateCompactionIdentity } from '../compaction/memory-identity.js';
 import { MemoryError } from '../compaction/memory.js';
+import { GOVERNANCE_CARD_FALLBACK_TEXT, normalizeGovernanceCard } from '../governance/card-normalize.js';
 function fail(path, expected) {
     throw new Error(`Invalid session file: ${path} must be ${expected}.`);
 }
@@ -145,6 +146,12 @@ const subagent = shape({
 });
 const ENTRY_FIELDS = {
     user: { text: string },
+    // A GOVERNANCE CARD IS HISTORY, so it is validated LENIENTLY (governance-mode 10.4):
+    // unknown fields are ignored (`shape` only reads the declared ones) and `card` is not
+    // shape-checked here at all - `sanitizeGovernanceEntries` below repairs a card it can
+    // and degrades one it cannot to a one-line notice, so a corrupt footnote never costs
+    // the session. `at` is advisory.
+    governance: { at: optional(number), card: () => { } },
     queued: { text: string, queueId: optional(nonempty) },
     notice: { text: string, level: enumeration('info', 'warn', 'error') },
     assistant: {
@@ -282,9 +289,33 @@ export function validateSession(value) {
     if (source.acceptance !== undefined) {
         prepared.acceptance = normalizeAcceptance(source.acceptance, [], { enabled: true }).items;
     }
-    prepared.entries = sanitizeEntryAcceptance(prepared.entries);
+    prepared.entries = sanitizeGovernanceEntries(sanitizeEntryAcceptance(prepared.entries));
     return prepared;
 }
+/**
+ * Repair every governance card the file carries, or degrade it to a one-line notice.
+ *
+ * The card is rebuilt from `normalizeGovernanceCard`'s output so only known fields survive
+ * (a hand-edited file cannot smuggle a 10 000-row table into the transcript), and a value
+ * with nothing renderable becomes a `notice` entry that keeps the entry's id: ids must stay
+ * unique and in order, and the transcript should say that something was here.
+ */
+function sanitizeGovernanceEntries(entries) {
+    if (!Array.isArray(entries))
+        return entries;
+    return entries.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return entry;
+        const record = entry;
+        if (record.kind !== 'governance')
+            return entry;
+        const card = normalizeGovernanceCard(record.card);
+        if (card === null) {
+            return { id: record.id, kind: 'notice', level: 'info', text: GOVERNANCE_CARD_FALLBACK_TEXT };
+        }
+        return { id: record.id, kind: 'governance', at: typeof record.at === 'number' ? record.at : 0, card };
+    });
+}
 /**
  * Drop the acceptance rows a persisted card cannot use, keeping every usable one.
  *

package/dist/team/runtime.d.ts

@@ -98,6 +98,14 @@ export interface TeamRuntimeDeps {
      * `TeamOverseer`), so a mid-dispatch `/fast off` stops the next look.
      */
     overseer?: OverseerProvider;
+    /**
+     * Governance hooks, passed straight through to `SubagentDeps` (governance-mode 13.2).
+     * ABSENT outside a governed session, which leaves every child built as before.
+     */
+    extraToolsFor?: SubagentDeps['extraToolsFor'];
+    narrowToolsFor?: SubagentDeps['narrowToolsFor'];
+    governanceRoleBlockFor?: SubagentDeps['governanceRoleBlockFor'];
+    extraPolicyExempt?: SubagentDeps['extraPolicyExempt'];
 }
 export declare class TeamRuntime {
     private readonly deps;

package/dist/team/runtime.js

@@ -512,6 +512,15 @@ export class TeamRuntime {
             ...(this.deps.contextManagerFor
                 ? { contextManagerFor: this.deps.contextManagerFor }
                 : {}),
+            // Site two of two for the four governance hooks, with the same silent failure as
+            // the lines above: declared on `TeamRuntimeDeps` and not forwarded here, a governed
+            // child would run with no role tools and the dispatch would simply never submit.
+            ...(this.deps.extraToolsFor ? { extraToolsFor: this.deps.extraToolsFor } : {}),
+            ...(this.deps.narrowToolsFor ? { narrowToolsFor: this.deps.narrowToolsFor } : {}),
+            ...(this.deps.governanceRoleBlockFor
+                ? { governanceRoleBlockFor: this.deps.governanceRoleBlockFor }
+                : {}),
+            ...(this.deps.extraPolicyExempt ? { extraPolicyExempt: this.deps.extraPolicyExempt } : {}),
             // Same conditional-spread rule: a dispatch without a supervisor builds
             // the exact pre-feature `SubagentDeps`, and the child's idle watchdog
             // keeps its un-lengthened ceiling (team-overseer §3.6).

package/dist/team/subagent.d.ts

@@ -138,6 +138,29 @@ export interface SubagentDeps {
     toolGateFor?: (label: string) => ToolGate;
     /** Added to each gated tool's executor timeout; see `gatedToolTimeouts`. */
     decisionBudgetMs?: number;
+    /**
+     * Governance hooks (governance-mode 13.2 / 14.3). ALL FOUR ABSENT outside a governed
+     * dispatch, and `buildSubagentTools` then produces exactly the array it always did.
+     *
+     * `extraToolsFor` returns the role tools this child gets (`gov_submit_*`, `ledger_*`,
+     * ...). They travel through the `teamTools` slot of the factory, next to the comm
+     * tools, so the plan gate and the ceiling treat them like `team_send`.
+     *
+     * `narrowToolsFor` runs on the factory's RESULT: it is where the inspector loses its
+     * write tools and gets the restricted `bash`, and where the governance-store tripwire is
+     * wrapped around the read-class tools. It is a separate hook (not folded into
+     * `extraToolsFor`) because it must see the finished built-ins, while the role tools must
+     * enter the factory. Both are closures supplied by the host, which keeps the dependency
+     * direction `governance/ -> team/` (this module never imports governance code).
+     *
+     * `extraPolicyExempt` is merged with `TEAM_SUBAGENT_TOOL_NAMES` for the skills ceiling
+     * (7.1 rule 6). Absent, `policyExempt` stays the SAME Set object as before, so the
+     * closed state is provable by identity.
+     */
+    extraToolsFor?: (spec: SubagentSpec) => AgentTool[];
+    narrowToolsFor?: (spec: SubagentSpec, tools: AgentTool[]) => AgentTool[];
+    governanceRoleBlockFor?: (spec: SubagentSpec) => string;
+    extraPolicyExempt?: ReadonlySet<string>;
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */

package/dist/team/subagent.js

@@ -77,7 +77,8 @@ export function buildSubagentTools(spec, deps, getAgent) {
                 : TEAM_LIMITS.waitMaxSeconds * 1000,
         }),
     ];
-    const tools = createBuiltinTools({
+    const extras = deps.extraToolsFor?.(spec) ?? [];
+    const built = createBuiltinTools({
         getCwd: deps.getCwd,
         confirmTools: deps.confirmTools,
         // THE CHILD ASKS THE CALLER TOO (section 2.3.7). Without this the approval
@@ -145,7 +146,9 @@ export function buildSubagentTools(spec, deps, getAgent) {
         // yields an empty array: a silent default is not a decision anyone can find
         // later.
         todoTools: [],
-        teamTools: commTools,
+        // Role tools ride the same slot as the comm tools (governance-mode 14.3). A spread
+        // only when a governed dispatch supplied some, so every other child is unchanged.
+        teamTools: extras.length > 0 ? [...commTools, ...extras] : commTools,
         // `spec.readOnly` forces the plan gate on for this child even in a BUILD
         // session. TIGHTENING ONLY (D-13): there is no field anywhere that gives a
         // child more permission than the session it was spawned from. Read LIVE, so
@@ -168,10 +171,13 @@ export function buildSubagentTools(spec, deps, getAgent) {
                 onToolPolicyEvent: (e) => deps.onChildToolPolicyEvent?.({ ...e, label: spec.label }),
                 // The two comm tools are not in the LEAD's registered tool list, so
                 // the ceiling would refuse them and dead-end the channel.
-                policyExempt: TEAM_SUBAGENT_TOOL_NAMES,
+                policyExempt: deps.extraPolicyExempt
+                    ? new Set([...TEAM_SUBAGENT_TOOL_NAMES, ...deps.extraPolicyExempt])
+                    : TEAM_SUBAGENT_TOOL_NAMES,
             }
             : {}),
     });
+    const tools = deps.narrowToolsFor ? deps.narrowToolsFor(spec, built) : built;
     // Mail rides on the NEXT tool result of whatever the child does next (D-4), so
     // every tool it can call has to carry the tail — the comm tools included, or a
     // child that only ever messages would never receive.
@@ -256,6 +262,11 @@ export function createSubagent(spec, deps, hooks) {
             peers: deps.bus.peersOf(spec.label),
         }),
         ...(fastBlock ? { fastBlock } : {}),
+        // The governed role block (governance-mode 6.1), after the subagent block. Spread
+        // only when this child is a governed one, so every other child's prompt is unchanged.
+        ...(spec.governance && deps.governanceRoleBlockFor
+            ? { governanceRoleBlock: deps.governanceRoleBlockFor(spec) }
+            : {}),
     });
     // LAZY ACCESSORS OVER `agentRef`, WHICH IS ASSIGNED AFTER THIS RETURNS. A
     // non-lazy read here is `undefined` at construction and the child's estimate

package/dist/team/types.d.ts

@@ -13,6 +13,7 @@
 import type { TokenUsage } from '@aragon-agent/core';
 import type { ActivityArgs } from './activity.js';
 import type { TimelineEntry } from './timeline.js';
+import type { GovernanceSpecExt } from '../governance/types.js';
 /** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
 export interface SubagentSpec {
     /** Slug, unique within the dispatch. Shown in the panel, the report and logs. */
@@ -27,6 +28,11 @@ export interface SubagentSpec {
      * permission than the session it was spawned from.
      */
     readOnly: boolean;
+    /**
+     * Set only by the governance engine (governance-mode section 8.3). Its presence is what
+     * `isGovernedDispatch` reads to keep a governed dispatch out of the transcript.
+     */
+    governance?: GovernanceSpecExt;
 }
 export type SubagentPhase = 'queued' | 'starting' | 'thinking' | 'tool' | 'waiting' | 'done' | 'failed' | 'aborted';
 /** Live, mutable record of one child. Projected into the UI and the report. */

package/dist/tools/index.d.ts

@@ -250,15 +250,38 @@ export interface BuiltinToolsOptions {
      * Tool names that skip the CEILING wrapper only (never the plan gate, never
      * confirmation).
      *
-     * It exists for a subagent's two comm tools and for nothing else (§3.11).
-     * `team_send` / `team_wait` are not in the LEAD's registered tool list, so
-     * evaluating them against the lead's `allowed-tools` ceiling would refuse them
-     * and dead-end the channel — the same dead end `SKILL_TOOL_FLOOR` exists to
-     * prevent one level up. Widening this set to anything that can write to disk
-     * would turn delegation into a ceiling bypass, which is exactly what §3.11
-     * re-applies the lead's policy to children to avoid.
+     * It has TWO users, and only two (§3.11, governance-mode 7.1 rule 6 / D-22b).
+     * First, a subagent's comm tools `team_send` / `team_wait`, which are not in the
+     * LEAD's registered tool list, so evaluating them against the lead's
+     * `allowed-tools` ceiling would refuse them and dead-end the channel. Second, the
+     * governance tools: the Orchestrator's `gov_run` / `gov_dispatch` and a governed
+     * child's role tools. Those are exempt for the same reason (a ceiling written
+     * before they existed names none of them) and because they never touch the user's
+     * workspace: the lead's two only write the host's own governance store, and the
+     * agents they dispatch each pass the full ceiling and plan gate for what they do.
+     *
+     * Widening this set to anything that can write to the user's workspace would turn
+     * delegation into a ceiling bypass, which is exactly what §3.11 re-applies the
+     * lead's policy to children to avoid. The governance names deliberately do NOT
+     * live in `HOST_TOOL_NAMES` / `SKILL_TOOL_FLOOR`: those feed `exec --allow-tool`
+     * validation and the `tools` diagnostics, and joining them would change both.
      */
     policyExempt?: ReadonlySet<string>;
+    /**
+     * The Orchestrator's two tools (`gov_run`, `gov_dispatch`), appended AFTER
+     * `teamTools` (governance-mode 14.3). Spread conditionally by the controller, so a
+     * session without governance builds the identical array.
+     */
+    governTools?: AgentTool[];
+    /**
+     * Live read of `{ governOn, mode }` for the governance gate. Never cached: Shift+Tab
+     * and `/gov off` flip it mid-run. Omitting it applies no gate, which is what keeps the
+     * closed state provable by object identity.
+     */
+    governGate?: () => {
+        governOn: boolean;
+        mode: AgentMode;
+    };
     /**
      * The non-interactive tool policy of `aragon exec`
      * (cli-integration-surface §4.2). A denied tool is NOT REGISTERED AT ALL, so

package/dist/tools/index.js

@@ -10,6 +10,7 @@
  */
 import { errorResult, evaluateToolCall, } from '@aragon-agent/core';
 import { planRefusal, submitPlanRefusal } from '../agent/agent-mode.js';
+import { withGovernanceGate } from '../governance/tools/guard.js';
 import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-tools.js';
 import { makeGlob, makeGrep } from './search-tools.js';
 import { makeBash } from './bash-tool.js';
@@ -382,6 +383,12 @@ export function createBuiltinTools(options) {
     if (options.teamTools && options.teamTools.length > 0) {
         tools = [...tools, ...options.teamTools];
     }
+    // The Orchestrator's tools, after `task` (governance-mode 14.3). Inside the factory for
+    // the reason `teamTools` records: appending later would let the ceiling and the plan
+    // gate see a different array than the one `HOST_TOOL_NAMES` is checked against.
+    if (options.governTools && options.governTools.length > 0) {
+        tools = [...tools, ...options.governTools];
+    }
     // --- The caller's per-call approval gate (headless-host-bridge §2.3.3). ---
     //
     // AFTER THE LAST APPEND AND BEFORE THE PERMISSION FILTER, for the two structural
@@ -495,6 +502,13 @@ export function createBuiltinTools(options) {
             return list;
         return list.map((tool) => withToolPostHooks(tool, hookRunner));
     };
+    // The governance gate is the INNER wrapper and the plan gate the outer one
+    // (governance-mode 13.2): `withPlanModeGate(withGovernanceGate(t))`, because the plan
+    // refusal is the more specific message and speaks first.
+    if (options.governGate) {
+        const getState = options.governGate;
+        tools = tools.map((t) => withGovernanceGate(t, getState));
+    }
     if (!options.agentMode)
         return withHooksPost(withJobNotices(tools));
     const getMode = options.agentMode;

package/dist/tools/plan-tools.d.ts

@@ -17,7 +17,7 @@
  * selected by whether an optional install step succeeded.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import { type HumanInputGate, type NormalizedQuestion } from './human-input.js';
+import { type HumanInputGate, type NormalizedPlan, type NormalizedQuestion } from './human-input.js';
 export interface PlanToolsOptions {
     gate: HumanInputGate;
     /**
@@ -52,8 +52,20 @@ export interface PlanToolsOptions {
      * This is the one place a `plan -> build` transition is not deferred to
      * `agent_end`, and the asymmetry is the whole point: the user has just read
      * the plan and authorized exactly this work. A stray `Shift+Tab` has not.
+     *
+     * Receives the approved plan (governance-mode 9.2): PLAN+GOVERN stashes it as the
+     * run specification. Returning a string REPLACES the tool result, which is how that
+     * path tells the model it is now the Orchestrator; returning nothing keeps
+     * `APPROVED_RESULT`, so every pre-existing caller is unchanged.
+     */
+    onPlanApproved: (plan: NormalizedPlan) => string | void;
+    /**
+     * Pre-submit check (governance-mode 9.2). Called after `normalizePlan` and BEFORE
+     * the review overlay opens; a non-null return is a refusal text, delivered as a
+     * NON-error result (an error invites an identical retry). Absent everywhere but
+     * PLAN+GOVERN, so plain plan mode is byte-identical.
      */
-    onPlanApproved: () => void;
+    beforeSubmit?: () => string | null;
 }
 /**
  * Build the plan tools, or `[]` for a channel that can never reach a human.

package/dist/tools/plan-tools.js

@@ -165,13 +165,16 @@ function makeSubmitPlan(opts) {
             const plan = normalizePlan(params);
             if (!plan)
                 return errorResult('A plan needs at least one step with a title.');
+            const refusal = opts.beforeSubmit?.() ?? null;
+            if (refusal !== null)
+                return textResult(refusal);
             const response = await opts.withHumanWait(() => opts.gate.request({ kind: 'plan', plan }, ctx.signal));
             if (response === null || response.kind !== 'planDecision') {
                 return textResult(DISMISSED_RESULT);
             }
             if (response.decision === 'approved') {
-                opts.onPlanApproved();
-                return textResult(APPROVED_RESULT);
+                const replacement = opts.onPlanApproved(plan);
+                return textResult(typeof replacement === 'string' ? replacement : APPROVED_RESULT);
             }
             if (response.decision === 'revise') {
                 return textResult(`Plan rejected. The user's feedback: "${response.feedback}". ` +