Making toolCallRequest more explicit: kind of action, verb and resource.

[MKaptein]

Hi all, three small ideas about toolCallRequest. They are closely related, so I am putting them in one discussion thread; if there is any enthusiasm I am happy to move them forward.

In my view, a capability string like filesystem.delete says three things at once:

1. the kind of action,
2. a verb (GET, POST, PATCH, DELETE like), and
3. the kind of resource.

However, the field is optional, and hence I was thinking whether we could not formalize this more and make each of the three more explicit. Here are some ideas:

• The kind of action. Give code execution and access to secrets a hook (or hook-type) of their own (say codeExecution and credentialAccess). A harness declares its hooks at the start of a session, so a Guardian would know whether code execution is reported at all. #153 points out that the open problem is that capability is optional; making it required would help too.
• The verb. An optional field with fixed values: read, create, update, delete. That is the existing memoryStore list plus read. The existing operation stays as it is.
• The resource. An optional resource (a URI for example). An entry in Intent.parsed has one already, but a tool call does not, so checking a call against the Intent seems to need a parser per tool (hope that's correct).

The capability field would still be the way to declare in advance what a tool or a skill may do. The other changes just describe the resource / "step" in more detail.

I may be missing existing work here; #8 and #227 seem related.

Some background on where this comes from is here. That's work we have been doing which is sparking some of these ideas. Ideally I would love to use ACS instead of AAG in some of our upstream applications, but we would need sufficiently granular step descriptions.

[victorm-hernandez]

@MKaptein, thank you for contributing your ideas. Could you elaborate on what you mean by the "kind of action"? The distinction seems a bit blurry. What new information does the kind of action provide? Could you please provide a few examples?

[MKaptein]

Of course, and sorry for being a bit fuzzy; in the end the basic idea is to have toolCalls with "security relevant semantics" tied to them, so it's inherently a bit vague. However, in the context of agents -- given our experience -- it is actually very solvable.

With "kind of action" I mean what the agent does in a step, whatever the tool is called. Actually, ACS already does this using specific hook names, so the Guardian knows what kind of step it is before it looks at the payload:

Kind of action	ACS hook today
Session or subagent starts / ends	sessionStart, sessionEnd, subagentStart, subagentStop
Message in	userMessage, agentTrigger
Message out	agentResponse
Memory read / write	memoryContextRetrieval, memoryStore
Knowledge retrieval	knowledgeRetrieval
Anything else	toolCallRequest, toolCallResult

So, the notion of "kind of action" in a way exists already. A memory write could also have been a generic tool call; ACS chose to give it a hook of its own. It is a choice whether to treat something as a generic "tool" or to provide a specific hook for a specific kind of action.

My suggestion is simply to extend this list with a number of categories that are recurring in agent behavior. Here are some suggestions based on "kind of actions" we currently use, how I think one would currently encode them in ACS, and how we could make them more explicit:

Kind of action	Today	Suggestion
Code execution	toolCallRequest, perhaps recognisable only by the optional capability	a hook of its own: codeExecution
Access to a secret	again simply toolCallRequest, no name for secrets	a hook of its own: credentialAccess (w. verb potentially)
Model call	no hook	see #122; it's an open discussion, but it's simply a variant of the same theme
Approval or check ("gate")	a tool call with some name, or not visible at all	see #231, a gate hook
Agent waiting (for a human, a timer, another agent)	no hook or mechanism?	minor, could be a later addition but it's something we often work around

With the added semantics, a toolCallRequest would then be what is left: reading or changing something outside the agent (a file, an API, a database). Alternatively, the semantics above could be added to toolCalls in a way that is predictable across harnesses.

I might not have been sufficiently explicit about what we would gain by adding such semantics, here are a few ideas of simple policies that would be easy to enforce:

• "Code execution needs approval first." Today I have to list tool names per harness (Bash, shell, python_repl, ...) or hope capability is filled in. With a hook of its own, it is one rule that holds for every harness.
• "After a secret was read, no message to an outside address in the same session." Same problem: the Guardian first has to know that a step was a secret read.

Actually, because the harness already declares its hooks at session start, the Guardian would know up front whether the harness reports code execution at all.

It stays a bit blurry, I agree: a shell command can also fetch a web page. The harness can only report what it knows. I am also not attached to separate hooks; a required field with a few fixed values on toolCallRequest would give the same information.