Capability Grant

​

Overview

​

Quick start

CapabilityResolver resolver = (ctx, agent) -> {
    String userId = ctx.getUserId();
    // Granularity is yours: per-(userId, agentId), or ignore agentId and return one
    // surface per user — the framework treats both identically.
    return new CapabilitySurface(
            authzService.allowedSkills(userId),      // allowed skill names; null = not set
            authzService.allowedToolGroups(userId),  // allowed ToolGroup names; null = not set
            authzService.allowedTools(userId));      // allowed tool names; null = not set
};

ReActAgent agent = ReActAgent.builder()
        .name("enterprise-agent").model(model)
        .toolkit(toolkit)
        .skillRepositories(repos)       // dynamic path for multi-tenancy; avoid static skillBox()
        .capabilityResolver(resolver)   // invoked by the framework at every call entry
        .build();

• When it resolves: once per call(), server-side, at the call entry; a null return means no trimming.
• Lifecycle: the resolved surface rides the RuntimeContext through the whole call chain — frozen per request, never persisted.
• Sub-agents: sub-agents without their own resolver reuse the parent’s surface instance (zero re-computation).
• Harness: HarnessAgent.builder().capabilityResolver(...) is supported as well; resolution happens before the sandbox acquire and skill pre-staging, so the staged set, the prompt catalog and every gate observe the same surface.
• Caching: the resolver runs at every call entry (exactly once per call). If its backend is an expensive lookup (DB / RPC), cache it yourself to match your business needs (e.g. per userId with a TTL), accepting the corresponding permission-propagation delay; the framework does not cache resolver results.
• Supersets are safe: surface contents may exceed any agent’s actual capabilities — names the agent does not have are simply never matched.

​

The three surface shapes (read this)

// Only tools in the "reporting" group; unset dimensions grant nothing extra
new CapabilitySurface(null, Set.of("reporting"), null);

// No trimming at all — the only unconditionally open shape
new CapabilitySurface(null, null, null);

// Deny everything except system capabilities
new CapabilitySurface(Set.of(), Set.of(), Set.of());

​

Grant decision rules

• Granting a skill implicitly grants its manual, scripts and associated tools (the skill tool group, convention-named skillId + "_skill_tools"), and automatically enables custom tool groups bound to it via activateOnSkill (the call entry merges bound groups into the grant set);
• Granting a ToolGroup implicitly grants every tool in it;
• Granting a tool by name grants exactly that tool (grouping is ignored, and it does not amplify to sibling tools in the same group).

​

System capability markers (system)

• a tool’s system exempts that tool’s visibility and execution;
• a group’s system exempts only the group’s own enumeration and activation — member tools stay governed by the grant surface (mark each member system if it needs the exemption);
• a skill’s system exempts its prompt visibility and loading.

Trust boundary: the system marker is open to and trusted from the assembler (the agent developer). The threat model is “end user vs. the agent’s capability surface”, not defense against the assembler.

​

Fail-closed behavior

• A throwing resolver aborts the call: the exception propagates to the caller and ERROR is logged — an authorization-infrastructure failure is not “no grants”. Catch inside your resolver and return DENY_ALL if graceful degradation is wanted.
• Direct execution: paths that execute tools directly without going through an agent call() entry (e.g. Toolkit.callTool / callTools) bypass grant resolution — a missing surface means no trimming; invoking DynamicSkillMiddleware directly behaves the same (no surface on the rc = trusted assembler code, skills stay visible). Place a surface on the RuntimeContext (rc.put(CapabilitySurface.class, surface)) to have grants applied.

​

Static skillBox path limitation