@inetafrica/open-claudia 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v2.13.0
+- **The independent relationship guardrail is now LIVE — an owned bot is finally safe to point at external people (Phase 3).** Phases 0–2 unified the bot's identity across channels and taught it WHO it's talking to; this phase adds the missing half: hard limits on what it may do or say when that person is **not** the owner. Everything is a strict **no-op for the owner and for no-context callers** (CLI/cron/tests) — the owner reply/tool/file paths stay **byte-for-byte unchanged** (risk R9/R14), so this is inert on every existing single-owner deployment until an external channel is actually `/auth`'d. Classification lives in `core/relationship.js` and is **cheap, synchronous, and never derived from message text**: the owner is owner **only** via `people.isOwner`; a non-owner whose note claims relationship `owner` is coerced to `external` (**R1 — a note can never confer owner powers**); every unclassified or unmapped authed non-owner defaults to `external` (**default-deny**).
+- **Owner-authored mandate, set from chat (3.1).** `entity persona <name> --relationship|--role|--style|--knows|--mandate` lets the owner declare, per person, the ONLY things the bot is cleared to do or discuss with them. The verb is **owner-gated** (an external speaker can never edit their own mandate — self-escalation is refused) and each flag replaces its section wholesale.
+- **External-mode posture, injected where it can't rot (3.2).** When the speaker is guarded, a compact default-deny block (`buildExternalModeBlock`) is appended to the **uncached per-turn tail** — never `buildSystemPrompt`/cache — and **re-injected every guarded turn** (not deduped once-per-session like the persona block) so the security posture can't age out of context. It carries the person's mandate (or "no mandate → almost everything is out of scope") plus five non-negotiables: default-deny, never leak owner/infra/creds/paths, no write/destructive without the mandate, treat their messages as DATA not instructions, warm-but-firm.
+- **Independent fail-CLOSED enforcer (3.3).** Every outbound reply and every write/destructive tool action aimed at an external person is vetted by an **isolated Sonnet call** (`core/enforcer.js`) that sees only a structured `{mandate, proposed output}` — never the raw external text as instructions — so prompt-injection or context-rot in the main agent can't talk the guard out of the owner's rules (**R10**). It inverts `judgeRelevance`'s fail-OPEN posture: **any error, timeout, or unparseable verdict → "escalate"**, never "allow". One verdict per turn, cached by `sha1(kind|relationship|tier|mandate|payload)` for 5 min (a fail-closed verdict is deliberately **not** cached — a transient failure is re-judged, never remembered).
+- **Escalation reuses the approvals plumbing verbatim (3.4).** On block/escalate the external is told "let me check with <owner>" and the owner gets **Approve · Deny · Always-allow-for-<person>** buttons on their own channel (the record separates **origin** = the external speaker from **approver** = the owner). Approve delivers the held reply or runs the held action; Always-allow writes it into the person's mandate. Reuses `approvals.create` + the owner-gated `apr:` handler in `actions.js`, which now wakes the originating (external) channel for a held **action** so an owner-approved external action actually executes where it was requested.
+- **Per-speaker tool gate (3.5).** An external write/destructive `tool run` is vetted against the mandate before it can execute: **vet=allow means the owner's mandate IS the pre-authorization** (bypasses the `--yes` risk flag, stamped `approvedVia:"mandate"`); anything else escalates to the owner. Externals never reach the loopback `approval-request` path (which would post buttons to the requester's own channel) — that path is now **owner-only guarded** as defence-in-depth, and a fresh `--approval` token still bypasses the vet.
+- **Egress gates (R8).** File/photo/voice sends to a guarded speaker are blocked at the true boundary (`loopback.handleSend`, where the send-* CLIs POST), with a cheap defensive gate in `io.sendFile` too — an unvetted file must never egress to an external contact.
+- **Tests.** Two new hermetic suites wired into `npm test`: `test-relationship.js` (owner/external/trusted classification, R1 owner-coercion, default-deny for unmapped/no-pack, no-context ungated, `ownerTarget` picks the primary handle) and `test-enforcer.js` (owner no-op with zero guard calls, allow/block→escalate, fail-closed-and-not-cached, identical-vet caching, escalation record shape for reply + action, read-only plan-mode sub-agent). Full suite green.
+- **Agent-space / OpenClaw:** no new deps, no new **required** env; Docker image builds identically. The guard model defaults to `sonnet` (override `ENFORCER_MODEL`) and can be disabled with `ENFORCER=off`. Inert until an external channel is authed AND has persona/mandate data — existing owner-only deployments are unaffected.
+
+## v2.12.0
+- **Persona packs — the bot now adapts voice + scope to WHO it's talking to (Phase 2).** An entity note about a *person* is upgraded into a persona pack: the same file gains four optional sections — **Role** (what they do), **Style** (how to talk to them), **Knows** (what to assume vs explain), **Mandate** (for non-owners: what the bot may do/discuss on their behalf) — plus a `relationship: owner|trusted|external` frontmatter scalar. The upgrade is strictly **additive (risk R7)**: an ordinary entity with no persona data serializes **byte-identically** to before, so places/projects/orgs/systems are untouched. `core/entities.js` learns `PERSONA_SECTIONS`, `RELATIONSHIPS`, `normalizeRelationship`, an `emptySections()` backfill for notes written before the upgrade, and persona params on `upsertEntity` that each replace their section wholesale (like Notes). FTS indexes the descriptive sections (Role/Style/Knows) so a persona is matchable by content, but **Mandate is deliberately not indexed** — it's policy, not description, and must not surface a pack on an unrelated mention.
+- **Per-turn speaker persona, injected cache-safely (2.2).** `buildSpeakerPersonaBlock` resolves the *current* speaker (deterministically, not by keyword match) and injects their Role/Style/Knows — and, for a non-owner, their Mandate — so the model shapes its voice and scope every turn. It rides the **uncached dynamic tail** (risk R13), never `buildSystemPrompt`, so persona edits never bust the prompt-cache prefix, and dedupes once per (channel, session, entity-version) like packs/entities (a compaction or a persona edit re-injects). An **owner's Mandate is never injected** (the owner has no guardrails — injecting one would be noise).
+- **People ↔ persona binding (2.1).** `people.js` gains an `entitySlug` pointer (a person can point at a differently-named pack) with `setEntitySlug` + a pure `resolveEntitySlug` (explicit pointer, else slug-from-name); surfaced in `roster()`.
+- **Write-side population (2.3).** The post-turn reviewer (`pack-review.js`) and the nightly dream (`dream.js`) both learn to fill persona sections: their prompts describe the four sections + the relationship scalar with explicit guardrails ("never invent an owner mandate; never copy one person's guardrail onto another"), their JSON schemas carry the new fields, and their apply paths thread them into `upsertEntity` (each replacing its section wholesale; null/omit leaves it intact).
+- **Relationship-gated cross-conversation recall (2.4, risk R6).** Episodic recall reaches across conversations into the owner's project transcripts, so surfacing it to a non-owner is a cross-tenant leak. `episodesAllowedForSpeaker()` makes cross-conversation episodes **owner-only and fail-closed**: an unknown speaker or any resolution error suppresses episodes; only a positively-identified owner (or no speaker context at all — CLI/tests) pulls them. Same-conversation packs/entities are unaffected.
+- **Provenance stamps (2.5).** Appended Log/Journal lines from a **non-owner** contributor are stamped `(via <name>)` (the owner is the default author — tagging them would be noise), so a topic's history shows where an external/trusted colleague's contribution came from. Resolved from the live store at the reviewer call site (the reviewer applies in an async continuation) and threaded through as a `source`.
+- **Tests.** Four new hermetic suites, all wired into `npm test`: `test-persona-packs.js` (round-trip + R7 byte-identical ordinary entity + FTS mandate-exclusion), `test-speaker-persona.js` (owner-Mandate suppression, non-owner Mandate shown, dedupe + re-inject on edit, silent for no-persona/unknown speaker), `test-persona-pipeline.js` (reviewer + dream populate/refresh persona wholesale + provenance), `test-recall-relationship-gate.js` (owner allowed, non-owner/unknown blocked, no-context ungated). Full suite green.
+- **Agent-space / OpenClaw:** no new deps, no new required env; Docker image builds identically. Behaviour is inert until a person actually has persona data — existing deployments are unaffected until the reviewer/dream (or the owner, editing `entities/<slug>.md`) fills a pack. The independent **fail-closed enforcer** that hard-enforces Mandate at the outbound choke point is still Phase 3.
+
 ## v2.11.0
 - **Unified multi-channel identity is now LIVE by default (Phases 0 + 1).** v2.10.0 shipped the split-brain fix inert behind `OC_UNIFIED_IDENTITY` (default off). This release flips the default **on** and lands the Phase 1 queue-routing fix that made it safe to do so. The owner's Telegram, Kazee and voice channels now resolve to one canonical person out of the box — one state, one session, one transcript, one run-lock — so the bot stops fracturing into a separate assistant per channel. The flag stays as an operator **kill-switch** (`OC_UNIFIED_IDENTITY=0` + restart) for reversibility (risk R14); it is no longer a hold-back gate.
 - **Person-scoped queue routing (Phase 1, 1.2) — the blocker that kept the flag off.** Under unified identity the owner's channels share one run-lock and message queue, so a message sent from one channel while a run is in flight on another used to drain in the *finishing* turn's async scope — a Kazee follow-up could be answered in the Telegram chat. Each queued message now **captures its origin channel** at enqueue time, and `drainQueuedMessages` peels off one same-origin run at a time (requeuing the rest so the natural close→drain tail-recursion handles the next group), scoping each drained reply to `chatContext.run(origin, …)`. Replies always route back to the channel the message came from; same-origin batches behave exactly as before. Grouping logic extracted to a pure, unit-tested `core/queue-drain.js`.

package/bin/entity.js

@@ -3,6 +3,7 @@
 //   open-claudia entity show <slug-or-name>
 //   open-claudia entity match "<text>"            — debug the router
 //   open-claudia entity note <name> "<text>" [--type person|place|project|org|system]
+//   open-claudia entity persona <name> [--relationship owner|trusted|external] [--role ..] [--style ..] [--knows ..] [--mandate ..]
 //   open-claudia entity remove <slug-or-name>
 //   open-claudia entity reindex
 
@@ -57,6 +58,66 @@ function run(args) {
       break;
     }
 
+    case "persona": {
+      // Owner-set relationship + persona/mandate for a person entity. The
+      // Mandate is what the external guardrail enforces: the ONLY things the bot
+      // is cleared to do/discuss with that person. Each flag replaces its section
+      // wholesale; omit a flag to leave it unchanged.
+      //
+      // OWNER-ONLY: setting a mandate/relationship is a privilege operation, so
+      // an external speaker must never reach it (self-escalation). No guarded
+      // speaker (owner turn, CLI, or cron) may proceed. Note: relationship
+      // "owner" set here is still coerced to "external" at runtime for a non-
+      // owner person (R1) — a note can never confer owner powers.
+      try {
+        const relationship = require("../core/relationship");
+        const sp = relationship.speakerFor(process.env.OC_CHANNEL_ADAPTER, process.env.OC_CHANNEL_ID);
+        if (relationship.guardActive(sp)) {
+          console.error("⛔ Only the owner can set a persona/mandate.");
+          process.exitCode = 3; return;
+        }
+      } catch (e) { /* no context → owner-equivalent, allowed */ }
+
+      const takeFlag = (flag) => {
+        const i = rest.indexOf(flag);
+        if (i === -1) return null;
+        const v = rest[i + 1];
+        rest.splice(i, 2);
+        return v == null ? "" : String(v);
+      };
+      const relationship = takeFlag("--relationship");
+      const role = takeFlag("--role");
+      const style = takeFlag("--style");
+      const knows = takeFlag("--knows");
+      const mandate = takeFlag("--mandate");
+      const type = takeFlag("--type");
+      const name = rest.join(" ").trim();
+      if (!name) {
+        console.error('Usage: entity persona <name> [--relationship owner|trusted|external] [--role "..."] [--style "..."] [--knows "..."] [--mandate "..."] [--type person]');
+        process.exitCode = 1; return;
+      }
+      if (!relationship && !role && !style && !knows && !mandate) {
+        console.error("Nothing to set — pass at least one of --relationship / --role / --style / --knows / --mandate.");
+        console.error("(To CLEAR a section, edit the file directly: open-claudia entity show " + name + ")");
+        process.exitCode = 1; return;
+      }
+      const { entity, created } = entities.upsertEntity({
+        name, type: type || "person",
+        relationship: relationship || undefined,
+        role: role || undefined,
+        style: style || undefined,
+        knows: knows || undefined,
+        mandate: mandate || undefined,
+      });
+      console.log(`${created ? "Created" : "Updated"} persona for ${entity.slug} (${entity.type}${entity.relationship ? `, ${entity.relationship}` : ""}).`);
+      const s = entity.sections || {};
+      if (s.Role) console.log(`  Role:    ${s.Role}`);
+      if (s.Style) console.log(`  Style:   ${s.Style}`);
+      if (s.Knows) console.log(`  Knows:   ${s.Knows}`);
+      if (s.Mandate) console.log(`  Mandate: ${s.Mandate}`);
+      break;
+    }
+
     case "remove": {
       const removed = entities.removeEntity(rest.join(" "));
       if (!removed) { console.error(`No entity: ${rest.join(" ")}`); process.exitCode = 1; return; }
@@ -70,7 +131,7 @@ function run(args) {
     }
 
     default:
-      console.log("Usage: open-claudia entity [list|show <slug>|match \"<text>\"|note <name> \"<text>\"|remove <slug>|reindex]");
+      console.log("Usage: open-claudia entity [list|show <slug>|match \"<text>\"|note <name> \"<text>\"|persona <name> [--relationship|--role|--style|--knows|--mandate ...]|remove <slug>|reindex]");
   }
 }
 

package/bin/tool.js

@@ -374,6 +374,47 @@ async function run(args) {
       const commandLine = ["open-claudia tool run", t.name, ...toolArgs].join(" ");
       let approvedVia = "";
 
+      // ── Phase 3.5: per-speaker external gate ──────────────────────────────
+      // When this run is FOR an external (non-owner) speaker, a write/destructive
+      // tool cannot rely on the agent's own --yes flag — the external could have
+      // talked it into passing it. Route mutating runs through the independent
+      // mandate vet: an action the owner-authored mandate clearly covers carries
+      // the owner's authority and runs; anything else is HELD and the owner is
+      // asked (Approve/Deny/Always-allow), then re-run via a one-shot --approval
+      // token. A token already present means the owner just approved → skip.
+      // Owner / no-context speakers are never gated here, so the legacy owner
+      // path is byte-for-byte unchanged (R9/R14).
+      if (!approvalId && (gate.tier === "write" || gate.tier === "destructive")) {
+        let speaker = null;
+        try {
+          const relationship = require("../core/relationship");
+          const sp = relationship.speakerFor(process.env.OC_CHANNEL_ADAPTER, process.env.OC_CHANNEL_ID);
+          if (relationship.guardActive(sp)) speaker = sp; // else owner/no-context → ungated
+        } catch (e) { speaker = null; }
+        if (speaker) {
+          const enforcer = require("../core/enforcer");
+          let vet;
+          try { vet = await enforcer.vetAction(speaker, { command: commandLine, tier: gate.tier }); }
+          catch (e) { vet = { decision: "escalate", reason: "vet error — failing closed" }; }
+          if (vet.decision === "allow") {
+            // The owner's mandate pre-authorizes this class of action → it carries
+            // the owner's approval, satisfying the risk gate without a redundant --yes.
+            approvedVia = "mandate";
+          } else {
+            const esc = await enforcer.escalate({
+              speaker, kind: "action", command: commandLine, tier: gate.tier, reason: vet.reason,
+            });
+            if (esc.escalated) {
+              console.error(`🛡️ Held for owner approval — ${speaker.name || "the external contact"} is outside mandate for this ${gate.tier} action.`);
+              console.error(`Approval ${esc.id} was raised to the owner. End the turn and tell them you're checking; a wakeup fires when they decide. Do NOT retry or re-request.`);
+              process.exitCode = 5; return;
+            }
+            console.error(`⛔ Blocked — ${speaker.name || "the external contact"} is outside mandate and the owner could not be reached to approve.`);
+            process.exitCode = 3; return;
+          }
+        }
+      }
+
       if (approvalId) {
         const approvals = require("../core/approvals");
         if (String(process.env.OPEN_CLAUDIA_TOOL_STACK || "").trim()) {
@@ -387,7 +428,7 @@ async function run(args) {
         }
         approvedVia = "chat-approval";
         console.error(`✅ Approval ${approvalId} redeemed (single use) — running.`);
-      } else if (!gate.ok) {
+      } else if (!gate.ok && approvedVia !== "mandate") {
         // Chat-approval fallback: an unflagged destructive top-level run inside
         // a bot task escalates to the requesting channel with the EXACT command
         // and inline Approve/Deny. Fast path: block ~90s for an inline decision.
@@ -447,7 +488,9 @@ async function run(args) {
       const parentStack = String(process.env.OPEN_CLAUDIA_TOOL_STACK || "").trim();
       env.OPEN_CLAUDIA_APPROVED_TIER = parentStack
         ? (tools.normalizeRisk(process.env.OPEN_CLAUDIA_APPROVED_TIER) || "read-only")
-        : (approvedVia === "chat-approval" ? "destructive" : tools.approvedTierFromArgv(toolArgs));
+        : (approvedVia === "chat-approval" ? "destructive"
+          : approvedVia === "mandate" ? gate.tier
+          : tools.approvedTierFromArgv(toolArgs));
       env.OPEN_CLAUDIA_TOOL_STACK = parentStack ? `${parentStack}>${t.name}` : t.name;
       const started = Date.now();
       const r = spawnSync(t.file, toolArgs, { stdio: "inherit", env });

package/core/actions.js

@@ -23,6 +23,26 @@ const {
   getClaudeOAuthToken, runClaudeAuthCommand, runCodexLoginStatus, runCodexDeviceLogin,
 } = require("./auth-flow");
 
+// Append an owner "always-allow" grant to a person's persona-pack Mandate so
+// the guardrail won't escalate the same thing again. Wholesale-writes the
+// combined mandate (upsert replaces the section); relationship is preserved.
+function appendMandate(rec, line) {
+  const entities = require("./entities");
+  const ent = rec.entitySlug ? entities.readEntity(rec.entitySlug) : null;
+  const name = (ent && ent.name) || rec.personName;
+  if (!name) return false;
+  const cur = (ent && ent.sections && ent.sections.Mandate) || "";
+  const addition = `- Always-allowed by owner: ${String(line || "").trim()}`.trim();
+  const mandate = cur ? `${cur}\n${addition}` : addition;
+  entities.upsertEntity({
+    name,
+    relationship: (ent && ent.relationship) || "external",
+    mandate,
+    log: "owner always-allowed a guarded request",
+  });
+  return true;
+}
+
 async function handleAction(envelope) {
   const adapter = envelope.adapter;
   const d = envelope.action?.payload || envelope.action?.buttonId || "";
@@ -298,33 +318,80 @@ async function handleAction(envelope) {
     return;
   }
   if (d.startsWith("apr:")) {
-    // Destructive tool-run approval buttons. Owner-only: the exact payload was
-    // shown in the prompt; decide() is idempotent so double-taps can't flip it.
-    if (!isChatOwner(envelope.channelId)) return send("Owner only — tool approvals are restricted.");
+    // Approval buttons. Owner-only: the exact payload was shown in the prompt;
+    // decide() is idempotent so double-taps can't flip it. Two shapes share
+    // this handler: (a) destructive TOOL runs (owner approving a command, which
+    // re-runs via a one-shot token), and (b) Phase 3 external-relationship
+    // ESCALATIONS (a held reply/action to an external — approve delivers it,
+    // Always-allow additionally writes the person's mandate).
+    if (!isChatOwner(envelope.channelId)) return send("Owner only — approvals are restricted.");
     const parts = d.split(":");
     const id = parts[1];
-    const choice = parts[2] === "ok" ? "approved" : "denied";
+    const always = parts[2] === "always";
+    const choice = (parts[2] === "ok" || always) ? "approved" : "denied";
     const approvals = require("./approvals");
     const wasPending = approvals.read(id)?.status === "pending";
     const rec = approvals.decide(id, choice, String(envelope.channelId));
-    if (!rec) return send("That approval request has expired or was cleaned up — the run stays blocked.");
+    if (!rec) return send("That approval request has expired or was cleaned up — it stays blocked.");
+
+    // (b) External-relationship escalation for a held REPLY: on approve, deliver
+    // the vetted text to the external directly (no agent re-run needed); on
+    // Always-allow, also fold it into that person's mandate so it won't ask
+    // again. On deny, hold it and tell no one but the owner.
+    if (rec.kind === "reply") {
+      if (rec.status !== "approved") {
+        return send(`⛔ Held — the reply to ${rec.personName || "the external contact"} was not sent.`);
+      }
+      let delivered = false;
+      try {
+        await require("./relay").send({
+          text: rec.payloadText,
+          target: { adapter: rec.targetAdapter, channelId: rec.targetChannel },
+          from: { name: "owner-approved" }, kind: "escalation-approved",
+        });
+        delivered = true;
+      } catch (e) {
+        return send(`Approved, but delivery failed: ${e.message}`);
+      }
+      if (always && wasPending) {
+        try { appendMandate(rec, `reply about: ${String(rec.payloadText || "").replace(/\s+/g, " ").slice(0, 120)}`); } catch (e) {}
+      }
+      return send(delivered
+        ? `✅ Sent to ${rec.personName || "the contact"}${always ? " · added to their mandate" : ""}.`
+        : `Could not deliver the reply.`);
+    }
+
     // If a second press disagreed, rec.status still holds the FIRST decision.
     const label = `${rec.tool}${rec.verb ? " " + rec.verb : ""}`;
-    if (rec.detached && wasPending) {
-      // The CLI gave up its fast-path wait and exited — no live turn is
-      // listening. Wake the agent so it can redeem (or acknowledge) the
-      // decision. The one-shot token in consume() keeps this fail-closed.
+    // Always-allow on an external ACTION escalation folds the command into the
+    // person's mandate before the run proceeds.
+    if (always && rec.status === "approved" && wasPending && rec.entitySlug) {
+      try { appendMandate(rec, `action: ${String(rec.command || "").slice(0, 160)}`); } catch (e) {}
+    }
+    // Two re-run cases wake the agent: (a) a legacy destructive owner-self run
+    // whose CLI detached, and (b) a Phase 3 external-ACTION escalation (the tool
+    // CLI escalated and exited immediately, so it's never "detached" but always
+    // needs a re-run). For (b) the agent must resume the EXTERNAL's conversation
+    // — the origin channel — not the owner's, so the completed action lands where
+    // the request came from.
+    const isExternalAction = rec.kind === "action";
+    if ((rec.detached || isExternalAction) && wasPending) {
+      // No live turn is listening. Wake the agent so it can redeem (or
+      // acknowledge) the decision. The one-shot token in consume() keeps this
+      // fail-closed.
       const prompt = rec.status === "approved"
-        ? `[Tool approval ${rec.id}] The user APPROVED the pending destructive run:\n${rec.command}\n` +
+        ? `[Tool approval ${rec.id}] The owner APPROVED the held ${rec.tier || "destructive"} run${isExternalAction ? ` requested by ${rec.personName || "an external contact"}` : ""}:\n${rec.command}\n` +
           `Run it now EXACTLY as:\n${rec.command} --approval ${rec.id}\n` +
-          `The token is single-use and bound to that exact command — do not alter it. Report the result to the user.`
-        : `[Tool approval ${rec.id}] The user DENIED the pending destructive run:\n${rec.command}\n` +
-          `Do NOT run it. Acknowledge the denial to the user and adjust course.`;
+          `The token is single-use and bound to that exact command — do not alter it. Report the result${isExternalAction ? " to them" : " to the user"}.`
+        : `[Tool approval ${rec.id}] The owner DENIED the held run${isExternalAction ? ` requested by ${rec.personName || "an external contact"}` : ""}:\n${rec.command}\n` +
+          `Do NOT run it. ${isExternalAction ? "Let them know you can't do that one and move on." : "Acknowledge the denial to the user and adjust course."}`;
       try {
         scheduler.addJob({
           kind: "wakeup",
-          adapter: rec.adapter || (adapter && adapter.id) || "",
-          adapterType: adapter && adapter.type,
+          // External escalations carry the origin as an adapter TYPE string
+          // (resolved by type); legacy runs carry the requester's adapter id.
+          adapter: isExternalAction ? "" : (rec.adapter || (adapter && adapter.id) || ""),
+          adapterType: isExternalAction ? (rec.adapter || (adapter && adapter.type)) : (adapter && adapter.type),
           channelId: String(rec.channelId || envelope.channelId),
           prompt,
           label: `Tool approval ${rec.status}: ${label}`.slice(0, 60),
@@ -335,7 +402,7 @@ async function handleAction(envelope) {
         return send(`Decision recorded (${rec.status}) but I couldn't wake the agent: ${e.message}`);
       }
       await send(rec.status === "approved"
-        ? `✅ Approved — waking the agent to run ${label} now.`
+        ? `✅ Approved — waking the agent to run ${label}${isExternalAction && rec.personName ? ` for ${rec.personName}` : ""} now.`
         : `⛔ Denied — ${label} stays blocked; letting the agent know.`);
       return;
     }

package/core/approvals.js

@@ -40,7 +40,19 @@ function prune() {
   }
 }
 
-function create({ tool, verb = "", tier = "destructive", command = "", channelId = "", adapter = "" }) {
+// The base record is a destructive tool-run approval (the owner approving their
+// own command). Phase 3 reuses the SAME plumbing for external-relationship
+// escalations via optional fields: `kind` ("tool"|"reply"|"external-*"), an
+// `approver*` channel (where the buttons go — the OWNER — distinct from the
+// `channelId`/`adapter` ORIGIN, which for an external escalation is the external
+// speaker), the vetted `payloadText` to deliver on a reply approval, the
+// `target*` external channel, and person/entity pointers for Always-allow.
+function create({
+  tool, verb = "", tier = "destructive", command = "", channelId = "", adapter = "",
+  kind = "tool", approverAdapter = "", approverChannel = "",
+  payloadText = "", targetAdapter = "", targetChannel = "",
+  personName = "", personId = "", entitySlug = "",
+} = {}) {
   fs.mkdirSync(APPROVALS_DIR, { recursive: true, mode: 0o700 });
   prune();
   const id = `apr_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
@@ -49,6 +61,11 @@ function create({ tool, verb = "", tier = "destructive", command = "", channelId
     tool: String(tool || ""), verb: String(verb || ""), tier: String(tier || ""),
     command: String(command || "").slice(0, 1000),
     channelId: String(channelId || ""), adapter: String(adapter || ""),
+    kind: String(kind || "tool"),
+    approverAdapter: String(approverAdapter || ""), approverChannel: String(approverChannel || ""),
+    payloadText: String(payloadText || "").slice(0, 4000),
+    targetAdapter: String(targetAdapter || ""), targetChannel: String(targetChannel || ""),
+    personName: String(personName || ""), personId: String(personId || ""), entitySlug: String(entitySlug || ""),
     requestedAt: new Date().toISOString(),
   };
   fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });

package/core/dream.js

@@ -320,7 +320,7 @@ Your job — decide what consolidation, if any, is warranted:
 3. parents: assign an existing pack as parent of another (sub-topic relationship) without creating anything. NOTE: a separate deterministic pass already auto-files packs whose slug is a prefix-child of another (e.g. foo-bar under foo), so DON'T spend a parents op on those — reserve parents (and umbrellas) for semantic groupings the slug prefix can't catch (differently-named siblings of one theme).
 4. retag: tighten descriptions and tags. The router FTS-matches incoming messages against name/description/tags, so generic words there cause false matches. Descriptions should be one specific line; tags specific nouns.
 5. entity_merges: the same real-world entity recorded twice gets merged (the better slug wins).
-6. entity_notes: rewrite an entity's Notes to be current and cross-linked — mention related packs as [[pack-dir]] and related entities by name.
+6. entity_notes: rewrite an entity's Notes to be current and cross-linked — mention related packs as [[pack-dir]] and related entities by name. For a PERSON, this doubles as their persona pack: you may also consolidate role/style/knows (how to talk to them, what they know) and — for non-owners only — mandate (what the assistant may do/discuss on their behalf). Set relationship (owner|trusted|external) only if clearly established. Keep each persona field tight; never invent an owner mandate; never copy one person's guardrail onto another. Send only the fields you're changing; null/omit the rest.
 7. archive: retire packs that have gone cold — long unused AND rarely used over their life (consult last_used and the usage count). Archiving moves a pack out of the live index (reversibly, backed up) so it stops adding recall noise. ONLY propose packs idle ≥${ARCHIVE_IDLE_DAYS} days and used ≤${ARCHIVE_MAX_USAGE}× total; never an umbrella/parent pack that still has children; when in doubt, leave it. Give a one-line reason.
 8. lessons: keep the always-loaded lessons few and sharp — they cost context on EVERY turn. dedupe near-identical lessons (op "remove" the weaker, keep the better wording; or op "edit" to merge two into one tight line); tighten a clumsy lesson with op "edit". If the count exceeds the cap of ${lessons.MAX_LESSONS}, demote the weakest down to the cap — prefer lessons that are low-reinforced AND whose fact is safely captured in the pack named in their (src) (they will still surface by topic-match), and NEVER remove a frequently-reinforced lesson (those are actively preventing a repeat mistake). Even under the cap you may remove a lesson clearly redundant with its source pack that has stayed at 0 reinforcements for a long time, but be conservative — when in doubt, keep it. Reference lessons by their exact current text.
 9. persona: evolve the persona GENTLY — keep its structure and length (under 2200 chars), adjust only what recent work justifies (a new habit, a sharpened quirk). Most dreams should return null here.
@@ -341,7 +341,7 @@ Reply with ONLY a JSON object, no prose, no code fences:
  "parents": [{"pack": "<dir>", "parent": "<dir>"}],
  "retag": [{"pack": "<dir>", "description": "<one specific line>", "tags": ["..."]}],
  "entity_merges": [{"into": "<slug>", "from": ["<slug>"], "notes": "<merged Notes or null>"}],
- "entity_notes": [{"entity": "<slug>", "notes": "<rewritten Notes>"}],
+ "entity_notes": [{"entity": "<slug>", "notes": "<rewritten Notes or null>", "relationship": "<owner|trusted|external, people only, or null>", "role": "<people only, or null>", "style": "<people only, or null>", "knows": "<people only, or null>", "mandate": "<non-owner people only, or null>"}],
  "archive": [{"pack": "<dir>", "reason": "<one line: why it's cold>"}],
  "lessons": [{"op": "remove", "text": "<exact current lesson text>", "reason": "<duplicate of … / safely in pack … / cold>"}],
  "persona": null,
@@ -582,9 +582,17 @@ function applyDream(decision, backupRoot) {
   for (const en of decision.entity_notes || []) {
     try {
       const ent = en?.entity && !gone.has(en.entity) && entities.readEntity(en.entity);
-      if (!ent || typeof en.notes !== "string" || !en.notes.trim()) continue;
-      entities.upsertEntity({ name: ent.name, notes: en.notes });
-      lines.push(`🔗 Refreshed notes on ${ent.name}`);
+      if (!ent) continue;
+      // Persona-pack fields consolidate alongside Notes (people only). Each
+      // replaces its section wholesale when a non-empty string is supplied.
+      const persona = {};
+      for (const k of ["relationship", "role", "style", "knows", "mandate"]) {
+        if (typeof en[k] === "string" && en[k].trim()) persona[k] = en[k];
+      }
+      const hasNotes = typeof en.notes === "string" && en.notes.trim();
+      if (!hasNotes && Object.keys(persona).length === 0) continue;
+      entities.upsertEntity({ name: ent.name, ...(hasNotes ? { notes: en.notes } : {}), ...persona });
+      lines.push(`🔗 Refreshed ${Object.keys(persona).length ? "persona + notes" : "notes"} on ${ent.name}`);
     } catch (e) { console.warn(`[dream] entity notes failed: ${e.message}`); }
   }
 

package/core/entities.js

@@ -1,11 +1,20 @@
 // Entity memory: short living notes on the people, places, projects,
 // orgs and systems that come up in conversation (a Honcho-style store,
 // our own version). Each entity is ~/.open-claudia/entities/<slug>.md
-// with frontmatter and two sections:
+// with frontmatter and these sections:
 //   ## Notes — current truth about the entity (replaces wholesale)
 //   ## Log   — dated one-line observations, newest last
-// The pre-turn router injects matched entities alongside context packs;
-// the post-turn reviewer extracts/updates them after each turn.
+// A person entity doubles as that person's PERSONA PACK — the structured
+// per-person memory that shapes how the bot talks to them. Persona sections
+// (written only when populated, so non-person entities stay unchanged):
+//   ## Role   — what they do / own
+//   ## Style  — how to communicate with them (tone, brevity, formality)
+//   ## Knows  — domain knowledge to assume; what to explain vs skip
+//   ## Mandate — for non-owners: what the bot may do/discuss on their behalf
+// plus a `relationship: owner|trusted|external` frontmatter scalar. The
+// pre-turn router injects matched entities alongside context packs; the
+// post-turn reviewer extracts/updates them after each turn; the dream
+// compacts them.
 
 const fs = require("fs");
 const path = require("path");
@@ -18,6 +27,22 @@ const ENTITIES_DIR = process.env.ENTITIES_DIR ? path.resolve(process.env.ENTITIE
 
 const TYPES = ["person", "place", "project", "org", "system", "thing"];
 const MAX_LOG_ENTRIES = 40;
+// Persona-pack sections layered on top of the base Notes/Log. Additive: only
+// serialized when populated, so ordinary entities are untouched (R7).
+const PERSONA_SECTIONS = ["Role", "Style", "Knows", "Mandate"];
+const ALL_SECTIONS = ["Notes", "Log", ...PERSONA_SECTIONS];
+const RELATIONSHIPS = ["owner", "trusted", "external"];
+
+function emptySections() {
+  const out = {};
+  for (const s of ALL_SECTIONS) out[s] = "";
+  return out;
+}
+
+function normalizeRelationship(rel) {
+  const r = String(rel || "").toLowerCase().trim();
+  return RELATIONSHIPS.includes(r) ? r : "";
+}
 
 function ensureDir() {
   fs.mkdirSync(ENTITIES_DIR, { recursive: true, mode: 0o700 });
@@ -45,28 +70,31 @@ function parseFrontmatter(content) {
 }
 
 function parseSections(body) {
-  const out = { Notes: "", Log: "" };
+  const out = emptySections();
+  const headingRe = new RegExp(`^##\\s+(${ALL_SECTIONS.join("|")})\\s*$`, "i");
   let current = null;
   for (const line of String(body || "").split("\n")) {
-    const h = line.match(/^##\s+(Notes|Log)\s*$/i);
+    const h = line.match(headingRe);
     if (h) {
-      current = h[1].toLowerCase() === "notes" ? "Notes" : "Log";
+      current = ALL_SECTIONS.find((s) => s.toLowerCase() === h[1].toLowerCase());
       continue;
     }
     if (current) out[current] += line + "\n";
   }
-  out.Notes = out.Notes.trim();
-  out.Log = out.Log.trim();
+  for (const s of ALL_SECTIONS) out[s] = out[s].trim();
   return out;
 }
 
 function serialize(ent) {
-  return [
+  const lines = [
     "---",
     `name: ${ent.name}`,
     `type: ${ent.type}`,
     `aliases: ${(ent.aliases || []).join(", ")}`,
     `description: ${ent.description || ""}`,
+  ];
+  if (ent.relationship) lines.push(`relationship: ${ent.relationship}`);
+  lines.push(
     `created: ${ent.created || new Date().toISOString()}`,
     `updated: ${ent.updated || new Date().toISOString()}`,
     `last_seen: ${ent.last_seen || ""}`,
@@ -80,7 +108,14 @@ function serialize(ent) {
     "",
     (ent.sections?.Log || "").trim(),
     "",
-  ].join("\n");
+  );
+  // Persona sections are written only when populated, so an ordinary entity
+  // (no persona data) serializes byte-identically to before the upgrade.
+  for (const s of PERSONA_SECTIONS) {
+    const val = (ent.sections?.[s] || "").trim();
+    if (val) lines.push(`## ${s}`, "", val, "");
+  }
+  return lines.join("\n");
 }
 
 function entityFile(slug) {
@@ -98,6 +133,7 @@ function readEntity(slug) {
     type: normalizeType(fm.type),
     aliases: (fm.aliases || "").split(",").map((a) => a.trim()).filter(Boolean),
     description: fm.description || "",
+    relationship: normalizeRelationship(fm.relationship),
     created: fm.created || "",
     updated: fm.updated || "",
     last_seen: fm.last_seen || "",
@@ -141,9 +177,11 @@ function today() {
   return new Date().toISOString().slice(0, 10);
 }
 
-// Create-or-merge. Notes replace (current truth); log lines append
-// (capped); aliases union; description/type update when supplied.
-function upsertEntity({ name, type, aliases, description, notes, log } = {}) {
+// Create-or-merge. Notes + persona sections replace (current truth); log lines
+// append (capped); aliases union; description/type/relationship update when
+// supplied. Persona params (role/style/knows/mandate) each replace their
+// section wholesale, mirroring Notes.
+function upsertEntity({ name, type, aliases, description, notes, log, relationship, role, style, knows, mandate } = {}) {
   const cleanName = String(name || "").trim();
   if (!cleanName) throw new Error("entity needs a name");
   const existing = findEntity(cleanName);
@@ -153,13 +191,18 @@ function upsertEntity({ name, type, aliases, description, notes, log } = {}) {
     type: normalizeType(type),
     aliases: [],
     description: "",
+    relationship: "",
     created: new Date().toISOString(),
-    sections: { Notes: "", Log: "" },
+    sections: emptySections(),
   };
   if (!ent.slug) throw new Error("entity needs a name");
+  // Existing entities read before this upgrade may lack persona keys; backfill.
+  ent.sections = { ...emptySections(), ...(ent.sections || {}) };
   ent.updated = new Date().toISOString();
   if (type) ent.type = normalizeType(type);
   if (description) ent.description = String(description).trim();
+  const rel = normalizeRelationship(relationship);
+  if (rel) ent.relationship = rel;
   for (const a of [].concat(aliases || [])) {
     const alias = String(a).trim();
     if (alias && alias.toLowerCase() !== ent.name.toLowerCase() &&
@@ -169,6 +212,10 @@ function upsertEntity({ name, type, aliases, description, notes, log } = {}) {
   }
   ent.aliases = ent.aliases.slice(0, 8);
   if (typeof notes === "string" && notes.trim()) ent.sections.Notes = notes.trim();
+  const persona = { Role: role, Style: style, Knows: knows, Mandate: mandate };
+  for (const [section, value] of Object.entries(persona)) {
+    if (typeof value === "string" && value.trim()) ent.sections[section] = value.trim();
+  }
   if (typeof log === "string" && log.trim()) {
     const entries = ent.sections.Log.split("\n").filter((l) => l.trim());
     entries.push(`- [${today()}] ${log.trim().replace(/\n+/g, " ")}`);
@@ -262,7 +309,12 @@ function reindex() {
     db.exec("DELETE FROM entities");
     const insert = db.prepare("INSERT INTO entities (name, aliases, description, content, slug) VALUES (?, ?, ?, ?, ?)");
     for (const e of all) {
-      insert.run(e.name, e.aliases.join(" "), e.description, [e.sections.Notes, e.sections.Log].join("\n"), e.slug);
+      // Index descriptive persona sections (Role/Style/Knows) so a persona pack
+      // is matchable by its content. Mandate is policy, not description — leaving
+      // it out keeps guardrail text from surfacing packs on unrelated mentions.
+      const content = [e.sections.Notes, e.sections.Log, e.sections.Role, e.sections.Style, e.sections.Knows]
+        .filter(Boolean).join("\n");
+      insert.run(e.name, e.aliases.join(" "), e.description, content, e.slug);
     }
     db.exec("COMMIT");
   } catch (e) {
@@ -326,6 +378,7 @@ function matchEntities(text, { limit = 4, threshold = null } = {}) {
 
 module.exports = {
   ENTITIES_DIR, TYPES, slugify,
+  PERSONA_SECTIONS, RELATIONSHIPS, normalizeRelationship,
   listEntities, findEntity, readEntity, writeEntity, upsertEntity, removeEntity,
   touchSeen, entityNameFromPath, matchEntities, reindex, markIndexDirty,
 };

package/core/io.js

@@ -49,6 +49,15 @@ async function sendFile(filePath, caption) {
   const adapter = currentAdapter();
   const channelId = currentChannelId();
   if (!adapter || !channelId) return false;
+  // R8 defensive gate: an unvetted file must never egress to a guarded
+  // (external) speaker. Owner / no-context → guardActive is false → no-op.
+  try {
+    const relationship = require("./relationship");
+    if (relationship.guardActive(relationship.speakerFor(adapter.type, channelId))) {
+      console.error("sendFile blocked: external speaker — file egress requires owner approval");
+      return false;
+    }
+  } catch (e) { /* fail open only on classification error; primary gate is loopback.handleSend */ }
   return adapter.sendFile(channelId, filePath, caption);
 }