Class: AgentsControl::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/agents_control/event.rb

Overview

A normalized event from an agent.

The core and the notification channel operate only on this type and know nothing about Claude Code or Codex. An agent adapter's job is to bring its own payload into this shape, and that's the extent of its knowledge of the outside world.

The shape wasn't picked arbitrarily: Claude Code and Codex independently converged on nearly the same set of events and the same way of returning a decision, so this describes an existing commonality rather than a speculative abstraction.

Constant Summary collapse

KINDS = 
%i[
  needs_permission
  needs_input
  finished
  error
  started
  ended
  progress
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(kind:, agent:, session_id:, cwd: nil, text: nil, options: [], tool_name: nil, tool_input: nil, transcript_path: nil, raw: {}) ⇒ Event

Returns a new instance of Event.

Raises:

  • (ArgumentError) 


29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/agents_control/event.rb', line 29

def initialize(kind:, agent:, session_id:, cwd: nil, text: nil, options: [],
               tool_name: nil, tool_input: nil, transcript_path: nil, raw: {})
  raise ArgumentError, "unknown event kind: #{kind}" unless KINDS.include?(kind)

  @kind = kind
  @agent = agent
  @session_id = session_id
  @cwd = cwd
  @text = text
  @options = options
  @tool_name = tool_name
  @tool_input = tool_input
  @transcript_path = transcript_path
  @raw = raw
end

Instance Attribute Details

#agent ⇒ Object (readonly)

Returns the value of attribute agent.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def agent
  @agent
end

#cwd ⇒ Object (readonly)

Returns the value of attribute cwd.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def cwd
  @cwd
end

#kind ⇒ Object (readonly)

Returns the value of attribute kind.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def kind
  @kind
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def options
  @options
end

#raw ⇒ Object (readonly)

Returns the value of attribute raw.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def raw
  @raw
end

#session_id ⇒ Object (readonly)

Returns the value of attribute session_id.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def session_id
  @session_id
end

#text ⇒ Object (readonly)

Returns the value of attribute text.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def text
  @text
end

#tool_input ⇒ Object (readonly)

Returns the value of attribute tool_input.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def tool_input
  @tool_input
end

#tool_name ⇒ Object (readonly)

Returns the value of attribute tool_name.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def tool_name
  @tool_name
end

#transcript_path ⇒ Object (readonly)

Returns the value of attribute transcript_path.



26
27
28
 
# File 'lib/agents_control/event.rb', line 26

def transcript_path
  @transcript_path
end

Instance Method Details

#ask_user_question? ⇒ Boolean

AskUserQuestion is structurally a permission request (it goes through the same PermissionRequest hook as any tool call), but answering it means picking one of its listed options — allow/deny doesn't apply, and neither does the usual reply-becomes-hook-response path.

Returns:

  • (Boolean) 


52
 
# File 'lib/agents_control/event.rb', line 52

def ask_user_question? = tool_name == "AskUserQuestion"

#label ⇒ Object

Short name of where this is happening. The full path in a notification only gets in the way — what matters in a list is recognizing the project, not seeing /Users/...



57
58
59
60
61
 
# File 'lib/agents_control/event.rb', line 57

def label
  return File.basename(cwd) if cwd && !cwd.empty?

  session_id.to_s[0, 8]
end

#question? ⇒ Boolean

Does a human need to weigh in. Everything else is background info.

Returns:

  • (Boolean) 


46
 
# File 'lib/agents_control/event.rb', line 46

def question? = %i[needs_permission needs_input].include?(kind)

#summary ⇒ Object

Description of what the agent is about to do.



64
65
66
67
68
69
70
71
 
# File 'lib/agents_control/event.rb', line 64

def summary
  case kind
  when :needs_permission then permission_summary
  when :needs_input then text.to_s
  when :error then "error: #{text}"
  else text.to_s
  end
end