The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
package cmd
import (
"strconv"
"strings"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/config"
hookdiff "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/diff"
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
)
// DeepSeek Harness payload readers and tool taxonomy.
//
// DeepSeek Harness (`dsh`) is a plugin-composed TypeScript agent runtime. It reaches Beacon
// through a bridge DeepSeek ships in the CLI, `@deepseek-ai/dsh-hooks-claude-code`, whose whole
// purpose is to run an existing Claude Code hooks file against the harness's own extension points.
// So the envelope is not merely similar to Claude Code's, it is Claude Code's, field for field:
//
// {"hook_event_name": "PreToolUse", "session_id": "...", "transcript_path": "",
// "cwd": "...", "tool_name": "bash", "tool_input": {...}, "tool_use_id": "...",
// "tool_response": "...", "prompt": "...", "source": "...",
// "agent_id": "...", "agent_type": "general-purpose", "stop_hook_active": false}
//
// dsh therefore rides the shared subcommands, the way Kiro and OpenHands do and for the same
// reason: the shared path already carries log rotation, session state, the policy seam, content
// retention and the tool call id, and a second implementation of those is the thing that drifts.
// There is no envelope reader in this file, because there is nothing to translate -- `session_id`,
// `cwd`, `prompt`, `tool_use_id` and the subagent pair all resolve through the shared default
// cases. MCP is the same story: dsh names an MCP tool `mcp__<server>__<tool>`, which is the
// spelling the shared detection and the shared server/tool split already read.
//
// What is here is everything the envelope does not settle:
//
// - The tool taxonomy. dsh publishes a generated tool catalog with both the names and the full
// argument schemas, so unlike Kiro this table is backed by schemas rather than inferred from
// names -- and it is exhaustive over what the catalog lists rather than a best guess.
//
// - `str_replace_editor`, which multiplexes view/create/str_replace/insert onto a `command`
// argument. That is the OpenHands `file_editor` and Kiro `fs_write` hazard exactly, and it is
// guarded the same way.
//
// - `terminal_send`, whose command line is named `text`. Nothing in the shared reader's key list
// finds it, so a persistent-terminal command would be recorded with no command in it.
//
// - The flattened result. The bridge collapses a tool result to text before it reaches the hook
// (`tool_response` is a string, not an object), so a shell command's output arrives as one
// string and the exit code arrives inside it, as the `[exit code: N]` marker dsh's bash and
// pwsh tools document.
//
// Deliberately not read: `hook_event_name`. Beacon binds each dsh event to a distinct subcommand
// in the hooks file it writes, so the command that is running already knows which event it is
// answering.
//
// Deliberately not read: `transcript_path`. The bridge always sends the empty string -- the
// harness's persistence seam exposes no artifact path, and its default session log is Zstandard
// compressed and not readable by a hook script. The shared default reader asks for the key and
// gets "", which is the correct answer rather than a gap to work around.
//
// Not collected, because the bridge exposes none of it on a hook: token usage and cost, a
// session-end event (dsh has none; `Stop` is the closing event and fires per turn), operator
// approval decisions (there is no PermissionRequest event -- see the pre-tool observing branch),
// compaction, and a per-tool error flag. That last one is why this file has no failure predicate:
// the bridge hands a hook `blocksToText(result.content)` and nothing else, so a tool that failed
// and a tool that succeeded are indistinguishable at the hook, and inventing a `tool.failed` from
// a non-zero shell exit would turn every failing test run into a high-severity event -- the call
// the Kiro and OpenHands readers already settled the same way.
const dshPlatform = "dsh"
// dshToolKind is what one dsh tool does, as far as the endpoint schema is concerned.
type dshToolKind int
const (
// dshToolOther is a tool with no filesystem or shell meaning. It is not absent from the table:
// an entry saying "this is a tool call and nothing more" is what keeps a future substring rule
// from guessing something else about it, and it records that the tool was considered.
dshToolOther dshToolKind = iota
dshToolRead
dshToolCreate
dshToolModify
dshToolShell
)
// dshToolKinds maps every tool in dsh's generated tool catalog onto what it does.
//
// Exhaustive over the catalog rather than a subset, for the reason the Kiro table gives: a name
// that is not here falls through to the generic classifier, which reasons from substrings and is
// wrong about most of these. Three of them would be wrong in ways that matter --
//
// - `write` and `edit` are the two most common write tools and neither contains a word the
// generic classifier looks for.
// - `terminal_read` and `terminal_list` contain "terminal", which the generic classifier reads
// as shell execution. They read retained output and enumerate sessions; neither runs anything.
// Entering them as `other` is what stops a later substring rule promoting them.
// - `send_message` and `spawn_teammate` contain neither, and are agent-coordination tools rather
// than filesystem or shell ones.
//
// Matched lowercased and exactly. There is no prefix or substring rule anywhere in this file.
var dshToolKinds = map[string]dshToolKind{
// Reads. `glob` and `grep` take a file *or directory* to search rather than a file that was
// read; recording that path under file.path with operation "read" is the shape the Kiro,
// OpenHands and Qwen taxonomies already produce, and it is the honest one -- a search did
// happen, and that path is what it touched.
"read": dshToolRead,
"read_image": dshToolRead,
"glob": dshToolRead,
"grep": dshToolRead,
// Writes. `write` creates or fully replaces, which is "create"; `edit` replaces literal text in
// a file that already exists, which is "modify". `str_replace_editor` is reclassified per call
// by dshEditorOperation, because it multiplexes four operations onto one name.
"write": dshToolCreate,
"edit": dshToolModify,
"str_replace_editor": dshToolCreate,
// Shell. `bash` and `pwsh` are the two dialects of the one executor seam; `terminal_send`
// writes a command line into a persistent terminal, which is the same act through a session
// that survives between calls.
//
// `run_code` is deliberately NOT here, and it is the entry most likely to be argued the other
// way: it executes a TypeScript program, and it is the one tool that can ask for
// `danger-full-access`. Two things decide it.
//
// First, a program's nested tool calls are not invisible. dsh dispatches them back through the
// complete guarded pipeline -- `scheduler.prepare` runs `tools/pre-execute` and the commit
// stage runs `tools/post-execute` for every sub-call -- which is the same seam the hook bridge
// listens on. So `await tools.bash({command: 'curl ... | sh'})` inside a program fires its own
// PreToolUse and PostToolUse hooks and is recorded as a command execution with a real command
// line. Classifying the outer wrapper as a command as well would double-count it.
//
// Second, command.command is a *shell* command line and every threat rule that reads it is
// written in shell terms. A TypeScript program in that field would match those rules on its
// comments and its string literals while matching none of them on what it does -- and it would
// do so instead of the precise nested events, not as well as them.
//
// The program text is still retained: dsh is in rawPayloadKeys, so the `code` argument arrives
// under raw.dsh.tool_input.code, secret-redacted and size-limited like every other field. That
// entry exists largely for this tool; see the note on it.
"bash": dshToolShell,
"pwsh": dshToolShell,
"terminal_send": dshToolShell,
// Terminal session management. `terminal_open` creates a session and takes a cwd, not a
// command; the rest inspect or end one. A signal is the closest of them to execution and is
// still not it: it delivers SIGINT to something already running.
"terminal_open": dshToolOther,
"terminal_read": dshToolOther,
"terminal_list": dshToolOther,
"terminal_close": dshToolOther,
"terminal_signal": dshToolOther,
// Background jobs. A job was started by the tool that started it -- `bash`, `pwsh` or
// `terminal_send` with run_in_background -- and that call is already recorded as a command.
// These three collect, list and kill it.
"job_output": dshToolOther,
"job_list": dshToolOther,
"job_kill": dshToolOther,
// Everything else the catalog publishes, entered so the generic classifier never sees it.
"run_code": dshToolOther,
"ask_user_question": dshToolOther,
"exit_plan_mode": dshToolOther,
"present": dshToolOther,
"plugin_manager": dshToolOther,
"lsp": dshToolOther,
"ralph": dshToolOther,
"skill": dshToolOther,
"workflow": dshToolOther,
"todo_write": dshToolOther,
"web_fetch": dshToolOther,
"web_search": dshToolOther,
"create_goal": dshToolOther,
"get_goal": dshToolOther,
"update_goal": dshToolOther,
"schedule_create": dshToolOther,
"schedule_delete": dshToolOther,
"schedule_list": dshToolOther,
"subagent": dshToolOther,
"list_subagent_models": dshToolOther,
"spawn_teammate": dshToolOther,
"wait_agent": dshToolOther,
"interrupt_agent": dshToolOther,
"list_agents": dshToolOther,
"send_message": dshToolOther,
"team_task_create": dshToolOther,
"team_task_get": dshToolOther,
"team_task_list": dshToolOther,
"team_task_update": dshToolOther,
"session_search": dshToolOther,
"session_trace": dshToolOther,
"session_event_read": dshToolOther,
"session_event_search": dshToolOther,
"session_event_trace": dshToolOther,
"cordis_inspect_list": dshToolOther,
"cordis_inspect_query": dshToolOther,
"stagehand_act": dshToolOther,
"stagehand_extract": dshToolOther,
"stagehand_navigate": dshToolOther,
"stagehand_observe": dshToolOther,
"stagehand_screenshot": dshToolOther,
"stagehand_tabs": dshToolOther,
"list_mcp_resources": dshToolOther,
"list_mcp_resource_templates": dshToolOther,
"read_mcp_resource": dshToolOther,
}
// dshEditorCommands are the operations `str_replace_editor` selects between.
//
// This set has a second job, and it is the one that would bite: `command` is also the argument name
// dsh's bash and pwsh tools use for the command line. Without knowing that an editor call's
// `command` names an operation rather than a shell command, the shared field extraction would write
// "str_replace" into command.command and let the policy seam upgrade the call from tool.invoked to
// command.executed. That is the OpenHands `file_editor` defect and the Kiro `fs_write` defect,
// guarded the same way.
var dshEditorCommands = map[string]bool{
"view": true,
"create": true,
"str_replace": true,
"insert": true,
}
// dshMultiplexedEditorTools are the tool names whose `command` argument names an editor operation
// rather than a shell command.
//
// Only `str_replace_editor`. Deliberately not every dsh tool: `command` means a shell command line
// on `bash` and `pwsh`, and a set that reached those would drop the one field that makes a shell
// event worth recording.
var dshMultiplexedEditorTools = map[string]bool{
"str_replace_editor": true,
}
// dshShellTools are the tools whose result text is a command's combined output.
//
// Kept beside the taxonomy rather than derived from it because the two answer different questions:
// the taxonomy says what kind of event this is, this says whose output the result string is. They
// agree today; a future tool that is command.executed without producing shell output would make
// them differ, and the difference should be stated rather than discovered.
var dshShellTools = map[string]bool{
"bash": true,
"pwsh": true,
"terminal_send": true,
}
// dshExitCodeMarkerPrefix is what dsh's bash and pwsh tools put in front of a non-zero exit.
//
// Both tools document the same contract: "Non-zero exits are reported as `[exit code: N]`". It is
// the only place an exit code reaches a hook, because the bridge flattens the tool result to text
// before the hook sees it -- there is no structured result to read a number out of.
//
// A zero exit produces no marker, which is why its absence is not read as success or failure by
// anything in this file. The marker is a source for command.exit_code when it is there, and
// nothing when it is not.
const dshExitCodeMarkerPrefix = "[exit code:"
// dshToolKindFor classifies a dsh tool by name, and reports whether the name is known at all.
//
// The second result matters: an unknown name is a tool this build has not seen -- an MCP tool, a
// tool added after this table was written, a tool a local plugin registered -- and the caller falls
// through to the shared classifier rather than being told the tool does nothing.
func dshToolKindFor(toolName string) (dshToolKind, bool) {
kind, ok := dshToolKinds[strings.ToLower(strings.TrimSpace(toolName))]
return kind, ok
}
// dshEditorOperation reads the operation a `str_replace_editor` call performed, or "" when the call
// is not one.
//
// Guarded on the tool name and on the value being a known editor operation, in that order. Both
// guards are load-bearing: the name keeps a shell command line out of here, and the value set keeps
// a shell command that happened to be run through a mis-named tool from being read as an operation.
//
// Only the arguments are consulted, unlike the Kiro reader which also looks at the result. dsh's
// result is a flattened string rather than an object, so there is no second place for the operation
// to be stated -- and reading a string for it would mean substring-matching tool output, which is
// how a file whose contents contain the word "create" gets classified.
func dshEditorOperation(toolName string, toolInput map[string]interface{}) string {
if !dshMultiplexedEditorTools[strings.ToLower(strings.TrimSpace(toolName))] {
return ""
}
value := strings.ToLower(strings.TrimSpace(firstToolString(toolInput, "command")))
if !dshEditorCommands[value] {
return ""
}
return value
}
// dshEditorCommandIsOperation reports whether a call's `command` argument names an editor operation
// rather than a shell command, so the shared field extraction can leave it alone.
func dshEditorCommandIsOperation(toolName string, toolInput map[string]interface{}) bool {
return dshEditorOperation(toolName, toolInput) != ""
}
// dshEditorKindForOperation maps an editor operation onto the write kind it is.
//
// `view` is a read: it is the same tool and the same arguments as the three writes, and the only
// thing that separates them is this word. Without it a `view` call would be recorded as a file
// creation, asserting that a file changed when the agent only looked at it.
func dshEditorKindForOperation(operation string) dshToolKind {
switch operation {
case "view":
return dshToolRead
case "create":
return dshToolCreate
default:
// "str_replace" and "insert". Both change a file that already exists.
return dshToolModify
}
}
// dshEffectiveToolKind is the kind a call has after its own arguments are taken into account.
//
// One place rather than four, because the multiplexed-editor reclassification has to happen
// identically in the action, the file operation, the edit predicate and the diff path, and four
// copies of "ask the table, then ask the arguments" is how those drift apart.
func dshEffectiveToolKind(toolName string, toolInput map[string]interface{}) (dshToolKind, bool) {
kind, known := dshToolKindFor(toolName)
if !known {
return dshToolOther, false
}
if operation := dshEditorOperation(toolName, toolInput); operation != "" {
kind = dshEditorKindForOperation(operation)
}
return kind, true
}
// dshToolAction maps a dsh tool call onto an endpoint event action, or returns "" to let the
// generic classifier decide.
//
// MCP is not asked first here, unlike the Kiro reader, because it does not have to be: dsh's MCP
// names carry the `mcp__` prefix the shared detection already reads, and no built-in in the table
// above can collide with it. A server tool named `read` arrives as `mcp__files__read`, which is not
// the string `read`, so the table simply does not match it and the shared MCP path takes it.
func dshToolAction(toolName string, toolInput map[string]interface{}) string {
kind, known := dshEffectiveToolKind(toolName, toolInput)
if !known {
return ""
}
switch kind {
case dshToolRead:
return "file.read"
case dshToolCreate, dshToolModify:
return "file.modified"
case dshToolShell:
return "command.executed"
default:
// A known tool with no filesystem or shell meaning. Returned directly rather than as ""
// so the generic substring classifier never sees the name: tools like terminal_read and
// read_mcp_resource contain substrings the classifier matches on, and "" is the signal
// for unknown tools that should fall through.
return "tool.invoked"
}
}
// dshFileOperation is the `file.operation` value for a dsh tool, or "" to fall through to the
// generic reader.
//
// Separate from dshToolAction, as the Kiro, Qwen and OpenHands pairs are, because the two answer
// different questions: an action says which event this is, an operation says what happened to the
// file.
func dshFileOperation(toolName string, toolInput map[string]interface{}) string {
kind, known := dshEffectiveToolKind(toolName, toolInput)
if !known {
return ""
}
switch kind {
case dshToolRead:
return "read"
case dshToolCreate:
return "create"
case dshToolModify:
return "modify"
default:
return ""
}
}
// isDshFileEditTool reports whether a dsh tool changes a file, which is what routes a post-tool
// payload down the diff path.
func isDshFileEditTool(toolName string, toolInput map[string]interface{}) bool {
kind, known := dshEffectiveToolKind(toolName, toolInput)
if !known {
return false
}
return kind == dshToolCreate || kind == dshToolModify
}
// dshResultText is the tool output the bridge flattened into `tool_response`.
//
// `tool_response` arrives as a plain string -- the bridge calls blocksToText on the result's
// content blocks before building the payload -- and the shared resolveToolResponse wraps a string
// response as {"result": <string>} so the rest of the pipeline has a map to work with. This reads
// that one key back out.
//
// The type assertion is deliberate rather than a call to the shared string reader, for the reason
// the Kiro version gives: that reader normalizes any value through fmt.Sprint, so a non-string
// would come back as Go's rendering of whatever it is, written into a field a person reads as
// command output.
func dshResultText(toolResponse map[string]interface{}) string {
if toolResponse == nil {
return ""
}
if text, ok := toolResponse["result"].(string); ok {
return text
}
return ""
}
// dshExitCode reads the exit status out of a shell tool's flattened output, and reports whether
// there was one to read.
//
// dsh's bash and pwsh tools both document that a non-zero exit is reported as `[exit code: N]` in
// the returned text. That marker is the only place an exit code reaches a hook on this runtime,
// because the bridge flattens the result before the hook sees it.
//
// The LAST marker rather than the first. The output above it is the command's own, and a command
// that prints something looking like the marker -- a test asserting on one, a log line quoting one
// -- would otherwise decide the event's exit code. dsh appends its marker at the end, so the last
// one is the runtime's.
//
// A missing marker returns false rather than 0. Zero is what dsh means by omitting it, but saying
// so here would make this function's two failure modes -- "the command succeeded" and "this output
// is not from a tool that reports exit codes" -- indistinguishable to the caller, which only calls
// it for tools that do.
func dshExitCode(output string) (int, bool) {
index := strings.LastIndex(output, dshExitCodeMarkerPrefix)
if index < 0 {
return 0, false
}
rest := output[index+len(dshExitCodeMarkerPrefix):]
end := strings.Index(rest, "]")
if end < 0 {
return 0, false
}
code, err := strconv.Atoi(strings.TrimSpace(rest[:end]))
if err != nil {
return 0, false
}
return code, true
}
// applyDshToolResult attaches what the shared toolFieldsWithResponse cannot reach: the operation a
// multiplexed editor call performed, and a shell command's output and exit status.
//
// The operation has to be applied here rather than left to fileOperation because it lives in the
// call's arguments, and the shared reader has already written its answer into the file field by the
// time this runs.
func applyDshToolResult(fields map[string]interface{}, toolName string, toolInput, toolResponse map[string]interface{}) {
if operation := dshFileOperation(toolName, toolInput); operation != "" {
if file, ok := fields["file"].(map[string]interface{}); ok {
file["operation"] = operation
}
}
if !dshShellTools[strings.ToLower(strings.TrimSpace(toolName))] {
return
}
output := dshResultText(toolResponse)
if output == "" {
return
}
command := mutableChild(fields["command"])
command["output"] = output
if code, ok := dshExitCode(output); ok {
command["exit_code"] = code
}
fields["command"] = command
// The retention marker describes the command output specifically, so it is not overwritten: a
// caller that already retained something -- a diff -- has the more specific claim.
if _, exists := fields["content"]; !exists {
fields["content"] = retainedContentFields(output)
}
}
// parseDshEdit turns one post-tool payload into the file edit it performed, or nil when it is not
// one.
//
// nil is not a failure. It means this payload is not a recordable edit -- a read, a shell command,
// an editor `view`, a write whose arguments this build could not read -- and the caller falls
// through to the observing path, which still records the tool call with its path and operation.
//
// There is no failed-write guard here, unlike the Kiro and Qwen readers, and its absence is the
// one thing about this function worth knowing. Those runtimes report a failed write with the same
// tool name and arguments as a successful one and a flag on the result that separates them; the
// dsh bridge sends no such flag, so a write that threw is indistinguishable at the hook from one
// that landed. The diff is built from the arguments either way. What that costs is a diff recorded
// for a write that failed -- stated here rather than papered over by substring-matching the result
// text for the word "error", which would drop real diffs whenever a file's contents contain it.
func parseDshEdit(input map[string]interface{}, logger *logging.Logger) *evaluationParams {
toolName := getFirstStr(input, "tool_name")
toolInput := resolveToolInput(input)
toolResponse := resolveToolResponse(input)
if !isDshFileEditTool(toolName, toolInput) {
return nil
}
filePath := hookdiff.NormalizePath(firstToolString(toolInput, "file_path", "path"))
if filePath == "" {
return nil
}
if !config.IsScannableFile(filePath) {
logger.Debug("Skipping non-scannable file: " + filePath)
return nil
}
diffStr := dshDiff(toolName, toolInput, toolResponse)
if diffStr == "" {
logger.Debug("Could not construct diff, skipping", "tool_name", toolName, "file_path", filePath)
return nil
}
return &evaluationParams{
sessionID: resolveSessionID(input, dshPlatform),
toolName: toolName,
filePath: filePath,
diffStr: diffStr,
// The taxonomy already answered this, and the shared diff path would otherwise write
// "modify" for a file that did not exist a moment ago.
fileOperation: dshFileOperation(toolName, toolInput),
}
}
// dshDiff builds the unified diff for a dsh write, choosing the builder by the shape of the call's
// arguments rather than by the tool's name alone.
//
// `write` and `edit` go through the shared FromToolResponse, which already knows both by those
// exact lowercase names and reads `file_path` with `content` and `old_string`/`new_string` -- dsh's
// fs tools use the ecosystem spellings verbatim, so there is nothing to translate.
//
// `str_replace_editor` goes through FromEditorCommandWrite, which is the Anthropic text-editor
// shape: `path` with `file_text`, `old_str` and `new_str`, selected by a `command` argument. dsh is
// the second runtime to ship that tool and the builder is the same one Kiro's write path uses.
func dshDiff(toolName string, toolInput, toolResponse map[string]interface{}) string {
if operation := dshEditorOperation(toolName, toolInput); operation != "" {
return hookdiff.FromEditorCommandWrite(operation, toolName, toolInput, toolResponse)
}
return hookdiff.FromToolResponse(strings.ToLower(strings.TrimSpace(toolName)), toolInput, toolResponse)
}