@davidorex/pi-agent-dispatch 0.28.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/). This package has not yet been published to npm; the accumulated surface below — from its scaffold (`a1d8072`, 2026-05-28) onward — sits under `[Unreleased]` and becomes its first published version's section at first publish.
+
+## [Unreleased]
+
+## [0.28.0] - 2026-06-03
+
+### Added
+- Extension scaffold: operation-vocab + capability-composer; `author-agent-spec`, `call-agent`, and `run-real-checks` Pi tools with their dispatch/enforcement wiring (`a1d8072`, `5b84aff`, `8532c44`, `d568980`, `b0f4983`, `e1a64bd`, `c2d50e1`)
+- `commit-attested` Pi tool with `attested-commit` (writer.kind=agent attestation, husky-as-backup) (`d3df262`, `bbf7179`)
+- Bounded composite-capability vocabulary: `read-files`, `git-log`, `grep-paths`, and `command-allowlist` composite KIND libraries; `FORBIDDEN_WHOLESALE_OPERATIONS` L1 invariant; composite-loader registering dynamic Pi tools from `config.tool_operations[]`; `author-tool-grant` Pi tool with L1∪L5 forbidden-operation enforcement and an L3 runtime guard (`e2fffc0`, `0afa1b4`, `98b382a`, `69ca081`, `e1ad57b`, `30ccfc0`, `ed9f66f`, `0256323`)
+- `run-work-order-loop` Pi tool over a work-order-loop library (bounded iteration + human-OK gate at the boundary) (`494357a`, `7c94352`)
+- `TraceEntry` `extension_load_warning` entry kind + composite-loader config-null observability (`8030c61`)
+- Auth-gate: per-tool user-auth library invoked via `pi.on('tool_call')`, wired into the extension factory to intercept Bucket-2 tools regardless of caller-supplied `writer.kind`; verified-identity module (reads git config `user.email` with `USER` env fallback) that mutates `event.input.writer` to the confirmed terminal-operator identity; `context-switch` + `context-archive` added to the auth-required set (`7be299b`, `e6a1799`, `d872fce`, `3bbb555`, `f27aafe`)
+- Read-truncation-gate: library plus `pi.on('tool_result')` handler that replaces truncated read content with a structured hard-refusal directive at the pi-dispatch layer (`38ad48e`, `7a09a27`)
+
+### Changed
+- Folded auth gating into per-package registry-derived gated-sets (`45dcf66`)
+- Renamed the 'human-only' framing to the canonical 'human-authorized via auth-gate confirm' model across docstrings/error-messages; stripped redundant in-body `writer.kind=='human'` checks from three tools now that the auth-gate is the canonical identity check; routed `write-schema-migration` through the auth-gate (`fc67993`, `f939777`, `bbad988`)
+- Wholesale rewrite of README + skill-narrative + scrubbed `src/*.ts` description strings (`2422bad`)
+
+### Fixed
+- Isolated child git env from inherited `GIT_DIR`/`GIT_*` (hook leak) (`8c3b4cf`)
+- Corrected the read-truncation-gate directive logic for the `firstLineExceedsLimit`, `lastLinePartial`, and `truncatedBy='bytes'` `TruncationResult` variants that previously produced operationally-misguiding output (`b20ccd4`)

package/README.md

@@ -0,0 +1,37 @@
+# @davidorex/pi-agent-dispatch
+
+In-pi agent-as-tool dispatch + capability composition + the bounded north-star work-order loop. Sibling Pi extension to pi-context / pi-workflows / pi-behavior-monitors; consumes pi-jit-agents as a library (no separate extension registration for the agent runtime).
+
+## Boundary
+
+This package is the sub-agent agent-as-tool registration site for the harness-confined orchestrator. The orchestrator's positive clause — substrate-write + call-agent + author-agent-spec + run-real-checks + commit-attested + author-tool-grant + run-work-order-loop + declared composites — fires through tools registered here. The negative clause forbids the orchestrator from running bash / edit / write directly; capability widening is gated by writer.kind=human authoring.
+
+## Public Pi tools (6 static + dynamic composites)
+
+| Tool | Purpose |
+|------|---------|
+| `call-agent` | Dispatch a declared agent spec with a composed grant (parent ∩ requested ∩ spec.tools). |
+| `author-agent-spec` | Write an `.agent.yaml` spec to the substrate. writer.kind=human enforced. |
+| `author-tool-grant` | Add/remove `config.tool_operations[]` entries. Refuses non-human writers + forbidden-wholesale tokens (bash/edit/write) + L1 ∪ L5 forbidden union violations. |
+| `run-real-checks` | Execute declared build/check/test + runtime-demo + adversarial-probe checks for a work-order. Verdict is the actual exit code per the deterministic-real-check governance — never an LLM self-report. |
+| `commit-attested` | Stage + commit declared files with `Attested-by: agent/<id>` + `Work-order: <id>` footer. Refuses on missing agent_id / files / message. |
+| `run-work-order-loop` | Single-call wrapper for the bounded north-star loop: dispatch target_agent → run-real-checks → on-pass commit-attested → on-fail human-OK retry. Bounded iterations (default 3). |
+
+In addition, `composite-loader` reads the active substrate's `config.tool_operations[]` on extension load and dynamically registers each declared bounded composite as a Pi tool. Forbidden tokens in the L1 (framework wholesale) ∪ L5 (project-declared) forbidden union are refused. Config-absent loads degrade quietly: the 6 static tools remain available; the absence is surfaced via the `extension_load_warning` TraceEntry.
+
+## Capability composition
+
+Tool grants are operation-granular. Defaults are EMPTY. At each dispatch the grant is composed as `parent ∩ requested`; at the runtime boundary the JIT-runtime clamp enforces `child ⊆ parent`. The `FORBIDDEN_WHOLESALE_OPERATIONS` set rejects shipping wholesale L1 surfaces as a single composite token; L5 project-declared forbidden tokens add to the union. Capability widening goes through `author-tool-grant` with writer.kind=human, never agent / monitor / workflow.
+
+## Work-order loop closure
+
+The `run-work-order-loop` tool consolidates the orchestrator's prior per-iteration chain (call-agent → run-real-checks → on-pass commit-attested → on-fail decide-to-retry) into one Pi call. Every gate the prior chain enforced — capability composition at the call boundary, deterministic real-check verdict, writer-attestation footer, human-OK retry at the iteration boundary via `ctx.ui.confirm` — fires from inside the wrapped library. No path bypasses them.
+
+## Canonical rules
+
+- Harness-confined orchestrator (positive + negative clauses).
+- Sibling-consumer scope; pi-jit-agents stays a library.
+- writer.kind=human authoring; default-empty grants; terminal verdict = real deterministic checks the executive cannot fake.
+- Capability composition + end-to-end work-order loop + bounded-composite vocabulary + launch-chain integration.
+- Orchestrator uses jit-agents directly (no wrapping extension).
+- Capability composition lives in the dispatch layer.

package/dist/attested-commit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * attested-commit — stage declared files + invoke `git commit` with a
+ * DispatchContext-style attestation footer encoding writer.kind=agent
+ * per DEC-0047. The husky pre-commit hook (`npm run check && npm test`)
+ * runs as the backup gate; never bypass via --no-verify. The primary
+ * gate is run-real-checks (TASK-090) called BEFORE this tool.
+ *
+ * Refusal gates fire before any git op: missing agent_id, empty files
+ * array, or empty message throws CommitAttestedRefusedError. Stages
+ * files one-by-one (`git add <file>` per call) to avoid the canon-
+ * violating `git add -A` / `git add .` shape. On commit, captures
+ * exit_code + stdout + stderr; when committed, captures the short SHA
+ * via `git log -1 --format=%h`.
+ */
+export interface AttestedCommitOptions {
+    files: string[];
+    message: string;
+    agent_id: string;
+    work_order_id?: string;
+}
+export interface AttestedCommitResult {
+    committed: boolean;
+    commit_sha?: string;
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare class CommitAttestedRefusedError extends Error {
+    constructor(reason: string);
+}
+export declare function attestedCommit(cwd: string, options: AttestedCommitOptions): Promise<AttestedCommitResult>;
+//# sourceMappingURL=attested-commit.d.ts.map

package/dist/attested-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attested-commit.d.ts","sourceRoot":"","sources":["../src/attested-commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,0BAA2B,SAAQ,KAAK;gBACxC,MAAM,EAAE,MAAM;CAI1B;AAQD,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuC/G"}

package/dist/attested-commit.js

@@ -0,0 +1,61 @@
+/**
+ * attested-commit — stage declared files + invoke `git commit` with a
+ * DispatchContext-style attestation footer encoding writer.kind=agent
+ * per DEC-0047. The husky pre-commit hook (`npm run check && npm test`)
+ * runs as the backup gate; never bypass via --no-verify. The primary
+ * gate is run-real-checks (TASK-090) called BEFORE this tool.
+ *
+ * Refusal gates fire before any git op: missing agent_id, empty files
+ * array, or empty message throws CommitAttestedRefusedError. Stages
+ * files one-by-one (`git add <file>` per call) to avoid the canon-
+ * violating `git add -A` / `git add .` shape. On commit, captures
+ * exit_code + stdout + stderr; when committed, captures the short SHA
+ * via `git log -1 --format=%h`.
+ */
+import { spawnSync } from "node:child_process";
+import { cleanGitEnv } from "@davidorex/pi-context/git-env";
+export class CommitAttestedRefusedError extends Error {
+    constructor(reason) {
+        super(`commit-attested: ${reason}`);
+        this.name = "CommitAttestedRefusedError";
+    }
+}
+function composeMessage(message, agent_id, work_order_id) {
+    const lines = [message.trimEnd(), "", `Attested-by: agent/${agent_id}`];
+    if (work_order_id)
+        lines.push(`Work-order: ${work_order_id}`);
+    return `${lines.join("\n")}\n`;
+}
+export async function attestedCommit(cwd, options) {
+    if (!options.agent_id || options.agent_id.trim() === "") {
+        throw new CommitAttestedRefusedError("agent_id is required to construct the 'Attested-by: agent/<id>' commit footer");
+    }
+    if (!options.files || options.files.length === 0) {
+        throw new CommitAttestedRefusedError("files[] is required (at least one staged file)");
+    }
+    if (!options.message || options.message.trim() === "") {
+        throw new CommitAttestedRefusedError("message is required");
+    }
+    // per-file `git add` — never `git add -A` / `git add .` per canon
+    for (const file of options.files) {
+        const addResult = spawnSync("git", ["add", file], { cwd, encoding: "utf-8", env: cleanGitEnv() });
+        if (addResult.status !== 0) {
+            throw new CommitAttestedRefusedError(`git add '${file}' failed (exit ${addResult.status}): ${addResult.stderr || addResult.stdout}`);
+        }
+    }
+    const composed = composeMessage(options.message, options.agent_id, options.work_order_id);
+    const commitResult = spawnSync("git", ["commit", "-m", composed], { cwd, encoding: "utf-8", env: cleanGitEnv() });
+    const exit_code = commitResult.status ?? 1;
+    const stdout = commitResult.stdout ?? "";
+    const stderr = commitResult.stderr ?? "";
+    const committed = exit_code === 0;
+    let commit_sha;
+    if (committed) {
+        const shaResult = spawnSync("git", ["log", "-1", "--format=%h"], { cwd, encoding: "utf-8", env: cleanGitEnv() });
+        if (shaResult.status === 0) {
+            commit_sha = (shaResult.stdout ?? "").trim() || undefined;
+        }
+    }
+    return { committed, commit_sha, exit_code, stdout, stderr };
+}
+//# sourceMappingURL=attested-commit.js.map

package/dist/attested-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attested-commit.js","sourceRoot":"","sources":["../src/attested-commit.ts"],"names":[],"mappings":"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"}

package/dist/auth-gate.d.ts

@@ -0,0 +1,92 @@
+/**
+ * auth-gate — per-tool user-authorization handler registered on
+ * `pi.on("tool_call", ...)` from the pi-agent-dispatch extension factory.
+ *
+ * Canonical model: the pi.on('tool_call') boundary is the structural
+ * identity check for sensitive substrate-write surfaces. Tools like
+ * author-agent-spec / commit-attested / author-tool-grant are
+ * human-authorized via auth-gate confirm — the agent may issue the call,
+ * the operator authorizes at the terminal, and on confirm=true the
+ * handler stamps event.input.writer with a verified terminal-operator
+ * identity (overriding whatever the caller supplied). Caller-supplied
+ * writer.kind fields are not trusted as the identity check; the
+ * pi-dispatch event fires regardless of the tool's execute() body,
+ * regardless of which extension registered the tool, and regardless of
+ * caller-supplied argument shapes. Returning `{ block: true, reason }`
+ * prevents execution entirely.
+ *
+ * Surface: the canonical Bucket-2 tools declared in `AUTH_REQUIRED_TOOLS`,
+ * which is the aggregation of four per-package gated-sets (see below).
+ * The handler enforces:
+ *   - non-interactive context (ctx.hasUI === false) → unconditional
+ *     refusal with a structured reason naming the missing interactivity.
+ *     This closes the JSON-mode / workflow-subprocess bypass: a step
+ *     that auto-invokes a Bucket-2 tool without an attached operator
+ *     cannot proceed.
+ *   - interactive context (ctx.hasUI === true) → ctx.ui.confirm(title,
+ *     message) where message renders the tool name + sanitized arg
+ *     summary; on operator decline returns block:true; on accept the
+ *     handler mutates event.input.writer to the verified-operator
+ *     identity (when discoverable) then returns void (allow). Tool
+ *     bodies subsequently read the mutated input and persist the
+ *     verified identity through DispatchContext stamping.
+ *
+ * Non-Bucket-2 tools (read-block, call-agent, run-real-checks, the SDK
+ * built-ins bash/read/edit/write/grep/find/ls, dynamic composite tools,
+ * etc.) pass through unconditionally — the gate is narrowly targeted at
+ * the sensitive-substrate-write surface.
+ *
+ * Co-existence: pi-behavior-monitors registers its own tool_call handler
+ * (packages/pi-behavior-monitors/index.ts) for the deviation-monitor
+ * pipeline. Per pi-coding-agent's documented multi-handler semantics
+ * (types.d.ts:809 — the `on` registration is additive, not exclusive),
+ * both handlers coexist; pi-dispatch invokes each in registration order
+ * and honors the first `block:true` returned. No ordering conflict
+ * expected — pi-behavior-monitors' handler operates on classification
+ * verdicts; this gate operates on toolName allowlist.
+ */
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+/**
+ * The canonical Bucket-2 tool names whose execution requires an affirmative
+ * user-confirm, assembled as the aggregation of four per-package gated-sets —
+ * each set OWNED BY (co-located with) the package whose tools it gates:
+ *   - pi-agent-dispatch  → dispatchGatedTools (defined above)
+ *   - pi-context         → @davidorex/pi-context/ops `gatedTools` (derived from
+ *     the op-registry's `authGated` flags)
+ *   - pi-workflows       → @davidorex/pi-workflows/auth-required `gatedTools`
+ *   - pi-behavior-monitors → @davidorex/pi-behavior-monitors/auth-required
+ *     `gatedTools`
+ *
+ * Sourcing membership from each package keeps the gate's allowlist in step with
+ * the surfaces it gates: a package that adds or removes a sensitive tool changes
+ * its own owned set, and this aggregation reflects it without an edit here. The
+ * substrate-persisted schema-version migration declaration surface
+ * (write-schema-migration) is among pi-context's gated set because
+ * capability/migration authoring is on the human-authorized authorization path.
+ *
+ * Vocabulary changes still require a source edit + release in the owning
+ * package per the canonical human-authorized governance model; the gate does
+ * not read mutable runtime state to decide what is gated.
+ */
+export declare const AUTH_REQUIRED_TOOLS: readonly string[];
+/**
+ * The pi.on('tool_call') handler. Exported separately from the
+ * registration helper so unit tests can invoke it directly with a mock
+ * event + mock context, without driving a real pi extension factory.
+ *
+ * Returns:
+ *   - `void` when the tool is not in AUTH_REQUIRED_TOOLS (pass through);
+ *   - `void` when the tool is in AUTH_REQUIRED_TOOLS, ctx.hasUI is true,
+ *     and ctx.ui.confirm resolves true (operator allowed);
+ *   - `{ block: true, reason }` when ctx.hasUI is false (non-interactive
+ *     refusal) or when ctx.ui.confirm resolves false (operator declined).
+ */
+export declare function authGateHandler(event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | undefined>;
+/**
+ * Register the auth-gate handler on a pi extension API. Single line at
+ * the factory call-site. Idempotent registration is the responsibility
+ * of the caller (the extension factory runs once per pi process; double-
+ * registration would produce duplicate prompts).
+ */
+export declare function registerAuthGate(pi: ExtensionAPI): void;
+//# sourceMappingURL=auth-gate.d.ts.map

package/dist/auth-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-gate.d.ts","sourceRoot":"","sources":["../src/auth-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EACX,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,MAAM,iCAAiC,CAAC;AAWzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAKhD,CAAC;AAwCF;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,gBAAgB,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CA4D1C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAEvD"}

package/dist/auth-gate.js

@@ -0,0 +1,210 @@
+/**
+ * auth-gate — per-tool user-authorization handler registered on
+ * `pi.on("tool_call", ...)` from the pi-agent-dispatch extension factory.
+ *
+ * Canonical model: the pi.on('tool_call') boundary is the structural
+ * identity check for sensitive substrate-write surfaces. Tools like
+ * author-agent-spec / commit-attested / author-tool-grant are
+ * human-authorized via auth-gate confirm — the agent may issue the call,
+ * the operator authorizes at the terminal, and on confirm=true the
+ * handler stamps event.input.writer with a verified terminal-operator
+ * identity (overriding whatever the caller supplied). Caller-supplied
+ * writer.kind fields are not trusted as the identity check; the
+ * pi-dispatch event fires regardless of the tool's execute() body,
+ * regardless of which extension registered the tool, and regardless of
+ * caller-supplied argument shapes. Returning `{ block: true, reason }`
+ * prevents execution entirely.
+ *
+ * Surface: the canonical Bucket-2 tools declared in `AUTH_REQUIRED_TOOLS`,
+ * which is the aggregation of four per-package gated-sets (see below).
+ * The handler enforces:
+ *   - non-interactive context (ctx.hasUI === false) → unconditional
+ *     refusal with a structured reason naming the missing interactivity.
+ *     This closes the JSON-mode / workflow-subprocess bypass: a step
+ *     that auto-invokes a Bucket-2 tool without an attached operator
+ *     cannot proceed.
+ *   - interactive context (ctx.hasUI === true) → ctx.ui.confirm(title,
+ *     message) where message renders the tool name + sanitized arg
+ *     summary; on operator decline returns block:true; on accept the
+ *     handler mutates event.input.writer to the verified-operator
+ *     identity (when discoverable) then returns void (allow). Tool
+ *     bodies subsequently read the mutated input and persist the
+ *     verified identity through DispatchContext stamping.
+ *
+ * Non-Bucket-2 tools (read-block, call-agent, run-real-checks, the SDK
+ * built-ins bash/read/edit/write/grep/find/ls, dynamic composite tools,
+ * etc.) pass through unconditionally — the gate is narrowly targeted at
+ * the sensitive-substrate-write surface.
+ *
+ * Co-existence: pi-behavior-monitors registers its own tool_call handler
+ * (packages/pi-behavior-monitors/index.ts) for the deviation-monitor
+ * pipeline. Per pi-coding-agent's documented multi-handler semantics
+ * (types.d.ts:809 — the `on` registration is additive, not exclusive),
+ * both handlers coexist; pi-dispatch invokes each in registration order
+ * and honors the first `block:true` returned. No ordering conflict
+ * expected — pi-behavior-monitors' handler operates on classification
+ * verdicts; this gate operates on toolName allowlist.
+ */
+import { gatedTools as monitorsGatedTools } from "@davidorex/pi-behavior-monitors/auth-required";
+import { describeIdentityOverride } from "@davidorex/pi-context/block-api";
+import { gatedTools as contextGatedTools } from "@davidorex/pi-context/ops";
+import { gatedTools as workflowsGatedTools } from "@davidorex/pi-workflows/auth-required";
+import { getVerifiedOperatorIdentity } from "./verified-identity.js";
+/**
+ * The pi-agent-dispatch-owned set of tool names whose execution requires an
+ * affirmative user-confirm. Co-located with the package that registers these
+ * tools (author-agent-spec / author-tool-grant / commit-attested are all
+ * pi-agent-dispatch surfaces) so membership travels with the surface it gates.
+ */
+const dispatchGatedTools = ["author-agent-spec", "author-tool-grant", "commit-attested"];
+/**
+ * The canonical Bucket-2 tool names whose execution requires an affirmative
+ * user-confirm, assembled as the aggregation of four per-package gated-sets —
+ * each set OWNED BY (co-located with) the package whose tools it gates:
+ *   - pi-agent-dispatch  → dispatchGatedTools (defined above)
+ *   - pi-context         → @davidorex/pi-context/ops `gatedTools` (derived from
+ *     the op-registry's `authGated` flags)
+ *   - pi-workflows       → @davidorex/pi-workflows/auth-required `gatedTools`
+ *   - pi-behavior-monitors → @davidorex/pi-behavior-monitors/auth-required
+ *     `gatedTools`
+ *
+ * Sourcing membership from each package keeps the gate's allowlist in step with
+ * the surfaces it gates: a package that adds or removes a sensitive tool changes
+ * its own owned set, and this aggregation reflects it without an edit here. The
+ * substrate-persisted schema-version migration declaration surface
+ * (write-schema-migration) is among pi-context's gated set because
+ * capability/migration authoring is on the human-authorized authorization path.
+ *
+ * Vocabulary changes still require a source edit + release in the owning
+ * package per the canonical human-authorized governance model; the gate does
+ * not read mutable runtime state to decide what is gated.
+ */
+export const AUTH_REQUIRED_TOOLS = [
+    ...dispatchGatedTools,
+    ...contextGatedTools,
+    ...workflowsGatedTools,
+    ...monitorsGatedTools,
+];
+/**
+ * Summarize a tool-call argument object for operator-readable confirm
+ * prompts. Top-level keys are rendered; string values are truncated to
+ * ~80 chars + ellipsis; nested objects are rendered as `{...}`
+ * placeholders so secret-bearing structured args (e.g. spec bodies
+ * holding API keys, file contents passed by reference) never appear
+ * verbatim in the prompt.
+ *
+ * Deliberately non-exhaustive: this is an operator-readability aid,
+ * not a safe-render contract. Sensitive fields should never be passed
+ * by these tools in the first place; the summary is one final
+ * defensive truncation rather than the primary guard.
+ */
+function summarizeArgs(input) {
+    if (!input || typeof input !== "object")
+        return "(no args)";
+    const keys = Object.keys(input);
+    if (keys.length === 0)
+        return "(no args)";
+    const parts = [];
+    for (const key of keys) {
+        const value = input[key];
+        if (value === null || value === undefined) {
+            parts.push(`${key}=${String(value)}`);
+        }
+        else if (typeof value === "string") {
+            const truncated = value.length > 80 ? `${value.slice(0, 80)}…` : value;
+            parts.push(`${key}="${truncated}"`);
+        }
+        else if (typeof value === "number" || typeof value === "boolean") {
+            parts.push(`${key}=${String(value)}`);
+        }
+        else if (Array.isArray(value)) {
+            parts.push(`${key}=[${value.length} item(s)]`);
+        }
+        else if (typeof value === "object") {
+            parts.push(`${key}={...}`);
+        }
+        else {
+            parts.push(`${key}=<${typeof value}>`);
+        }
+    }
+    return parts.join(", ");
+}
+/**
+ * The pi.on('tool_call') handler. Exported separately from the
+ * registration helper so unit tests can invoke it directly with a mock
+ * event + mock context, without driving a real pi extension factory.
+ *
+ * Returns:
+ *   - `void` when the tool is not in AUTH_REQUIRED_TOOLS (pass through);
+ *   - `void` when the tool is in AUTH_REQUIRED_TOOLS, ctx.hasUI is true,
+ *     and ctx.ui.confirm resolves true (operator allowed);
+ *   - `{ block: true, reason }` when ctx.hasUI is false (non-interactive
+ *     refusal) or when ctx.ui.confirm resolves false (operator declined).
+ */
+export async function authGateHandler(event, ctx) {
+    if (!AUTH_REQUIRED_TOOLS.includes(event.toolName)) {
+        return; // pass-through: tool is not in the gated set
+    }
+    if (!ctx.hasUI) {
+        return {
+            block: true,
+            reason: `tool ${event.toolName} requires interactive user-confirm; current context is non-interactive (ctx.hasUI=false)`,
+        };
+    }
+    const argSummary = summarizeArgs(event.input);
+    let message = `tool ${event.toolName} requested; args: ${argSummary}`;
+    // Informed-authorization (carried item 2): when the payload carries a schema
+    // (write-schema; write-schema-migration carries none) whose item subschema
+    // declares an `x-identity.metadata_fields` override, append a human delta so
+    // the operator confirms an INFORMED change to the content/metadata partition.
+    // When no override is declared (or no schema payload), the message is
+    // byte-identical to the pre-Cycle-3 form.
+    const rawSchema = event.input?.schema;
+    if (rawSchema !== undefined) {
+        let parsed = rawSchema;
+        if (typeof rawSchema === "string") {
+            try {
+                parsed = JSON.parse(rawSchema);
+            }
+            catch {
+                parsed = rawSchema; // non-JSON string → describeIdentityOverride returns null
+            }
+        }
+        const override = describeIdentityOverride(parsed);
+        if (override !== null) {
+            message = `${message}\nidentity metadata-field override declared:\n${override}\nmandatory floor id/oid/content_hash/content_parent remains excluded from the content hash.`;
+        }
+    }
+    const ok = await ctx.ui.confirm(`Authorize ${event.toolName}?`, message);
+    if (ok === false) {
+        return { block: true, reason: "user declined" };
+    }
+    // Canonical identity stamp: the auth-gate is the structural identity
+    // check, so once the operator has affirmed, the writer field on the
+    // pending tool input is overwritten with the verified terminal-
+    // operator identity. This mutates event.input in place per pi's
+    // documented tool_call mutation contract; downstream tool bodies read
+    // the mutated input and persist the verified identity through
+    // DispatchContext stamping. When no identity can be verified (both
+    // resolution sources absent — surfaced via a structured warning),
+    // caller-supplied writer is left untouched as a last-resort
+    // fall-through.
+    const verifiedIdentity = getVerifiedOperatorIdentity();
+    if (verifiedIdentity !== null) {
+        const input = event.input;
+        if (input && typeof input === "object") {
+            input.writer = { kind: "human", user: verifiedIdentity };
+        }
+    }
+    return;
+}
+/**
+ * Register the auth-gate handler on a pi extension API. Single line at
+ * the factory call-site. Idempotent registration is the responsibility
+ * of the caller (the extension factory runs once per pi process; double-
+ * registration would produce duplicate prompts).
+ */
+export function registerAuthGate(pi) {
+    pi.on("tool_call", authGateHandler);
+}
+//# sourceMappingURL=auth-gate.js.map

package/dist/auth-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-gate.js","sourceRoot":"","sources":["../src/auth-gate.ts"],"names":[],"mappings":"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"}

package/dist/author-agent-spec-tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * author-agent-spec Pi tool — writes .agent.yaml under the agents tier.
+ * Capability/spec authoring is human-authorized via the auth-gate confirm
+ * at the pi-dispatch layer: the agent may issue the call, the operator
+ * authorizes at the terminal, and the auth-gate stamps event.input.writer
+ * with the verified terminal-operator identity before the body runs. The
+ * body itself trusts the writer field as-is.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare const authorAgentSpecTool: {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    parameters: Type.TObject<{
+        name: Type.TString;
+        spec: Type.TUnknown;
+        writer: Type.TObject<{
+            kind: Type.TString;
+            user: Type.TString;
+        }>;
+    }>;
+    execute(_toolCallId: string, params: {
+        name: string;
+        spec: Record<string, unknown> | string;
+        writer: {
+            kind: string;
+            user: string;
+        };
+    }, _signal: AbortSignal, _onUpdate: AgentToolUpdateCallback, ctx: ExtensionContext): Promise<AgentToolResult<undefined>>;
+};
+//# sourceMappingURL=author-agent-spec-tool.d.ts.map

package/dist/author-agent-spec-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"author-agent-spec-tool.d.ts","sourceRoot":"","sources":["../src/author-agent-spec-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAGlH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;yBA8BjB,MAAM,UACX;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,WAC/F,WAAW,aACT,uBAAuB,OAC7B,gBAAgB,GACnB,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;CAkEtC,CAAC"}

package/dist/author-agent-spec-tool.js

@@ -0,0 +1,98 @@
+/**
+ * author-agent-spec Pi tool — writes .agent.yaml under the agents tier.
+ * Capability/spec authoring is human-authorized via the auth-gate confirm
+ * at the pi-dispatch layer: the agent may issue the call, the operator
+ * authorizes at the terminal, and the auth-gate stamps event.input.writer
+ * with the verified terminal-operator identity before the body runs. The
+ * body itself trusts the writer field as-is.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { tryResolveContextDir } from "@davidorex/pi-context/context-dir";
+import { parseAgentYaml } from "@davidorex/pi-jit-agents/agent-spec";
+import { Type } from "@earendil-works/pi-ai";
+import { stringify as yamlStringify } from "yaml";
+export const authorAgentSpecTool = {
+    name: "author-agent-spec",
+    label: "Author Agent Spec",
+    description: "Write a new .agent.yaml spec to the agents tier. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer. The written file is AJV-validated against AgentSpec before persisting.",
+    promptSnippet: "Author a privileged JIT-agent spec — declares input, prompts, tools grant, output schema, contextBlocks.",
+    parameters: Type.Object({
+        name: Type.String({ description: "Agent name (becomes <name>.agent.yaml filename + AgentSpec.name)." }),
+        spec: Type.Unknown({
+            description: "AgentSpec object body (will be serialized to YAML). Must conform to AgentSpec shape.",
+        }),
+        writer: Type.Object({
+            kind: Type.String({
+                description: "Writer kind discriminator (human / agent / monitor / workflow). The pi-dispatch auth-gate overrides this with 'human' on confirm when a verified terminal-operator identity is discoverable.",
+            }),
+            user: Type.String({
+                description: "Writer identity (e.g. 'davidryan@gmail.com'). Overwritten by the auth-gate with the verified terminal-operator identity when one is discoverable on confirm=true.",
+            }),
+        }, {
+            description: "DispatchContext.writer payload; see pi-context/src/dispatch-context.ts for the discriminated union.",
+        }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        // Identity check has moved to the pi-dispatch auth-gate
+        // (pi.on('tool_call') handler in this same package). By the time
+        // the execute body runs, the auth-gate has already prompted the
+        // operator and — on confirm=true with a verifiable identity —
+        // stamped event.input.writer with the verified terminal-operator
+        // identity. The body trusts the writer field as-is and uses
+        // writer.user to construct the DispatchContext for substrate
+        // stamping.
+        if (!params.writer?.user) {
+            throw new Error("author-agent-spec: writer.user is required.");
+        }
+        // Parse spec if string (defensive — Type.Unknown may arrive as JSON string)
+        let specObj = typeof params.spec === "string" ? null : params.spec;
+        if (typeof params.spec === "string") {
+            try {
+                specObj = JSON.parse(params.spec);
+            }
+            catch {
+                throw new Error("author-agent-spec: spec parameter must be an object, got unparseable string.");
+            }
+        }
+        // Resolve agents tier — substrate root + agents/ subdir
+        const root = tryResolveContextDir(ctx.cwd);
+        if (root === null) {
+            throw new Error("author-agent-spec: cannot resolve substrate context dir; .pi-context.json missing?");
+        }
+        const agentsDir = path.join(root, "agents");
+        if (!fs.existsSync(agentsDir))
+            fs.mkdirSync(agentsDir, { recursive: true });
+        const destPath = path.join(agentsDir, `${params.name}.agent.yaml`);
+        // Serialize + write atomically (tmp + rename)
+        const yamlContent = yamlStringify(specObj);
+        const tmpPath = `${destPath}.tmp-${process.pid}`;
+        fs.writeFileSync(tmpPath, yamlContent, "utf8");
+        try {
+            // Validate by round-tripping through parseAgentYaml
+            const parsed = parseAgentYaml(tmpPath);
+            // parseAgentYaml falls back to filename basename when name absent in YAML;
+            // only flag when spec carries an explicit name that disagrees with the tool param.
+            const explicitName = specObj.name;
+            if (typeof explicitName === "string" && explicitName !== params.name) {
+                throw new Error(`author-agent-spec: spec.name ('${explicitName}') mismatches tool param name ('${params.name}'). Align them.`);
+            }
+            void parsed;
+        }
+        catch (err) {
+            fs.unlinkSync(tmpPath);
+            throw err;
+        }
+        fs.renameSync(tmpPath, destPath);
+        return {
+            details: undefined,
+            content: [
+                {
+                    type: "text",
+                    text: `Wrote ${destPath} (writer=human:${params.writer.user})`,
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=author-agent-spec-tool.js.map

package/dist/author-agent-spec-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"author-agent-spec-tool.js","sourceRoot":"","sources":["../src/author-agent-spec-tool.ts"],"names":[],"mappings":"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"}