{
  "uid": "cogitave.learn.docs.agent-identity-and-capabilities",
  "kind": "doc",
  "href": "/docs/agent-identity-and-capabilities/",
  "title": "Agent identity and capabilities",
  "summary": "Every Cogitave agent acts under its own identity inside an explicit least-privilege capability grant, in a sandbox, with every action recorded as evidence. What that model guarantees, and where a human is still required.",
  "type": "explanation",
  "products": [
    "namzu",
    "yuva"
  ],
  "roles": [
    "developer",
    "solution-architect",
    "platform-engineer"
  ],
  "levels": [
    "intermediate"
  ],
  "subjects": [],
  "headings": [
    "1. An agent acts under its own identity",
    "2. Authority is an explicit grant, and the default is deny",
    "3. Execution is sandboxed",
    "4. Every action is recorded as evidence",
    "Where a human is still required",
    "Next steps"
  ],
  "source": "\n# Agent identity and capabilities\n\nAn agent that inherits whatever authority the process around it happens to have\nis not something you can reason about, audit, or safely leave running. Cogitave's\nauthorisation model exists to make an agent's authority **explicit, narrow, and\nrecorded**.\n\nFour rules carry it.\n\n## 1. An agent acts under its own identity\n\nEvery agent is a **first-class identity**. It does not borrow a human's session,\nand it does not run on an ambient credential that happens to be lying around in\nthe environment. When an action is later reviewed, the actor is the agent - not\n\"whoever deployed it\".\n\nThis is what makes the audit trail meaningful. An action attributable to a shared\nidentity is attributable to nobody.\n\n## 2. Authority is an explicit grant, and the default is deny\n\nAn agent may use **only** the tools and resources named in its grant. Nothing is\navailable because it happened to be reachable.\n\n- Capabilities are an **allow-list**, not a deny-list. An agent can do exactly\n  what it declares and nothing more.\n- Adding a behaviour means adding a declared capability - and, because behaviour\n  changes are gated, a scenario that proves the new behaviour is safe.\n- If a task needs more authority than the grant carries, the correct move is to\n  request a grant change through a human. Widening a grant to make a step easier\n  is the failure mode this model exists to prevent.\n\n> [!CAUTION]\n> Never widen a capability to make a failing check pass. Capabilities follow the\n> behaviour you can prove safe, not the other way around. A grant widened to get\n> a green result has removed the only evidence that the result meant anything.\n\n## 3. Execution is sandboxed\n\nThe grant says what an agent may reach; the sandbox enforces it. Namzu ships\nisolation as a pluggable layer (`@namzu/sandbox`): process-level isolation using\nthe platform's own primitives - bubblewrap on Linux, Seatbelt on macOS - and\ncontainer-level isolation with a JWT-authenticated egress proxy when network\nreach has to be mediated rather than merely configured.\n\nDeclared in the kernel, enforced by the sandbox. That pairing is the whole\nsecurity model: a declaration nobody enforces is documentation, and enforcement\nwithout a declaration is a guess.\n\n## 4. Every action is recorded as evidence\n\nActions are traced and recorded, to the OpenTelemetry specification, as\nwrite-once evidence. Assume non-repudiation: the record is not a debugging\nconvenience that can be edited later, it is the artefact a reviewer or an auditor\nreads.\n\n`@namzu/telemetry` is the exporter pipeline for that stream - traces and metrics\nover OTLP, with resource attributes attached.\n\n## Where a human is still required\n\nAutonomy inside the rails is the default: an agent acts unattended while it stays\ninside its grant, its typed inputs and outputs hold, policy checks pass, its\neffects are reversible or bounded, and the evaluation gate is green.\n\nA human is summoned as an **exception**, not as a routine checkpoint:\n\n- an automated guardrail or check fails;\n- confidence is low, or the case is novel;\n- drift, an anomaly, or a policy violation is detected;\n- or the action is in the small, explicit always-human set - applying,\n  merging, releasing, rotating a secret, changing organisation settings, and the\n  irreversible-catastrophic actions such as mass data deletion, billing, and\n  external publication.\n\nThat set is deliberately minimal and shrinks as the rails prove themselves. What\ndoes not shrink is the requirement that every autonomous action stays traceable\nto the identity that took it.\n\n## Next steps\n\n- [What Namzu is](what-is-namzu.md) - where the declaration lives.\n- [What Yuva is](what-is-yuva.md) - the layer built to enforce it on hardware\n  Cogitave controls.\n- [Packages](packages.md) - `@namzu/sandbox` and `@namzu/telemetry`.\n",
  "lastReviewed": "2026-07-26",
  "order": 3
}