Thursdays with Koog: Permissions

Knosh 0.3.0, a one-shot coding agent built on the Koog framework, implements a permission system that allows agents to deny specific tools by their unique identifiers in frontmatter, with filesystem-manipulating tools requiring more fine-grained access controls. The system, adapted from OpenCode, defaults to allowing all tools but supports a 'deny' flag, while omitting OpenCode's 'ask' prompt because Knosh is non-interactive.

A month ago, in a past "Thursdays with Koog" issue, I described Koog's https://docs.koog.ai framework for tools https://pac.commonsware.com/archive/thursdays-with-koog-tools/ . Today, I'd like to talk a bit about how Knosh https://knosh.commonsware.com works with tools, in particular how things get secured. Knosh sticks to Koog's tools-as-classes pattern, and so it has a bunch of SimpleTool subclasses like GetWorkingDirectoryTool : python package com.commonsware.knosh.tools import ai.koog.agents.core.tools.SimpleTool import ai.koog.serialization.typeToken import com.commonsware.knosh.common.RuntimeContext import kotlinx.serialization.Serializable // Raw string is exempt from MaxLineLength per project Detekt config excludeRawStrings: true private val DESCRIPTION = """ You MUST use this tool to get the current working directory. You do not have access to a shell, Bash, or any command-line tools — do not guess or assume the working directory. Usage: - Takes no arguments. - The returned path is absolute and can be used to resolve relative paths or to understand the root from which other tools operate. """ .trimIndent / Tool that returns the current working directory as an absolute filesystem path string. Takes no meaningful input. / public class GetWorkingDirectoryTool private val context: RuntimeContext : SimpleTool<GetWorkingDirectoryTool.Args argsType = typeToken<Args , name = "get-working-directory", description = DESCRIPTION, { / Arguments for GetWorkingDirectoryTool . There are no meaningful arguments; pass an empty object. / @Serializable public class Args / Returns the current working directory as an absolute filesystem path. @param args unused @return the absolute path of the current working directory / override suspend fun execute args: Args : String = context.workingDir.toString } from Knosh 0.3.0 https://codeberg.org/commonsguy/knosh/src/tag/0.3.0/lib/knosh-tools/src/main/kotlin/com/commonsware/knosh/tools/GetWorkingDirectoryTool.kt KnoshToolSet has a list of all of those tools https://codeberg.org/commonsguy/knosh/src/tag/0.3.0/lib/knosh-agents/src/main/kotlin/com/commonsware/knosh/agents/KnoshToolSet.kt L47-L61 : private val tools: List<Tool< , = listOf CreateDirectoryTool dispatcher, context , DeleteFileTool dispatcher, context , FileInfoTool dispatcher, context , GetWorkingDirectoryTool context , GlobTool dispatcher, context , GrepTool dispatcher, context , ListDirectoryTreeTool dispatcher, context , MoveContentTool dispatcher, context , TextEditTool dispatcher, context , TextReadTool dispatcher, context , TextWriteTool dispatcher, context , WebFetchTool httpClient , Here, dispatcher is a CoroutineDispatcher for doing work asynchronously, and context is a RuntimeContext that provides access to things that need to be overridden in tests, such as environment variables and the filesystem. However, not all agents need all tools. If you have an agent that is solely for code reviews, you might not want it to have the ability to write to files, delete files, etc. Hence, in the frontmatter for an agent definition, you can enable and disable tools in a permission structure: permission: text-write: "deny" web-fetch: "allow" Each tool has its unique identifier e.g., text-write maps to TextWriteTool . By default, tools are allowed, but those an agent flags as deny get removed from the list. OpenCode — whose permission system Knosh adapts — also supports ask , which prompts the user at the time of tool use whether to allow it. Knosh is a one-shot coding agent, designed for non-interactive use, so it does not support ask . However, tools that manipulate the filesystem need more fine-grained access controls than a top-level allow/deny flag. By default, files inside of the current working directory can be accessed, while files elsewhere cannot. But, you can further constrain that if desired: permission: text-edit: " ": "deny" " .kt": "allow" " .kts": "allow" "/Users/alice/projects/my-app/ ": "allow" Inside Knosh, since Koog's Tool is an abstract class , we can use the decorator pattern. PermissionCheckDecorator https://codeberg.org/commonsguy/knosh/src/tag/0.3.0/lib/knosh-agents/src/main/kotlin/com/commonsware/knosh/agents/PermissionCheckDecorator.kt wraps a Knosh tool and enforces permissions before allowing the tool itself to its job: / A Tool decorator that enforces both agent-level and command-level permissions and logs each tool call. Wraps wrapped transparently, forwarding all execute calls after permission checks pass. On each successful execution, emits an INFO log event with the tool name as the message and args / result attributes. When logFullToolCalls is false , long content in args is redacted via LoggableContent.logContent and result strings that are longer than 200 characters or contain a newline are truncated: the text up to the first newline or first 80 characters whichever is shorter is kept, followed by <redacted: N chars . Enforces a dual-gate permission model: both the agent's permissions and the command's permissions must allow a tool invocation for it to proceed. First, agentConfig 's permissions are checked. Then, commandPermissions and commandExternalDirectories are checked independently. Either gate may throw ToolException.ValidationFailure via fail if a permission is denied. / internal class PermissionCheckDecorator<A, B private val wrapped: Tool<A, B , internal val agentConfig: AgentConfig, private val commandPermissions: Map<String, List<ToolPermission = emptyMap , private val commandExternalDirectories: Map<String, Boolean = emptyMap , private val logFullToolCalls: Boolean = false, private val workingDir: Path = System.getProperty "user.dir" .toPath , private val userHome: Path = System.getProperty "user.home" .toPath , : Tool<A, B argsType = wrapped.argsType, resultType = wrapped.resultType, descriptor = wrapped.descriptor { // whole lotta code } This allows the whole permission system to be abstracted out, tested in isolation, etc. This works nicely for tools that are known in advance. Things get a bit interesting for tools that are not known in advance, notably MCP servers. In next week's "Thursdays with Koog", I'll talk about the soon-to-be-released Knosh 0.4.0 , what MCP is, and how Knosh supports MCP.