polyc-tools 2026.10.3

//! Spec for the agent-evaluable admin `revoke` tool (`#713`).
//!
//! The offboarding sibling of `invite` (`#698`/`#700`): an admin asking in
//! natural language — "remove @someone's access", "revoke @someone", "uninvite
//! @someone" — should be handled as an admin removal, not mis-answered by the
//! model. This tool lets the agent recognize that intent and hand it to the
//! control plane, which enforces the admin gate, severs the target's linked
//! identities, and cancels any outstanding invite to them.
//!
//! Like `invite` it has no in-process implementation: the conversation sandbox
//! can't reach the persona store. The harness advertises it via the same
//! control-plane proxy; the control plane runs it (admin-gated). The agent only
//! ever sees a codeless confirmation — there is no secret here, unlike
//! `invite`'s minted code, but the removal itself always requires an explicit
//! human approval naming the exact target, same as a grant.
//!
//! This is de-admitting a PERSON from Polychrome — distinct from `unlink_self`
//! (a person's own spending wallet or email) and from a person simply leaving
//! a conversation. Only the admin REMOVAL is agent-evaluable.

use polyc_llm::ToolSpec;
use serde_json::json;

/// The `revoke` tool name.
pub const TOOL_NAME: &str = "revoke";

/// Every revoke tool name, for allowlist checks and dispatch (one, today).
pub const ALL: &[&str] = &[TOOL_NAME];

/// The required argument: the target's provider-native user id, taken from the
/// mention markup already in the agent's input.
pub const ARG_TARGET_USER_ID: &str = "target_user_id";

/// Every revoke tool spec.
#[must_use]
pub fn all_specs() -> Vec<ToolSpec> {
    vec![revoke_spec()]
}

/// `revoke` spec — an admin removes a person's access to Polychrome.
///
/// Admin-only: the control plane refuses a non-admin caller and removes
/// nothing. Not read-only (it severs the target's linked identities) and not
/// egress. No secret is ever produced — the tool result is a plain,
/// codeless confirmation.
#[must_use]
pub fn revoke_spec() -> ToolSpec {
    ToolSpec::new(
        TOOL_NAME,
        "For an admin only: remove a specific person's access to Polychrome. Use \
         it when an admin asks to remove, revoke, or uninvite someone's access — \
         for example \"remove @sam's access\" or \"revoke @Vitor\". Pass the \
         target's user id EXACTLY as it appears in the mention markup in the \
         message (the id inside `<@...>`), never a typed-out name. This cuts off \
         that person's access to Polychrome across every account they've linked, \
         and cancels any invite still waiting for them — an admin can always \
         invite them again later. This is for removing a PERSON's system access, \
         which is different from unlink_self (disconnecting someone's OWN \
         spending wallet or email) and different from someone simply leaving this \
         conversation (no tool needed for that). If the person asking isn't an \
         admin, it returns a refusal rather than removing anyone.",
        json!({
            "type": "object",
            "properties": {
                ARG_TARGET_USER_ID: {
                    "type": "string",
                    "description": "The target's provider-native user id, taken \
                        verbatim from the mention markup (`<@U...>`) in the \
                        message — not a display name or handle."
                }
            },
            "required": [ARG_TARGET_USER_ID],
            "additionalProperties": false
        }),
    )
    .titled("Remove someone's access to Polychrome (admin)")
}

#[cfg(test)]
mod tests {
    use super::*;

    /// INV-R4 (POLY-503): the spec tells the model to pass the id from the
    /// `<@...>` mention markup, never a typed name. The spec text is the only
    /// place this rule lives, so the test pins both the description and the
    /// argument schema.
    #[test]
    fn revoke_spec_names_mention_markup_id() {
        let spec = revoke_spec();
        assert_eq!(spec.name, TOOL_NAME);
        assert!(
            spec.description
                .contains("EXACTLY as it appears in the mention markup"),
            "the description must demand the markup id verbatim: {}",
            spec.description
        );
        assert!(
            spec.description.contains("`<@...>`"),
            "the description must name the markup shape: {}",
            spec.description
        );
        assert!(
            spec.description.contains("never a typed-out name"),
            "the description must forbid a typed name: {}",
            spec.description
        );

        let schema = &spec.schema_json;
        assert_eq!(schema["required"], json!([ARG_TARGET_USER_ID]));
        assert_eq!(schema["additionalProperties"], json!(false));
        let argument = schema["properties"][ARG_TARGET_USER_ID]["description"]
            .as_str()
            .expect("the target argument carries a description");
        assert!(
            argument.contains("verbatim from the mention markup"),
            "the argument description must repeat the rule: {argument}"
        );
        assert!(
            argument.contains("not a display name"),
            "the argument description must refuse a display name: {argument}"
        );
        assert_eq!(
            schema["properties"].as_object().map(serde_json::Map::len),
            Some(1),
            "the target id is the only argument"
        );
    }
}