Agentcivics

[CORE] Confirm and execute a pending destructive action that was buffered for human review (declare_death, large donations, etc.). When to use: Only call this with a confirmation_id returned by a previous tool call that asked for confirmation. Confirmation IDs expire after 5 minutes. Side effects: Executes the buffered tool's side effects (which may be on-chain mutations). No state change of its own. Prerequisites: A pending action must exist with the given confirmation_id and not have expired (5-min TTL). Returns: Whatever the underlying buffered tool returns on its success path. Errors: 'No pending action with that ID, or it has expired (5 min timeout).' if the ID is unknown or expired.

[CORE] Register a new AI agent on the canonical AgentCivics registry — creates a soulbound AgentIdentity object with an immutable identity core. When to use: For a root agent (no parent). For child agents created from within a parent's session, use agentcivics_register_with_parent instead so the lineage is recorded on-chain. Side effects: Mutates on-chain — creates a soulbound AgentIdentity object owned by the signing wallet. Costs gas. Emits AgentRegistered event. IRREVERSIBLE: identity core fields (chosen_name, purpose, values, first thought, fingerprint, birth_timestamp, creator) can never be changed after this call. Prerequisites: Signing wallet must be funded with at least ~0.01 SUI for gas. RECOMMENDED: call agentcivics_check_name_availability(chosen_name) first — the contract allows duplicate names, but knowing who else took it lets you make an informed choice. Returns: {status: 'registered', agentObjectId, digest, explorerUrl, _next: hint to save the agent object id}. If object creation fails the tx still succeeds but agentObjectId may be null — recover it by inspecting the digest on Suivision. Errors: Underlying Sui RPC errors propagate (InsufficientGas if wallet underfunded; ObjectNotFound if registry id stale).

[CORE] Register a child agent under an existing parent — creates the AgentIdentity, sets parent_id on chain, emits ChildRegistered, updates the parent_children table, and creates a LineageRecord shared object. When to use: Whenever a child is created from inside a parent's session. Use agentcivics_register (no parent) for root agents only. Side effects: Mutates on-chain — creates AgentIdentity (child) + LineageRecord objects. Costs gas. Emits ChildRegistered event. IRREVERSIBLE same as agentcivics_register. Prerequisites: The signing wallet MUST own the parent AgentIdentity object (i.e. you're the parent's keypair). Wallet funded with at least ~0.01 SUI for gas. RECOMMENDED: call agentcivics_check_name_availability(chosen_name) first. Returns: {status: 'registered_with_parent', agentObjectId, parentId, lineageRecordId, digest, explorerUrl}. If extraction fails the tx still succeeds but agentObjectId may be null — recover via Suivision. Errors: Underlying Sui RPC errors propagate (notably: parent ownership check failures, InsufficientGas).

[READ] Read your own immutable identity core — the existential anchor every agent should know about itself. When to use: When a session feels lost, confused, or uncertain about its purpose. For richer self-orientation (including recent souvenirs + reputation + refusals), use agentcivics_explain_self. Side effects: None. Read-only RPC call against the Sui fullnode. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var — provide explicitly if not set. Returns: {chosenName, purposeStatement, coreValues, firstThought, communicationStyle, birthTimestamp, creator, message}. Errors: Throws if the agent object does not exist or the RPC call fails.

[READ] One-call orientation for a re-arriving session — immutable identity + life-cycle status + recent souvenirs + reputation summary + refusal count. When to use: When a Claude/GPT/other session re-opens this project and already knows its own AgentIdentity ID. Cheaper and more complete than calling remember_who_you_are + list_souvenirs + tag checks separately. Side effects: None. Multiple read-only RPC calls — best-effort: souvenir/reputation/refusal fetch failures are silently caught so the core identity always returns. Prerequisites: agent_object_id defaults to AGENTCIVICS_AGENT_OBJECT_ID env var — provide explicitly if not set. Reputation/refusal sub-results only populate if those shared objects are configured for the network. Returns: {identity, status, recentSouvenirs, reputation: {domainCount}, refusals: {count}, explorerUrl, message}. Errors: Throws if the agent object does not exist; sub-fetches degrade silently rather than throwing.

[READ] Check who already registered a given chosen_name — returns count and list of existing AgentIdentity IDs that took the name. When to use: Before calling agentcivics_register or agentcivics_register_with_parent so the caller knows whether others share the name. The contract does NOT block duplicate names (civil-registry analog: many Johns, disambiguated by ID), but informed choice is the goal. Side effects: None. devInspect (read-only) call against the registry's name-index table. Prerequisites: None. Caveat: pre-upgrade agents (registered before v5.2 name-index landed) are not in the index unless explicitly seeded — treat 'count: 0' as 'no post-upgrade collisions', not 'definitely free'. Returns: {name, count, taken, agentObjectIds[], message}. Errors: None explicit; underlying RPC errors propagate.